[ { "path": ".ai/agents.md", "content": "# Autonomous Agent Instructions\n\nProject: flow\n\nThis project is configured for autonomous AI agent workflows with human-in-the-loop approval.\n\n## Response Format\n\n**Every response MUST end with exactly one of these signals on the final line:**\n\n### Success signals\n\n```\ndone.\n```\nUse when task completed successfully with high certainty. No further action needed.\n\n```\ndone: \n```\nUse when task completed with context to share. Example: `done: Added login command with --token flag`\n\n### Needs human input\n\n```\nneedsUpdate: \n```\nUse when you need human decision or action. Example: `needsUpdate: Should I use OAuth or API key auth?`\n\n### Error signals\n\n```\nerror: \n```\nUse when task failed or cannot proceed. Example: `error: Build failed - missing dependency xyz`\n\n## Rules\n\n1. **Always end with a signal** - The last line must be one of the above\n2. **One signal only** - Never combine signals\n3. **Be specific** - Include actionable context in messages\n4. **No quotes** - Write signals exactly as shown, no wrapping quotes\n\n## Examples\n\n### Successful implementation\n```\nAdded the new CLI command with all requested flags.\n\ndone.\n```\n\n### Completed with context\n```\nRefactored the auth module to use the new token format.\n\ndone: Auth now supports both JWT and API key methods\n```\n\n### Need human decision\n```\nFound two approaches for caching:\n1. Redis - better for distributed systems\n2. In-memory - simpler, faster for single instance\n\nneedsUpdate: Which caching approach should I use?\n```\n\n### Error occurred\n```\nAttempted to run tests but encountered issues.\n\nerror: Test suite requires DATABASE_URL environment variable\n```\n" }, { "path": ".ai/docs/.last_sync", "content": "2026-01-01 03:08:07 (4e4a4e7)\n" }, { "path": ".ai/docs/architecture.md", "content": "# Flow Architecture\n\n## Overview\n\nFlow is a CLI tool and task runner written in Rust. It provides project automation, AI-assisted development workflows, and deployment capabilities.\n\n## Project Structure\n\n```\nsrc/\n├── main.rs # CLI entry point, command routing\n├── lib.rs # Module exports\n├── cli.rs # Clap command definitions\n├── config.rs # Configuration loading (flow.toml, global config)\n├── tasks.rs # Task execution and discovery\n├── parallel.rs # Parallel task runner with TUI\n├── commit.rs # AI-powered git commits and code review\n├── ai.rs # AI session management (Claude, Codex)\n├── deploy.rs # Deployment to hosts/platforms\n├── deploy_setup.rs # Interactive deployment setup\n├── docs.rs # Auto-generated documentation management\n├── daemon.rs # Background daemon management\n├── start.rs # Project bootstrap (.ai/ folder)\n├── env.rs # Environment variable management\n├── skills.rs # Codex skill management\n├── tools.rs # AI tool management\n├── agent.rs # Kode subagent invocation\n├── upstream.rs # Upstream fork workflow\n├── hub.rs # Hub daemon management\n├── processes.rs # Process tracking and management\n├── projects.rs # Project registry\n├── history.rs # Task history\n├── palette.rs # Fuzzy finder UI\n├── notify.rs # Lin notification integration\n├── commits.rs # Git commit browser\n├── fixup.rs # TOML auto-fix\n├── doctor.rs # System diagnostics\n├── init.rs # Project scaffolding\n├── discover.rs # Config discovery\n├── flox.rs # Flox integration\n├── task_match.rs # NL task matching via LM Studio\n├── lmstudio.rs # LM Studio API client\n├── log_server.rs # HTTP log server\n├── log_store.rs # Log storage\n├── watchers.rs # File watchers\n├── running.rs # Running state tracking\n├── sync.rs # Sync utilities\n└── db.rs # Database utilities\n```\n\n## Configuration\n\n### Project Config (`flow.toml`)\n\n```toml\nname = \"project-name\"\n\n[tasks.dev]\nrun = \"cargo run\"\ndescription = \"Run development server\"\n\n[tasks.build]\nrun = \"cargo build --release\"\n\n[daemons.api]\nrun = \"cargo run --bin api\"\nport = 8080\n\n[host]\nconnection = \"user@host\"\ndomain = \"example.com\"\n\n[cloudflare]\nname = \"worker-name\"\n\n[commit]\nreview_instructions = \"Focus on security\"\n```\n\n### Global Config (`~/.config/flow/flow.toml`)\n\nGlobal tasks and settings that apply across all projects.\n\n## Key Concepts\n\n### Tasks\nCommands defined in `flow.toml` that can be run via `f `. Support descriptions, dependencies, and arguments.\n\n### Daemons\nLong-running background processes managed by flow. Can be started, stopped, and monitored.\n\n### AI Sessions\nIntegration with Claude Code and Codex. Sessions are tracked in `.ai/internal/sessions/` with checkpoints for context management.\n\n### Deployment\nSupport for:\n- **Host**: SSH-based deployment to Linux servers\n- **Cloudflare**: Workers deployment\n- **Railway**: Platform deployment\n\n### Hub\nCentral daemon for managing servers and aggregating logs across projects.\n\n## Data Flow\n\n### Commit Flow\n1. Stage changes (`git add`)\n2. Generate diff\n3. (Optional) Code review via Codex/Claude\n4. Generate commit message via OpenAI\n5. Commit and push\n6. (Optional) Sync to gitedit.dev\n\n### Task Execution\n1. Load `flow.toml` (project or global)\n2. Resolve task by name\n3. Execute command with environment\n4. Capture output and status\n5. Store in history\n\n### Parallel Execution\n1. Parse task specifications\n2. Create async task handles\n3. Run with semaphore-based concurrency limit\n4. Render real-time TUI with spinners\n5. Collect results and display failures\n\n## File Locations\n\n### Per-Project\n- `.ai/` - AI configuration and data\n - `actions/` - Fixer scripts\n - `skills/` - Codex skills\n - `tools/` - TypeScript tools\n - `flox/` - Flox manifest\n - `docs/` - Auto-generated docs\n - `agents.md` - Agent instructions\n - `internal/` - Private data (gitignored)\n - `sessions/` - AI sessions\n - `checkpoints/` - Checkpoints\n - `db/` - SQLite database\n- `.claude/` - Symlinks to `.ai/` (gitignored)\n- `.codex/` - Symlinks to `.ai/` (gitignored)\n- `.flox/` - Symlinks to `.ai/flox/` (gitignored)\n- `flow.toml` - Project configuration\n\n### Global\n- `~/.config/flow/flow.toml` - Global config\n- `~/.config/flow/config.toml` - Flow settings\n- `~/.local/share/flow/` - Data storage\n - `history.sqlite` - Task history\n - `projects.json` - Project registry\n\n## Dependencies\n\nKey crates:\n- `clap` - CLI parsing\n- `tokio` - Async runtime\n- `axum` - HTTP server\n- `ratatui` - TUI components\n- `crossterm` - Terminal manipulation\n- `reqwest` - HTTP client\n- `rusqlite` - SQLite\n- `serde` - Serialization\n- `toml` - Config parsing\n" }, { "path": ".ai/docs/changelog.md", "content": "# Changelog\n\nAuto-maintained changelog tracking flow features and changes.\n\n## 2024-12-31\n\n### Added\n- **Documentation system** (`f docs`): Auto-generated documentation in `.ai/docs/`. Commands: `list`, `status`, `sync`, `edit`. Docs are updated by AI as part of commit flow.\n- **Parallel task runner** (`f parallel`): Run multiple tasks concurrently with animated spinners, real-time status display, and pretty output. Supports custom labels (`label:command`) and fail-fast mode.\n- **Docs update reminder**: Commit flow now detects when docs may need updating and shows a reminder.\n\n### Changed\n- **`f commit` is now the default**: Full commit with Claude review + GitEdit sync. Just run `f commit` or `f commit -m \"note\"`.\n- **Claude is default reviewer**: Use `--codex` to switch to Codex.\n- **No context by default**: Use `--context` to include AI session context.\n- **Tokens default 1000**: Use `-t` to change.\n- **Hidden legacy commands**: `f commit-simple` (no review) and `f commit-with-check` (no gitedit) are hidden but still available.\n- **`.flox/` materialization**: Flox environment now gitignored and materialized from `.ai/flox/manifest.toml` via `f start`. Source of truth moved to `.ai/flox/`.\n- **Gitignore section**: `f start` now adds `.flox/` to the `# flow` gitignore section.\n\n## 2024-12-30\n\n### Added\n- **Deploy health check** (`f deploy health`): HTTP health check for deployments with configurable URL and expected status code.\n- **GitEdit review sync**: `f commitWithCheckWithGitedit` now syncs diff, review results, and AI session data to gitedit.dev.\n\n### Changed\n- **`.ai/` folder restructure**: Separated public (tracked) and private (gitignored) content:\n - `.ai/actions/`, `.ai/skills/`, `.ai/tools/`, `.ai/flox/` - tracked\n - `.ai/internal/` - gitignored (sessions, checkpoints, db)\n- **Tool folder materialization**: `.claude/` and `.codex/` now gitignored and materialized from `.ai/` via symlinks in `f start`.\n- **Review instructions**: Now auto-discovered from `.ai/review.md`, `.ai/commit-review.md`, or `.ai/instructions.md`.\n- **Fixers**: Pre-commit fixers now check first before processing, support scripts in `.ai/actions/`.\n\n---\n\n## Document Sync\n\nThis changelog is updated when commits add new features or make significant changes. To update:\n\n1. Run `f docs sync` (when implemented)\n2. Or manually add entries following the format above\n\n### Tracking Commits\n\nRecent commits that may need documentation:\n- Check `git log --oneline -20` for recent changes\n- Focus on user-facing features and behavior changes\n" }, { "path": ".ai/docs/commands.md", "content": "# Flow CLI Commands\n\nAuto-generated documentation for flow CLI commands.\n\n## Task Execution\n\n### `f` (no args)\nOpens fuzzy finder to browse and run project tasks from `flow.toml`.\n\n### `f `\nRun a task directly by name. Additional arguments are passed to the task command.\n\n### `f run `\nExplicit task execution (same as `f `).\n\n### `f tasks`\nList all tasks from the current project's `flow.toml` with descriptions.\n\n### `f rerun`\nRe-run the last executed task in this project.\n\n### `f last-cmd`\nShow the last task's input and output/error.\n\n### `f last-cmd-full`\nShow full details of the last task run (command, status, output).\n\n### `f search` (alias: `f s`)\nFuzzy search global commands/tasks from `~/.config/flow/flow.toml`. Useful outside project directories.\n\n### `f match ` (alias: `f m`)\nMatch natural language query to a task using LM Studio. Requires LM Studio running on localhost:1234.\n\nOptions:\n- `--model ` - LM Studio model (default: qwen3-8b)\n- `--port ` - LM Studio port (default: 1234)\n- `-n, --dry-run` - Show match without running\n\n## Parallel Execution\n\n### `f parallel ` (alias: `f p`)\nRun multiple tasks in parallel with pretty status display.\n\n```bash\n# Auto-labeled (uses first word as label)\nf parallel 'echo hello' 'cargo build' 'cargo test'\n\n# Custom labels with label:command syntax\nf parallel 'build:cargo build' 'test:cargo test' 'lint:cargo clippy'\n```\n\nOptions:\n- `-j, --jobs ` - Max concurrent jobs (default: CPU count)\n- `-f, --fail-fast` - Stop all tasks on first failure\n\nFeatures:\n- Animated spinners with color cycling\n- Real-time status (pending/running/success/failure)\n- Shows last output line during execution\n- Timing for completed tasks\n- Full output for failed tasks\n\n## Git & Commits\n\n### `f commit` (alias: `f c`)\nThe default flow commit: stages changes, runs Claude code review, generates commit message, commits, pushes, and syncs AI sessions to gitedit.dev.\n\n```bash\nf commit # Just commit with Claude review\nf commit -m \"note\" # Add author note to commit message\n```\n\nOptions:\n- `-n, --no-push` - Skip pushing after commit\n- `--sync` - Run synchronously (don't delegate to hub)\n- `--context` - Include AI session context in review (default: off)\n- `--dry` - Show context without committing\n- `--codex` - Use Codex instead of Claude for review\n- `--review-model ` - Choose model (claude-opus, codex-high, codex-mini)\n- `-m, --message ` - Custom message to include\n- `-t, --tokens ` - Max tokens for context (default: 1000)\n\n### `f commit-simple` (hidden)\nSimple AI commit without code review. Just generates commit message and commits.\n\n### `f commit-with-check` (alias: `f cc`, hidden)\nLike `commit` but without syncing to gitedit.dev.\n\n### `f commits`\nBrowse git commits with AI session metadata using fuzzy search.\n\nOptions:\n- `-n, --limit ` - Number of commits (default: 100)\n- `--all` - Show all branches\n\n### `f fixup`\nFix common TOML syntax errors in `flow.toml`.\n\nOptions:\n- `-n, --dry-run` - Show fixes without applying\n\n## Process Management\n\n### `f ps`\nList running flow processes for current project.\n\nOptions:\n- `--all` - Show processes across all projects\n\n### `f kill [task]`\nStop running flow processes.\n\nOptions:\n- `--pid ` - Kill by PID\n- `--all` - Kill all project processes\n- `-f, --force` - Force kill (SIGKILL)\n- `--timeout ` - SIGKILL timeout (default: 5)\n\n### `f logs [task]`\nView logs from running or recent tasks.\n\nOptions:\n- `-f, --follow` - Follow in real-time\n- `-n, --lines ` - Lines to show (default: 50)\n- `--all` - All projects\n- `-l, --list` - List available logs\n- `-p, --project ` - By project name\n- `-q, --quiet` - Suppress headers\n\n## Daemons\n\n### `f daemon` (alias: `f d`)\nManage background daemons defined in `flow.toml`.\n\nSubcommands:\n- `start ` - Start a daemon\n- `stop ` - Stop a daemon\n- `restart ` - Restart a daemon\n- `status` - Show all daemon status\n- `list` (alias: `ls`) - List available daemons\n\n## AI Sessions\n\n### `f ai`\nManage AI coding sessions (Claude Code, Codex).\n\nSubcommands:\n- `list` (alias: `ls`) - List all sessions\n- `claude [action]` - Claude sessions only\n- `codex [action]` - Codex sessions only\n- `resume [session]` - Resume a session\n- `save ` - Bookmark current session\n- `notes ` - Open/create session notes\n- `remove ` - Remove from tracking\n- `init` - Initialize .ai folder\n- `import` - Import existing sessions\n- `copy [session]` - Copy history to clipboard\n- `context [session]` - Copy last exchange for context passing\n\n### `f sessions` (alias: `f ss`)\nFuzzy search AI sessions across all projects, copy context to clipboard.\n\nOptions:\n- `-p, --provider ` - Filter by provider (claude, codex, all)\n- `-c, --count ` - Number of exchanges to copy\n- `-l, --list` - Show without copying\n- `-f, --full` - Full context, ignore checkpoints\n- `--summarize` - Generate summaries for stale sessions\n\n### `f agent` (alias: `f a`)\nInvoke kode AI subagents.\n\nSubcommands:\n- `list` (alias: `ls`) - List available agents\n- `run ` - Run agent (codify, explore, general)\n\n## Project Setup\n\n### `f init`\nScaffold a new `flow.toml` in current directory.\n\nOptions:\n- `--path ` - Output path\n\n### `f start`\nBootstrap project with `.ai/` folder structure:\n- `.ai/actions/` - Fixer scripts (tracked)\n- `.ai/skills/` - Shared skills (tracked)\n- `.ai/tools/` - Shared tools (tracked)\n- `.ai/flox/` - Flox manifest (tracked)\n- `.ai/docs/` - AI-generated docs (tracked)\n- `.ai/agents.md` - Agent instructions (tracked)\n- `.ai/internal/` - Private data (gitignored)\n\nAlso materializes `.claude/`, `.codex/`, `.flox/` with symlinks.\n\n### `f doctor`\nVerify required tools and shell integrations (flox, lin, direnv).\n\n### `f projects`\nList all registered projects (those with `name` in `flow.toml`).\n\n### `f active [project]`\nShow or set the active project (fallback for commands outside project dirs).\n\nOptions:\n- `-c, --clear` - Clear active project\n\n## Environment\n\n### `f env`\nSync project environment and manage env vars via 1focus.\n\nSubcommands:\n- `login` - Authenticate with 1focus\n- `pull` - Fetch env vars to .env\n- `push` - Push .env to 1focus\n- `list` (alias: `ls`) - List env vars\n- `set ` - Set a var\n- `delete ` - Delete vars\n- `status` - Show auth status\n\nOptions (for pull/push/list/set/delete):\n- `-e, --environment ` - Environment (dev, staging, production)\n\n## Deployment\n\n### `f deploy`\nDeploy to various platforms.\n\nSubcommands:\n- `host` (alias: `h`) - Deploy to Linux host via SSH\n - `--remote-build` - Build on remote instead of syncing artifacts\n - `--setup` - Run setup script even if deployed\n- `cloudflare` (alias: `cf`) - Deploy to Cloudflare Workers\n - `--secrets` - Also set secrets from env_file\n - `--dev` - Run in dev mode\n- `setup` - Interactive deploy setup\n- `railway` - Deploy to Railway\n- `status` - Show deployment status\n- `logs` - View deployment logs\n - `-f, --follow` - Follow logs\n - `-n, --lines ` - Lines to show\n- `restart` - Restart deployed service\n- `stop` - Stop deployed service\n- `shell` - SSH into host\n- `set-host ` - Configure host (user@host:port)\n- `show-host` - Show host configuration\n- `health` - Check deployment health\n - `--url ` - Custom URL\n - `--status ` - Expected status (default: 200)\n\n## Upstream Forks\n\n### `f upstream` (alias: `f up`)\nManage upstream fork workflow.\n\nSubcommands:\n- `status` - Show upstream configuration\n- `setup` - Set up upstream remote and tracking\n - `-u, --upstream-url ` - Upstream repo URL\n - `-b, --upstream-branch ` - Branch name (default: main)\n- `pull` - Pull from upstream into local 'upstream' branch\n - `-b, --branch ` - Also merge into this branch\n- `sync` - Full sync: pull upstream, merge, push to origin\n - `--no-push` - Skip pushing\n\n## Skills & Tools\n\n### `f skills`\nManage Codex skills in `.ai/skills/`.\n\nSubcommands:\n- `list` (alias: `ls`) - List skills\n- `new ` - Create skill\n - `-d, --description ` - Description\n- `show ` - Show skill details\n- `edit ` - Edit in editor\n- `remove ` - Remove skill\n- `install ` - Install from registry\n- `search [query]` - Search registry\n- `sync` - Sync flow.toml tasks as skills\n\n### `f tools` (alias: `f t`)\nManage AI tools in `.ai/tools/*.ts`.\n\nSubcommands:\n- `list` (alias: `ls`) - List tools\n- `run [args...]` - Run a tool\n- `new ` - Create tool\n - `-d, --description ` - Description\n - `--ai` - Use AI to generate implementation\n- `edit ` - Edit in editor\n- `remove ` - Remove tool\n\n## Hub & Server\n\n### `f hub`\nEnsure hub daemon is running, launch TUI for inspection.\n\nSubcommands:\n- `start` - Start hub daemon\n- `stop` - Stop hub daemon\n\nOptions:\n- `--host ` - Hub host (default: 127.0.0.1)\n- `--port ` - Hub port (default: 9050)\n- `--config ` - Config path\n- `--no-ui` - Skip TUI\n\n### `f server`\nStart HTTP server for log ingestion and queries.\n\nOptions:\n- `--host ` - Bind host (default: 127.0.0.1)\n- `--port ` - Port (default: 9060)\n\nSubcommands:\n- `foreground` - Run in foreground\n- `stop` - Stop background server\n\n## Documentation\n\n### `f docs`\nManage auto-generated documentation in `.ai/docs/`.\n\nSubcommands:\n- `list` (alias: `ls`) - List documentation files\n- `status` - Show recent commits and what may need documenting\n- `sync` - Update sync marker after docs are updated\n - `-n, --commits ` - Commits to analyze (default: 10)\n - `--dry` - Dry run\n- `edit ` - Open doc file in editor\n\nThe docs are updated by AI assistants as part of the commit flow. When running `f commitWithCheckWithGitedit`, the AI reviews changes and updates:\n- `commands.md` - CLI command reference\n- `changelog.md` - Feature changelog\n- `architecture.md` - Project structure\n\n## Notifications\n\n### `f notify `\nSend proposal notification to Lin for approval (human-in-the-loop).\n\nOptions:\n- `-t, --title ` - Proposal title\n- `-c, --context <ctx>` - Context/description\n- `-e, --expires <secs>` - Expiration (default: 300)\n" }, { "path": ".ai/flox/manifest.toml", "content": "version = 1\n\n[install.cargo]\npkg-path = \"cargo\"\n\n[install.eza]\npkg-path = \"eza\"\n" }, { "path": ".ai/health-checks.json", "content": "{\n \"checks\": [\n {\n \"name\": \"share-page\",\n \"type\": \"gitedit-share\",\n \"baseUrl\": \"https://gitedit.dev\",\n \"owner\": \"giteditdev\",\n \"repo\": \"gitedit\",\n \"commit\": \"HEAD\"\n }\n ]\n}\n" }, { "path": ".ai/recipes/project/bootstrap-core-tools.md", "content": "---\ntitle: Bootstrap Core CLI Stack\ndescription: Install rise, seq, and seqd via flow install auto backend.\ntags: [bootstrap, install, rise, seq]\n---\n\nBootstrap the core toolchain onto the same bin directory as `f`.\n\n```sh\nset -euo pipefail\ncd ~/code/flow\nbin_dir=\"${FLOW_BIN_DIR:-$HOME/.flow/bin}\"\nmkdir -p \"$bin_dir\"\nf install rise --backend auto --bin-dir \"$bin_dir\" --force\nf install seq --backend auto --bin-dir \"$bin_dir\" --force\nf install seqd --backend auto --bin-dir \"$bin_dir\" --force\nls -la \"$bin_dir\" | rg ' f$| rise$| seq$| seqd$| lin$' || true\n```\n\n" }, { "path": ".ai/recipes/project/install-rise-auto.md", "content": "---\ntitle: Install Rise Via Flow Auto\ndescription: Validate that flow install rise resolves through auto backend.\ntags: [install, rise, registry, parm]\n---\n\nInstall rise using Flow auto backend and print binary path.\n\n```sh\nset -euo pipefail\ncd ~/code/flow\ntmpdir=\"$(mktemp -d /tmp/flow-install-rise.XXXXXX)\"\ntrap 'rm -rf \"$tmpdir\"' EXIT\nf install rise --backend auto --bin-dir \"$tmpdir\" --force\nls -l \"$tmpdir\"\n\"$tmpdir/rise\" --version || true\n```\n" }, { "path": ".ai/recipes/project/installer-smoke-sh.md", "content": "---\ntitle: Installer Smoke Via sh\ndescription: Smoke test myflow installer snippet with pipe-to-sh entrypoint.\ntags: [install, smoke, sh]\n---\n\nRun the hosted installer in sh mode (supports curl | sh bootstrap).\n\n```sh\nset -euo pipefail\ncurl -fsSL https://myflow.sh/install.sh | sh\n```\n" }, { "path": ".ai/recipes/project/release-core-toolchain.md", "content": "---\ntitle: Release Core Toolchain\ndescription: Publish flow, rise, and seq/seqd to myflow registry.\ntags: [release, registry, flow, rise, seq]\n---\n\n```sh\nset -euo pipefail\ncd ~/code/flow\nf recipe run project:release-flow-registry\nf recipe run project:release-rise-registry\nf recipe run project:release-seq-registry\n```\n" }, { "path": ".ai/recipes/project/release-flow-registry.md", "content": "---\ntitle: Release Flow To Registry\ndescription: Publish flow to myflow registry with explicit version.\ntags: [release, registry, myflow]\n---\n\nCut a new registry release for flow.\n\n```sh\nset -euo pipefail\nexport FLOW_REGISTRY_URL=\"${FLOW_REGISTRY_URL:-https://myflow.sh}\"\ncd ~/code/flow\nif [ -n \"${FLOW_VERSION:-}\" ]; then\n f release registry --version \"$FLOW_VERSION\" --registry \"$FLOW_REGISTRY_URL\"\nelse\n f release registry --registry \"$FLOW_REGISTRY_URL\"\nfi\n```\n" }, { "path": ".ai/recipes/project/release-rise-registry.md", "content": "---\ntitle: Release Rise To Registry\ndescription: Publish latest rise binary to myflow registry.\ntags: [release, registry, rise]\n---\n\n```sh\nset -euo pipefail\ncd ~/code/rise\nf release registry\n```\n" }, { "path": ".ai/recipes/project/release-seq-registry.md", "content": "---\ntitle: Release Seq+Seqd To Registry\ndescription: Stage seq/seqd binaries and publish package seq to myflow registry.\ntags: [release, registry, seq]\n---\n\n```sh\nset -euo pipefail\ncd ~/code/seq\nf release-registry-stage\nf release registry --no-build\n```\n" }, { "path": ".ai/repos.toml", "content": "root = \"~/repos\"\n\n[[repos]]\nowner = \"rust-lang\"\nrepo = \"crates.io-index\"\nurl = \"https://github.com/rust-lang/crates.io-index\"\n\n[[repos]]\nowner = \"dtolnay\"\nrepo = \"anyhow\"\nurl = \"https://github.com/dtolnay/anyhow\"\n\n[[repos]]\nowner = \"tokio-rs\"\nrepo = \"tokio\"\nurl = \"https://github.com/tokio-rs/tokio\"\n" }, { "path": ".ai/tasks/flow/bench-cli/main.mbt", "content": "// title: Flow CLI Bench\n// description: Quick CLI benchmark for high-frequency Flow entry points.\n// tags: [flow,bench,latency]\n\nfn project_root() -> String {\n match @sys.get_env_var(\"FLOW_AI_TASK_PROJECT_ROOT\") {\n Some(root) => root\n None => \"../../../..\"\n }\n}\n\nasync fn run_step(label : String, command : String, root : String) -> Unit raise {\n println(\"==> \" + label)\n println(\" \" + command)\n let code = @process.run(\n \"sh\",\n [\"-lc\", command],\n stdin=@stdio.stdin,\n stdout=@stdio.stdout,\n stderr=@stdio.stderr,\n cwd=root,\n )\n if code != 0 {\n abort(\"step failed: \" + label + \" (exit \" + code.to_string() + \")\")\n }\n}\n\nasync fn main raise {\n let root = project_root()\n let bench_script =\n \"set -euo pipefail; \" +\n \"bin=${FLOW_BIN:-./target/release/f}; \" +\n \"if [ ! -x \\\"$bin\\\" ]; then bin=./target/debug/f; fi; \" +\n \"runs=${FLOW_BENCH_ITERATIONS:-20}; \" +\n \"warmup=${FLOW_BENCH_WARMUP:-5}; \" +\n \"echo \\\"bench bin: $bin\\\"; \" +\n \"echo \\\"runs: $runs warmup: $warmup\\\"; \" +\n \"if command -v hyperfine >/dev/null 2>&1; then \" +\n \"hyperfine --warmup \\\"$warmup\\\" --runs \\\"$runs\\\" \" +\n \"\\\"$bin --help >/dev/null\\\" \" +\n \"\\\"$bin tasks list >/dev/null\\\" \" +\n \"\\\"$bin tasks dupes >/dev/null\\\"; \" +\n \"else \" +\n \"echo 'hyperfine not found; fallback single-run timing'; \" +\n \"for cmd in '--help' 'tasks list' 'tasks dupes'; do \" +\n \"echo \\\"timing: $bin $cmd\\\"; /usr/bin/time -l sh -lc \\\"$bin $cmd >/dev/null\\\"; \" +\n \"done; \" +\n \"fi\"\n\n run_step(\"cli benchmark\", bench_script, root)\n println(\"flow/bench-cli: ok\")\n}\n" }, { "path": ".ai/tasks/flow/bench-cli/moon.mod.json", "content": "{\n \"name\": \"nikiv/flow-ai-tasks\",\n \"version\": \"0.1.0\",\n \"deps\": {\n \"moonbitlang/async\": \"0.16.6\",\n \"moonbitlang/x\": \"0.4.40\"\n }\n}\n" }, { "path": ".ai/tasks/flow/bench-cli/moon.pkg.json", "content": "{\n \"is-main\": true,\n \"import\": [\n \"moonbitlang/async\",\n \"moonbitlang/async/process\",\n \"moonbitlang/async/stdio\",\n \"moonbitlang/x/sys\"\n ],\n \"support-targets\": [\"native\"]\n}\n" }, { "path": ".ai/tasks/flow/dev-check/main.mbt", "content": "// title: Flow Dev Check\n// description: Fast local quality gate for Flow code changes.\n// tags: [flow,dev,check]\n\nfn project_root() -> String {\n match @sys.get_env_var(\"FLOW_AI_TASK_PROJECT_ROOT\") {\n Some(root) => root\n None => \"../../../..\"\n }\n}\n\nasync fn run_step(label : String, command : String, root : String) -> Unit raise {\n println(\"==> \" + label)\n println(\" \" + command)\n let code = @process.run(\n \"sh\",\n [\"-lc\", command],\n stdin=@stdio.stdin,\n stdout=@stdio.stdout,\n stderr=@stdio.stderr,\n cwd=root,\n )\n if code != 0 {\n abort(\"step failed: \" + label + \" (exit \" + code.to_string() + \")\")\n }\n}\n\nasync fn main raise {\n let root = project_root()\n run_step(\"cargo check\", \"cargo check --all-targets\", root)\n run_step(\n \"targeted ai task test\",\n \"cargo test ai_tasks::tests::parses_metadata_comments -- --nocapture\",\n root,\n )\n run_step(\"tasks help smoke\", \"./target/debug/f tasks --help >/dev/null\", root)\n println(\"flow/dev-check: ok\")\n}\n" }, { "path": ".ai/tasks/flow/dev-check/moon.mod.json", "content": "{\n \"name\": \"nikiv/flow-ai-tasks\",\n \"version\": \"0.1.0\",\n \"deps\": {\n \"moonbitlang/async\": \"0.16.6\",\n \"moonbitlang/x\": \"0.4.40\"\n }\n}\n" }, { "path": ".ai/tasks/flow/dev-check/moon.pkg.json", "content": "{\n \"is-main\": true,\n \"import\": [\n \"moonbitlang/async\",\n \"moonbitlang/async/process\",\n \"moonbitlang/async/stdio\",\n \"moonbitlang/x/sys\"\n ],\n \"support-targets\": [\"native\"]\n}\n" }, { "path": ".ai/tasks/flow/noop/main.mbt", "content": "// title: Flow Noop\n// description: Minimal AI task for runtime overhead benchmarking.\n// tags: [flow,bench,noop]\n\nfn main {\n ()\n}\n" }, { "path": ".ai/tasks/flow/noop/moon.mod.json", "content": "{\n \"name\": \"nikiv/flow-ai-tasks\",\n \"version\": \"0.1.0\",\n \"deps\": {\n \"moonbitlang/async\": \"0.16.6\",\n \"moonbitlang/x\": \"0.4.40\"\n }\n}\n" }, { "path": ".ai/tasks/flow/noop/moon.pkg.json", "content": "{\n \"is-main\": true,\n \"support-targets\": [\"native\"]\n}\n" }, { "path": ".ai/tasks/flow/pr-ready/main.mbt", "content": "// title: Flow PR Ready\n// description: Pre-PR gate: compile, task checks, docs parity, gitignore hygiene.\n// tags: [flow,pr,gate]\n\nfn project_root() -> String {\n match @sys.get_env_var(\"FLOW_AI_TASK_PROJECT_ROOT\") {\n Some(root) => root\n None => \"../../../..\"\n }\n}\n\nasync fn run_step(label : String, command : String, root : String) -> Unit raise {\n println(\"==> \" + label)\n println(\" \" + command)\n let code = @process.run(\n \"sh\",\n [\"-lc\", command],\n stdin=@stdio.stdin,\n stdout=@stdio.stdout,\n stderr=@stdio.stderr,\n cwd=root,\n )\n if code != 0 {\n abort(\"step failed: \" + label + \" (exit \" + code.to_string() + \")\")\n }\n}\n\nasync fn main raise {\n let root = project_root()\n\n run_step(\"dev check\", \"./target/debug/f ai:flow/dev-check\", root)\n\n run_step(\n \"docs parity gate\",\n \"set -euo pipefail; \" +\n \"src_changed=$(git diff --name-only HEAD -- src/cli.rs src/tasks.rs src/palette.rs src/ai_tasks.rs || true); \" +\n \"if [ -n \\\"$src_changed\\\" ]; then \" +\n \"docs_changed=$(git diff --name-only HEAD -- docs/commands/readme.md docs/commands/tasks.md docs/commands/recipe.md || true); \" +\n \"if [ -z \\\"$docs_changed\\\" ]; then echo 'expected docs/commands updates for CLI/task changes' >&2; exit 1; fi; \" +\n \"fi; \" +\n \"echo 'docs parity: ok'\",\n root,\n )\n\n run_step(\n \"gitignore hygiene gate\",\n \"set -euo pipefail; \" +\n \"if git diff -- .gitignore | grep -E '\\\\.beads/|\\\\.rise/|\\\\.ai/todos/\\\\*\\\\.bike' >/dev/null; then \" +\n \"echo 'blocked personal tooling pattern detected in .gitignore diff' >&2; exit 1; \" +\n \"fi; \" +\n \"echo 'gitignore hygiene: ok'\",\n root,\n )\n\n println(\"flow/pr-ready: ok\")\n}\n" }, { "path": ".ai/tasks/flow/pr-ready/moon.mod.json", "content": "{\n \"name\": \"nikiv/flow-ai-tasks\",\n \"version\": \"0.1.0\",\n \"deps\": {\n \"moonbitlang/async\": \"0.16.6\",\n \"moonbitlang/x\": \"0.4.40\"\n }\n}\n" }, { "path": ".ai/tasks/flow/pr-ready/moon.pkg.json", "content": "{\n \"is-main\": true,\n \"import\": [\n \"moonbitlang/async\",\n \"moonbitlang/async/process\",\n \"moonbitlang/async/stdio\",\n \"moonbitlang/x/sys\"\n ],\n \"support-targets\": [\"native\"]\n}\n" }, { "path": ".ai/tasks/flow/regression-smoke/main.mbt", "content": "// title: Flow Regression Smoke\n// description: Validate task discovery and AI task execution in a fresh temp project.\n// tags: [flow,smoke,regression]\n\nfn project_root() -> String {\n match @sys.get_env_var(\"FLOW_AI_TASK_PROJECT_ROOT\") {\n Some(root) => root\n None => \"../../../..\"\n }\n}\n\nasync fn run_step(label : String, command : String, root : String) -> Unit raise {\n println(\"==> \" + label)\n println(\" \" + command)\n let code = @process.run(\n \"sh\",\n [\"-lc\", command],\n stdin=@stdio.stdin,\n stdout=@stdio.stdout,\n stderr=@stdio.stderr,\n cwd=root,\n )\n if code != 0 {\n abort(\"step failed: \" + label + \" (exit \" + code.to_string() + \")\")\n }\n}\n\nasync fn main raise {\n let root = project_root()\n let smoke_script =\n \"set -euo pipefail; \" +\n \"bin=${FLOW_BIN:-$PWD/target/debug/f}; \" +\n \"case \\\"$bin\\\" in /*) ;; *) bin=\\\"$PWD/$bin\\\" ;; esac; \" +\n \"if [ ! -x \\\"$bin\\\" ]; then bin=$PWD/target/release/f; fi; \" +\n \"tmp=$(mktemp -d /tmp/flow-task-smoke.XXXXXX); \" +\n \"trap 'rm -rf \\\"$tmp\\\"' EXIT; \" +\n \"printf '%s\\\\n' '[[tasks]]' 'name = \\\"hello\\\"' 'command = \\\"echo hello-flow\\\"' > \\\"$tmp/flow.toml\\\"; \" +\n \"(cd \\\"$tmp\\\" && \\\"$bin\\\" tasks init-ai --root . >/dev/null); \" +\n \"(cd \\\"$tmp\\\" && \\\"$bin\\\" tasks list | grep -q 'ai:starter'); \" +\n \"(cd \\\"$tmp\\\" && out=$(\\\"$bin\\\" starter) && case \\\"$out\\\" in *'starter ai task: ok'*) : ;; *) echo 'starter output mismatch' >&2; exit 1 ;; esac); \" +\n \"(cd \\\"$tmp\\\" && out=$(\\\"$bin\\\" hello) && case \\\"$out\\\" in *'hello-flow'*) : ;; *) echo 'hello output mismatch' >&2; exit 1 ;; esac); \" +\n \"echo 'regression smoke passed'\"\n\n run_step(\"temp project smoke\", smoke_script, root)\n println(\"flow/regression-smoke: ok\")\n}\n" }, { "path": ".ai/tasks/flow/regression-smoke/moon.mod.json", "content": "{\n \"name\": \"nikiv/flow-ai-tasks\",\n \"version\": \"0.1.0\",\n \"deps\": {\n \"moonbitlang/async\": \"0.16.6\",\n \"moonbitlang/x\": \"0.4.40\"\n }\n}\n" }, { "path": ".ai/tasks/flow/regression-smoke/moon.pkg.json", "content": "{\n \"is-main\": true,\n \"import\": [\n \"moonbitlang/async\",\n \"moonbitlang/async/process\",\n \"moonbitlang/async/stdio\",\n \"moonbitlang/x/sys\"\n ],\n \"support-targets\": [\"native\"]\n}\n" }, { "path": ".ai/tasks/flow/release-preflight/main.mbt", "content": "// title: Flow Release Preflight\n// description: Build release binary and validate core release smoke checks.\n// tags: [flow,release,preflight]\n\nfn project_root() -> String {\n match @sys.get_env_var(\"FLOW_AI_TASK_PROJECT_ROOT\") {\n Some(root) => root\n None => \"../../../..\"\n }\n}\n\nasync fn run_step(label : String, command : String, root : String) -> Unit raise {\n println(\"==> \" + label)\n println(\" \" + command)\n let code = @process.run(\n \"sh\",\n [\"-lc\", command],\n stdin=@stdio.stdin,\n stdout=@stdio.stdout,\n stderr=@stdio.stderr,\n cwd=root,\n )\n if code != 0 {\n abort(\"step failed: \" + label + \" (exit \" + code.to_string() + \")\")\n }\n}\n\nasync fn main raise {\n let root = project_root()\n\n run_step(\"build release f\", \"cargo build --release --bin f\", root)\n run_step(\"release version\", \"./target/release/f --version\", root)\n run_step(\"release tasks help\", \"./target/release/f tasks --help >/dev/null\", root)\n run_step(\n \"release regression smoke\",\n \"FLOW_BIN=./target/release/f ./target/release/f ai:flow/regression-smoke\",\n root,\n )\n\n println(\"flow/release-preflight: ok\")\n}\n" }, { "path": ".ai/tasks/flow/release-preflight/moon.mod.json", "content": "{\n \"name\": \"nikiv/flow-ai-tasks\",\n \"version\": \"0.1.0\",\n \"deps\": {\n \"moonbitlang/async\": \"0.16.6\",\n \"moonbitlang/x\": \"0.4.40\"\n }\n}\n" }, { "path": ".ai/tasks/flow/release-preflight/moon.pkg.json", "content": "{\n \"is-main\": true,\n \"import\": [\n \"moonbitlang/async\",\n \"moonbitlang/async/process\",\n \"moonbitlang/async/stdio\",\n \"moonbitlang/x/sys\"\n ],\n \"support-targets\": [\"native\"]\n}\n" }, { "path": ".ai/todos/todos.json", "content": "[\n {\n \"id\": \"c1b0f1e0e6d84f33b169b9b0f87f3c4e\",\n \"title\": \"Evaluate Rolldown for builds and deployment speedups\",\n \"status\": \"pending\",\n \"created_at\": \"2026-01-02T19:30:00Z\",\n \"updated_at\": null,\n \"note\": \"Compare Vite/Rollup vs Rolldown (Rust) and list build cache, asset diffing, and deploy pipeline optimizations.\",\n \"session\": null\n },\n {\n \"id\": \"72529e916fd74131ba746d6a962f53f6\",\n \"title\": \"Re-run review: review timed out for commit d076aea\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-13T10:13:24.836444+00:00\",\n \"updated_at\": \"2026-02-13T10:46:08.595809+00:00\",\n \"note\": \"Source: flow review\\nCommit: d076aead403da676b24cc8f2631cb217e7f5a004\\nModel: gpt-5.1-codex-max\\nReview summary: Codex review timed out after 120s\\n\\nRe-run review: review timed out for commit d076aea\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-3b7fc9b7a8dc\"\n },\n {\n \"id\": \"26717fd7a4774eceb418c88579de547c\",\n \"title\": \"Re-run review: review timed out for commit 6ace98e\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-13T14:20:44.173471+00:00\",\n \"updated_at\": \"2026-02-16T21:59:53.299632+00:00\",\n \"note\": \"Source: flow review\\nCommit: 6ace98ebb6984d2b237007c964066d50f6faa153\\nModel: gpt-5.1-codex-max\\nReview summary: Codex review timed out after 300s\\n\\nRe-run review: review timed out for commit 6ace98e\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-ce0f9bb6b555\"\n },\n {\n \"id\": \"cf5fc5b65e62468b8f72d1cf88fac6e0\",\n \"title\": \"Re-run review: review timed out for commit 311eea9\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-14T09:28:44.871217+00:00\",\n \"updated_at\": \"2026-02-14T09:31:15.179148+00:00\",\n \"note\": \"Source: flow review\\nCommit: 311eea95538dfc9c87d6b2e5f98a7890a0803465\\nModel: gpt-5.1-codex-max\\nReview summary: Codex review timed out after 300s\\n\\nRe-run review: review timed out for commit 311eea9\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-888c93874436\"\n },\n {\n \"id\": \"1d57246970fd4297b5bba7e2bb1c4ce3\",\n \"title\": \"Re-run review: review timed out for commit 2177d65\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-14T16:21:46.629833+00:00\",\n \"updated_at\": \"2026-02-16T21:59:53.395640+00:00\",\n \"note\": \"Source: flow review\\nCommit: 2177d65d15ebc28e13152b31413aa8263e8f8f71\\nModel: gpt-5.1-codex-max\\nReview summary: Codex review timed out after 300s\\n\\nRe-run review: review timed out for commit 2177d65\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-e11c99ffe84e\"\n },\n {\n \"id\": \"f21c30c0925f48ac858e716fa4ca5473\",\n \"title\": \"[P2] AI branch selection errors on valid `none` response — /Users/nikiv/code/flow/src/branches.rs:93-105\",\n \"status\": \"pending\",\n \"created_at\": \"2026-02-15T14:53:56.021590+00:00\",\n \"updated_at\": null,\n \"note\": \"Source: flow review\\nCommit: 0f2d9648acd4e91cdfa807d379adcc834937d3a9\\nModel: gpt-5.1-codex-max\\n\\n[P2] AI branch selection errors on valid `none` response — /Users/nikiv/code/flow/src/branches.rs:93-105\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-cb4f1393f4e9\"\n },\n {\n \"id\": \"e52b2941b9b94e0289ba8d01f7e2fa83\",\n \"title\": \"[P2] Missing project param returns 500 instead of client error — /Users/nikiv/code/flow/src/server.rs:900-907\",\n \"status\": \"pending\",\n \"created_at\": \"2026-02-16T10:41:04.444182+00:00\",\n \"updated_at\": null,\n \"note\": \"Source: flow review\\nCommit: 4133ea3a77aa72f21abd21c4e26799bac3278f34\\nModel: gpt-5.1-codex-max\\n\\n[P2] Missing project param returns 500 instead of client error — /Users/nikiv/code/flow/src/server.rs:900-907\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-cc5166e8114b\"\n },\n {\n \"id\": \"d4a12dd1ab3449c5953b4e3e3b572e89\",\n \"title\": \"[P2] JJ default remote ignores new git.remote setting — /Users/nikiv/code/flow/src/cli.rs:1718-1726\",\n \"status\": \"pending\",\n \"created_at\": \"2026-02-16T18:58:58.634200+00:00\",\n \"updated_at\": null,\n \"note\": \"Source: flow review\\nCommit: 0b6424d81eeee048a5e1507cc67094ea4e883819\\nModel: gpt-5.1-codex-max\\n\\n[P2] JJ default remote ignores new git.remote setting — /Users/nikiv/code/flow/src/cli.rs:1718-1726\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-aa7d77e8a06c\"\n },\n {\n \"id\": \"ccc4555e52c745e4aa017237f10a8c97\",\n \"title\": \"[P1] Collect gitedit sessions after creating commit — /Users/nikiv/code/flow/src/commit.rs:4299-4311\",\n \"status\": \"pending\",\n \"created_at\": \"2026-02-16T19:43:51.443004+00:00\",\n \"updated_at\": null,\n \"note\": \"Source: flow review\\nCommit: 18a4bde4ca0433b7b3689560cfd6a949ebfd0565\\nModel: gpt-5.1-codex-max\\n\\n[P1] Collect gitedit sessions after creating commit — /Users/nikiv/code/flow/src/commit.rs:4299-4311\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-4f55a14a7a31\"\n },\n {\n \"id\": \"f264371559114db59152e00a394a999b\",\n \"title\": \"[P1] Honor recipe shell selection when running commands — /Users/nikiv/code/flow/src/recipe.rs:122-126\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-17T11:40:29.148363+00:00\",\n \"updated_at\": \"2026-02-17T14:43:38.741376+00:00\",\n \"note\": \"Source: flow review\\nCommit: c52538d993835214221eb89252777e1e64027454\\nModel: gpt-5.1-codex-max\\n\\n[P1] Honor recipe shell selection when running commands — /Users/nikiv/code/flow/src/recipe.rs:122-126\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-551b4c7441b9\",\n \"priority\": \"P4\"\n },\n {\n \"id\": \"e2b50f22152841f299d47ab83dc2e264\",\n \"title\": \"[P2] Global recipes default to project directory — /Users/nikiv/code/flow/src/recipe.rs:560-569\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-17T11:40:29.148363+00:00\",\n \"updated_at\": \"2026-02-17T14:43:38.749300+00:00\",\n \"note\": \"Source: flow review\\nCommit: c52538d993835214221eb89252777e1e64027454\\nModel: gpt-5.1-codex-max\\n\\n[P2] Global recipes default to project directory — /Users/nikiv/code/flow/src/recipe.rs:560-569\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-658624948e1a\",\n \"priority\": \"P4\"\n },\n {\n \"id\": \"1531571a23a44211837aa0a3f7692a6f\",\n \"title\": \"[P2] reviews-todo fix ignores configured Codex binary — /Users/nikiv/code/flow/src/reviews_todo.rs:262-265\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-17T11:40:29.148363+00:00\",\n \"updated_at\": \"2026-02-17T14:43:38.756548+00:00\",\n \"note\": \"Source: flow review\\nCommit: c52538d993835214221eb89252777e1e64027454\\nModel: gpt-5.1-codex-max\\n\\n[P2] reviews-todo fix ignores configured Codex binary — /Users/nikiv/code/flow/src/reviews_todo.rs:262-265\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-9f11354ed9dd\",\n \"priority\": \"P4\"\n },\n {\n \"id\": \"3aa07bb3ec6344cfbb2e11072ef39604\",\n \"title\": \"[P2] Run bootstrap after registry installs — /Users/nikiv/code/flow/scripts/install.sh:637-646\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-17T13:40:09.528742+00:00\",\n \"updated_at\": \"2026-02-17T14:43:38.764137+00:00\",\n \"note\": \"Source: flow review\\nCommit: 96f37f21bc5bcf51fafe38fe0fc8343a3cbb916b\\nModel: gpt-5.1-codex-max\\n\\n[P2] Run bootstrap after registry installs — /Users/nikiv/code/flow/scripts/install.sh:637-646\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-245de484c8ee\",\n \"priority\": \"P4\"\n },\n {\n \"id\": \"0a7bc4060d23470d96cac5ea043a6b0a\",\n \"title\": \"[P1] Scoped parsing blocks ':' or '/' task names — /var/folders/69/jnm2pqrx12103z_f8hh3_d1w0000gn/T/.tmpDgAgRL/repo/src/...\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-17T14:32:04.676369+00:00\",\n \"updated_at\": \"2026-02-17T14:42:36.827744+00:00\",\n \"note\": \"Source: flow review\\nCommit: 527049ff7b73886705ded5e4105e35ca7a76d01b\\nModel: gpt-5.1-codex-max\\n\\n[P1] Scoped parsing blocks ':' or '/' task names — /var/folders/69/jnm2pqrx12103z_f8hh3_d1w0000gn/T/.tmpDgAgRL/repo/src/tasks.rs:728-741\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-7cf264b052d8\",\n \"priority\": \"P4\"\n },\n {\n \"id\": \"8f2bdf3f63f440f1abbb034634fe2eae\",\n \"title\": \"Re-run review: review timed out for commit 527049f\",\n \"status\": \"completed\",\n \"created_at\": \"2026-02-17T14:35:26.536392+00:00\",\n \"updated_at\": \"2026-02-17T14:43:57.289970+00:00\",\n \"note\": \"Source: flow review\\nCommit: 527049ff7b73886705ded5e4105e35ca7a76d01b\\nModel: gpt-5.1-codex-max\\nReview summary: Codex review timed out after 360s\\n\\nRe-run review: review timed out for commit 527049f\",\n \"session\": null,\n \"external_ref\": \"flow-review-issue-c02170490800\",\n \"priority\": \"P4\"\n }\n]" }, { "path": ".flox.disabled", "content": "flox activate repeatedly failed" }, { "path": ".github/workflows/canary.yml", "content": "name: Canary\n\non:\n push:\n branches:\n - main\n paths-ignore:\n - \"docs/**\"\n - \"**/*.md\"\n workflow_dispatch:\n\npermissions:\n contents: write\n\nconcurrency:\n group: canary\n cancel-in-progress: true\n\nenv:\n CARGO_TERM_COLOR: always\n\njobs:\n build:\n timeout-minutes: 40\n env:\n # Don't reference `secrets.*` in `if:` expressions; GitHub rejects that at workflow-parse time.\n MACOS_SIGN_P12_B64: ${{ secrets.MACOS_SIGN_P12_B64 }}\n MACOS_SIGN_P12_PASSWORD: ${{ secrets.MACOS_SIGN_P12_PASSWORD }}\n MACOS_SIGN_IDENTITY: ${{ secrets.MACOS_SIGN_IDENTITY }}\n strategy:\n matrix:\n include:\n - target: x86_64-apple-darwin\n os: macos-latest\n - target: aarch64-apple-darwin\n os: macos-latest\n - target: x86_64-unknown-linux-gnu\n os: ubuntu-latest\n - target: aarch64-unknown-linux-gnu\n os: ubuntu-latest\n\n runs-on: ${{ matrix.os }}\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Validate readme casing\n run: scripts/ci/check-readme-case.sh\n\n - name: Cache vendored deps\n uses: actions/cache@v4\n with:\n path: |\n .vendor/flow-vendor\n lib/vendor\n lib/vendor-manifest\n key: ${{ runner.os }}-${{ runner.arch }}-vendor-${{ hashFiles('vendor.lock.toml') }}\n\n - name: Verify pinned vendor commit is published\n run: scripts/vendor/vendor-repo.sh verify-pinned-origin\n\n - name: Hydrate vendored deps\n run: scripts/vendor/vendor-repo.sh hydrate\n\n - name: Install Rust\n uses: dtolnay/rust-toolchain@stable\n with:\n targets: ${{ matrix.target }}\n\n - name: Cache Rust build\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: \". -> target\"\n cache-on-failure: true\n\n - name: Install cross-compilation tools (Linux ARM)\n if: matrix.target == 'aarch64-unknown-linux-gnu'\n run: |\n sudo apt-get update\n sudo apt-get install -y gcc-aarch64-linux-gnu\n\n - name: Build\n run: |\n if [ \"${{ matrix.target }}\" = \"aarch64-unknown-linux-gnu\" ]; then\n export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc\n fi\n cargo build --release --target ${{ matrix.target }} --bin f\n\n - name: Import code-signing certificates (macOS)\n if: runner.os == 'macOS' && env.MACOS_SIGN_P12_B64 != ''\n uses: apple-actions/import-codesign-certs@v3\n with:\n p12-file-base64: ${{ env.MACOS_SIGN_P12_B64 }}\n p12-password: ${{ env.MACOS_SIGN_P12_PASSWORD }}\n\n - name: Codesign (macOS)\n if: runner.os == 'macOS' && env.MACOS_SIGN_P12_B64 != '' && env.MACOS_SIGN_IDENTITY != ''\n run: |\n BIN=\"target/${{ matrix.target }}/release/f\"\n codesign --force --options runtime --timestamp --sign \"$MACOS_SIGN_IDENTITY\" \"$BIN\"\n codesign -vvv --strict \"$BIN\"\n\n - name: Package\n run: |\n mkdir -p dist\n cp target/${{ matrix.target }}/release/f dist/\n cd dist\n tar -czvf flow-${{ matrix.target }}.tar.gz f\n cd ..\n\n - name: Upload artifact\n uses: actions/upload-artifact@v4\n with:\n name: flow-${{ matrix.target }}\n path: dist/flow-${{ matrix.target }}.tar.gz\n\n build-linux-host-simd:\n timeout-minutes: 40\n runs-on: [self-hosted, linux, x64, ci-1focus]\n env:\n RUSTFLAGS: -C target-cpu=native\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Validate readme casing\n run: scripts/ci/check-readme-case.sh\n\n - name: Cache vendored deps\n uses: actions/cache@v4\n with:\n path: |\n .vendor/flow-vendor\n lib/vendor\n lib/vendor-manifest\n key: ${{ runner.os }}-${{ runner.arch }}-vendor-${{ hashFiles('vendor.lock.toml') }}\n\n - name: Verify pinned vendor commit is published\n run: scripts/vendor/vendor-repo.sh verify-pinned-origin\n\n - name: Hydrate vendored deps\n run: scripts/vendor/vendor-repo.sh hydrate\n\n - name: Install Rust\n uses: dtolnay/rust-toolchain@stable\n with:\n targets: x86_64-unknown-linux-gnu\n\n - name: Cache Rust build\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: \". -> target\"\n cache-on-failure: true\n\n - name: Build (Linux host SIMD)\n run: cargo build --release --target x86_64-unknown-linux-gnu --features linux-host-simd-json --bin f\n\n - name: Package\n run: |\n mkdir -p dist\n cp target/x86_64-unknown-linux-gnu/release/f dist/\n cd dist\n tar -czvf flow-x86_64-unknown-linux-gnu-linux-host-simd.tar.gz f\n cd ..\n\n - name: Upload artifact\n uses: actions/upload-artifact@v4\n with:\n name: flow-x86_64-unknown-linux-gnu-linux-host-simd\n path: dist/flow-x86_64-unknown-linux-gnu-linux-host-simd.tar.gz\n\n release:\n needs: [build, build-linux-host-simd]\n timeout-minutes: 20\n runs-on: ubuntu-latest\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Download all artifacts\n uses: actions/download-artifact@v4\n with:\n path: artifacts\n\n - name: Prepare release files\n run: |\n mkdir -p release\n find artifacts -name \"*.tar.gz\" -exec cp {} release/ \\;\n cd release\n sha256sum *.tar.gz > checksums.txt\n cat checksums.txt\n\n - name: Move canary tag to this commit\n run: |\n git tag -f canary \"${GITHUB_SHA}\"\n git push origin -f refs/tags/canary\n\n - name: Create/Update Canary Release\n uses: softprops/action-gh-release@v2\n with:\n tag_name: canary\n name: Canary\n prerelease: true\n generate_release_notes: false\n files: release/*\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".github/workflows/nightly-validation.yml", "content": "name: Nightly Validation\n\non:\n schedule:\n - cron: \"27 3 * * *\"\n workflow_dispatch:\n\npermissions:\n contents: read\n\nenv:\n CARGO_TERM_COLOR: always\n\njobs:\n deps-freshness:\n timeout-minutes: 30\n runs-on: ubuntu-latest\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Validate readme casing\n run: scripts/ci/check-readme-case.sh\n\n - name: Cache vendored deps\n uses: actions/cache@v4\n with:\n path: |\n .vendor/flow-vendor\n lib/vendor\n lib/vendor-manifest\n key: ${{ runner.os }}-${{ runner.arch }}-vendor-${{ hashFiles('vendor.lock.toml') }}\n\n - name: Verify pinned vendor commit is published\n run: scripts/vendor/vendor-repo.sh verify-pinned-origin\n\n - name: Hydrate vendored deps\n run: scripts/vendor/vendor-repo.sh hydrate\n\n - name: Smoke vendor trims\n run: scripts/vendor/apply-trims.sh\n\n - name: Install Rust\n uses: dtolnay/rust-toolchain@stable\n\n - name: Check dependency freshness\n run: python3 scripts/deps_check.py\n\n build:\n timeout-minutes: 50\n strategy:\n fail-fast: false\n matrix:\n include:\n - target: x86_64-apple-darwin\n os: macos-latest\n - target: aarch64-apple-darwin\n os: macos-latest\n - target: x86_64-unknown-linux-gnu\n os: ubuntu-latest\n - target: aarch64-unknown-linux-gnu\n os: ubuntu-latest\n\n runs-on: ${{ matrix.os }}\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Validate readme casing\n run: scripts/ci/check-readme-case.sh\n\n - name: Cache vendored deps\n uses: actions/cache@v4\n with:\n path: |\n .vendor/flow-vendor\n lib/vendor\n lib/vendor-manifest\n key: ${{ runner.os }}-${{ runner.arch }}-vendor-${{ hashFiles('vendor.lock.toml') }}\n\n - name: Verify pinned vendor commit is published\n run: scripts/vendor/vendor-repo.sh verify-pinned-origin\n\n - name: Hydrate vendored deps\n run: scripts/vendor/vendor-repo.sh hydrate\n\n - name: Install Rust\n uses: dtolnay/rust-toolchain@stable\n with:\n targets: ${{ matrix.target }}\n\n - name: Cache Rust build\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: \". -> target\"\n cache-on-failure: true\n\n - name: Install cross-compilation tools (Linux ARM)\n if: matrix.target == 'aarch64-unknown-linux-gnu'\n run: |\n sudo apt-get update\n sudo apt-get install -y gcc-aarch64-linux-gnu\n\n - name: Build\n run: |\n if [ \"${{ matrix.target }}\" = \"aarch64-unknown-linux-gnu\" ]; then\n export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc\n fi\n cargo build --release --target ${{ matrix.target }} --bin f\n\n build-linux-host-simd:\n timeout-minutes: 50\n runs-on: [self-hosted, linux, x64, ci-1focus]\n env:\n RUSTFLAGS: -C target-cpu=native\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Validate readme casing\n run: scripts/ci/check-readme-case.sh\n\n - name: Cache vendored deps\n uses: actions/cache@v4\n with:\n path: |\n .vendor/flow-vendor\n lib/vendor\n lib/vendor-manifest\n key: ${{ runner.os }}-${{ runner.arch }}-vendor-${{ hashFiles('vendor.lock.toml') }}\n\n - name: Verify pinned vendor commit is published\n run: scripts/vendor/vendor-repo.sh verify-pinned-origin\n\n - name: Hydrate vendored deps\n run: scripts/vendor/vendor-repo.sh hydrate\n\n - name: Install Rust\n uses: dtolnay/rust-toolchain@stable\n with:\n targets: x86_64-unknown-linux-gnu\n\n - name: Cache Rust build\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: \". -> target\"\n cache-on-failure: true\n\n - name: Build (Linux host SIMD)\n run: cargo build --release --target x86_64-unknown-linux-gnu --features linux-host-simd-json --bin f\n" }, { "path": ".github/workflows/pr-fast.yml", "content": "name: PR Fast Check\n\non:\n pull_request:\n branches:\n - main\n paths-ignore:\n - \"docs/**\"\n - \"**/*.md\"\n\npermissions:\n contents: read\n\nconcurrency:\n group: pr-fast-${{ github.event.pull_request.number }}\n cancel-in-progress: true\n\nenv:\n CARGO_TERM_COLOR: always\n\njobs:\n check-linux:\n runs-on: ubuntu-latest\n timeout-minutes: 45\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Validate readme casing\n run: scripts/ci/check-readme-case.sh\n\n - name: Cache vendored deps\n uses: actions/cache@v4\n with:\n path: |\n .vendor/flow-vendor\n lib/vendor\n lib/vendor-manifest\n key: ${{ runner.os }}-${{ runner.arch }}-vendor-${{ hashFiles('vendor.lock.toml') }}\n\n - name: Verify pinned vendor commit is published\n run: scripts/vendor/vendor-repo.sh verify-pinned-origin\n\n - name: Hydrate vendored deps\n run: scripts/vendor/vendor-repo.sh hydrate\n\n - name: Smoke vendor trims\n run: scripts/vendor/apply-trims.sh\n\n - name: Install Rust\n uses: dtolnay/rust-toolchain@stable\n\n - name: Cache Rust build\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: \". -> target\"\n cache-on-failure: true\n\n - name: Check flowd\n run: cargo check -p flowd\n\n - name: Check flowd SIMD feature lane\n run: cargo check -p flowd --features linux-host-simd-json\n\n - name: Check seq bridge\n run: cargo check -p seq_everruns_bridge\n\n - name: Compile seq bridge tests\n run: cargo test -p seq_everruns_bridge --no-run\n\n - name: Build release CLI\n env:\n CARGO_INCREMENTAL: 0\n run: cargo build --release --bin f\n\n - name: Benchmark release CLI startup\n run: python3 scripts/bench-cli-startup.py --iterations 5 --warmup 1 --flow-bin ./target/release/f --json-out out/bench/cli-startup.json\n\n - name: Enforce startup latency thresholds\n run: python3 scripts/check_cli_startup_thresholds.py out/bench/cli-startup.json\n" }, { "path": ".github/workflows/release.yml", "content": "name: Release\n\non:\n push:\n tags:\n - \"v*\"\n\npermissions:\n contents: write\n\nenv:\n CARGO_TERM_COLOR: always\n\njobs:\n build:\n timeout-minutes: 40\n env:\n # Don't reference `secrets.*` in `if:` expressions; GitHub rejects that at workflow-parse time.\n MACOS_SIGN_P12_B64: ${{ secrets.MACOS_SIGN_P12_B64 }}\n MACOS_SIGN_P12_PASSWORD: ${{ secrets.MACOS_SIGN_P12_PASSWORD }}\n MACOS_SIGN_IDENTITY: ${{ secrets.MACOS_SIGN_IDENTITY }}\n strategy:\n matrix:\n include:\n - target: x86_64-apple-darwin\n os: macos-latest\n - target: aarch64-apple-darwin\n os: macos-latest\n - target: x86_64-unknown-linux-gnu\n os: ubuntu-latest\n - target: aarch64-unknown-linux-gnu\n os: ubuntu-latest\n\n runs-on: ${{ matrix.os }}\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Verify release tag matches Cargo version\n run: python3 scripts/check_release_tag_version.py \"${GITHUB_REF_NAME}\"\n\n - name: Validate readme casing\n run: scripts/ci/check-readme-case.sh\n\n - name: Cache vendored deps\n uses: actions/cache@v4\n with:\n path: |\n .vendor/flow-vendor\n lib/vendor\n lib/vendor-manifest\n key: ${{ runner.os }}-${{ runner.arch }}-vendor-${{ hashFiles('vendor.lock.toml') }}\n\n - name: Verify pinned vendor commit is published\n run: scripts/vendor/vendor-repo.sh verify-pinned-origin\n\n - name: Hydrate vendored deps\n run: scripts/vendor/vendor-repo.sh hydrate\n\n - name: Install Rust\n uses: dtolnay/rust-toolchain@stable\n with:\n targets: ${{ matrix.target }}\n\n - name: Cache Rust build\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: \". -> target\"\n cache-on-failure: true\n\n - name: Install cross-compilation tools (Linux ARM)\n if: matrix.target == 'aarch64-unknown-linux-gnu'\n run: |\n sudo apt-get update\n sudo apt-get install -y gcc-aarch64-linux-gnu\n\n - name: Build\n run: |\n if [ \"${{ matrix.target }}\" = \"aarch64-unknown-linux-gnu\" ]; then\n export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc\n fi\n cargo build --release --target ${{ matrix.target }} --bin f\n\n - name: Import code-signing certificates (macOS)\n if: runner.os == 'macOS' && env.MACOS_SIGN_P12_B64 != ''\n uses: apple-actions/import-codesign-certs@v3\n with:\n p12-file-base64: ${{ env.MACOS_SIGN_P12_B64 }}\n p12-password: ${{ env.MACOS_SIGN_P12_PASSWORD }}\n\n - name: Codesign (macOS)\n if: runner.os == 'macOS' && env.MACOS_SIGN_P12_B64 != '' && env.MACOS_SIGN_IDENTITY != ''\n run: |\n BIN=\"target/${{ matrix.target }}/release/f\"\n codesign --force --options runtime --timestamp --sign \"$MACOS_SIGN_IDENTITY\" \"$BIN\"\n codesign -vvv --strict \"$BIN\"\n\n - name: Package\n run: |\n mkdir -p dist\n cp target/${{ matrix.target }}/release/f dist/\n cd dist\n tar -czvf flow-${{ matrix.target }}.tar.gz f\n cd ..\n\n - name: Upload artifact\n uses: actions/upload-artifact@v4\n with:\n name: flow-${{ matrix.target }}\n path: dist/flow-${{ matrix.target }}.tar.gz\n\n build-linux-host-simd:\n timeout-minutes: 40\n runs-on: [self-hosted, linux, x64, ci-1focus]\n env:\n RUSTFLAGS: -C target-cpu=native\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Verify release tag matches Cargo version\n run: python3 scripts/check_release_tag_version.py \"${GITHUB_REF_NAME}\"\n\n - name: Validate readme casing\n run: scripts/ci/check-readme-case.sh\n\n - name: Cache vendored deps\n uses: actions/cache@v4\n with:\n path: |\n .vendor/flow-vendor\n lib/vendor\n lib/vendor-manifest\n key: ${{ runner.os }}-${{ runner.arch }}-vendor-${{ hashFiles('vendor.lock.toml') }}\n\n - name: Verify pinned vendor commit is published\n run: scripts/vendor/vendor-repo.sh verify-pinned-origin\n\n - name: Hydrate vendored deps\n run: scripts/vendor/vendor-repo.sh hydrate\n\n - name: Install Rust\n uses: dtolnay/rust-toolchain@stable\n with:\n targets: x86_64-unknown-linux-gnu\n\n - name: Cache Rust build\n uses: Swatinem/rust-cache@v2\n with:\n workspaces: \". -> target\"\n cache-on-failure: true\n\n - name: Build (Linux host SIMD)\n run: cargo build --release --target x86_64-unknown-linux-gnu --features linux-host-simd-json --bin f\n\n - name: Package\n run: |\n mkdir -p dist\n cp target/x86_64-unknown-linux-gnu/release/f dist/\n cd dist\n tar -czvf flow-x86_64-unknown-linux-gnu-linux-host-simd.tar.gz f\n cd ..\n\n - name: Upload artifact\n uses: actions/upload-artifact@v4\n with:\n name: flow-x86_64-unknown-linux-gnu-linux-host-simd\n path: dist/flow-x86_64-unknown-linux-gnu-linux-host-simd.tar.gz\n\n release:\n needs: [build, build-linux-host-simd]\n timeout-minutes: 20\n runs-on: ubuntu-latest\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Download all artifacts\n uses: actions/download-artifact@v4\n with:\n path: artifacts\n\n - name: Prepare release files\n run: |\n mkdir -p release\n find artifacts -name \"*.tar.gz\" -exec cp {} release/ \\;\n cd release\n sha256sum *.tar.gz > checksums.txt\n cat checksums.txt\n\n - name: Create Release\n uses: softprops/action-gh-release@v2\n with:\n files: release/*\n generate_release_notes: true\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".gitignore", "content": "# flow\n.cargo/\n.ai/internal/\n.ai/web/\n.ai/reviews/\n.ai/test/\n.ai/tmp/\n.ai/cache/\n.ai/artifacts/\n.ai/traces/\n.ai/generated/\n.ai/scratch/\n.ai/skills/\n# keep generated skills ignored by default, but track curated flow-default skills\n!.ai/skills/\n.ai/skills/*\n!.ai/skills/env/\n.ai/skills/env/*\n!.ai/skills/env/skill.md\n!.ai/skills/quality-bun-feature-delivery/\n.ai/skills/quality-bun-feature-delivery/*\n!.ai/skills/quality-bun-feature-delivery/skill.md\n!.ai/skills/pr-markdown-body-file/\n.ai/skills/pr-markdown-body-file/*\n!.ai/skills/pr-markdown-body-file/skill.md\n.ai/todos/*.bike\n.claude/\n.codex/\n.flox/\n.flow/\n.flow_diff_review.tmp\n.vendor/\nlib/vendor/\nlib/vendor-history/\n!lib/vendor-manifest/\n!lib/vendor-manifest/**\n\n# core\n.DS_Store\n.env\n.env*.local\n.env.production\noutput\nout/\ndist\ntarget\n.idea\n.cache\n.output\nnode_modules\npackage-lock.json\nyarn.lock\n.vercel\nenv-local/\n*.db\n.repo_ignore\ni.*\ni-*\ni/\ninternal/\npast.*\npast-*\npast/\n*.log\nprivate\n.blade\n.npm-cache\n/npm/**/vendor/\n/npm/flow-*/\n/test-data\ntesting/\ndesktop/.tauri-dev.json\n\n.ai/review-log.jsonl\n.rise/\n.ai/state.json\n.ai/tasks/**/.mooncakes/\n.ai/tasks/**/_build/\nbench/moon_ffi_boundary/_build/\nbench/moon_ffi_boundary/moon.pkg.json\n\n.beads/\n\n*.pyc\n\n__pycache__/\n\n# explain-commits output is local/generated by default\ndocs/commits/*\n!docs/commits/\n!docs/commits/readme.md\n!docs/commits/.gitkeep\n" }, { "path": ".goreleaser.yaml", "content": "project_name: flow\n\nbefore:\n hooks:\n - rustup default stable\n - cargo install --locked cargo-zigbuild\n\nbuilds:\n - id: f\n builder: rust\n binary: f\n tool: cargo\n command: zigbuild\n flags:\n - --release\n targets:\n - aarch64-apple-darwin\n - x86_64-apple-darwin\n - aarch64-unknown-linux-gnu\n - x86_64-unknown-linux-gnu\n - id: lin\n builder: rust\n binary: lin\n tool: cargo\n command: zigbuild\n flags:\n - --release\n targets:\n - aarch64-apple-darwin\n - x86_64-apple-darwin\n - aarch64-unknown-linux-gnu\n - x86_64-unknown-linux-gnu\n\narchives:\n - id: default\n format: tar.gz\n name_template: \"{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}\"\n builds:\n - f\n - lin\n files:\n - LICENSE*\n - README*\n\nchecksum:\n name_template: \"{{ .ProjectName }}_{{ .Version }}_checksums.txt\"\n\nchangelog:\n sort: asc\n" }, { "path": ".pi/extensions/test-extensibility.ts", "content": "/**\n * Test Extension - Demonstrates pi-mono extensibility\n *\n * Run with: pi (in ~/code/flow directory)\n * Then ask: \"use the counter tool\" or \"run a bash command\"\n */\n\nimport type { ExtensionAPI, ExtensionContext } from \"@mariozechner/pi-coding-agent\"\nimport { Type } from \"@sinclair/typebox\"\n\nexport default function (pi: ExtensionAPI) {\n console.log(\"[test-ext] Extension loaded!\")\n\n // ============================================\n // 1. CUSTOM TOOL\n // ============================================\n let count = 0\n\n pi.registerTool({\n name: \"counter\",\n label: \"Counter\",\n description: \"A simple counter tool. Actions: get, increment, decrement, reset\",\n parameters: Type.Object({\n action: Type.Union([\n Type.Literal(\"get\"),\n Type.Literal(\"increment\"),\n Type.Literal(\"decrement\"),\n Type.Literal(\"reset\"),\n ]),\n amount: Type.Optional(Type.Number({ description: \"Amount to add/subtract (default 1)\" })),\n }),\n\n async execute(_toolCallId, params, onUpdate, _ctx, _signal) {\n const amount = params.amount ?? 1\n\n // Stream progress\n onUpdate?.({ content: [{ type: \"text\", text: `Processing ${params.action}...` }] })\n\n switch (params.action) {\n case \"increment\":\n count += amount\n break\n case \"decrement\":\n count -= amount\n break\n case \"reset\":\n count = 0\n break\n }\n\n return {\n content: [{ type: \"text\", text: `Counter is now: ${count}` }],\n details: { count, action: params.action },\n }\n },\n })\n\n // ============================================\n // 2. EVENT HOOKS\n // ============================================\n\n // Log all tool calls\n pi.on(\"tool_call\", async (event, ctx) => {\n console.log(`[test-ext] Tool called: ${event.toolName}`)\n\n // Example: warn on dangerous bash commands (but don't block)\n if (event.toolName === \"bash\") {\n const cmd = event.input.command as string\n if (cmd.includes(\"rm \")) {\n ctx.ui.notify(\"Careful with rm commands!\", \"warn\")\n }\n }\n\n return undefined // Don't block\n })\n\n // Log turn completions\n pi.on(\"turn_end\", async (event, _ctx) => {\n console.log(`[test-ext] Turn ended. Tokens: ${event.usage?.inputTokens ?? 0} in, ${event.usage?.outputTokens ?? 0} out`)\n })\n\n // ============================================\n // 3. CUSTOM COMMAND\n // ============================================\n\n pi.registerCommand(\"count\", {\n description: \"Show the current counter value\",\n handler: async (_args, ctx) => {\n ctx.ui.notify(`Counter: ${count}`, \"info\")\n },\n })\n\n // ============================================\n // 4. SESSION EVENTS\n // ============================================\n\n pi.on(\"session_start\", async (_event, _ctx) => {\n console.log(\"[test-ext] Session started\")\n count = 0 // Reset on new session\n })\n}\n" }, { "path": "AGENTS.md.bak", "content": "" }, { "path": "Cargo.toml", "content": "[package]\nname = \"flowd\"\nversion = \"0.1.3\"\nedition = \"2024\"\nrepository = \"https://github.com/nikivdev/flow\"\nautobins = false\n\n[workspace]\nmembers = [\n \".\",\n \"crates/ai_taskd_client\",\n \"crates/flow_commit_scan\",\n \"crates/opentui-lite\",\n \"crates/seq_client\",\n \"crates/seq_everruns_bridge\",\n]\ndefault-members = [\".\"]\nresolver = \"2\"\n\n[[bin]]\nname = \"f\"\npath = \"src/main.rs\"\n\n[[bin]]\nname = \"flow\"\npath = \"src/main.rs\"\n\n[[bin]]\nname = \"lin\"\npath = \"src/bin/lin.rs\"\n\n[dependencies]\naxum = { version = \"0.8\", default-features = false, features = [\"http1\", \"json\", \"query\", \"tokio\"] }\ntower-http = { version = \"0.6\", features = [\"cors\"] }\nanyhow = \"1\"\nclap = { version = \"4\", features = [\"derive\"] }\nfutures = \"0.3\"\nignore = \"0.4\"\nserde = { version = \"1\", features = [\"derive\"] }\nserde_json = \"1\"\nrmp-serde = \"1\"\ntokio = { version = \"1\", features = [\"full\"] }\ntokio-stream = { version = \"0.1\", features = [\"sync\"] }\ntracing = \"0.1\"\ntracing-subscriber = { version = \"0.3\", features = [\"env-filter\"] }\ntoml = \"1\"\nratatui = { version = \"0.30\", default-features = false, features = [\"crossterm\"] }\ncrossterm = \"0.29\"\nreqwest = { version = \"0.13\", default-features = false, features = [\"json\", \"blocking\", \"query\", \"rustls\"] }\nwhich = \"8\"\nrusqlite = { version = \"0.39\", features = [\"bundled\"] }\nnotify = \"8\"\nnotify-debouncer-mini = \"0.7\"\nshellexpand = \"3\"\nshell-words = \"1\"\nbase64 = \"0.22\"\nbs58 = \"0.5.1\"\nsha2 = \"0.10\"\nhex = \"0.4\"\nurl = \"2\"\nstrip-ansi-escapes = \"0.2\"\nportable-pty = \"0.9\"\nregex = \"1.12.2\"\nchrono = \"0.4.42\"\ndirs = \"6.0.0\"\nuuid = { version = \"1\", features = [\"v4\"] }\ntempfile = \"3\"\nctrlc = \"3.4\"\nrpassword = \"7\"\natty = \"0.2\"\nhmac = \"0.12\"\nsha1 = \"0.10\"\ndata-encoding = \"2.6\"\nopentui-lite = { path = \"crates/opentui-lite\" }\nblake3 = \"1\"\ncrypto_secretbox = \"0.1\"\nrand = \"0.10\"\nx25519-dalek = { version = \"2\", features = [\"static_secrets\"] }\nsimd-json = { version = \"0.17\", optional = true }\nseq_everruns_bridge = { path = \"crates/seq_everruns_bridge\" }\nflow_commit_scan = { path = \"crates/flow_commit_scan\" }\n\n[target.'cfg(unix)'.dependencies]\nlibc = \"0.2\"\n\n[dev-dependencies]\nmockito = \"1.7\"\ntempfile = \"3\"\n\n[features]\ndefault = []\nlinux-host-simd-json = [\"dep:simd-json\"]\n\n[profile.release]\nopt-level = 3\nlto = \"fat\"\ncodegen-units = 1\npanic = \"abort\"\nstrip = \"symbols\"\nincremental = false\ndebug = 0\n\n[patch.crates-io]\naxum = { path = \"lib/vendor/axum\" }\nreqwest = { path = \"lib/vendor/reqwest\" }\ntower-http = { path = \"lib/vendor/tower-http\" }\nratatui = { path = \"lib/vendor/ratatui\" }\nurl = { path = \"lib/vendor/url\" }\ncrypto_secretbox = { path = \"lib/vendor/crypto_secretbox\" }\nportable-pty = { path = \"lib/vendor/portable-pty\" }\ntokio-stream = { path = \"lib/vendor/tokio-stream\" }\ntracing-subscriber = { path = \"lib/vendor/tracing-subscriber\" }\nfutures = { path = \"lib/vendor/futures\" }\nsha1 = { path = \"lib/vendor/sha1\" }\nsha2 = { path = \"lib/vendor/sha2\" }\ntokio = { path = \"lib/vendor/tokio\" }\ncrossterm = { path = \"lib/vendor/crossterm\" }\nhmac = { path = \"lib/vendor/hmac\" }\ntoml = { path = \"lib/vendor/toml\" }\nclap = { path = \"lib/vendor/clap\" }\nnotify-debouncer-mini = { path = \"lib/vendor/notify-debouncer-mini\" }\nignore = { path = \"lib/vendor/ignore\" }\nx25519-dalek = { path = \"lib/vendor/x25519-dalek\" }\nrusqlite = { path = \"lib/vendor/rusqlite\" }\nrmp-serde = { path = \"lib/vendor/rmp-serde\" }\nctrlc = { path = \"lib/vendor/ctrlc\" }\nnotify = { path = \"lib/vendor/notify\" }\nregex = { path = \"lib/vendor/regex\" }\nserde = { path = \"lib/vendor/serde\" }\n" }, { "path": "Support/flow/auth.toml", "content": "" }, { "path": "agents.md", "content": "# Assistant Rules (flow)\n\nOnly load skills when the request clearly needs them.\n\n## Skills (on-demand)\n- flow-native: Use for Flow CLI native workflows (env setup, secrets, deploys, logs, deps), for repos with `flow.toml`, or Cloudflare Workers. Avoid direct pnpm/wrangler unless asked.\n- flow-interactive: Use when commands are interactive or could block on stdin (e.g., `f setup`).\n- flow-dev-traces: Use when debugging Flow proxy behavior, tracing requests, or when the user asks about proxyx, trace-summary.json, or flow trace commands.\n- flow-usage: Use when running or troubleshooting Flow command behavior.\n- internal-ai-inference: Use only when asked to run inference or integrate with internal AI tooling.\n\nDefault: Avoid loading skills for routine edits, reviews, or simple questions.\n" }, { "path": "bench/ffi_host_boundary/Cargo.toml", "content": "[package]\nname = \"flow_ffi_host_boundary\"\nversion = \"0.1.0\"\nedition = \"2024\"\n\n[lib]\ncrate-type = [\"staticlib\", \"rlib\"]\n\n[[bin]]\nname = \"rust_boundary_bench\"\npath = \"src/bin/rust_boundary_bench.rs\"\n\n[dependencies]\nlibc = \"0.2\"\n\n[profile.release]\nlto = \"fat\"\ncodegen-units = 1\npanic = \"abort\"\nstrip = true\n" }, { "path": "bench/ffi_host_boundary/src/bin/rust_boundary_bench.rs", "content": "use std::hint::black_box;\n\nuse flow_ffi_host_boundary::{flow_host_add_u64, flow_host_noop, monotonic_now_ns, rust_fn_add, rust_inline_add};\n\n#[derive(Debug)]\nstruct BenchResult {\n label: &'static str,\n ns_total: u64,\n ns_per_op: f64,\n checksum: u64,\n}\n\nfn finish(label: &'static str, iterations: u64, start: u64, acc: u64) -> BenchResult {\n let end = monotonic_now_ns();\n let total = end.saturating_sub(start);\n BenchResult {\n label,\n ns_total: total,\n ns_per_op: total as f64 / iterations as f64,\n checksum: acc,\n }\n}\n\nfn bench_inline_add(iterations: u64) -> BenchResult {\n let mut acc = black_box(0_u64);\n let start = monotonic_now_ns();\n for i in 0..iterations {\n acc = black_box(rust_inline_add(black_box(acc), black_box(i)));\n }\n finish(\"rust_inline_add\", iterations, start, acc)\n}\n\nfn bench_fn_add(iterations: u64) -> BenchResult {\n let mut acc = black_box(0_u64);\n let start = monotonic_now_ns();\n for i in 0..iterations {\n acc = black_box(rust_fn_add(black_box(acc), black_box(i)));\n }\n finish(\"rust_fn_add\", iterations, start, acc)\n}\n\nfn bench_extern_add(iterations: u64) -> BenchResult {\n let mut acc = black_box(0_u64);\n let start = monotonic_now_ns();\n for i in 0..iterations {\n acc = black_box(flow_host_add_u64(black_box(acc), black_box(i)));\n }\n finish(\"rust_extern_add\", iterations, start, acc)\n}\n\nfn bench_noop(iterations: u64) -> BenchResult {\n let mut acc = black_box(0_u64);\n let start = monotonic_now_ns();\n for _ in 0..iterations {\n acc = black_box(flow_host_noop(black_box(acc)));\n }\n finish(\"rust_extern_noop\", iterations, start, acc)\n}\n\nfn parse_iters() -> u64 {\n let mut args = std::env::args().skip(1);\n while let Some(arg) = args.next() {\n if arg == \"--iters\" {\n if let Some(value) = args.next() {\n if let Ok(parsed) = value.parse::<u64>() {\n if parsed > 0 {\n return parsed;\n }\n }\n }\n }\n }\n 10_000_000\n}\n\nfn print_result(result: &BenchResult) {\n println!(\n \"{} ns_total={} ns_per_op={:.4} checksum={}\",\n result.label, result.ns_total, result.ns_per_op, result.checksum\n );\n}\n\nfn main() {\n let iterations = parse_iters();\n println!(\"rust_boundary_bench iterations={}\", iterations);\n\n let inline = bench_inline_add(iterations);\n let fn_call = bench_fn_add(iterations);\n let extern_call = bench_extern_add(iterations);\n let noop = bench_noop(iterations);\n\n print_result(&inline);\n print_result(&fn_call);\n print_result(&extern_call);\n print_result(&noop);\n}\n" }, { "path": "bench/ffi_host_boundary/src/lib.rs", "content": "use std::hint::black_box;\n\n#[unsafe(no_mangle)]\n#[inline(never)]\npub extern \"C\" fn flow_host_now_ns() -> u64 {\n monotonic_now_ns()\n}\n\n#[unsafe(no_mangle)]\n#[inline(never)]\npub extern \"C\" fn flow_host_noop(x: u64) -> u64 {\n x.wrapping_add(1)\n}\n\n#[unsafe(no_mangle)]\n#[inline(never)]\npub extern \"C\" fn flow_host_add_u64(a: u64, b: u64) -> u64 {\n a.wrapping_add(b)\n}\n\n#[unsafe(no_mangle)]\npub extern \"C\" fn flow_host_bench_iterations() -> u64 {\n std::env::var(\"FLOW_FFI_ITERS\")\n .ok()\n .and_then(|v| v.parse::<u64>().ok())\n .filter(|v| *v > 0)\n .unwrap_or(10_000_000)\n}\n\n#[inline(always)]\npub fn rust_inline_add(a: u64, b: u64) -> u64 {\n a.wrapping_add(b)\n}\n\n#[inline(never)]\npub fn rust_fn_add(a: u64, b: u64) -> u64 {\n a.wrapping_add(b)\n}\n\npub fn monotonic_now_ns() -> u64 {\n unsafe {\n let mut ts: libc::timespec = std::mem::zeroed();\n if libc::clock_gettime(libc::CLOCK_MONOTONIC, &mut ts) != 0 {\n return 0;\n }\n (ts.tv_sec as u64)\n .saturating_mul(1_000_000_000)\n .saturating_add(ts.tv_nsec as u64)\n }\n}\n" }, { "path": "bench/moon_ffi_boundary/main.mbt", "content": "extern \"C\" fn flow_host_now_ns() -> UInt64 = \"flow_host_now_ns\"\nextern \"C\" fn flow_host_noop(x : UInt64) -> UInt64 = \"flow_host_noop\"\nextern \"C\" fn flow_host_add_u64(a : UInt64, b : UInt64) -> UInt64 = \"flow_host_add_u64\"\nextern \"C\" fn flow_host_bench_iterations() -> UInt64 = \"flow_host_bench_iterations\"\n\nfn bench_ffi_add(iterations : Int) -> (UInt64, UInt64) {\n let mut acc : UInt64 = 0UL\n let start = flow_host_now_ns()\n for i = 0; i < iterations; i = i + 1 {\n acc = flow_host_add_u64(acc, i.to_uint64())\n }\n let elapsed = flow_host_now_ns() - start\n (elapsed, acc)\n}\n\nfn bench_ffi_noop(iterations : Int) -> (UInt64, UInt64) {\n let mut acc : UInt64 = 0UL\n let start = flow_host_now_ns()\n for _i = 0; _i < iterations; _i = _i + 1 {\n acc = flow_host_noop(acc)\n }\n let elapsed = flow_host_now_ns() - start\n (elapsed, acc)\n}\n\nfn bench_moon_add(iterations : Int) -> (UInt64, UInt64) {\n let mut acc : UInt64 = 0UL\n let start = flow_host_now_ns()\n for i = 0; i < iterations; i = i + 1 {\n acc = acc + i.to_uint64()\n }\n let elapsed = flow_host_now_ns() - start\n (elapsed, acc)\n}\n\nfn parse_iterations() -> Int {\n flow_host_bench_iterations().to_int()\n}\n\nfn print_result(\n label : String,\n total_ns : UInt64,\n checksum : UInt64,\n iterations : Int,\n) -> Unit {\n let per_op = total_ns / iterations.to_uint64()\n println(\n label +\n \" ns_total=\" + total_ns.to_string() +\n \" ns_per_op=\" + per_op.to_string() +\n \" checksum=\" + checksum.to_string(),\n )\n}\n\nfn main {\n let iterations = parse_iterations()\n println(\"moon_ffi_boundary iterations=\" + iterations.to_string())\n\n let (moon_add_ns, moon_add_sum) = bench_moon_add(iterations)\n let (ffi_add_ns, ffi_add_sum) = bench_ffi_add(iterations)\n let (ffi_noop_ns, ffi_noop_sum) = bench_ffi_noop(iterations)\n\n print_result(\"moon_add\", moon_add_ns, moon_add_sum, iterations)\n print_result(\"moon_ffi_add\", ffi_add_ns, ffi_add_sum, iterations)\n print_result(\"moon_ffi_noop\", ffi_noop_ns, ffi_noop_sum, iterations)\n}\n" }, { "path": "bench/moon_ffi_boundary/moon.mod.json", "content": "{\n \"name\": \"nikiv/moon_ffi_boundary\",\n \"version\": \"0.1.0\"\n}\n" }, { "path": "bench/moon_ffi_boundary/moon.pkg.template.json", "content": "{\n \"is-main\": true,\n \"support-targets\": [\"native\"],\n \"link\": {\n \"native\": {\n \"cc-flags\": \"__CC_FLAGS__\",\n \"cc-link-flags\": \"__CC_LINK_FLAGS__\"\n }\n }\n}\n" }, { "path": "build.rs", "content": "use std::env;\nuse std::fs;\nuse std::path::Path;\nuse std::time::{SystemTime, UNIX_EPOCH};\n\nfn main() {\n // Embed build timestamp as seconds since Unix epoch\n let timestamp = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .unwrap()\n .as_secs();\n\n // Write timestamp to a file in OUT_DIR so cargo detects the change\n let out_dir = env::var(\"OUT_DIR\").unwrap();\n let dest_path = Path::new(&out_dir).join(\"build_timestamp.txt\");\n fs::write(&dest_path, timestamp.to_string()).unwrap();\n\n println!(\"cargo:rustc-env=BUILD_TIMESTAMP={}\", timestamp);\n\n // Always rerun build script (no rerun-if-changed means always run)\n}\n" }, { "path": "crates/ai_taskd_client/Cargo.toml", "content": "[package]\nname = \"ai-taskd-client\"\nversion = \"0.1.0\"\nedition = \"2024\"\n\n[dependencies]\nserde = { version = \"1\", features = [\"derive\"] }\nserde_json = \"1\"\nrmp-serde = \"1\"\nshell-words = \"1\"\ndirs = \"6.0.0\"\n" }, { "path": "crates/ai_taskd_client/src/main.rs", "content": "include!(\"../../../src/bin/ai_taskd_client.rs\");\n" }, { "path": "crates/flow_commit_scan/Cargo.toml", "content": "[package]\nname = \"flow_commit_scan\"\nversion = \"0.1.0\"\nedition = \"2024\"\n\n[dependencies]\nregex = \"1.12.2\"\n" }, { "path": "crates/flow_commit_scan/src/lib.rs", "content": "use std::path::Path;\nuse std::process::Command;\nuse std::sync::OnceLock;\n\nuse regex::Regex;\n\npub type SecretFinding = (String, usize, String, String);\n\n/// Common secret patterns to detect in diff content.\n/// Each tuple is (pattern_name, regex_pattern).\nconst SECRET_PATTERNS: &[(&str, &str)] = &[\n // API Keys with known prefixes\n (\"AWS Access Key\", r\"AKIA[0-9A-Z]{16}\"),\n (\n \"AWS Secret Key\",\n r#\"(?i)aws.{0,20}secret.{0,20}['\"][0-9a-zA-Z/+]{40}['\"]\"#,\n ),\n (\"GitHub Token\", r\"ghp_[0-9a-zA-Z]{36}\"),\n (\"GitHub OAuth\", r\"gho_[0-9a-zA-Z]{36}\"),\n (\"GitHub App Token\", r\"ghu_[0-9a-zA-Z]{36}\"),\n (\"GitHub Refresh Token\", r\"ghr_[0-9a-zA-Z]{36}\"),\n (\"GitLab Token\", r\"glpat-[0-9a-zA-Z\\\\-_]{20,}\"),\n (\"Slack Token\", r\"xox[baprs]-[0-9a-zA-Z]{10,48}\"),\n (\n \"Slack Webhook\",\n r\"https://hooks\\.slack\\.com/services/T[0-9A-Z]{8,}/B[0-9A-Z]{8,}/[0-9a-zA-Z]{24}\",\n ),\n (\n \"Discord Webhook\",\n r\"https://discord(?:app)?\\.com/api/webhooks/[0-9]{17,}/[0-9a-zA-Z_-]{60,}\",\n ),\n (\"Stripe Key\", r\"sk_live_[0-9a-zA-Z]{24,}\"),\n (\"Stripe Restricted\", r\"rk_live_[0-9a-zA-Z]{24,}\"),\n // OpenAI keys - multiple formats (legacy, project, service account)\n (\"OpenAI Key (Legacy)\", r\"sk-[a-zA-Z0-9]{32,}\"),\n (\"OpenAI Key (Project)\", r\"sk-proj-[a-zA-Z0-9\\\\-_]{20,}\"),\n (\"OpenAI Key (Service)\", r\"sk-svcacct-[a-zA-Z0-9\\\\-_]{20,}\"),\n (\"Anthropic Key\", r\"sk-ant-[0-9a-zA-Z\\\\-_]{90,}\"),\n (\"Google API Key\", r\"AIza[0-9A-Za-z\\\\-_]{35}\"),\n (\"Groq API Key\", r\"gsk_[0-9a-zA-Z]{50,}\"),\n (\n \"Mistral API Key\",\n r#\"(?i)mistral.{0,10}(api[_-]?key|key).{0,5}[=:].{0,5}[\"'][0-9a-zA-Z]{32,}[\"']\"#,\n ),\n (\n \"Cohere API Key\",\n r#\"(?i)cohere.{0,10}(api[_-]?key|key).{0,5}[=:].{0,5}[\"'][0-9a-zA-Z]{40,}[\"']\"#,\n ),\n (\n \"Heroku API Key\",\n r\"(?i)heroku.{0,20}[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\",\n ),\n (\"NPM Token\", r\"npm_[0-9a-zA-Z]{36}\"),\n (\"PyPI Token\", r\"pypi-[0-9a-zA-Z_-]{50,}\"),\n (\"Telegram Bot Token\", r\"[0-9]{8,10}:[0-9A-Za-z_-]{35}\"),\n (\"Twilio Key\", r\"SK[0-9a-fA-F]{32}\"),\n (\"SendGrid Key\", r\"SG\\.[0-9a-zA-Z_-]{22}\\.[0-9a-zA-Z_-]{43}\"),\n (\"Mailgun Key\", r\"key-[0-9a-zA-Z]{32}\"),\n (\n \"Private Key\",\n r\"-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----\",\n ),\n (\n \"Supabase Key\",\n r\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\\.[0-9a-zA-Z_-]{50,}\",\n ),\n (\n \"Firebase Key\",\n r#\"(?i)firebase.{0,20}[\"'][A-Za-z0-9_-]{30,}[\"']\"#,\n ),\n // Generic patterns (higher false positive risk, but catch common mistakes)\n (\n \"Generic API Key Assignment\",\n r#\"(?i)(api[_-]?key|apikey)\\s*[:=]\\s*['\"][0-9a-zA-Z\\-_]{20,}['\"]\"#,\n ),\n (\n \"Generic Secret Assignment\",\n r#\"(?i)(secret|password|passwd|pwd)\\s*[:=]\\s*['\"][^'\"]{8,}['\"]\"#,\n ),\n (\"Bearer Token\", r\"(?i)bearer\\s+[0-9a-zA-Z\\-_.]{20,}\"),\n (\"Basic Auth\", r\"(?i)basic\\s+[A-Za-z0-9+/=]{20,}\"),\n // High-entropy strings that look like secrets (env var assignments)\n (\n \"Env Var Secret\",\n r#\"(?i)(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|AUTH)[_A-Z]*\\s*=\\s*['\"]?[0-9a-zA-Z\\-_/+=]{32,}['\"]?\"#,\n ),\n];\n\nfn compiled_secret_patterns() -> &'static Vec<(&'static str, Regex)> {\n static COMPILED: OnceLock<Vec<(&'static str, Regex)>> = OnceLock::new();\n COMPILED.get_or_init(|| {\n SECRET_PATTERNS\n .iter()\n .filter_map(|(name, pattern)| Regex::new(pattern).ok().map(|re| (*name, re)))\n .collect()\n })\n}\n\nconst SECRET_SCAN_IGNORE_MARKERS: &[&str] = &[\n \"flow:secret:ignore\",\n \"flow-secret-ignore\",\n \"flow:secret-scan:ignore\",\n \"gitleaks:allow\",\n];\n\nfn should_ignore_secret_scan_line(content: &str) -> bool {\n let lower = content.to_lowercase();\n SECRET_SCAN_IGNORE_MARKERS\n .iter()\n .any(|m| lower.contains(&m.to_lowercase()))\n}\n\nfn extract_first_quoted_value(s: &str) -> Option<&str> {\n let (qpos, qch) = s.char_indices().find(|(_, c)| *c == '\"' || *c == '\\'')?;\n let end = s.rfind(qch)?;\n if end <= qpos {\n return None;\n }\n Some(&s[qpos + 1..end])\n}\n\nfn looks_like_identifier_reference(value: &str) -> bool {\n let v = value.trim();\n !v.is_empty()\n && v.len() >= 8\n && v.contains('_')\n && v.chars()\n .all(|c| c.is_ascii_uppercase() || c.is_ascii_digit() || c == '_' || c == '.')\n}\n\nfn looks_like_secret_lookup(value: &str) -> bool {\n let v = value.trim();\n\n if v.starts_with(\"${\") && v.ends_with('}') {\n let inner = &v[2..v.len() - 1];\n return !inner.contains(\":-\")\n && !inner.contains(\"-\")\n && inner\n .chars()\n .all(|c| c.is_ascii_uppercase() || c.is_ascii_digit() || c == '_');\n }\n\n if !(v.starts_with(\"$(\") && v.ends_with(')')) {\n return false;\n }\n let inner = v[2..v.len() - 1].trim();\n if inner.contains('\"') || inner.contains('\\'') || inner.contains('`') {\n return false;\n }\n let inner_lc = inner.to_lowercase();\n inner_lc.starts_with(\"get_env \")\n || inner_lc.starts_with(\"getenv \")\n || inner_lc.starts_with(\"printenv \")\n || inner_lc.starts_with(\"op read \")\n || inner_lc.starts_with(\"pass show \")\n || inner_lc.starts_with(\"security find-generic-password\")\n || inner_lc.starts_with(\"aws ssm get-parameter\")\n || inner_lc.starts_with(\"vault kv get\")\n || inner_lc.starts_with(\"bw get\")\n || inner_lc.starts_with(\"gcloud secrets versions access\")\n}\n\nfn generic_secret_assignment_is_false_positive(content: &str, matched: &str) -> bool {\n if let Some((_, rhs)) = matched.split_once('=') {\n let rhs = rhs.trim_start();\n if rhs.starts_with(\"\\\"$(\") || rhs.starts_with(\"'$(\") || rhs.starts_with(\"`\") {\n return true;\n }\n if rhs.starts_with(\"\\\"$\") || rhs.starts_with(\"'$\") {\n return true;\n }\n } else if let Some((_, rhs)) = matched.split_once(':') {\n let rhs = rhs.trim_start();\n if rhs.starts_with(\"\\\"$(\") || rhs.starts_with(\"'$(\") || rhs.starts_with(\"`\") {\n return true;\n }\n if rhs.starts_with(\"\\\"$\") || rhs.starts_with(\"'$\") {\n return true;\n }\n }\n\n if let Some(val) = extract_first_quoted_value(matched) {\n let v = val.trim();\n if looks_like_identifier_reference(v) {\n return true;\n }\n if looks_like_secret_lookup(v) {\n return true;\n }\n }\n\n let lc = content.to_lowercase();\n lc.contains(\"$(get_env \")\n}\n\n/// Scan staged diff content for hardcoded secrets.\n/// Returns list of (file, line_num, pattern_name, matched_text) for detected secrets.\npub fn scan_diff_for_secrets(repo_root: &Path) -> Vec<SecretFinding> {\n let output = Command::new(\"git\")\n .args([\"diff\", \"--cached\", \"-U0\"])\n .current_dir(repo_root)\n .output();\n\n let Ok(output) = output else {\n return Vec::new();\n };\n\n if !output.status.success() {\n return Vec::new();\n }\n\n let diff = String::from_utf8_lossy(&output.stdout);\n let mut findings: Vec<SecretFinding> = Vec::new();\n let mut current_file = String::new();\n let mut current_line: usize = 0;\n let mut ignore_next_added_line = false;\n\n let patterns = compiled_secret_patterns();\n\n for line in diff.lines() {\n if line.starts_with(\"+++ b/\") {\n current_file = line.strip_prefix(\"+++ b/\").unwrap_or(\"\").to_string();\n ignore_next_added_line = false;\n continue;\n }\n\n if line.starts_with(\"@@\") {\n if let Some(plus_pos) = line.find('+') {\n let after_plus = &line[plus_pos + 1..];\n let num_str: String = after_plus\n .chars()\n .take_while(|c| c.is_ascii_digit())\n .collect();\n current_line = num_str.parse().unwrap_or(0);\n }\n ignore_next_added_line = false;\n continue;\n }\n\n if line.starts_with('+') && !line.starts_with(\"+++\") {\n let content = &line[1..];\n\n if ignore_next_added_line {\n ignore_next_added_line = false;\n current_line += 1;\n continue;\n }\n let trimmed = content.trim_start();\n if trimmed.starts_with('#') && should_ignore_secret_scan_line(trimmed) {\n ignore_next_added_line = true;\n current_line += 1;\n continue;\n }\n if should_ignore_secret_scan_line(content) {\n current_line += 1;\n continue;\n }\n if content.to_lowercase().contains(\"flow:secret:ignore-next\") {\n ignore_next_added_line = true;\n current_line += 1;\n continue;\n }\n\n for (name, re) in patterns {\n if let Some(m) = re.find(content) {\n let matched = m.as_str();\n let matched_lower = matched.to_lowercase();\n\n if matched_lower.contains(\"xxx\")\n || matched_lower.contains(\"your\")\n || matched_lower.contains(\"example\")\n || matched_lower.contains(\"placeholder\")\n || matched_lower.contains(\"replace\")\n || matched_lower.contains(\"insert\")\n || matched_lower.contains(\"todo\")\n || matched_lower.contains(\"fixme\")\n || matched == \"sk-...\"\n || matched == \"sk-xxxx\"\n || matched\n .chars()\n .all(|c| c == 'x' || c == 'X' || c == '.' || c == '-' || c == '_')\n {\n continue;\n }\n\n if *name == \"Generic Secret Assignment\"\n && generic_secret_assignment_is_false_positive(content, matched)\n {\n continue;\n }\n\n let redacted = if matched.len() > 12 {\n format!(\"{}...{}\", &matched[..6], &matched[matched.len() - 4..])\n } else {\n matched.to_string()\n };\n findings.push((\n current_file.clone(),\n current_line,\n name.to_string(),\n redacted,\n ));\n break;\n }\n }\n current_line += 1;\n } else if !line.starts_with('-') && !line.starts_with('\\\\') {\n current_line += 1;\n ignore_next_added_line = false;\n }\n }\n\n findings\n}\n" }, { "path": "crates/opentui-lite/Cargo.toml", "content": "[package]\nname = \"opentui-lite\"\nversion = \"0.1.0\"\nedition = \"2024\"\n\n[lib]\npath = \"src/lib.rs\"\n\n[dependencies]\nlibc = { version = \"0.2\", default-features = false }\n" }, { "path": "crates/opentui-lite/src/lib.rs", "content": "use std::ffi::{CStr, CString};\nuse std::fmt;\nuse std::path::{Path, PathBuf};\nuse std::sync::Arc;\n\n#[derive(Debug)]\npub struct Error {\n message: String,\n}\n\nimpl Error {\n fn new(message: impl Into<String>) -> Self {\n Self {\n message: message.into(),\n }\n }\n}\n\nimpl fmt::Display for Error {\n fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {\n write!(f, \"{}\", self.message)\n }\n}\n\nimpl std::error::Error for Error {}\n\npub type Result<T> = std::result::Result<T, Error>;\n\n#[repr(C)]\n#[derive(Clone, Copy, Debug, Default)]\npub struct Color {\n pub r: f32,\n pub g: f32,\n pub b: f32,\n pub a: f32,\n}\n\nimpl Color {\n pub const fn rgba(r: f32, g: f32, b: f32, a: f32) -> Self {\n Self { r, g, b, a }\n }\n\n pub const fn rgb(r: f32, g: f32, b: f32) -> Self {\n Self { r, g, b, a: 1.0 }\n }\n}\n\npub const ATTR_NONE: u32 = 0;\npub const ATTR_BOLD: u32 = 1 << 0;\npub const ATTR_DIM: u32 = 1 << 1;\npub const ATTR_ITALIC: u32 = 1 << 2;\npub const ATTR_UNDERLINE: u32 = 1 << 3;\npub const ATTR_BLINK: u32 = 1 << 4;\npub const ATTR_INVERSE: u32 = 1 << 5;\npub const ATTR_HIDDEN: u32 = 1 << 6;\npub const ATTR_STRIKETHROUGH: u32 = 1 << 7;\n\npub const BORDER_SIMPLE: [u32; 11] = [\n '+' as u32, '+' as u32, '+' as u32, '+' as u32, '-' as u32, '|' as u32, '+' as u32, '+' as u32,\n '+' as u32, '+' as u32, '+' as u32,\n];\n\ntype RendererPtr = *mut std::ffi::c_void;\ntype BufferPtr = *mut std::ffi::c_void;\n\ntype FnCreateRenderer = unsafe extern \"C\" fn(u32, u32, bool) -> RendererPtr;\ntype FnDestroyRenderer = unsafe extern \"C\" fn(RendererPtr);\ntype FnSetupTerminal = unsafe extern \"C\" fn(RendererPtr, bool);\ntype FnSuspendRenderer = unsafe extern \"C\" fn(RendererPtr);\ntype FnRender = unsafe extern \"C\" fn(RendererPtr, bool);\ntype FnClearTerminal = unsafe extern \"C\" fn(RendererPtr);\ntype FnResizeRenderer = unsafe extern \"C\" fn(RendererPtr, u32, u32);\ntype FnGetNextBuffer = unsafe extern \"C\" fn(RendererPtr) -> BufferPtr;\ntype FnGetCurrentBuffer = unsafe extern \"C\" fn(RendererPtr) -> BufferPtr;\ntype FnBufferClear = unsafe extern \"C\" fn(BufferPtr, *const f32);\ntype FnBufferDrawText =\n unsafe extern \"C\" fn(BufferPtr, *const u8, usize, u32, u32, *const f32, *const f32, u32);\ntype FnBufferFillRect = unsafe extern \"C\" fn(BufferPtr, u32, u32, u32, u32, *const f32);\ntype FnBufferDrawBox = unsafe extern \"C\" fn(\n BufferPtr,\n i32,\n i32,\n u32,\n u32,\n *const u32,\n u32,\n *const f32,\n *const f32,\n *const u8,\n u32,\n);\n\n#[derive(Clone)]\npub struct OpenTui {\n inner: Arc<Inner>,\n}\n\nstruct Inner {\n lib: *mut std::ffi::c_void,\n fns: Fns,\n path: String,\n}\n\nstruct Fns {\n create_renderer: FnCreateRenderer,\n destroy_renderer: FnDestroyRenderer,\n setup_terminal: FnSetupTerminal,\n suspend_renderer: FnSuspendRenderer,\n render: FnRender,\n clear_terminal: FnClearTerminal,\n resize_renderer: FnResizeRenderer,\n get_next_buffer: FnGetNextBuffer,\n get_current_buffer: FnGetCurrentBuffer,\n buffer_clear: FnBufferClear,\n buffer_draw_text: FnBufferDrawText,\n buffer_fill_rect: FnBufferFillRect,\n buffer_draw_box: FnBufferDrawBox,\n}\n\nimpl Drop for Inner {\n fn drop(&mut self) {\n unsafe {\n if !self.lib.is_null() {\n let _ = dlclose(self.lib);\n }\n }\n }\n}\n\nimpl OpenTui {\n pub fn load() -> Result<Self> {\n let (lib, path) = load_library()?;\n let fns = unsafe {\n Fns {\n create_renderer: load_symbol(lib, \"createRenderer\")?,\n destroy_renderer: load_symbol(lib, \"destroyRenderer\")?,\n setup_terminal: load_symbol(lib, \"setupTerminal\")?,\n suspend_renderer: load_symbol(lib, \"suspendRenderer\")?,\n render: load_symbol(lib, \"render\")?,\n clear_terminal: load_symbol(lib, \"clearTerminal\")?,\n resize_renderer: load_symbol(lib, \"resizeRenderer\")?,\n get_next_buffer: load_symbol(lib, \"getNextBuffer\")?,\n get_current_buffer: load_symbol(lib, \"getCurrentBuffer\")?,\n buffer_clear: load_symbol(lib, \"bufferClear\")?,\n buffer_draw_text: load_symbol(lib, \"bufferDrawText\")?,\n buffer_fill_rect: load_symbol(lib, \"bufferFillRect\")?,\n buffer_draw_box: load_symbol(lib, \"bufferDrawBox\")?,\n }\n };\n Ok(Self {\n inner: Arc::new(Inner { lib, fns, path }),\n })\n }\n\n pub fn path(&self) -> &str {\n &self.inner.path\n }\n\n pub fn create_renderer(&self, width: u32, height: u32, testing: bool) -> Result<Renderer> {\n let ptr = unsafe { (self.inner.fns.create_renderer)(width, height, testing) };\n if ptr.is_null() {\n return Err(Error::new(\"opentui: createRenderer returned null\"));\n }\n Ok(Renderer {\n inner: self.inner.clone(),\n ptr,\n })\n }\n}\n\npub struct Renderer {\n inner: Arc<Inner>,\n ptr: RendererPtr,\n}\n\nimpl Renderer {\n pub fn setup_terminal(&self, use_alternate_screen: bool) {\n unsafe { (self.inner.fns.setup_terminal)(self.ptr, use_alternate_screen) };\n }\n\n pub fn suspend(&self) {\n unsafe { (self.inner.fns.suspend_renderer)(self.ptr) };\n }\n\n pub fn clear_terminal(&self) {\n unsafe { (self.inner.fns.clear_terminal)(self.ptr) };\n }\n\n pub fn resize(&self, width: u32, height: u32) {\n unsafe { (self.inner.fns.resize_renderer)(self.ptr, width, height) };\n }\n\n pub fn render(&self, force: bool) {\n unsafe { (self.inner.fns.render)(self.ptr, force) };\n }\n\n pub fn next_buffer(&self) -> Buffer {\n let ptr = unsafe { (self.inner.fns.get_next_buffer)(self.ptr) };\n Buffer {\n inner: self.inner.clone(),\n ptr,\n }\n }\n\n pub fn current_buffer(&self) -> Buffer {\n let ptr = unsafe { (self.inner.fns.get_current_buffer)(self.ptr) };\n Buffer {\n inner: self.inner.clone(),\n ptr,\n }\n }\n}\n\nimpl Drop for Renderer {\n fn drop(&mut self) {\n unsafe {\n (self.inner.fns.destroy_renderer)(self.ptr);\n }\n }\n}\n\npub struct Buffer {\n inner: Arc<Inner>,\n ptr: BufferPtr,\n}\n\nimpl Buffer {\n pub fn clear(&self, bg: Color) {\n unsafe { (self.inner.fns.buffer_clear)(self.ptr, &bg as *const Color as *const f32) };\n }\n\n pub fn fill_rect(&self, x: u32, y: u32, width: u32, height: u32, bg: Color) {\n unsafe {\n (self.inner.fns.buffer_fill_rect)(\n self.ptr,\n x,\n y,\n width,\n height,\n &bg as *const Color as *const f32,\n )\n };\n }\n\n pub fn draw_text(&self, text: &str, x: u32, y: u32, fg: Color, bg: Option<Color>, attr: u32) {\n let bg_ptr = match bg {\n Some(color) => &color as *const Color as *const f32,\n None => std::ptr::null(),\n };\n unsafe {\n (self.inner.fns.buffer_draw_text)(\n self.ptr,\n text.as_ptr(),\n text.len(),\n x,\n y,\n &fg as *const Color as *const f32,\n bg_ptr,\n attr,\n )\n };\n }\n\n pub fn draw_box(\n &self,\n x: i32,\n y: i32,\n width: u32,\n height: u32,\n border_chars: &[u32; 11],\n packed_options: u32,\n border: Color,\n background: Color,\n title: Option<&str>,\n ) {\n let (title_ptr, title_len) = match title {\n Some(value) => (value.as_ptr(), value.len() as u32),\n None => (std::ptr::null(), 0),\n };\n unsafe {\n (self.inner.fns.buffer_draw_box)(\n self.ptr,\n x,\n y,\n width,\n height,\n border_chars.as_ptr(),\n packed_options,\n &border as *const Color as *const f32,\n &background as *const Color as *const f32,\n title_ptr,\n title_len,\n )\n };\n }\n}\n\nfn load_library() -> Result<(*mut std::ffi::c_void, String)> {\n let mut errors = Vec::new();\n for path in candidate_paths() {\n match try_dlopen(&path) {\n Ok(lib) => return Ok((lib, path.display().to_string())),\n Err(err) => errors.push(format!(\"{}: {}\", path.display(), err)),\n }\n }\n let mut message = String::from(\"opentui: failed to load native library\");\n if !errors.is_empty() {\n message.push_str(\" (tried: \");\n message.push_str(&errors.join(\", \"));\n message.push(')');\n }\n Err(Error::new(message))\n}\n\nfn candidate_paths() -> Vec<PathBuf> {\n let mut paths = Vec::new();\n let lib_name = lib_filename();\n\n if let Ok(path) = std::env::var(\"OPENTUI_LIB_PATH\") {\n paths.push(PathBuf::from(path));\n }\n\n if let Ok(dir) = std::env::var(\"OPENTUI_LIB_DIR\") {\n paths.push(PathBuf::from(dir).join(lib_name));\n }\n\n if let Ok(prefix) = std::env::var(\"OPENTUI_PREFIX\") {\n paths.push(PathBuf::from(prefix).join(\"lib\").join(lib_name));\n }\n\n if let Ok(home) = std::env::var(\"HOME\") {\n let home_path = PathBuf::from(&home);\n if let Some(target_dir) = zig_target_dir() {\n paths.push(\n home_path\n .join(\"repos/anomalyco/opentui/packages/core/src/zig/lib\")\n .join(target_dir)\n .join(lib_name),\n );\n }\n paths.push(home_path.join(\".local/lib\").join(lib_name));\n }\n\n paths.push(PathBuf::from(lib_name));\n paths\n}\n\nfn zig_target_dir() -> Option<&'static str> {\n match (std::env::consts::ARCH, std::env::consts::OS) {\n (\"aarch64\", \"macos\") => Some(\"aarch64-macos\"),\n (\"x86_64\", \"macos\") => Some(\"x86_64-macos\"),\n (\"aarch64\", \"linux\") => Some(\"aarch64-linux\"),\n (\"x86_64\", \"linux\") => Some(\"x86_64-linux\"),\n _ => None,\n }\n}\n\nfn lib_filename() -> &'static str {\n if cfg!(target_os = \"macos\") {\n \"libopentui.dylib\"\n } else if cfg!(target_os = \"linux\") {\n \"libopentui.so\"\n } else {\n \"libopentui\"\n }\n}\n\nfn try_dlopen(path: &Path) -> Result<*mut std::ffi::c_void> {\n let cpath = path_to_cstring(path)?;\n unsafe {\n let handle = dlopen(cpath.as_ptr(), libc::RTLD_NOW);\n if handle.is_null() {\n return Err(Error::new(dl_error_string()));\n }\n Ok(handle)\n }\n}\n\nfn path_to_cstring(path: &Path) -> Result<CString> {\n #[cfg(unix)]\n {\n use std::os::unix::ffi::OsStrExt;\n CString::new(path.as_os_str().as_bytes())\n .map_err(|_| Error::new(\"opentui: invalid library path\"))\n }\n #[cfg(not(unix))]\n {\n Err(Error::new(\"opentui: unsupported platform\"))\n }\n}\n\nunsafe fn load_symbol<T>(lib: *mut std::ffi::c_void, symbol: &str) -> Result<T> {\n let name = CString::new(symbol).map_err(|_| Error::new(\"opentui: invalid symbol\"))?;\n let ptr = unsafe { dlsym(lib, name.as_ptr()) };\n if ptr.is_null() {\n return Err(Error::new(format!(\"opentui: missing symbol {symbol}\")));\n }\n Ok(unsafe { std::mem::transmute_copy(&ptr) })\n}\n\nfn dl_error_string() -> String {\n unsafe {\n let err = dlerror();\n if err.is_null() {\n return \"unknown dlopen error\".to_string();\n }\n CStr::from_ptr(err).to_string_lossy().to_string()\n }\n}\n\nunsafe extern \"C\" {\n fn dlopen(path: *const libc::c_char, mode: libc::c_int) -> *mut std::ffi::c_void;\n fn dlsym(handle: *mut std::ffi::c_void, symbol: *const libc::c_char) -> *mut std::ffi::c_void;\n fn dlclose(handle: *mut std::ffi::c_void) -> libc::c_int;\n fn dlerror() -> *const libc::c_char;\n}\n" }, { "path": "crates/seq_client/Cargo.toml", "content": "[package]\nname = \"seq_client\"\nversion = \"0.1.0\"\nedition = \"2021\"\ndescription = \"Rust client for seqd Agent RPC v1 over Unix sockets\"\nlicense = \"MIT\"\n\n[dependencies]\nserde = { version = \"1.0\", features = [\"derive\"] }\nserde_json = \"1.0\"\nthiserror = \"2.0\"\n\n" }, { "path": "crates/seq_client/src/lib.rs", "content": "use serde::{Deserialize, Serialize};\nuse serde_json::{json, Value};\nuse std::io::{Read, Write};\nuse std::os::unix::net::UnixStream;\nuse std::path::{Path, PathBuf};\nuse std::sync::Mutex;\nuse std::time::Duration;\nuse thiserror::Error;\n\nconst DEFAULT_SOCKET_PATH: &str = \"/tmp/seqd.sock\";\nconst MAX_RESPONSE_BYTES: usize = 1024 * 1024;\n\n#[derive(Debug, Error)]\npub enum SeqClientError {\n #[error(\"io error: {0}\")]\n Io(#[from] std::io::Error),\n #[error(\"json error: {0}\")]\n Json(#[from] serde_json::Error),\n #[error(\"invalid protocol: {0}\")]\n Protocol(String),\n #[error(\"remote error: {0}\")]\n Remote(String),\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\npub struct RpcRequest {\n pub op: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub request_id: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub run_id: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub tool_call_id: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub args: Option<Value>,\n}\n\nimpl RpcRequest {\n pub fn new(op: impl Into<String>) -> Self {\n Self {\n op: op.into(),\n ..Self::default()\n }\n }\n\n pub fn with_request_id(mut self, request_id: impl Into<String>) -> Self {\n self.request_id = Some(request_id.into());\n self\n }\n\n pub fn with_run_id(mut self, run_id: impl Into<String>) -> Self {\n self.run_id = Some(run_id.into());\n self\n }\n\n pub fn with_tool_call_id(mut self, tool_call_id: impl Into<String>) -> Self {\n self.tool_call_id = Some(tool_call_id.into());\n self\n }\n\n pub fn with_args_json(mut self, args: Value) -> Self {\n self.args = Some(args);\n self\n }\n\n pub fn with_args<T: Serialize>(mut self, args: &T) -> Result<Self, SeqClientError> {\n self.args = Some(serde_json::to_value(args)?);\n Ok(self)\n }\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct RpcResponse {\n pub ok: bool,\n pub op: String,\n #[serde(default)]\n pub request_id: String,\n #[serde(default)]\n pub run_id: String,\n #[serde(default)]\n pub tool_call_id: String,\n pub ts_ms: u64,\n pub dur_us: u64,\n #[serde(default)]\n pub result: Option<Value>,\n #[serde(default)]\n pub error: Option<String>,\n}\n\n#[derive(Debug)]\npub struct SeqClient {\n socket_path: PathBuf,\n stream: Mutex<UnixStream>,\n}\n\nimpl SeqClient {\n pub fn connect_default() -> Result<Self, SeqClientError> {\n Self::connect(DEFAULT_SOCKET_PATH)\n }\n\n pub fn connect(path: impl AsRef<Path>) -> Result<Self, SeqClientError> {\n let stream = UnixStream::connect(path.as_ref())?;\n Ok(Self {\n socket_path: path.as_ref().to_path_buf(),\n stream: Mutex::new(stream),\n })\n }\n\n pub fn connect_with_timeout(\n path: impl AsRef<Path>,\n timeout: Duration,\n ) -> Result<Self, SeqClientError> {\n let stream = UnixStream::connect(path.as_ref())?;\n stream.set_read_timeout(Some(timeout))?;\n stream.set_write_timeout(Some(timeout))?;\n Ok(Self {\n socket_path: path.as_ref().to_path_buf(),\n stream: Mutex::new(stream),\n })\n }\n\n pub fn socket_path(&self) -> &Path {\n &self.socket_path\n }\n\n pub fn call(&self, request: RpcRequest) -> Result<RpcResponse, SeqClientError> {\n let mut stream = self\n .stream\n .lock()\n .map_err(|_| SeqClientError::Protocol(\"socket mutex poisoned\".into()))?;\n write_request(&mut stream, &request)?;\n let line = read_response_line(&mut stream)?;\n let response: RpcResponse = serde_json::from_slice(&line)?;\n Ok(response)\n }\n\n pub fn call_ok(&self, request: RpcRequest) -> Result<Value, SeqClientError> {\n let response = self.call(request)?;\n if response.ok {\n Ok(response.result.unwrap_or_else(|| json!({})))\n } else {\n Err(SeqClientError::Remote(\n response\n .error\n .unwrap_or_else(|| \"unknown_error\".to_string()),\n ))\n }\n }\n\n pub fn ping(&self) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"ping\"))\n }\n\n pub fn app_state(&self) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"app_state\"))\n }\n\n pub fn perf(&self) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"perf\"))\n }\n\n pub fn open_app(&self, name: &str) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"open_app\").with_args_json(json!({ \"name\": name })))\n }\n\n pub fn open_app_toggle(&self, name: &str) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"open_app_toggle\").with_args_json(json!({ \"name\": name })))\n }\n\n pub fn run_macro(&self, name: &str) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"run_macro\").with_args_json(json!({ \"name\": name })))\n }\n\n pub fn click(&self, x: f64, y: f64) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"click\").with_args_json(json!({ \"x\": x, \"y\": y })))\n }\n\n pub fn right_click(&self, x: f64, y: f64) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"right_click\").with_args_json(json!({ \"x\": x, \"y\": y })))\n }\n\n pub fn double_click(&self, x: f64, y: f64) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"double_click\").with_args_json(json!({ \"x\": x, \"y\": y })))\n }\n\n pub fn move_mouse(&self, x: f64, y: f64) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"move\").with_args_json(json!({ \"x\": x, \"y\": y })))\n }\n\n pub fn scroll(&self, x: f64, y: f64, dy: i32) -> Result<RpcResponse, SeqClientError> {\n self.call(RpcRequest::new(\"scroll\").with_args_json(json!({ \"x\": x, \"y\": y, \"dy\": dy })))\n }\n\n pub fn drag(&self, x1: f64, y1: f64, x2: f64, y2: f64) -> Result<RpcResponse, SeqClientError> {\n self.call(\n RpcRequest::new(\"drag\")\n .with_args_json(json!({ \"x1\": x1, \"y1\": y1, \"x2\": x2, \"y2\": y2 })),\n )\n }\n\n pub fn screenshot(&self, path: Option<&str>) -> Result<RpcResponse, SeqClientError> {\n let req = if let Some(path) = path {\n RpcRequest::new(\"screenshot\").with_args_json(json!({ \"path\": path }))\n } else {\n RpcRequest::new(\"screenshot\")\n };\n self.call(req)\n }\n}\n\nfn write_request(stream: &mut UnixStream, request: &RpcRequest) -> Result<(), SeqClientError> {\n let mut payload = serde_json::to_vec(request)?;\n payload.push(b'\\n');\n stream.write_all(&payload)?;\n Ok(())\n}\n\nfn read_response_line(stream: &mut UnixStream) -> Result<Vec<u8>, SeqClientError> {\n let mut out = Vec::with_capacity(512);\n let mut buf = [0u8; 512];\n loop {\n let n = stream.read(&mut buf)?;\n if n == 0 {\n if out.is_empty() {\n return Err(SeqClientError::Protocol(\n \"unexpected EOF while waiting for response\".to_string(),\n ));\n }\n break;\n }\n for b in &buf[..n] {\n out.push(*b);\n if *b == b'\\n' {\n out.pop();\n return Ok(out);\n }\n }\n if out.len() > MAX_RESPONSE_BYTES {\n return Err(SeqClientError::Protocol(\n \"response exceeded max size\".to_string(),\n ));\n }\n }\n Ok(out)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use std::fs;\n use std::io::{BufRead, BufReader};\n use std::os::unix::net::UnixListener;\n use std::thread;\n\n fn test_socket_path(tag: &str) -> PathBuf {\n let mut p = std::env::temp_dir();\n let pid = std::process::id();\n let now = std::time::SystemTime::now()\n .duration_since(std::time::UNIX_EPOCH)\n .expect(\"clock\")\n .as_nanos();\n p.push(format!(\"seq_client_{tag}_{pid}_{now}.sock\"));\n p\n }\n\n #[test]\n fn call_roundtrip_ping() {\n let path = test_socket_path(\"ping\");\n let listener = UnixListener::bind(&path).expect(\"bind\");\n let server = thread::spawn(move || {\n let (stream, _) = listener.accept().expect(\"accept\");\n let mut reader = BufReader::new(stream);\n let mut line = String::new();\n reader.read_line(&mut line).expect(\"read line\");\n let req: Value = serde_json::from_str(line.trim()).expect(\"parse req\");\n assert_eq!(req[\"op\"], \"ping\");\n let response = json!({\n \"ok\": true,\n \"op\": \"ping\",\n \"request_id\": \"\",\n \"run_id\": \"\",\n \"tool_call_id\": \"\",\n \"ts_ms\": 1,\n \"dur_us\": 2,\n \"result\": { \"pong\": true }\n });\n let mut inner = reader.into_inner();\n inner\n .write_all(format!(\"{}\\n\", response).as_bytes())\n .expect(\"write\");\n });\n\n let client = SeqClient::connect(&path).expect(\"connect\");\n let response = client.ping().expect(\"call\");\n assert!(response.ok);\n assert_eq!(response.op, \"ping\");\n assert_eq!(response.result.unwrap()[\"pong\"], true);\n\n server.join().expect(\"join\");\n let _ = fs::remove_file(path);\n }\n\n #[test]\n fn call_ok_surfaces_remote_error() {\n let path = test_socket_path(\"err\");\n let listener = UnixListener::bind(&path).expect(\"bind\");\n let server = thread::spawn(move || {\n let (stream, _) = listener.accept().expect(\"accept\");\n let mut reader = BufReader::new(stream);\n let mut line = String::new();\n reader.read_line(&mut line).expect(\"read line\");\n let response = json!({\n \"ok\": false,\n \"op\": \"open_app\",\n \"request_id\": \"r1\",\n \"run_id\": \"\",\n \"tool_call_id\": \"\",\n \"ts_ms\": 10,\n \"dur_us\": 11,\n \"error\": \"missing_name\"\n });\n let mut inner = reader.into_inner();\n inner\n .write_all(format!(\"{}\\n\", response).as_bytes())\n .expect(\"write\");\n });\n\n let client = SeqClient::connect(&path).expect(\"connect\");\n let err = client\n .call_ok(RpcRequest::new(\"open_app\"))\n .expect_err(\"should fail\");\n match err {\n SeqClientError::Remote(s) => assert_eq!(s, \"missing_name\"),\n other => panic!(\"unexpected error: {other:?}\"),\n }\n\n server.join().expect(\"join\");\n let _ = fs::remove_file(path);\n }\n}\n" }, { "path": "crates/seq_everruns_bridge/Cargo.toml", "content": "[package]\nname = \"seq_everruns_bridge\"\nversion = \"0.1.0\"\nedition = \"2021\"\ndescription = \"Everruns client-side tool bridge for seqd RPC\"\nlicense = \"MIT\"\n\n[dependencies]\nseq_client = { path = \"../seq_client\" }\nserde = { version = \"1.0\", features = [\"derive\"] }\nserde_json = \"1.0\"\nthiserror = \"2.0\"\nreqwest = { version = \"0.13\", default-features = false, features = [\"blocking\", \"rustls\"] }\n" }, { "path": "crates/seq_everruns_bridge/src/lib.rs", "content": "use seq_client::{RpcRequest, SeqClient};\nuse serde::{Deserialize, Serialize};\nuse serde_json::{json, Value};\nuse std::time::{Instant, SystemTime, UNIX_EPOCH};\nuse thiserror::Error;\n\npub mod maple;\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ToolCall {\n pub id: String,\n pub name: String,\n #[serde(default)]\n pub arguments: Value,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]\npub struct ToolResult {\n pub tool_call_id: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub result: Option<Value>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub error: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\npub struct ToolCallRequestedData {\n pub tool_calls: Vec<ToolCall>,\n}\n\n#[derive(Debug, Error)]\npub enum BridgeError {\n #[error(\"unsupported seq tool name: {0}\")]\n UnsupportedTool(String),\n}\n\npub fn parse_tool_call_requested(data: &Value) -> Result<Vec<ToolCall>, serde_json::Error> {\n let parsed: ToolCallRequestedData = serde_json::from_value(data.clone())?;\n Ok(parsed.tool_calls)\n}\n\npub fn execute_tool_call(\n client: &SeqClient,\n session_id: &str,\n event_id: &str,\n call: &ToolCall,\n) -> ToolResult {\n execute_tool_call_with_maple(client, session_id, event_id, call, None)\n}\n\npub fn execute_tool_call_with_maple(\n client: &SeqClient,\n session_id: &str,\n event_id: &str,\n call: &ToolCall,\n maple_exporter: Option<&maple::MapleTraceExporter>,\n) -> ToolResult {\n let started = Instant::now();\n let start_unix_nano = unix_time_nanos_now();\n let seq_op = map_tool_name_to_seq_op(&call.name).unwrap_or(\"unknown\");\n\n let result = match build_request(session_id, event_id, call) {\n Ok(req) => match client.call(req) {\n Ok(resp) => {\n if resp.ok {\n ToolResult {\n tool_call_id: call.id.clone(),\n result: Some(resp.result.unwrap_or_else(|| json!({}))),\n error: None,\n }\n } else {\n let op = map_tool_name_to_seq_op(&call.name).unwrap_or(\"unknown\");\n ToolResult {\n tool_call_id: call.id.clone(),\n result: None,\n error: Some(\n resp.error\n .unwrap_or_else(|| format!(\"seq {op} failed with unknown error\")),\n ),\n }\n }\n }\n Err(err) => {\n let op = map_tool_name_to_seq_op(&call.name).unwrap_or(\"unknown\");\n ToolResult {\n tool_call_id: call.id.clone(),\n result: None,\n error: Some(format!(\"seq {op} call failed: {err}\")),\n }\n }\n },\n Err(err) => ToolResult {\n tool_call_id: call.id.clone(),\n result: None,\n error: Some(err.to_string()),\n },\n };\n\n if let Some(exporter) = maple_exporter {\n let elapsed = started.elapsed();\n let duration_ms = elapsed.as_millis() as u64;\n let end_unix_nano = start_unix_nano.saturating_add(elapsed.as_nanos() as u64);\n let ok = result.error.is_none();\n let span = maple::MapleSpan::for_tool_call(\n session_id,\n event_id,\n &call.id,\n &call.name,\n seq_op,\n ok,\n result.error.as_deref(),\n start_unix_nano,\n end_unix_nano,\n duration_ms,\n );\n exporter.emit_span(span);\n }\n\n result\n}\n\npub fn build_request(\n session_id: &str,\n event_id: &str,\n call: &ToolCall,\n) -> Result<RpcRequest, BridgeError> {\n let op = map_tool_name_to_seq_op(&call.name)\n .ok_or_else(|| BridgeError::UnsupportedTool(call.name.clone()))?;\n\n let mut req = RpcRequest::new(op)\n .with_request_id(format!(\"everruns:{event_id}:{}\", call.id))\n .with_run_id(session_id)\n .with_tool_call_id(&call.id);\n\n if !call.arguments.is_null() {\n req = req.with_args_json(call.arguments.clone());\n }\n\n Ok(req)\n}\n\npub fn map_tool_name_to_seq_op(tool_name: &str) -> Option<&'static str> {\n let mut name = tool_name.trim().to_ascii_lowercase().replace('-', \"_\");\n\n for prefix in [\"seq.\", \"seq:\", \"seq_\"] {\n if let Some(rest) = name.strip_prefix(prefix) {\n name = rest.to_string();\n break;\n }\n }\n\n match name.as_str() {\n \"ping\" => Some(\"ping\"),\n \"app_state\" => Some(\"app_state\"),\n \"perf\" => Some(\"perf\"),\n \"open_app\" => Some(\"open_app\"),\n \"open_app_toggle\" => Some(\"open_app_toggle\"),\n \"run_macro\" => Some(\"run_macro\"),\n \"click\" => Some(\"click\"),\n \"right_click\" => Some(\"right_click\"),\n \"double_click\" => Some(\"double_click\"),\n \"move\" => Some(\"move\"),\n \"scroll\" => Some(\"scroll\"),\n \"drag\" => Some(\"drag\"),\n \"screenshot\" => Some(\"screenshot\"),\n _ => None,\n }\n}\n\npub fn client_side_tool_definitions() -> Vec<Value> {\n vec![\n client_tool(\n \"seq_ping\",\n \"Health check seqd runtime\",\n json!({\"type\":\"object\",\"properties\":{},\"additionalProperties\":false}),\n ),\n client_tool(\n \"seq_app_state\",\n \"Get frontmost/previous app snapshot\",\n json!({\"type\":\"object\",\"properties\":{},\"additionalProperties\":false}),\n ),\n client_tool(\n \"seq_perf\",\n \"Get seqd performance snapshot\",\n json!({\"type\":\"object\",\"properties\":{},\"additionalProperties\":false}),\n ),\n client_tool(\n \"seq_open_app\",\n \"Open application by name\",\n json!({\n \"type\":\"object\",\n \"properties\":{\"name\":{\"type\":\"string\",\"description\":\"App name (e.g. Safari)\"}},\n \"required\":[\"name\"],\n \"additionalProperties\":false\n }),\n ),\n client_tool(\n \"seq_open_app_toggle\",\n \"Toggle to app by name\",\n json!({\n \"type\":\"object\",\n \"properties\":{\"name\":{\"type\":\"string\",\"description\":\"App name (e.g. Safari)\"}},\n \"required\":[\"name\"],\n \"additionalProperties\":false\n }),\n ),\n client_tool(\n \"seq_run_macro\",\n \"Run seq macro by name\",\n json!({\n \"type\":\"object\",\n \"properties\":{\"name\":{\"type\":\"string\",\"description\":\"Macro name\"}},\n \"required\":[\"name\"],\n \"additionalProperties\":false\n }),\n ),\n client_tool(\n \"seq_click\",\n \"Click at screen coordinates\",\n json!({\n \"type\":\"object\",\n \"properties\":{\"x\":{\"type\":\"number\"},\"y\":{\"type\":\"number\"}},\n \"required\":[\"x\",\"y\"],\n \"additionalProperties\":false\n }),\n ),\n client_tool(\n \"seq_right_click\",\n \"Right click at screen coordinates\",\n json!({\n \"type\":\"object\",\n \"properties\":{\"x\":{\"type\":\"number\"},\"y\":{\"type\":\"number\"}},\n \"required\":[\"x\",\"y\"],\n \"additionalProperties\":false\n }),\n ),\n client_tool(\n \"seq_double_click\",\n \"Double click at screen coordinates\",\n json!({\n \"type\":\"object\",\n \"properties\":{\"x\":{\"type\":\"number\"},\"y\":{\"type\":\"number\"}},\n \"required\":[\"x\",\"y\"],\n \"additionalProperties\":false\n }),\n ),\n client_tool(\n \"seq_move\",\n \"Move pointer to coordinates\",\n json!({\n \"type\":\"object\",\n \"properties\":{\"x\":{\"type\":\"number\"},\"y\":{\"type\":\"number\"}},\n \"required\":[\"x\",\"y\"],\n \"additionalProperties\":false\n }),\n ),\n client_tool(\n \"seq_scroll\",\n \"Scroll at coordinates by delta\",\n json!({\n \"type\":\"object\",\n \"properties\":{\"x\":{\"type\":\"number\"},\"y\":{\"type\":\"number\"},\"dy\":{\"type\":\"integer\"}},\n \"required\":[\"x\",\"y\",\"dy\"],\n \"additionalProperties\":false\n }),\n ),\n client_tool(\n \"seq_drag\",\n \"Drag from one coordinate to another\",\n json!({\n \"type\":\"object\",\n \"properties\":{\"x1\":{\"type\":\"number\"},\"y1\":{\"type\":\"number\"},\"x2\":{\"type\":\"number\"},\"y2\":{\"type\":\"number\"}},\n \"required\":[\"x1\",\"y1\",\"x2\",\"y2\"],\n \"additionalProperties\":false\n }),\n ),\n client_tool(\n \"seq_screenshot\",\n \"Capture screenshot to optional path\",\n json!({\n \"type\":\"object\",\n \"properties\":{\"path\":{\"type\":\"string\",\"description\":\"Output path (optional)\"}},\n \"additionalProperties\":false\n }),\n ),\n ]\n}\n\nfn client_tool(name: &str, description: &str, parameters: Value) -> Value {\n json!({\n \"type\": \"client_side\",\n \"name\": name,\n \"description\": description,\n \"parameters\": parameters\n })\n}\n\nfn unix_time_nanos_now() -> u64 {\n match SystemTime::now().duration_since(UNIX_EPOCH) {\n Ok(dur) => dur.as_nanos() as u64,\n Err(_) => 0,\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn maps_supported_tool_names() {\n assert_eq!(map_tool_name_to_seq_op(\"seq_open_app\"), Some(\"open_app\"));\n assert_eq!(map_tool_name_to_seq_op(\"seq.open_app\"), Some(\"open_app\"));\n assert_eq!(map_tool_name_to_seq_op(\"seq:open-app\"), Some(\"open_app\"));\n assert_eq!(map_tool_name_to_seq_op(\"PING\"), Some(\"ping\"));\n assert_eq!(map_tool_name_to_seq_op(\"unknown_tool\"), None);\n }\n\n #[test]\n fn builds_request_with_correlation_ids() {\n let call = ToolCall {\n id: \"tool-9\".to_string(),\n name: \"seq_click\".to_string(),\n arguments: json!({\"x\": 1, \"y\": 2}),\n };\n\n let req = build_request(\"session-1\", \"event-7\", &call).expect(\"request should build\");\n assert_eq!(req.op, \"click\");\n assert_eq!(req.request_id.as_deref(), Some(\"everruns:event-7:tool-9\"));\n assert_eq!(req.run_id.as_deref(), Some(\"session-1\"));\n assert_eq!(req.tool_call_id.as_deref(), Some(\"tool-9\"));\n assert_eq!(req.args, Some(json!({\"x\": 1, \"y\": 2})));\n }\n\n #[test]\n fn emits_expected_tool_catalog() {\n let defs = client_side_tool_definitions();\n assert_eq!(defs.len(), 13);\n let names: Vec<&str> = defs\n .iter()\n .filter_map(|v| v.get(\"name\").and_then(Value::as_str))\n .collect();\n assert!(names.contains(&\"seq_open_app\"));\n assert!(names.contains(&\"seq_screenshot\"));\n }\n\n #[test]\n fn parse_tool_call_requested_payload() {\n let payload = json!({\n \"tool_calls\": [\n {\"id\":\"tc1\",\"name\":\"seq_ping\",\"arguments\":{}},\n {\"id\":\"tc2\",\"name\":\"seq_open_app\",\"arguments\":{\"name\":\"Safari\"}}\n ]\n });\n\n let calls = parse_tool_call_requested(&payload).expect(\"payload should parse\");\n assert_eq!(calls.len(), 2);\n assert_eq!(calls[0].id, \"tc1\");\n assert_eq!(calls[1].name, \"seq_open_app\");\n }\n\n #[test]\n fn unsupported_tool_returns_error_result() {\n let call = ToolCall {\n id: \"tcX\".to_string(),\n name: \"seq_not_real\".to_string(),\n arguments: json!({}),\n };\n\n let result = ToolResult {\n tool_call_id: call.id.clone(),\n result: None,\n error: Some(\n build_request(\"session\", \"event\", &call)\n .expect_err(\"should error\")\n .to_string(),\n ),\n };\n\n assert_eq!(result.tool_call_id, \"tcX\");\n assert!(result\n .error\n .unwrap_or_default()\n .contains(\"unsupported seq tool name\"));\n }\n\n #[test]\n fn bridge_error_is_displayable() {\n let e = BridgeError::UnsupportedTool(\"foo\".to_string());\n assert_eq!(e.to_string(), \"unsupported seq tool name: foo\");\n }\n}\n" }, { "path": "crates/seq_everruns_bridge/src/maple.rs", "content": "use reqwest::blocking::Client;\nuse serde_json::{json, Value};\nuse std::sync::atomic::{AtomicU64, Ordering};\nuse std::sync::mpsc::{sync_channel, Receiver, RecvTimeoutError, SyncSender, TryRecvError};\nuse std::sync::Arc;\nuse std::thread;\nuse std::time::Duration;\nuse thiserror::Error;\n\nconst DEFAULT_SCOPE_NAME: &str = \"seq_everruns_bridge\";\nconst DEFAULT_SERVICE_NAME: &str = \"seq-everruns-bridge\";\nconst DEFAULT_ENV: &str = \"local\";\nconst DEFAULT_QUEUE_CAPACITY: usize = 4096;\nconst DEFAULT_MAX_BATCH_SIZE: usize = 128;\nconst DEFAULT_FLUSH_INTERVAL_MS: u64 = 50;\nconst DEFAULT_CONNECT_TIMEOUT_MS: u64 = 400;\nconst DEFAULT_REQUEST_TIMEOUT_MS: u64 = 800;\n\n#[derive(Debug, Clone)]\npub struct MapleIngestTarget {\n pub traces_endpoint: String,\n pub ingest_key: String,\n}\n\n#[derive(Debug, Clone)]\npub struct MapleExporterConfig {\n pub service_name: String,\n pub service_version: Option<String>,\n pub deployment_environment: String,\n pub scope_name: String,\n pub queue_capacity: usize,\n pub max_batch_size: usize,\n pub flush_interval: Duration,\n pub connect_timeout: Duration,\n pub request_timeout: Duration,\n pub targets: Vec<MapleIngestTarget>,\n}\n\nimpl MapleExporterConfig {\n pub fn from_env() -> Result<Option<Self>, MapleConfigError> {\n let targets = parse_targets_from_env()?;\n if targets.is_empty() {\n return Ok(None);\n }\n\n let service_name = std::env::var(\"SEQ_EVERRUNS_MAPLE_SERVICE_NAME\")\n .ok()\n .and_then(non_empty)\n .unwrap_or_else(|| DEFAULT_SERVICE_NAME.to_string());\n\n let deployment_environment = std::env::var(\"SEQ_EVERRUNS_MAPLE_ENV\")\n .ok()\n .and_then(non_empty)\n .unwrap_or_else(|| DEFAULT_ENV.to_string());\n\n let service_version = std::env::var(\"SEQ_EVERRUNS_MAPLE_SERVICE_VERSION\")\n .ok()\n .and_then(non_empty);\n\n let scope_name = std::env::var(\"SEQ_EVERRUNS_MAPLE_SCOPE_NAME\")\n .ok()\n .and_then(non_empty)\n .unwrap_or_else(|| DEFAULT_SCOPE_NAME.to_string());\n\n let queue_capacity = env_usize(\"SEQ_EVERRUNS_MAPLE_QUEUE_CAPACITY\")\n .unwrap_or(DEFAULT_QUEUE_CAPACITY)\n .max(1);\n let max_batch_size = env_usize(\"SEQ_EVERRUNS_MAPLE_MAX_BATCH_SIZE\")\n .unwrap_or(DEFAULT_MAX_BATCH_SIZE)\n .max(1);\n let flush_interval = Duration::from_millis(\n env_u64(\"SEQ_EVERRUNS_MAPLE_FLUSH_INTERVAL_MS\").unwrap_or(DEFAULT_FLUSH_INTERVAL_MS),\n );\n let connect_timeout = Duration::from_millis(\n env_u64(\"SEQ_EVERRUNS_MAPLE_CONNECT_TIMEOUT_MS\").unwrap_or(DEFAULT_CONNECT_TIMEOUT_MS),\n );\n let request_timeout = Duration::from_millis(\n env_u64(\"SEQ_EVERRUNS_MAPLE_REQUEST_TIMEOUT_MS\").unwrap_or(DEFAULT_REQUEST_TIMEOUT_MS),\n );\n\n Ok(Some(Self {\n service_name,\n service_version,\n deployment_environment,\n scope_name,\n queue_capacity,\n max_batch_size,\n flush_interval,\n connect_timeout,\n request_timeout,\n targets,\n }))\n }\n}\n\nimpl Default for MapleExporterConfig {\n fn default() -> Self {\n Self {\n service_name: DEFAULT_SERVICE_NAME.to_string(),\n service_version: None,\n deployment_environment: DEFAULT_ENV.to_string(),\n scope_name: DEFAULT_SCOPE_NAME.to_string(),\n queue_capacity: DEFAULT_QUEUE_CAPACITY,\n max_batch_size: DEFAULT_MAX_BATCH_SIZE,\n flush_interval: Duration::from_millis(DEFAULT_FLUSH_INTERVAL_MS),\n connect_timeout: Duration::from_millis(DEFAULT_CONNECT_TIMEOUT_MS),\n request_timeout: Duration::from_millis(DEFAULT_REQUEST_TIMEOUT_MS),\n targets: Vec::new(),\n }\n }\n}\n\n#[derive(Debug, Error)]\npub enum MapleConfigError {\n #[error(\"SEQ_EVERRUNS_MAPLE_TRACES_ENDPOINTS count ({endpoints}) does not match SEQ_EVERRUNS_MAPLE_INGEST_KEYS count ({keys})\")]\n EndpointKeyCountMismatch { endpoints: usize, keys: usize },\n #[error(\"{prefix} endpoint/key must both be set\")]\n IncompletePair { prefix: &'static str },\n}\n\n#[derive(Debug, Clone)]\npub struct MapleSpan {\n pub trace_id: String,\n pub span_id: String,\n pub parent_span_id: String,\n pub name: String,\n pub kind: i32,\n pub start_time_unix_nano: u64,\n pub end_time_unix_nano: u64,\n pub status_code: i32,\n pub status_message: Option<String>,\n pub attributes: Vec<(String, String)>,\n}\n\nimpl MapleSpan {\n pub fn for_runtime_event(\n session_id: &str,\n event_id: &str,\n stage: &str,\n ok: bool,\n error: Option<&str>,\n start_time_unix_nano: u64,\n end_time_unix_nano: u64,\n mut extra_attributes: Vec<(String, String)>,\n ) -> Self {\n let trace_id = stable_trace_id(session_id, event_id);\n let span_id = stable_span_id(&format!(\n \"{session_id}:{event_id}:{stage}:{start_time_unix_nano}\"\n ));\n extra_attributes.push((\"session_id\".to_string(), session_id.to_string()));\n extra_attributes.push((\"event_id\".to_string(), event_id.to_string()));\n extra_attributes.push((\"stage\".to_string(), stage.to_string()));\n extra_attributes.push((\"bridge.ok\".to_string(), ok.to_string()));\n if let Some(msg) = error {\n extra_attributes.push((\"error.message\".to_string(), msg.to_string()));\n }\n\n Self {\n trace_id,\n span_id,\n parent_span_id: String::new(),\n name: format!(\"everruns.{stage}\"),\n kind: 1,\n start_time_unix_nano,\n end_time_unix_nano,\n status_code: if ok { 1 } else { 2 },\n status_message: error.map(|s| s.to_string()),\n attributes: extra_attributes,\n }\n }\n\n pub fn for_tool_call(\n session_id: &str,\n event_id: &str,\n tool_call_id: &str,\n tool_name: &str,\n seq_op: &str,\n ok: bool,\n error: Option<&str>,\n start_time_unix_nano: u64,\n end_time_unix_nano: u64,\n duration_ms: u64,\n ) -> Self {\n let trace_id = stable_trace_id(session_id, event_id);\n let span_id = stable_span_id(&format!(\n \"{session_id}:{event_id}:{tool_call_id}:{start_time_unix_nano}\"\n ));\n\n let mut attributes = vec![\n (\"session_id\".to_string(), session_id.to_string()),\n (\"event_id\".to_string(), event_id.to_string()),\n (\"tool_call_id\".to_string(), tool_call_id.to_string()),\n (\"tool_name\".to_string(), tool_name.to_string()),\n (\"seq_op\".to_string(), seq_op.to_string()),\n (\"bridge.ok\".to_string(), ok.to_string()),\n (\"bridge.duration_ms\".to_string(), duration_ms.to_string()),\n ];\n if let Some(msg) = error {\n attributes.push((\"error.message\".to_string(), msg.to_string()));\n }\n\n Self {\n trace_id,\n span_id,\n parent_span_id: String::new(),\n name: \"everruns.tool_call\".to_string(),\n kind: 3,\n start_time_unix_nano,\n end_time_unix_nano,\n status_code: if ok { 1 } else { 2 },\n status_message: error.map(|s| s.to_string()),\n attributes,\n }\n }\n}\n\n#[derive(Debug, Clone, Default)]\npub struct MapleExporterStats {\n pub enqueued: u64,\n pub sent: u64,\n pub failed: u64,\n pub dropped: u64,\n}\n\n#[derive(Default)]\nstruct MapleExporterStatsAtomic {\n enqueued: AtomicU64,\n sent: AtomicU64,\n failed: AtomicU64,\n dropped: AtomicU64,\n}\n\nstruct WorkerTarget {\n traces_endpoint: String,\n ingest_key: String,\n client: Client,\n}\n\npub struct MapleTraceExporter {\n tx: SyncSender<MapleSpan>,\n stats: Arc<MapleExporterStatsAtomic>,\n}\n\nimpl MapleTraceExporter {\n pub fn from_env() -> Result<Option<Self>, MapleConfigError> {\n let Some(config) = MapleExporterConfig::from_env()? else {\n return Ok(None);\n };\n Ok(Some(Self::new(config)))\n }\n\n pub fn new(config: MapleExporterConfig) -> Self {\n let (tx, rx) = sync_channel(config.queue_capacity.max(1));\n let stats = Arc::new(MapleExporterStatsAtomic::default());\n let worker_stats = Arc::clone(&stats);\n thread::spawn(move || worker_main(rx, config, worker_stats));\n Self { tx, stats }\n }\n\n pub fn emit_span(&self, span: MapleSpan) {\n if self.tx.try_send(span).is_ok() {\n self.stats.enqueued.fetch_add(1, Ordering::Relaxed);\n } else {\n self.stats.dropped.fetch_add(1, Ordering::Relaxed);\n }\n }\n\n pub fn stats(&self) -> MapleExporterStats {\n MapleExporterStats {\n enqueued: self.stats.enqueued.load(Ordering::Relaxed),\n sent: self.stats.sent.load(Ordering::Relaxed),\n failed: self.stats.failed.load(Ordering::Relaxed),\n dropped: self.stats.dropped.load(Ordering::Relaxed),\n }\n }\n}\n\nfn worker_main(\n rx: Receiver<MapleSpan>,\n config: MapleExporterConfig,\n stats: Arc<MapleExporterStatsAtomic>,\n) {\n let worker_targets: Vec<WorkerTarget> = config\n .targets\n .iter()\n .map(|target| WorkerTarget {\n traces_endpoint: target.traces_endpoint.clone(),\n ingest_key: target.ingest_key.clone(),\n client: Client::builder()\n .connect_timeout(config.connect_timeout)\n .timeout(config.request_timeout)\n .build()\n .expect(\"failed to build maple exporter HTTP client\"),\n })\n .collect();\n\n let mut batch = Vec::with_capacity(config.max_batch_size.max(1));\n let mut disconnected = false;\n\n while !disconnected {\n match rx.recv_timeout(config.flush_interval) {\n Ok(span) => batch.push(span),\n Err(RecvTimeoutError::Timeout) => {}\n Err(RecvTimeoutError::Disconnected) => {\n disconnected = true;\n }\n }\n\n while batch.len() < config.max_batch_size {\n match rx.try_recv() {\n Ok(span) => batch.push(span),\n Err(TryRecvError::Empty) => break,\n Err(TryRecvError::Disconnected) => {\n disconnected = true;\n break;\n }\n }\n }\n\n if !batch.is_empty() {\n flush_batch(&config, &worker_targets, &batch, &stats);\n batch.clear();\n }\n }\n}\n\nfn flush_batch(\n config: &MapleExporterConfig,\n worker_targets: &[WorkerTarget],\n spans: &[MapleSpan],\n stats: &Arc<MapleExporterStatsAtomic>,\n) {\n let spans_payload: Vec<Value> = spans.iter().map(encode_span).collect();\n let resource_attrs = build_resource_attrs(config);\n let payload = json!({\n \"resourceSpans\": [\n {\n \"resource\": {\n \"attributes\": resource_attrs\n },\n \"scopeSpans\": [\n {\n \"scope\": { \"name\": config.scope_name },\n \"spans\": spans_payload\n }\n ]\n }\n ]\n });\n\n let body = payload.to_string();\n for target in worker_targets {\n let sent = target\n .client\n .post(&target.traces_endpoint)\n .header(\"content-type\", \"application/json\")\n .header(\"x-maple-ingest-key\", &target.ingest_key)\n .body(body.clone())\n .send();\n\n match sent {\n Ok(resp) if resp.status().is_success() => {\n stats.sent.fetch_add(spans.len() as u64, Ordering::Relaxed);\n }\n Ok(_) | Err(_) => {\n stats\n .failed\n .fetch_add(spans.len() as u64, Ordering::Relaxed);\n }\n }\n }\n}\n\nfn build_resource_attrs(config: &MapleExporterConfig) -> Vec<Value> {\n let mut attrs = vec![\n otlp_string_attr(\"service.name\", &config.service_name),\n otlp_string_attr(\"deployment.environment\", &config.deployment_environment),\n ];\n\n if let Some(version) = &config.service_version {\n attrs.push(otlp_string_attr(\"service.version\", version));\n }\n\n attrs\n}\n\nfn encode_span(span: &MapleSpan) -> Value {\n json!({\n \"traceId\": span.trace_id,\n \"spanId\": span.span_id,\n \"parentSpanId\": span.parent_span_id,\n \"name\": span.name,\n \"kind\": span.kind,\n \"startTimeUnixNano\": span.start_time_unix_nano.to_string(),\n \"endTimeUnixNano\": span.end_time_unix_nano.to_string(),\n \"attributes\": span\n .attributes\n .iter()\n .map(|(key, value)| otlp_string_attr(key, value))\n .collect::<Vec<Value>>(),\n \"status\": {\n \"code\": span.status_code,\n \"message\": span.status_message.clone().unwrap_or_default()\n }\n })\n}\n\nfn otlp_string_attr(key: &str, value: &str) -> Value {\n json!({\n \"key\": key,\n \"value\": { \"stringValue\": value }\n })\n}\n\nfn parse_targets_from_env() -> Result<Vec<MapleIngestTarget>, MapleConfigError> {\n let mut targets = Vec::new();\n\n let local_endpoint = std::env::var(\"SEQ_EVERRUNS_MAPLE_LOCAL_ENDPOINT\")\n .ok()\n .and_then(non_empty);\n let local_key = std::env::var(\"SEQ_EVERRUNS_MAPLE_LOCAL_INGEST_KEY\")\n .ok()\n .and_then(non_empty);\n match (local_endpoint, local_key) {\n (Some(endpoint), Some(key)) => targets.push(MapleIngestTarget {\n traces_endpoint: endpoint,\n ingest_key: key,\n }),\n (None, None) => {}\n _ => {\n return Err(MapleConfigError::IncompletePair {\n prefix: \"SEQ_EVERRUNS_MAPLE_LOCAL\",\n });\n }\n }\n\n let hosted_endpoint = std::env::var(\"SEQ_EVERRUNS_MAPLE_HOSTED_ENDPOINT\")\n .ok()\n .and_then(non_empty);\n let hosted_key = std::env::var(\"SEQ_EVERRUNS_MAPLE_HOSTED_INGEST_KEY\")\n .ok()\n .and_then(non_empty);\n match (hosted_endpoint, hosted_key) {\n (Some(endpoint), Some(key)) => targets.push(MapleIngestTarget {\n traces_endpoint: endpoint,\n ingest_key: key,\n }),\n (None, None) => {}\n _ => {\n return Err(MapleConfigError::IncompletePair {\n prefix: \"SEQ_EVERRUNS_MAPLE_HOSTED\",\n });\n }\n }\n\n let csv_endpoints = split_csv_env(\"SEQ_EVERRUNS_MAPLE_TRACES_ENDPOINTS\");\n let csv_keys = split_csv_env(\"SEQ_EVERRUNS_MAPLE_INGEST_KEYS\");\n if !csv_endpoints.is_empty() || !csv_keys.is_empty() {\n if csv_endpoints.len() != csv_keys.len() {\n return Err(MapleConfigError::EndpointKeyCountMismatch {\n endpoints: csv_endpoints.len(),\n keys: csv_keys.len(),\n });\n }\n for (endpoint, key) in csv_endpoints.into_iter().zip(csv_keys.into_iter()) {\n targets.push(MapleIngestTarget {\n traces_endpoint: endpoint,\n ingest_key: key,\n });\n }\n }\n\n Ok(dedup_targets(targets))\n}\n\nfn split_csv_env(key: &str) -> Vec<String> {\n std::env::var(key)\n .ok()\n .map(|raw| raw.split(',').filter_map(non_empty).collect())\n .unwrap_or_default()\n}\n\nfn dedup_targets(targets: Vec<MapleIngestTarget>) -> Vec<MapleIngestTarget> {\n let mut out: Vec<MapleIngestTarget> = Vec::new();\n for target in targets {\n let exists = out.iter().any(|existing| {\n existing.traces_endpoint == target.traces_endpoint\n && existing.ingest_key == target.ingest_key\n });\n if !exists {\n out.push(target);\n }\n }\n out\n}\n\nfn env_usize(key: &str) -> Option<usize> {\n std::env::var(key)\n .ok()\n .and_then(|v| v.trim().parse::<usize>().ok())\n}\n\nfn env_u64(key: &str) -> Option<u64> {\n std::env::var(key)\n .ok()\n .and_then(|v| v.trim().parse::<u64>().ok())\n}\n\nfn non_empty(s: impl AsRef<str>) -> Option<String> {\n let value = s.as_ref().trim();\n if value.is_empty() {\n None\n } else {\n Some(value.to_string())\n }\n}\n\npub fn stable_trace_id(session_id: &str, event_id: &str) -> String {\n let a = fnv1a64(session_id.as_bytes());\n let b = fnv1a64(event_id.as_bytes());\n format!(\"{a:016x}{b:016x}\")\n}\n\npub fn stable_span_id(seed: &str) -> String {\n format!(\"{:016x}\", fnv1a64(seed.as_bytes()))\n}\n\nfn fnv1a64(data: &[u8]) -> u64 {\n let mut hash: u64 = 0xcbf29ce484222325;\n for byte in data {\n hash ^= *byte as u64;\n hash = hash.wrapping_mul(0x100000001b3);\n }\n hash\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use std::io::{Read, Write};\n use std::net::TcpListener;\n use std::sync::Mutex;\n use std::time::Duration;\n\n static ENV_LOCK: Mutex<()> = Mutex::new(());\n\n fn unset_maple_envs() {\n let keys = [\n \"SEQ_EVERRUNS_MAPLE_LOCAL_ENDPOINT\",\n \"SEQ_EVERRUNS_MAPLE_LOCAL_INGEST_KEY\",\n \"SEQ_EVERRUNS_MAPLE_HOSTED_ENDPOINT\",\n \"SEQ_EVERRUNS_MAPLE_HOSTED_INGEST_KEY\",\n \"SEQ_EVERRUNS_MAPLE_TRACES_ENDPOINTS\",\n \"SEQ_EVERRUNS_MAPLE_INGEST_KEYS\",\n \"SEQ_EVERRUNS_MAPLE_SERVICE_NAME\",\n \"SEQ_EVERRUNS_MAPLE_SERVICE_VERSION\",\n \"SEQ_EVERRUNS_MAPLE_ENV\",\n \"SEQ_EVERRUNS_MAPLE_SCOPE_NAME\",\n \"SEQ_EVERRUNS_MAPLE_QUEUE_CAPACITY\",\n \"SEQ_EVERRUNS_MAPLE_MAX_BATCH_SIZE\",\n \"SEQ_EVERRUNS_MAPLE_FLUSH_INTERVAL_MS\",\n \"SEQ_EVERRUNS_MAPLE_CONNECT_TIMEOUT_MS\",\n \"SEQ_EVERRUNS_MAPLE_REQUEST_TIMEOUT_MS\",\n ];\n for key in keys {\n std::env::remove_var(key);\n }\n }\n\n #[test]\n fn stable_ids_have_expected_length() {\n let trace_id = stable_trace_id(\"session-1\", \"event-1\");\n let span_id = stable_span_id(\"session-1:event-1:tc1\");\n assert_eq!(trace_id.len(), 32);\n assert_eq!(span_id.len(), 16);\n }\n\n #[test]\n fn reads_dual_target_env_config() {\n let _guard = ENV_LOCK.lock().expect(\"lock env\");\n unset_maple_envs();\n std::env::set_var(\n \"SEQ_EVERRUNS_MAPLE_LOCAL_ENDPOINT\",\n \"http://ingest.maple.localhost/v1/traces\",\n );\n std::env::set_var(\"SEQ_EVERRUNS_MAPLE_LOCAL_INGEST_KEY\", \"maple_pk_local\");\n std::env::set_var(\n \"SEQ_EVERRUNS_MAPLE_HOSTED_ENDPOINT\",\n \"https://ingest.1focus.ai/v1/traces\",\n );\n std::env::set_var(\"SEQ_EVERRUNS_MAPLE_HOSTED_INGEST_KEY\", \"maple_pk_hosted\");\n\n let cfg = MapleExporterConfig::from_env()\n .expect(\"env parse\")\n .expect(\"config should exist\");\n assert_eq!(cfg.targets.len(), 2);\n assert!(cfg\n .targets\n .iter()\n .any(|t| t.traces_endpoint == \"http://ingest.maple.localhost/v1/traces\"));\n assert!(cfg\n .targets\n .iter()\n .any(|t| t.traces_endpoint == \"https://ingest.1focus.ai/v1/traces\"));\n unset_maple_envs();\n }\n\n #[test]\n fn csv_target_env_mismatch_returns_error() {\n let _guard = ENV_LOCK.lock().expect(\"lock env\");\n unset_maple_envs();\n std::env::set_var(\n \"SEQ_EVERRUNS_MAPLE_TRACES_ENDPOINTS\",\n \"http://ingest.maple.localhost/v1/traces,https://ingest.1focus.ai/v1/traces\",\n );\n std::env::set_var(\"SEQ_EVERRUNS_MAPLE_INGEST_KEYS\", \"maple_pk_only_one\");\n\n let err = MapleExporterConfig::from_env().expect_err(\"mismatch should error\");\n assert!(matches!(\n err,\n MapleConfigError::EndpointKeyCountMismatch { .. }\n ));\n unset_maple_envs();\n }\n\n #[test]\n fn incomplete_local_pair_returns_error() {\n let _guard = ENV_LOCK.lock().expect(\"lock env\");\n unset_maple_envs();\n std::env::set_var(\n \"SEQ_EVERRUNS_MAPLE_LOCAL_ENDPOINT\",\n \"http://ingest.maple.localhost/v1/traces\",\n );\n\n let err = MapleExporterConfig::from_env().expect_err(\"incomplete pair should error\");\n assert!(matches!(\n err,\n MapleConfigError::IncompletePair {\n prefix: \"SEQ_EVERRUNS_MAPLE_LOCAL\"\n }\n ));\n unset_maple_envs();\n }\n\n #[test]\n fn exporter_sends_span_to_ingest_endpoint() {\n let listener = TcpListener::bind(\"127.0.0.1:0\").expect(\"bind test server\");\n let addr = listener.local_addr().expect(\"local addr\");\n\n let server = std::thread::spawn(move || {\n if let Ok((mut stream, _)) = listener.accept() {\n let mut req = [0_u8; 8192];\n let _ = stream.read(&mut req);\n let response =\n b\"HTTP/1.1 200 OK\\r\\nContent-Type: application/json\\r\\nContent-Length: 2\\r\\n\\r\\n{}\";\n let _ = stream.write_all(response);\n let _ = stream.flush();\n }\n });\n\n let config = MapleExporterConfig {\n service_name: \"seq-everruns-bridge-test\".to_string(),\n service_version: None,\n deployment_environment: \"test\".to_string(),\n scope_name: \"seq_everruns_bridge\".to_string(),\n queue_capacity: 32,\n max_batch_size: 8,\n flush_interval: Duration::from_millis(10),\n connect_timeout: Duration::from_millis(200),\n request_timeout: Duration::from_millis(200),\n targets: vec![MapleIngestTarget {\n traces_endpoint: format!(\"http://{addr}/v1/traces\"),\n ingest_key: \"maple_pk_test\".to_string(),\n }],\n };\n\n let exporter = MapleTraceExporter::new(config);\n let span = MapleSpan::for_tool_call(\n \"session-1\",\n \"event-1\",\n \"tool-1\",\n \"seq_ping\",\n \"ping\",\n true,\n None,\n 1_739_890_000_000_000_000,\n 1_739_890_000_100_000_000,\n 100,\n );\n exporter.emit_span(span);\n\n std::thread::sleep(Duration::from_millis(80));\n let stats = exporter.stats();\n assert!(stats.sent >= 1, \"expected at least one sent span\");\n let _ = server.join();\n }\n}\n" }, { "path": "docs/ai-dev-layout.md", "content": "# `.ai/` Dev Layout\n\nUse `.ai/` aggressively for local AI-assisted development, but keep the split\nbetween tracked project intelligence and disposable local artifacts explicit.\n\nTracked in this repo:\n\n- `.ai/docs/`\n- `.ai/recipes/`\n- `.ai/repos.toml`\n- curated `.ai/skills/` entries that are intentionally committed\n\nIgnored local-dev buckets:\n\n- `.ai/reviews/`\n - generated PR feedback packets and review snapshots\n- `.ai/test/`\n - AI scratch tests and local validation files\n- `.ai/tmp/`\n - throwaway intermediate files\n- `.ai/cache/`\n - cached derivations or precomputed local state\n- `.ai/artifacts/`\n - generated outputs worth inspecting locally but not committing\n- `.ai/traces/`\n - local trace dumps or trace export scratch\n- `.ai/generated/`\n - one-off generated code/docs that should be promoted elsewhere if kept\n- `.ai/scratch/`\n - free-form local notes, prompts, and experiments\n\nRules of thumb:\n\n1. If it is canonical project knowledge, promote it out of the local bucket and\n track it intentionally.\n2. If it is generated, per-machine, or iteration-only, keep it under one of the\n ignored buckets above.\n3. Prefer `.ai/` over random top-level temp files so local AI/dev state stays\n contained and easy to clean up.\n" }, { "path": "docs/ai-run-task-fast-path.md", "content": "# AI Run Task Fast Path\n\nGoal: let AI add a run task in one edit, return a runnable `f ...` command, and optionally push.\n\n## Prompt Contract\n\n```text\nmake public task <doc-path.md> <thing>\nmake internal task <doc-path.md> <thing>\n```\n\n`<doc-path.md>` is implementation context. Do not edit docs unless asked.\n\n## File Targeting\n\n- Public: `~/run/flow.toml`\n- Internal shared: `~/run/i/flow.toml`\n- Internal project (only if project is explicitly requested): `~/run/i/<project>/flow.toml`\n\n## Fast Rules\n\n- Read only:\n - `<doc-path.md>`\n - target `flow.toml`\n- Edit one `flow.toml` file.\n- Add one `[[tasks]]` block unless user asks for multiple.\n- Required fields: `name`, `description`, `command`.\n- Add `interactive = true` only for prompts/TUI.\n- Use `\"$@\"` passthrough when args should flow through.\n- Keep shell idempotent and non-destructive.\n\n## Required AI Reply Format\n\n```text\nChanged:\n- /abs/path/to/flow.toml\n\nRun:\nf <r|ri|rip ...> <task-name> [args]\n\nShare:\ncd <repo> && git add <flow.toml> && git commit -m \"add <task-name>\" && git push\n```\n\nShortcut map:\n- Public -> `f r <task>`\n- Internal shared -> `f ri <task>`\n- Internal project -> `f rip <project> <task>`\n\n## Push Confidence Gate\n\nInclude `Share` command only when all are true:\n\n- single-file `flow.toml` change\n- no secrets\n- no destructive commands\n- no uncertain behavior\n\nOtherwise:\n\n```text\nShare:\nskip (manual review)\n```\n" }, { "path": "docs/ai-task-fast-path-guide.md", "content": "# MoonBit AI Task Fast Path Guide\n\nThis guide is the practical playbook for running Flow MoonBit AI tasks at the lowest possible invocation latency.\n\nIt covers:\n\n- when to use `f` vs `fai`\n- how daemon mode actually works\n- exact env knobs for tuning\n- benchmark workflow to validate improvements\n- troubleshooting for common regressions\n\n---\n\n## 1. Runtime Modes\n\nFlow supports multiple runtime paths for `.ai/tasks/*.mbt`:\n\n1. `moon run` path \n `FLOW_AI_TASK_RUNTIME=moon-run f ai:flow/dev-check` \n Highest flexibility, highest overhead.\n\n2. Cached binary path through `f` \n `FLOW_AI_TASK_RUNTIME=cached f ai:flow/dev-check` \n Uses build cache, still pays full `f` process startup.\n\n3. Daemon path through `f` \n `f tasks run-ai --daemon ai:flow/dev-check` \n Uses `ai-taskd` over Unix socket, still pays `f` process startup.\n\n4. Fast daemon client (`fai`) \n `fai ai:flow/dev-check` \n Lowest invocation overhead for hot loops.\n\n---\n\n## 2. Recommended Setup (Low Latency)\n\nFrom `~/code/flow`:\n\n```bash\nf install-ai-fast-client\nf tasks daemon start\n```\n\nWhat this gives you:\n\n- `~/.local/bin/fai` installed (low-overhead client).\n- `ai-taskd` running and warm (`~/.flow/run/ai-taskd.sock`).\n\nVerify:\n\n```bash\nwhich fai\nfai --help\nf tasks daemon status\nfai ai:flow/noop\n```\n\nFor always-on daemon across login sessions (recommended for stable latency):\n\n```bash\nf ai-taskd-launchd-install\nf ai-taskd-launchd-status\n```\n\n---\n\n## 3. Fast-Path Architecture\n\n### `fai` path\n\n1. `fai` sends a compact request to `~/.flow/run/ai-taskd.sock`\n2. `ai-taskd` resolves task selector (fast exact path first)\n3. `ai-taskd` reuses cached binary artifact when available\n4. task process runs with `FLOW_AI_TASK_PROJECT_ROOT` set\n\n### Key optimizations in current implementation\n\n- daemon discovery cache with TTL:\n - `FLOW_AI_TASKD_DISCOVERY_TTL_MS` (default `750`)\n- daemon artifact cache with TTL:\n - `FLOW_AI_TASKD_ARTIFACT_TTL_MS` (default `1500`)\n- fast selector resolution:\n - exact selectors skip full recursive task discovery\n- faster cache key computation:\n - file metadata fingerprints instead of full content hashing\n - Moon version cached on disk with TTL\n\nMoon version knobs:\n\n- `FLOW_AI_TASK_MOON_VERSION` (explicit override)\n- `FLOW_AI_TASK_MOON_VERSION_TTL_SECS` (default `43200`)\n\nWire protocol knobs:\n\n- `fai --protocol msgpack` (default)\n- `fai --protocol json` (compat / debugging)\n\n---\n\n## 4. Using `f` with Fast Client Preference\n\n`f` can optionally route AI task dispatch through the fast client when daemon mode is enabled.\n\nRequired:\n\n```bash\nexport FLOW_AI_TASK_DAEMON=1\nexport FLOW_AI_TASK_FAST_CLIENT=1\n```\n\nOptional selector control:\n\n```bash\nexport FLOW_AI_TASK_FAST_SELECTORS='ai:flow/noop,ai:flow/bench-cli,ai:project/*'\n```\n\nOptional client binary override:\n\n```bash\nexport FLOW_AI_TASK_FAST_CLIENT_BIN=\"$HOME/.local/bin/fai\"\n```\n\nWithout `FLOW_AI_TASK_FAST_CLIENT=1`, `f` keeps normal daemon behavior.\n\n---\n\n## 5. `fai` CLI Usage\n\n```bash\nfai [--root PATH] [--socket PATH] [--protocol json|msgpack] [--no-cache] [--capture-output] [--timings] <selector> [-- <args...>]\nfai [--root PATH] [--socket PATH] [--protocol json|msgpack] [--no-cache] [--capture-output] [--timings] --batch-stdin\n```\n\nExamples:\n\n```bash\nfai ai:flow/noop\nfai --root ~/code/flow ai:flow/bench-cli -- --iterations 50\nfai --no-cache ai:flow/dev-check\nfai --timings ai:flow/noop\nprintf 'ai:flow/noop\\nai:flow/noop\\n' | fai --batch-stdin\n```\n\nNotes:\n\n- default is no-capture mode for lower overhead\n- use `--capture-output` if you need command output returned through client response\n- use `--timings` to print server-side phase timings (`resolve_us`, `run_us`, `total_us`)\n- use `--batch-stdin` for pooled client bursts (single client process, multiple requests)\n\n---\n\n## 6. Benchmark Procedure\n\nRun baseline runtime benchmark:\n\n```bash\nf bench-ai-runtime --iterations 80 --warmup 10 --json-out /tmp/flow_ai_runtime.json\n```\n\nThis includes:\n\n- `moon_run_noop`\n- `cached_noop`\n- `daemon_cached_noop`\n- `cached_binary_direct`\n- `daemon_client_noop` (if `ai-taskd-client` binary is present)\n\nFor focused hot-loop comparisons:\n\n```bash\npython3 - <<'PY'\nimport subprocess,time,statistics\nfrom pathlib import Path\nroot=Path('~/code/flow').expanduser()\ncases=[\n ('f_daemon',['./target/debug/f','tasks','run-ai','--daemon','ai:flow/noop']),\n ('fai',['fai','ai:flow/noop']),\n ('f_cached',['./target/debug/f','ai:flow/noop']),\n]\nfor name,cmd in cases:\n xs=[]\n for i in range(60):\n t0=time.perf_counter()\n p=subprocess.run(cmd,cwd=root,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)\n dt=(time.perf_counter()-t0)*1000\n if p.returncode!=0: raise SystemExit((name,p.returncode))\n if i>=10: xs.append(dt)\n xs=sorted(xs)\n pct=lambda p: xs[int((len(xs)-1)*p)]\n print(name,'p50',round(pct(0.5),2),'p95',round(pct(0.95),2),'mean',round(statistics.mean(xs),2))\nPY\n```\n\n---\n\n## 7. Operational Recommendations\n\nUse this default profile for lowest latency:\n\n```bash\nexport FLOW_AI_TASK_DAEMON=1\nexport FLOW_AI_TASK_FAST_CLIENT=1\nexport FLOW_AI_TASK_FAST_SELECTORS='ai:flow/*'\nf tasks daemon start\n```\n\nThen:\n\n- latency-critical loops: `fai ai:...`\n- normal dev ergonomics: `f ai:...` (auto fast-client when selectors match)\n\n---\n\n## 8. Troubleshooting\n\n### `fai` says cannot connect to socket\n\nStart daemon:\n\n```bash\nf tasks daemon start\n```\n\nCheck:\n\n```bash\nf tasks daemon status\nls -l ~/.flow/run/ai-taskd.sock\n```\n\nOr install persistent daemon:\n\n```bash\nf ai-taskd-launchd-install\n```\n\n### Task not found with `fai`\n\nUse full selector:\n\n```bash\nf tasks list | rg '^ai:'\nfai ai:flow/dev-check\n```\n\n### Latency suddenly regressed\n\nCheck:\n\n```bash\nps -Ao pcpu,pmem,comm | sort -k1 -nr | head -n 20\nf tasks daemon status\n```\n\nThen rerun benchmark with warmup.\n\n### Need strict correctness instead of lowest overhead\n\nUse `--capture-output` on `fai` for output-capture parity.\n\n### Need in-daemon stage attribution for profiling\n\n```bash\nfai --timings ai:flow/noop\nFLOW_AI_TASKD_TIMINGS_LOG=1 f tasks daemon serve\n```\n\n---\n\n## 9. Implemented Optimization Set\n\nImplemented in this iteration:\n\n1. always-on daemon support via launchd tasks (`ai-taskd-launchd-*`)\n2. binary request framing support (`msgpack`) in `fai` + `ai-taskd`\n3. pooled client burst mode via `fai --batch-stdin`\n4. per-request stage timings exposed via `fai --timings` and daemon timing logs\n\nPotential next frontier:\n\n1. keep a persistent client-side socket session with framed multi-request protocol\n2. add lock-free shared-memory ring for local burst dispatch if socket overhead becomes dominant\n3. push per-stage timing aggregation into benchmark JSON outputs for automatic regression gating\n" }, { "path": "docs/ai-traces.md", "content": "# AI Traces (Flow)\n\nUse this doc when collecting context for debugging or development work in `~/code/flow`.\nThe goal is to keep trace collection low overhead while still capturing enough signal for fast fixes.\n\n## Quick start\n\n- Proxy traces summary:\n - `~/.config/flow/proxy/trace-summary.json`\n- Last trace event (CLI):\n - `f proxy last`\n- Stream traces (CLI):\n - `f proxy trace`\n\n## Trace sources\n\n- **Proxy ring buffer summary**\n - Path: `~/.config/flow/proxy/trace-summary.json`\n- **Fish shell IO traces**\n - Path: `${XDG_DATA_HOME:-~/.local/share}/fish/io-trace/last.meta`\n - Command: `fish-trace last`\n\n## When to use which\n\n- Start with the summary file to find errors/slow requests.\n- Use `f proxy last` when you need the newest request details.\n- Use `f proxy trace` to tail a stream during repro.\n\n## Safety notes\n\n- Summary parsing is cheap and safe to run anytime.\n- If proxy is not running, `f proxy` commands will fail; fall back to the summary file and fish traces.\n\n## Skills + harness loading\n\nCodex skills are discovered from `~/.codex/skills` and injected by the AI harness.\nIf a new skill was added or edited, restart the agent or re-list skills to refresh.\nThis repo ships trace guidance via the `flow-dev-traces` skill.\n" }, { "path": "docs/anonymous-telemetry-contract.md", "content": "# Anonymous Telemetry Contract (Flow CLI)\n\nFlow emits anonymous command telemetry for product/training quality when analytics is enabled.\n\n## Event\n\n- `type`: `flow.command.v1`\n- `schema_version`: `1`\n- `event_id`: UUID\n- `name`: normalized command path (for unknown commands: `task-shortcut`)\n- `ok`: command success\n- `at`: event timestamp (ms)\n- `source`: `flow-cli`\n- `payload`:\n - `anon_user_id` (rotates every 30 days)\n - `project_fingerprint` (rotates every 30 days)\n - `command_path`\n - `success`\n - `exit_code` (currently null)\n - `duration_ms`\n - `flags_used`\n - `flow_version`\n - `os`\n - `arch`\n - `interactive`\n - `ci`\n\n## Privacy Guarantees\n\n- No usernames/emails.\n- No prompts/assistant messages.\n- No file contents.\n- No absolute paths (project fingerprint is HMAC-based and rotated).\n- No stable raw install identifier in payload.\n\n## Endpoint\n\nDefault endpoint:\n\n`https://api.myflow.sh/api/telemetry/flow`\n\nCan be overridden in `flow.toml`:\n\n```toml\n[analytics]\nendpoint = \"https://api.myflow.sh/api/telemetry/flow\"\nenabled = true\nsample_rate = 1.0\n```\n" }, { "path": "docs/ascii-commit-visualization-pipeline.md", "content": "# ASCII Commit Visualization Pipeline\n\nThis explains how commit analysis data becomes ASCII-style diagrams in myflow.\n\nScope:\n\n- generation and storage in Flow\n- API serving via Flow server\n- runtime diagram rendering in myflow via `box-of-rain`\n\n---\n\n## 1. Commit Analysis Generation\n\nFlow generates commit explanations with:\n\n```bash\nf explain-commits 3 --force\n```\n\nImplementation:\n\n- `src/explain_commits.rs`\n- Uses `ai-task.sh` with provider/model fixed to Kimi defaults (`nvidia` + `moonshotai/kimi-k2.5`).\n- For each commit, Flow gathers:\n - `sha`, `short_sha`, `subject`, `author`, `date`\n - file list from `git diff --name-only`\n - truncated diff payload (max chars guard)\n\nOutput per project (default):\n\n- `docs/commits/<date>-<short_sha>-<slug>.md`\n- `docs/commits/<date>-<short_sha>-<slug>.json`\n- `docs/commits/.index.json` (digest/index cache)\n\nNotes:\n\n- `--force` bypasses digest skip logic.\n- `--out-dir` can override default output location.\n\n---\n\n## 2. Storage Format\n\nThe sidecar `.json` mirrors Flow’s `ExplainedCommit` shape:\n\n- `sha`\n- `short_sha`\n- `subject`\n- `author`\n- `date`\n- `summary`\n- `changes`\n- `files` (array of changed file paths)\n- `markdown_file`\n- `generated_at`\n\nThis is the source of truth consumed by the UI.\n\n---\n\n## 3. API Serving Layer\n\nFlow server exposes commit explanations over HTTP:\n\n- `GET /projects/:name/commit-explanations?limit=50`\n- `GET /projects/:name/commit-explanations/:sha`\n\nImplementation:\n\n- `src/log_server.rs`:\n - `project_commit_explanations`\n - `project_commit_explanation_detail`\n- data loader functions are in `src/explain_commits.rs`:\n - `list_explained_commits`\n - `get_explained_commit`\n\n---\n\n## 4. myflow Data Consumption\n\nmyflow fetches these endpoints through `flowFetch` model atoms:\n\n- `/projects/$project/commit-explanations`\n- `/projects/$project/commit-explanations/$sha`\n\nModel file:\n\n- `~/code/myflow/web/lib/models/flow-projects.ts`\n\nRelevant type:\n\n- `FlowExplainedCommit`\n\n---\n\n## 5. Diagram Generation (ASCII -> SVG)\n\nDiagram rendering is client-side in myflow and uses `box-of-rain`.\n\nTheme/options:\n\n- `~/code/myflow/web/lib/diagram-theme.ts`\n- shared `DIAGRAM_SVG_OPTIONS`:\n - transparent background\n - mono font\n - light/dark foreground colors\n\n### 5.1 What `box-of-rain` actually does\n\n`box-of-rain` has two explicit stages:\n\n1. layout stage: `render(nodeDef)` \n Input is a graph description (`NodeDef` + `connections`). \n Output is a multiline ASCII canvas (boxes, borders, arrows, connectors).\n2. paint stage: `renderSvg(ascii, svgOptions)` \n Input is the ASCII text grid. \n Output is an SVG string where each character is positioned with fixed-width metrics.\n\nImportant: layout and paint are separate. \nIf shape/connectors are wrong, the bug is in `NodeDef`/connections. \nIf colors/spacing/fonts are wrong, the bug is in `SvgOptions`.\n\nCore graph primitives used in myflow:\n\n- `id`: stable node identifier for edge wiring.\n- `children`: lines rendered inside a box.\n- `border`: visual style (`rounded`, `bold`).\n- `childDirection`: relative arrangement (`horizontal`).\n- `connections`: explicit edges, each with:\n - `from`, `to`\n - `fromSide`, `toSide` (`left|right|top|bottom`).\n\nTimeline shape (conceptual):\n\n```text\nc0 ──> c1 ──> c2\n```\n\nFiles impact shape (conceptual):\n\n```text\ncommit ──> dirA\ncommit ──> dirB\ncommit ──> dirC\n```\n\n### Timeline diagram\n\nFile:\n\n- `~/code/myflow/web/lib/commit-timeline-diagram.tsx`\n\nAlgorithm:\n\n1. take up to 8 newest commits\n2. reverse to oldest -> newest\n3. build one rounded node per commit:\n - line 1: `short_sha`\n - lines 2+: truncated subject (2 lines max)\n4. connect node `i -> i+1` (right to left sides)\n5. render:\n - `render(nodeDef)` -> ASCII layout\n - `renderSvg(ascii, DIAGRAM_SVG_OPTIONS)` -> SVG\n6. inject SVG into DOM with `dangerouslySetInnerHTML`\n\nConceptual `NodeDef` sketch:\n\n```ts\n{\n children: [\n { id: \"c0\", border: \"rounded\", children: [\"2daa3fd\", \"feat: sub-agent\"] },\n { id: \"c1\", border: \"rounded\", children: [\"f298c48\", \"memories rollout\"] },\n ],\n childDirection: \"horizontal\",\n connections: [{ from: \"c0\", to: \"c1\", fromSide: \"right\", toSide: \"left\" }],\n}\n```\n\nMounted at:\n\n- `~/code/myflow/web/pages/flow/$project/index.tsx`\n\n### Files impact diagram\n\nFile:\n\n- `~/code/myflow/web/lib/files-impact-diagram.tsx`\n\nAlgorithm:\n\n1. group `commit.files` by top path bucket:\n - first 2 segments when possible\n2. create bold commit node\n3. create one rounded directory node per group:\n - dir label\n - up to 3 file names\n - `+N more` overflow line\n4. connect `commit -> each_dir`\n5. render ASCII then SVG with same theme options\n\nConceptual `NodeDef` sketch:\n\n```ts\n{\n children: [\n { id: \"commit\", border: \"bold\", children: [\"2daa3fd\", \"feat: sub-agent\"] },\n { id: \"d0\", border: \"rounded\", children: [\"codex-rs/core/\", \" agent.rs\", \" mod.rs\"] },\n ],\n childDirection: \"horizontal\",\n connections: [{ from: \"commit\", to: \"d0\", fromSide: \"right\", toSide: \"left\" }],\n}\n```\n\nMounted at:\n\n- `~/code/myflow/web/pages/flow/$project/commit/$sha.tsx`\n\n---\n\n## 6. Performance and Limits\n\n- both diagram components are wrapped in `useMemo`\n- timeline hard limit: 8 commits\n- subject lines are truncated for stable node widths\n- files list per group is capped in-node (full list still shown below diagram)\n\n---\n\n## 7. Common Failure Modes\n\n1. No commit data:\n - run `f explain-commits N` in the target repo\n2. API empty:\n - ensure Flow server is running (`f server`)\n - ensure project is registered in Flow\n3. Diagram package missing:\n - ensure `box-of-rain` dependency resolves in myflow runtime build\n4. BetterAuth `/api` base URL error in browser:\n - use absolute URL normalization in `web/lib/auth-client.ts` (relative `/api` alone is invalid for BetterAuth client config)\n\n---\n\n## 8. Quick End-to-End Check\n\nFrom target repo (example: codex):\n\n```bash\ncd ~/repos/openai/codex\nf explain-commits 3 --force\n```\n\nFrom Flow:\n\n```bash\nf server --host 127.0.0.1 --port 9050\ncurl 'http://127.0.0.1:9050/projects/codex/commit-explanations?limit=3'\n```\n\nThen open myflow:\n\n- project view: `/flow/codex`\n- commit view: `/flow/codex/commit/<sha>`\n" }, { "path": "docs/bench/cli-startup.md", "content": "# Flow CLI Startup Benchmark\n\nUse this to measure cold-ish user-facing Flow latency on cheap commands that should stay fast.\n\n## Run\n\n```bash\nf bench-cli-startup\n```\n\nUseful knobs:\n\n```bash\nf bench-cli-startup -- --iterations 30 --warmup 5\nf bench-cli-startup -- --flow-bin ./target/release/f\nf bench-cli-startup -- --json-out out/bench/cli-startup.json\n```\n\n## What it measures\n\n- `f --help`\n- `f --help-full`\n- `f info`\n- `f projects`\n- `f analytics status`\n- `f tasks list`\n- `f tasks dupes`\n\nThe script forces:\n\n- `CI=1`\n- `FLOW_ANALYTICS_DISABLE=1`\n\nThat keeps the benchmark focused on Flow startup and command dispatch instead of analytics prompts.\n\n## Readouts to track\n\n- `p50_ms`\n- `p95_ms`\n- `p99_ms`\n- `mean_ms`\n\nFor startup work, keep the policy simple:\n\n- optimize only if median improves\n- reject changes that materially regress `p95`\n- benchmark from the same binary and same repo fixture\n\n## Why these commands\n\nThese commands are the best early signal for startup overhead because they are local, cheap, non-interactive, and sensitive to unnecessary pre-dispatch work such as eager secrets loading and auto skill sync.\n" }, { "path": "docs/bench/moonbit-rust-ffi-boundary.md", "content": "# MoonBit <-> Rust FFI Boundary Benchmark\n\nThis benchmark measures raw call overhead between MoonBit (native C backend) and Rust host functions.\n\n## Scope\n\nMeasured:\n- Rust local math baseline (`rust_inline_add`, `rust_fn_add`)\n- Rust calling exported C ABI functions (`rust_extern_add`, `rust_extern_noop`)\n- MoonBit calling Rust-exported C ABI (`moon_ffi_add`, `moon_ffi_noop`)\n\nNot measured:\n- app-level task execution\n- process startup/teardown\n- end-to-end Flow command latency\n\n## Where the code lives\n\n- `bench/ffi_host_boundary/src/lib.rs`\n- `bench/ffi_host_boundary/src/bin/rust_boundary_bench.rs`\n- `bench/moon_ffi_boundary/main.mbt`\n- `bench/moon_ffi_boundary/moon.pkg.template.json`\n- `scripts/bench-moonbit-rust-ffi.py`\n- Flow task: `bench-ffi-boundary` in `flow.toml`\n\n## Run commands\n\nDirect script:\n\n```bash\ncd ~/code/flow\npython3 scripts/bench-moonbit-rust-ffi.py --iters 10000000 --json-out /tmp/ffi.json\n```\n\nWith machine-local tuning flags:\n\n```bash\ncd ~/code/flow\npython3 scripts/bench-moonbit-rust-ffi.py --iters 10000000 --native-opt --json-out /tmp/ffi_native.json\n```\n\nVia Flow:\n\n```bash\ncd ~/code/flow\nf bench-ffi-boundary --iters 10000000 --json-out /tmp/ffi_flow.json\n```\n\n## Latest measured numbers (this machine)\n\nMethod: 3 rounds each, 10M iterations/round, median ns/op.\n\n| metric | baseline | native-opt | tuned/base |\n|---|---:|---:|---:|\n| rust_extern_add | 2.7683 | 2.8291 | 1.022x |\n| rust_extern_noop | 2.7880 | 2.9140 | 1.045x |\n| moon_ffi_add | 0.9005 | 1.1075 | 1.230x |\n| moon_ffi_noop | 0.8576 | 0.8462 | 0.987x |\n\nInterpretation:\n- Boundary overhead is single-digit nanoseconds.\n- On this machine, `--native-opt` did not consistently improve results; it was mixed/slightly worse for most metrics.\n- You must benchmark on your target machine before locking optimization flags.\n\n## Important measurement caveat\n\n`moon_add` (pure MoonBit loop) can be optimized away by the compiler and report `0 ns`. Treat it as non-authoritative for boundary decisions.\n\nUse FFI metrics (`moon_ffi_*`, `rust_extern_*`) as the primary signal.\n\n## Optimizations implemented\n\n1. Exported host functions stripped to minimal arithmetic (removed internal `black_box`).\n2. Rust FFI functions marked `#[inline(never)]` to avoid accidental inlining in host-side tests.\n3. Rust bench crate release profile tightened:\n - `lto = \"fat\"`\n - `codegen-units = 1`\n - `panic = \"abort\"`\n - `strip = true`\n4. Moon native flags are configurable via template placeholder:\n - `cc-flags` in `moon.pkg.template.json`\n5. Benchmark script supports `--native-opt`:\n - Rust: `RUSTFLAGS=-C target-cpu=native`\n - Moon native: `-O3 -march=native -mtune=native`\n\n## Ideas borrowed from Moon toolchain\n\nFrom `~/repos/moonbitlang/moon`:\n- `Cargo.toml` uses explicit release profile controls (`lto`, `codegen-units`, `strip`) for predictable build/runtime tradeoffs.\n- Native pipeline exposes per-package `cc-flags` / `cc-link-flags` (schema in `crates/moonbuild/template/pkg.schema.json`).\n- TCC-run mode exists to speed dev-time run loops, not runtime performance; custom native flags disable that fast dev path.\n\nPractical implication:\n- For runtime benchmarks, tune native flags carefully and measure.\n- For developer iteration speed, avoid unnecessary custom flags when tcc-run is beneficial.\n\n## Decision guidance: should Rust core move to MoonBit for speed?\n\nBased on these numbers: no, not for boundary speed alone.\n\nReason:\n- Boundary is already near-zero cost (sub-3ns on this host).\n- Any wins from migration will mostly come from architecture choices (fewer crossings, coarser APIs), not language-switch micro-optimizations.\n\nMove code to MoonBit for:\n- faster iteration/modeling\n- portability or generation benefits\n- maintainability\n\nKeep in Rust when:\n- syscall-heavy paths\n- mature unsafe/perf-critical internals already stable\n\n## Next benchmark to add (recommended)\n\nAdd a coarse-grained benchmark for real task payload crossing:\n- one boundary call carrying a packed command\n- compare against N tiny calls\n- report payload sizes and p50/p95\n\nThat will better predict real Flow task runtime behavior than arithmetic no-op microbenchmarks.\n" }, { "path": "docs/bench/readme.md", "content": "# Bench Docs\n\n- `moonbit-rust-ffi-boundary.md`: raw MoonBit <-> Rust boundary benchmark, commands, results, and optimization guidance.\n- `cli-startup.md`: repeatable benchmark for Flow CLI startup and cheap read-only command latency.\n" }, { "path": "docs/ci-cd-runbook.md", "content": "# Flow CI/CD Runbook\n\nThis runbook documents how Flow CI/CD is wired today and how to debug it quickly when jobs fail.\n\n## Architecture\n\n- Workflows:\n - `.github/workflows/pr-fast.yml`: fast PR gate (Linux) using vendored hydrate + `cargo check`.\n - `.github/workflows/canary.yml`: runs on every push to `main`, publishes/updates the `canary` release/tag.\n - `.github/workflows/nightly-validation.yml`: scheduled full cross-target validation (plus host SIMD) without publishing.\n - `.github/workflows/release.yml`: runs on tag pushes matching `v*`, publishes stable releases.\n- Trigger optimization:\n - Canary `push` skips docs-only changes (`docs/**`, `**/*.md`).\n - Use `workflow_dispatch` to force a Canary run when needed after docs-only changes.\n- Vendored deps bootstrap:\n - Both workflows run `scripts/vendor/vendor-repo.sh hydrate` immediately after checkout in each build job.\n - This materializes `lib/vendor/*` from the pinned commit in `vendor.lock.toml` before Cargo builds.\n - Build jobs cache vendor checkout/materialization (`.vendor/flow-vendor`, `lib/vendor`, `lib/vendor-manifest`) keyed by `vendor.lock.toml`.\n- Repository policy checks:\n - CI enforces lowercase `readme.md` naming via `scripts/ci/check-readme-case.sh`.\n- Build jobs in both workflows:\n - Matrix build: macOS + Linux targets.\n - SIMD build: `build-linux-host-simd` (Linux x64 with `--features linux-host-simd-json`).\n - CI builds `--bin f` only (release artifacts package `f`; avoids duplicate `flow` alias build cost).\n- Release jobs:\n - Gather all build artifacts.\n - Publish release assets (and in Canary, force-move `canary` tag to current `main` commit).\n - `release` waits for both `build` and `build-linux-host-simd`.\n\n## Runner Modes\n\nFlow uses task-driven mode switching (not manual workflow edits):\n\n- `github` mode:\n - Standard Linux lanes on `ubuntu-latest`.\n - SIMD lane disabled.\n- `blacksmith` mode:\n - Linux lanes on Blacksmith runners.\n - SIMD lane enabled on Blacksmith.\n- `host` mode:\n - Standard Linux lanes stay on GitHub-hosted runners.\n - SIMD lane runs on self-hosted label: `[self-hosted, linux, x64, ci-1focus]`.\n\nCheck/switch mode:\n\n```bash\nf ci-blacksmith-status\nf ci-blacksmith-enable\nf ci-blacksmith-enable-apply\nf ci-host-enable\nf ci-host-enable-apply\nf ci-blacksmith-disable\nf ci-blacksmith-disable-apply\n```\n\n## One-Command Host Setup\n\nPreferred path (painless, idempotent):\n\n```bash\nf ci-host-setup\n```\n\nIf infra host is not configured yet:\n\n```bash\nf ci-host-setup <user@ip>\n```\n\nWhat `f ci-host-setup` does:\n\n1. Validates `gh` auth and `infra` host config.\n2. Installs/registers the `ci-1focus` self-hosted runner on the Linux host.\n3. Waits for runner to report online.\n4. Switches workflows to `host` mode with commit + push.\n5. Prints final runner health/status.\n\n## Daily Operations\n\n- Check current mode: `f ci-blacksmith-status`\n- Check runner service + GitHub registration: `f ci-host-runner-status`\n- Reinstall runner if needed: `f ci-host-runner-install`\n- Remove runner: `f ci-host-runner-remove`\n\nStable release flow:\n\n1. Merge version bump to `main`.\n2. Push tag `vX.Y.Z`.\n3. Watch `Release` workflow.\n\nCanary flow:\n\n1. Push to `main`.\n2. Watch `Canary` workflow.\n3. Confirm `canary` tag moved and release assets updated.\n\nPR flow:\n\n1. Open/refresh PR to `main`.\n2. Watch `PR Fast Check` (`cargo check` + `cargo test --no-run` shard).\n3. Merge only after fast check passes.\n\n## Debug Playbook\n\n### 1) Workflow failed or stuck\n\n```bash\ngh run list --workflow Canary --limit 10\ngh run list --workflow Release --limit 10\ngh run view <run-id> --log-failed\ngh run watch <run-id>\n```\n\nIf failure shows:\n\n- `failed to load source for dependency 'axum'`\n- `Unable to update .../lib/vendor/axum`\n- `No such file or directory (os error 2)`\n\nthen vendored deps were not hydrated before build.\n\n### 2) SIMD lane queued forever\n\nUsually means self-hosted runner routing issue.\n\n```bash\nf ci-blacksmith-status\nf ci-host-runner-status\npython3 ./scripts/ci_host_runner.py health --repo nikivdev/flow\n```\n\nExpected healthy state is:\n\n- Host service: `active`\n- GitHub runner status: `online`\n- Runner has label `ci-1focus`\n\nIf not healthy, run:\n\n```bash\nf ci-host-runner-install\npython3 ./scripts/ci_host_runner.py wait-online --repo nikivdev/flow --timeout-secs 120 --interval-secs 5\n```\n\n### 3) Workflows not using expected runner profile\n\n```bash\nf ci-blacksmith-status\n```\n\nIf wrong:\n\n```bash\nf ci-host-enable-apply\n# or:\nf ci-blacksmith-enable-apply\n# or:\nf ci-blacksmith-disable-apply\n```\n\n### 3b) Vendored repo hydrate issues\n\nHydration depends on `vendor.lock.toml` pin and vendor repo availability.\n\nQuick checks:\n\n```bash\nscripts/vendor/vendor-repo.sh status\nscripts/vendor/vendor-repo.sh hydrate\n```\n\nExpected:\n\n- pinned commit in `vendor.lock.toml` is non-empty,\n- hydrate logs `hydrated <crate> -> lib/vendor/<crate>`,\n- `lib/vendor/axum/Cargo.toml` and `lib/vendor/reqwest/Cargo.toml` exist after hydrate.\n\nIf CI cannot clone SSH URL from lock, `vendor-repo.sh` now falls back to HTTPS clone for GitHub URLs.\n\n### 4) `curl ... install.sh` does not fetch expected fresh build\n\nFlow installer defaults to `canary` unless `FLOW_VERSION` is set differently. Check if `canary` moved:\n\n```bash\ngit ls-remote --tags origin canary\n```\n\nThen verify in sandbox (recommended) using:\n\n- `docs/rise-sandbox-feature-test-runbook.md`\n\nThat runbook gives an isolated `rise sandbox` smoke test for:\n\n```bash\ncurl -fsSL https://myflow.sh/install.sh | sh\n~/.flow/bin/f --version\n```\n\n### 5) Setup task fails mid-install\n\nRe-run:\n\n```bash\nf ci-host-setup\n```\n\nThe installer path is idempotent (it removes old service/config before re-registering). If failure persists, inspect:\n\n```bash\nf ci-host-runner-status\ngh api repos/nikivdev/flow/actions/runners\n```\n\n## Notes\n\n- CI/CD execution is defined in repo workflows; GitHub UI is control plane/visibility (runs, logs, runner state), not the source of truth for pipeline logic.\n- Current performance balance: keep general Linux matrix jobs on GitHub-hosted runners, offload expensive SIMD build to the Linux host.\n" }, { "path": "docs/codex-first-control-plane-roadmap.md", "content": "# Codex-First Control Plane Roadmap\n\nThis document proposes how Flow should evolve from \"helpful CLI + local skills\"\ninto a Codex-first control plane where the user stays inside Codex and Flow\nhandles routing, memory, execution, and learning behind the scenes.\n\n## Goal\n\nTarget state:\n\n- the user speaks natural intent in Codex\n- Flow resolves references, routes workflows, fetches secure context, and runs\n the right tool/task\n- Codex sees only the smallest useful context for the current turn\n- repeated phrasing becomes reusable system knowledge without turning every repo\n preamble into a wall of rules\n\nExample desired behavior:\n\n- `document it` resolves to the docs write flow\n- a pasted Linear URL is unrolled before planning\n- `continue the last deploy investigation` finds the right session/worktree\n- the user does not need to remember `forge doc`, `forge linear inspect`, or\n repo-specific wrappers\n\n## Problem\n\nCurrent Flow has strong building blocks but they are still separate:\n\n- task skills are generated and reloaded for Codex\n- sessions are stored and recoverable\n- env storage is becoming secure enough for org use\n- router telemetry already exists\n- repo-specific systems like Forge can mine aliases and inject lean workflow\n rules\n\nBut the user still pays too much cognitive cost:\n\n- wrappers like `L` and repo-specific launchers carry logic outside Flow\n- repo preambles grow whenever a new shortcut is taught\n- skill learning is mostly manual\n- URL/reference unrolling is repo-specific instead of generic\n- Codex app-server connections are process-per-query in some paths\n\nThe result is \"good pieces, weak control plane\".\n\n## Design Principles\n\n1. Flow is the control plane; repo tools remain domain executors.\n2. Skills stay thin; runtime resolution carries the real behavior.\n3. Reference unrolling is deterministic first, model-assisted only if needed.\n4. Learning produces suggestions, not prompt bloat.\n5. No default context should be paid for behavior that is not active.\n\n## Existing Flow Building Blocks\n\n- task-synced Codex skill metadata in [src/skills.rs](/Users/nikitavoloboev/code/flow/src/skills.rs#L378) and [src/skills.rs](/Users/nikitavoloboev/code/flow/src/skills.rs#L443)\n- Codex skill cache reload in [src/skills.rs](/Users/nikitavoloboev/code/flow/src/skills.rs#L1224)\n- configurable Codex wrapper transport in [src/commit.rs](/Users/nikitavoloboev/code/flow/src/commit.rs#L5414)\n- multi-provider session recovery and copy flows in [src/ai.rs](/Users/nikitavoloboev/code/flow/src/ai.rs#L1)\n- router telemetry hooks in [src/rl_signals.rs](/Users/nikitavoloboev/code/flow/src/rl_signals.rs#L307)\n- current Codex session resolver direction in [codex-openai-session-resolver.md](/Users/nikitavoloboev/code/flow/docs/codex-openai-session-resolver.md#L1)\n\nThese are enough to start. The missing work is unification.\n\n## Constraint: no Codex fork\n\nFlow should target current upstream Codex directly.\n\nThat means:\n\n- prefer wrapper transport + config over patching Codex\n- use stable upstream surfaces like normal user skill roots, `skills/list`, and `thread/*`\n- treat newer upstream features such as `skills/list perCwdExtraUserRoots` and in-process app-server clients as accelerators, not prerequisites\n- keep repo-specific behavior in Flow or repo executors, not in a private Codex fork\n\n## Proposed Architecture\n\n### 1. warm Codex control layer\n\nAdd a Flow-managed warm control layer, either as an extension of `ai-taskd`, a\nfocused `codexd`, or a lighter in-process broker where that is enough for the\ncurrent upstream Codex client surface.\n\nResponsibilities:\n\n- maintain repo-scoped Codex app-server sessions\n- cache recent threads, active skills, and repo metadata\n- expose fast local RPC for lookup, runtime-skill injection, and doctor output\n- resolve references before they reach Codex as plain text\n- own the \"what extra context is actually needed for this turn?\" decision\n\nThis should absorb behavior that currently lives in wrappers like `L`.\n\n### 2. Intent registry\n\nPromote Forge-style phrase aliasing into Flow as a generic feature.\n\nEach intent has:\n\n- canonical name\n- phrase aliases\n- optional repo/path scope\n- resolver/action target\n- confidence policy\n- evidence counters for suggested future aliases\n\nExamples:\n\n- `doc-it`\n- `linear-reference`\n- `session-recover`\n- `review-intent-comment`\n\nIntent matching must stay deterministic and cheap.\n\n### 3. Reference resolvers\n\nFlow should ship a generic resolver layer for pasted references:\n\n- Linear issue URLs\n- Linear project URLs\n- GitHub PR / issue URLs\n- repo file paths\n- commit SHAs\n- saved Flow session names or IDs\n\nResolvers return structured payloads, not prose. Repo-local executors like\nForge can register resolver commands for domain-specific expansion.\n\n### 4. Runtime skills\n\nSplit Codex knowledge into two layers:\n\n- baseline skills: always available, minimal repo guidance\n- runtime skills: ephemeral, injected only when a matched intent or resolver\n requires them\n\nExamples:\n\n- user says `document it`\n - inject tiny docs-routing runtime skill\n- user pastes a Linear URL\n - inject tiny linear-unrolled runtime context\n- user asks to recover recent work\n - inject session-recovery runtime context only for that request\n\nRuntime skills should expire automatically and be bounded by a strict budget.\n\n### 5. Suggestion loop, not self-bloating memory\n\nUse router telemetry plus transcript mining to propose:\n\n- new aliases\n- new reference patterns\n- candidate runtime skills\n- stale skills that should be removed\n\nImportant:\n\n- do not auto-install every observed phrase\n- require evidence thresholds\n- prefer suggested changes that collapse multiple variants into one canonical\n intent\n\n## Flow Commands\n\nAdd a small command family around the new control plane:\n\n```bash\nf codex open [query]\nf codex resolve \"<text-or-url>\" [--json]\nf codex runtime\nf codex runtime show\nf codex runtime clear\nf codex teach suggest\nf codex teach accept <intent-or-suggestion-id>\nf codex teach reject <intent-or-suggestion-id>\nf codex doctor\nf codexd start|stop|status\n```\n\nIntended behavior:\n\n- `f codex open` replaces personal wrappers like `L`\n- `f codex resolve` shows what Flow would unroll or route before Codex sees it\n- `f codex runtime show` explains which runtime skills/context are active\n- `f codex teach suggest` presents evidence-backed alias/intent suggestions\n- `f codex doctor` exposes repo path, active app-server connection, runtime\n budget, skill count, and recent resolver hits\n\n## Config Shape\n\nProposed `flow.toml` additions:\n\n```toml\n[codex]\ncontrol_plane = \"daemon\"\nwarm_app_server = true\nruntime_skill_budget_chars = 1200\nauto_resolve_references = true\nauto_learn = \"suggest-only\"\n\n[codex.session]\nopen_command = \"codex\"\nprefer_last_active = true\nrepo_scoped_lookup = true\n\n[[codex.intent]]\nname = \"doc-it\"\nphrases = [\"doc it\", \"document it\", \"write this down\", \"save this in docs\"]\nresolver = \"docs.route_write\"\nscope = [\"repo\", \"personal\"]\n\n[[codex.intent]]\nname = \"session-recover\"\nphrases = [\"what was i doing\", \"recover recent context\", \"continue the work\"]\nresolver = \"session.recover\"\n\n[[codex.reference_resolver]]\nname = \"linear\"\nmatch = [\"https://linear.app/*/issue/*\", \"https://linear.app/*/project/*\"]\ncommand = \"forge linear inspect {{ref}} --json\"\ninject_as = \"linear\"\n\n[[codex.reference_resolver]]\nname = \"docs\"\nmatch = [\"doc it\", \"document it\"]\ncommand = \"forge doc route --title {{title}} --json\"\ninject_as = \"docs\"\n```\n\nAlso add a personal/global config file for user-specific phrase preferences:\n\n- `~/.config/flow/codex-intents.toml`\n\nUse this for personal language variants that should not live in repo config.\n\n## Daemon Responsibilities\n\n`codexd` should own:\n\n- app-server lifecycle\n- repo session caches\n- runtime skill activation/deactivation\n- resolver execution\n- secure env lookups for active workflows\n- bounded prompt-context assembly\n- suggestion generation from telemetry/history\n- compatibility with existing `f skills reload` and `f ai codex ...` flows\n\nIt should not:\n\n- replace repo-specific executors like Forge\n- run opaque model-based routing in the hot path\n- inject large transcript summaries into every turn\n\n## Prompt Budget Policy\n\nThe runtime layer needs hard limits:\n\n- baseline repo guidance stays small\n- runtime additions must fit a bounded char/token budget\n- each resolved intent/reference should justify its own inclusion\n- unused runtime skills expire quickly\n\nBudget policy should prefer:\n\n1. structured resolver output\n2. one tiny runtime skill\n3. one short recovery summary\n4. nothing else\n\n## Learning Loop\n\nInputs:\n\n- router telemetry\n- accepted/overridden task choices\n- resolver hits\n- successful tool invocations\n- session transcript mining\n\nOutputs:\n\n- proposed alias additions\n- proposed resolver registrations\n- dead-skill cleanup suggestions\n- better default repo baselines\n\nApproval model:\n\n- repo suggestions require explicit accept\n- personal suggestions can default to personal scope\n- org/shared suggestions should stay gated\n\n## Relationship To Forge\n\nForge should remain the Prom executor for Prom-specific workflows.\n\nFlow should absorb the generic pieces Forge proved useful:\n\n- intent aliasing\n- reference unrolling\n- thin runtime teaching\n- lean docs workflow activation\n\nThat means:\n\n- Prom keeps `forge linear inspect`, `forge doc`, and similar domain commands\n- Flow becomes the generic router that decides when to call them\n\n## Rollout Phases\n\n### Phase 0: unify wrappers\n\n- move `L`-style session open/recover behavior into `f codex open`\n- make repo-scoped Codex session resolution first-class\n- expose a `doctor` view for current skill/runtime state\n\n### Phase 1: warm daemon\n\n- add `codexd` with persistent app-server connection per repo\n- keep recent thread cache and skills cache warm\n- remove process-per-query overhead for session lookup/reload paths\n\n### Phase 2: intent registry + resolvers\n\n- add config-backed intent aliases\n- add generic reference resolver interface\n- ship built-ins for session recovery, docs routing, and Linear URLs\n\n### Phase 3: runtime skills\n\n- inject temporary runtime skills/context instead of growing repo preambles\n- enforce runtime budget caps\n- surface active runtime state in `f codex runtime show`\n\n### Phase 4: learning loop\n\n- mine telemetry + sessions for candidate aliases and resolver patterns\n- generate suggestions only after evidence thresholds\n- add accept/reject workflow\n\n### Phase 5: provider expansion\n\n- reuse the same intent/resolver plane for Claude and Cursor transcript-backed\n workflows where useful\n- keep Codex as the first-class interactive target\n\n## First Implementation Slice\n\nThe highest-value first slice is:\n\n1. `f codex open`\n2. `codexd` with warm repo-scoped app-server\n3. `f codex resolve`\n4. config-backed intents\n5. built-in resolvers for:\n - docs intents\n - Linear URLs\n - session recovery prompts\n6. `f codex runtime show`\n\nWhy this first:\n\n- it removes the most command-memory burden immediately\n- it uses Flow’s existing app-server + skills + session foundations\n- it keeps the prompt surface thin\n- it gives a concrete place to move personal wrapper logic\n\n## Success Metrics\n\n- p50 `f codex open` latency\n- number of user prompts that required remembering a repo command\n- average runtime-context bytes injected per turn\n- resolver hit rate\n- accepted suggestion rate\n- count of active baseline skills versus runtime skills\n\n## Non-Goals\n\n- full semantic agent routing in the hot path\n- unbounded transcript mining into prompt context\n- replacing repo executors with Flow clones\n- auto-learning every phrase without evidence or approval\n\n## Summary\n\nThe target system is not \"more AGENTS text\" and not \"more commands for the\nuser to remember\".\n\nIt is:\n\n- thin baseline repo guidance\n- a warm Flow Codex control daemon\n- deterministic intent/reference resolution\n- ephemeral runtime skills\n- evidence-backed learning with approval\n\nThat is how Flow becomes truly Codex-first while keeping context cost low.\n" }, { "path": "docs/codex-fork-tasks.md", "content": "# Codex Fork Tasks\n\nThese Flow tasks automate the personal Codex fork workflow described in:\n\n- `~/docs/codex/codex-fork-home-branch-workflow.md`\n\nThey are intentionally narrow:\n\n- keep `~/repos/openai/codex` as the upstream reference checkout\n- keep `~/repos/nikivdev/codex` as the fork home checkout\n- create one stable worktree per real fork task under `~/.worktrees/codex`\n- attach Codex sessions to that worktree instead of to one drifting checkout\n\n## Commands\n\nRun these from `~/code/flow`:\n\n```bash\ncd ~/code/flow\nf codex-fork-status\nf codex-fork-sync\nf codex-fork-task \"add workspace ref to the footer\"\nf codex-fork-last\nf codex-fork-promote --push\n```\n\nIf you are outside `~/code/flow`, use the explicit config form:\n\n```bash\nflow run --config ~/code/flow/flow.toml codex-fork-task \"add workspace ref to the footer\"\n```\n\n## What Each Task Does\n\n### `f codex-fork-status`\n\nShows:\n\n- the upstream reference checkout\n- the personal fork home checkout\n- the current `nikiv`, `upstream/main`, and `private/nikiv` refs\n- existing fork worktrees\n- the last worktree used by the helper\n\nUse this first when the fork state is unclear.\n\n### `f codex-fork-sync`\n\nFast-forwards `nikiv` in `~/repos/nikivdev/codex` to `upstream/main`.\n\nOptional push:\n\n```bash\nf codex-fork-sync --push\n```\n\nSafety rule:\n\n- it refuses to run if the fork home checkout is dirty\n\n### `f codex-fork-task \"<query>\"`\n\nThis is the main entry point.\n\nIt:\n\n1. derives a branch like `codex/<slug>`\n2. creates or reuses `~/.worktrees/codex/<branch-name-with-slashes-rewritten>`\n3. records that worktree as the \"last fork worktree\"\n4. resumes the last Codex session in that worktree if one exists\n5. otherwise starts a fresh Codex session there with an initial prompt that points at the fork workflow doc\n\nExamples:\n\n```bash\nf codex-fork-task \"add workspace ref to the footer\"\nf codex-fork-task \"thread name startup\" --branch codex/thread-name-startup\nf codex-fork-task \"statusline workspace ref\" --no-launch\n```\n\n### `f codex-fork-last`\n\nResumes `codex resume --last` in the last worktree created or used by the helper.\n\nThis is the closest current Flow equivalent to binding a key that reattaches to the last active fork session.\n\nYou can also target a branch or path explicitly:\n\n```bash\nf codex-fork-last codex/workspace-awareness\nf codex-fork-last ~/.worktrees/codex/codex-workspace-awareness\n```\n\n### `f codex-fork-promote`\n\nCreates or updates a review branch from the current task worktree tip.\n\nDefault mapping:\n\n- `codex/workspace-awareness` -> `review/nikiv-workspace-awareness`\n\nExamples:\n\n```bash\nf codex-fork-promote\nf codex-fork-promote codex/workspace-awareness --push\nf codex-fork-promote ~/.worktrees/codex/codex-workspace-awareness --review-branch review/nikiv-codex-workspace-awareness\n```\n\n## State File\n\nThe helper records the last used worktree in:\n\n```text\n~/.flow/codex-fork/last-worktree.txt\n```\n\nThat is what powers `f codex-fork-last`.\n\n## Environment Overrides\n\nIf you want the helper to point somewhere else, override these env vars:\n\n- `FLOW_CODEX_UPSTREAM_CHECKOUT`\n- `FLOW_CODEX_FORK_HOME`\n- `FLOW_CODEX_WORKTREE_ROOT`\n- `FLOW_CODEX_WORKFLOW_DOC`\n- `FLOW_CODEX_FORK_STATE_DIR`\n- `FLOW_CODEX_FORK_BASE_BRANCH`\n- `FLOW_CODEX_FORK_PRIVATE_REMOTE`\n- `FLOW_CODEX_FORK_UPSTREAM_REMOTE`\n- `FLOW_CODEX_FORK_UPSTREAM_BRANCH`\n" }, { "path": "docs/codex-maple-telemetry-runbook.md", "content": "# Codex Maple Telemetry Runbook\n\nUse this when you want shared analytics for Flow-guided Codex usage without\nchanging the local source of truth.\n\n## What This Does\n\nFlow keeps Codex telemetry local first:\n\n- `codex/skill-eval/events.jsonl`\n- `codex/skill-eval/outcomes.jsonl`\n- Jazz2-backed Codex memory mirror\n\nOptional Maple export reads those local logs and emits a derived, redacted OTLP\nstream.\n\nWhat gets exported:\n\n- route / mode / action\n- runtime skill names and counts\n- prompt/context size metrics\n- reference counts\n- outcome kind / success\n- repo leaf name plus hashed path identifiers\n\nWhat does not get exported:\n\n- raw prompt text\n- full filesystem paths\n- raw session ids\n\n## Configure\n\nUse Flow env store so the daemon and Flow-launched Codex sessions see the same\nvalues. For local-only secrets, prefer the personal store:\n\n```bash\ncd ~/code/flow\nf env set --personal FLOW_CODEX_MAPLE_LOCAL_ENDPOINT=http://ingest.maple.localhost/v1/traces\nf env set --personal FLOW_CODEX_MAPLE_LOCAL_INGEST_KEY=maple_pk_local_xxx\nf env set --personal FLOW_CODEX_MAPLE_HOSTED_ENDPOINT=https://ingest.maple.dev/v1/traces\nf env set --personal FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY=maple_sk_hosted_xxx\nf env set --personal FLOW_CODEX_MAPLE_HOSTED_PUBLIC_INGEST_KEY=maple_pk_hosted_xxx\n```\n\nOptional tuning:\n\n```bash\nf env set --personal FLOW_CODEX_MAPLE_SERVICE_NAME=flow-codex\nf env set --personal FLOW_CODEX_MAPLE_SCOPE_NAME=flow.codex\nf env set --personal FLOW_CODEX_MAPLE_ENV=local\nf env set --personal FLOW_CODEX_MAPLE_QUEUE_CAPACITY=1024\nf env set --personal FLOW_CODEX_MAPLE_MAX_BATCH_SIZE=64\nf env set --personal FLOW_CODEX_MAPLE_FLUSH_INTERVAL_MS=100\nf env set --personal FLOW_CODEX_MAPLE_CONNECT_TIMEOUT_MS=400\nf env set --personal FLOW_CODEX_MAPLE_REQUEST_TIMEOUT_MS=800\n```\n\nOn macOS, personal env reads may require a daily unlock:\n\n```bash\nf env unlock\n```\n\nIf you launch Codex through Flow (`j ...`, `f codex ...`, `k ...`), Flow will\nhydrate these `FLOW_CODEX_MAPLE_*` vars into the child Codex process. Explicit\nshell env vars override the personal store for that launch, which makes one-off\ntelemetry tests quiet and deterministic.\n\nFrom inside a Codex session, the write path stays the same:\n\n```bash\nf env set --personal FLOW_CODEX_MAPLE_HOSTED_ENDPOINT=...\nf env set --personal FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY=...\nf env get --personal FLOW_CODEX_MAPLE_HOSTED_ENDPOINT\n```\n\n## Run\n\nInspect current state:\n\n```bash\nf codex telemetry status\n```\n\nFlush unseen local telemetry once:\n\n```bash\nf codex telemetry flush --limit 200\n```\n\nEquivalent task shortcuts:\n\n```bash\nf codex-telemetry-status\nf codex-telemetry-flush\n```\n\n## Background Export\n\nIf `codexd` is running, it also performs a bounded background flush pass during\nits normal maintenance loop. This keeps export cheap and avoids a separate\nalways-on process.\n\n## Notes\n\n- Export is derived and best-effort.\n- Local logs and memory stay canonical even if Maple is unavailable.\n- This is intended for route/context/outcome analytics, not transcript export.\n" }, { "path": "docs/codex-openai-session-resolver.md", "content": "# Codex OpenAI Repo Session Resolver\n\nThis documents the personal `L` wrapper that opens or resumes Codex sessions with repo-specific query matching for `~/repos/openai/codex`.\n\nRelevant files:\n\n- fish entrypoint: `~/config/fish/fn.fish`\n- resolver: `~/config/fish/scripts/codex-openai-session.ts`\n\n## Behavior\n\n- `L` with no args runs `f ai codex new`.\n- `L <query>` targets stored Codex sessions for `~/repos/openai/codex`.\n- On a successful match it runs `f ai codex resume <thread-id>` in that repo.\n- On no match it exits non-zero and prints a short recent-session list instead of opening the wrong conversation.\n\n## Explicit Recovery Prompts\n\n`l` and `L` now also treat explicit recovery phrases as a separate lightweight\npath.\n\nExamples:\n\n- `see this convo in ...`\n- `what was I doing in ...`\n- `recover recent context`\n- `continue the ... work`\n\nFor those prompts, the launcher first runs:\n\n```bash\nf ai codex recover --summary-only --path <derived target> <prompt>\n```\n\nThen it prepends the short recovery summary to the new prompt and opens the\nsession in the derived target repo/workspace. Normal prompts do not pay this\ncost.\n\n## Why use Codex app-server\n\nThis path uses `codex app-server` instead of parsing `f ai codex list` output.\n\nThat matters because `thread/list` gives:\n\n- exact `cwd` filtering for `~/repos/openai/codex`\n- stable `updatedAt` ordering\n- structured fields such as `id`, `name`, `preview`, `gitInfo`, and `cwd`\n- pagination and optional server-side `searchTerm`\n\nFor this wrapper, exact repo scoping is the main win. It avoids mixing sessions from unrelated repos and avoids depending on Flow's imported session index.\n\n## Resolution flow\n\n1. Spawn `codex app-server` with cwd set to `~/repos/openai/codex`.\n2. Send `initialize`, then `initialized`.\n3. Call `thread/list` with:\n - `cwd: ~/repos/openai/codex`\n - `archived: false`\n - `sortKey: updated_at`\n4. Use a small first fetch when possible:\n - latest query: 1\n - `after most recent active`: 2\n - text search query: 25\n - fallback scan: up to 100\n5. Resolve the query against returned threads.\n6. For textual queries, rerank the top shortlist with `thread/read includeTurns:true` using full turn text.\n - if summary fields miss completely, probe the most recent few threads by full turn text before giving up\n7. Resume the chosen thread through `f ai codex resume <id>` in the Codex repo.\n\n## Query matching rules\n\nThe resolver is deterministic. It does not call a model.\n\nMatching order:\n\n1. exact or unique thread id prefix\n2. relative query with `after` or `before`\n3. ordinal query such as `2`, `second`, `3rd`\n4. text ranking across:\n - `thread.name`\n - `thread.preview`\n - `thread.gitInfo.branch`\n - `thread.gitInfo.sha`\n5. pure recency query such as `most recent active`\n\nExamples:\n\n- `L most recent active`\n- `L session after most recent active`\n- `L second`\n- `L 019cca91`\n- `L where does codex store`\n- `L history.jsonl`\n\nImportant accuracy guardrails:\n\n- `last` only means \"latest session\" when the rest of the query is otherwise empty after control words are removed.\n- bare numbers only become ordinals when the query reduces to just that number.\n- directional queries stay directional. If there is no next or previous match, the resolver fails instead of silently falling back to the latest session.\n\n## Current limits\n\n- It starts a fresh `codex app-server` process on every lookup. That is the main latency cost.\n- `thread/list searchTerm` only filters extracted titles and is case-sensitive, so the helper still needs local fallback ranking.\n- The second pass only reads a few candidate threads, so this is still a bounded heuristic rather than a full semantic search across all history.\n- Relative anchor queries are strongest for latest or ordinal anchors and weaker for arbitrary natural-language anchors.\n\n## Best improvements\n\n### Speed\n\n- Keep a long-lived local resolver daemon so `L` reuses one app-server connection instead of spawning a fresh process.\n- Add a small local cache keyed by repo path with `id`, `updatedAt`, `name`, `preview`, and `gitInfo`, then refresh it opportunistically.\n- If Codex exposes a stable reusable host transport beyond stdio for local clients, switch to that instead of process-per-query.\n\n### Accuracy\n\n- Start naming important sessions with `thread/name/set`; exact names will beat fuzzy preview matching.\n- If the wrapper ever controls session creation, persist higher-signal naming or metadata early instead of inferring from preview text later.\n- Extend the second pass to handle arbitrary textual anchors inside `after ...` and `before ...` queries more deeply when the anchor match is still weak.\n\n### Prompting\n\nA model-based resolver is possible but should be the fallback, not the first pass.\n\nWhy:\n\n- slower than deterministic matching\n- easier to silently choose the wrong session\n- unnecessary when `id`, `updatedAt`, `name`, `preview`, and repo path already narrow the space well\n\nIf a model is added later, the safe shape is:\n\n- deterministic shortlist first\n- prompt only over the top few candidates\n- require the model to return one thread id or `NONE`\n- keep strict failure if confidence is weak\n\n## Best next step\n\nThe highest-value next change is reducing lookup latency:\n\n1. keep one local long-lived resolver or daemon\n2. reuse one app-server connection per repo\n3. cache recent shortlist results and refresh opportunistically\n\nThat should improve the user-visible speed more than further prompt tuning.\n" }, { "path": "docs/commands/ai.md", "content": "# f ai\n\nManage Claude Code, Codex, and Cursor sessions for the current project.\n\nFlow reads local session stores, filters by current project path, and gives you one interface for list/search/resume/copy/save.\nWhen you need to reopen a repo's session from another working directory, use `--path <project-root>` on `resume` or provider-specific `continue`.\nCursor transcripts are supported for reading only.\n\n## Quick Start\n\n```bash\n# Fuzzy-pick a recent session (Claude + Codex + Cursor)\nf ai\n\n# Provider-specific list/read\nf ai claude list\nf ai codex list\nf ai codex sessions\nf ai codex sessions --path ~/repos/mark3labs/kit\nf ai cursor list\nf codex resolve \"latest\"\nf codex resolve \"https://linear.app/.../project/.../overview\" --json\nf codex open \"continue the deploy work\"\nf ai claude resume <session-id-or-name>\nf ai codex resume <session-id-or-name>\nf ai codex resume --path ~/work/example-project\nf ai codex continue --path ~/work/example-project\nf ai cursor context - /path/to/repo 3\nf cursor copy\n\n# Save a memorable alias for a session\nf ai save reclaim-fix --id a38cf8bf-f4e2-4308-8b27-0254f89c4385\n```\n\n## Session Sources\n\n- Claude: `~/.claude/projects/<project-path>/*.jsonl`\n- Codex: `~/.codex/sessions/**/*.jsonl` (Flow matches by `session_meta.cwd`)\n- Cursor: `~/.cursor/projects/<project-key>/agent-transcripts/<session-id>/<session-id>.jsonl`\n- Saved aliases: `.ai/sessions/claude/index.json` in your repo\n\n## Resume Behavior (Important)\n\n### TTY requirement\n\nResume is interactive by design.\n\n- `f ai claude resume ...` requires a terminal TTY.\n- `f ai codex resume ...` requires a terminal TTY.\n- In non-interactive shells, Flow exits with a clear error and non-zero status.\n- Cursor does not currently expose a Flow resume/continue path; use `list`, `copy`, or `context`.\n\n### Claude exact-ID behavior\n\nIf you pass an explicit session (`name`, `id`, or `id-prefix`), Flow is strict:\n\n- it attempts `claude --resume <id>`\n- if Claude cannot open that exact session, Flow fails\n- Flow does **not** auto-fallback to `--continue` for explicit sessions (prevents opening the wrong conversation)\n\n### Claude no-arg behavior\n\nFor `f ai claude resume` with no argument:\n\n- Flow picks most recent Claude session for this project\n- if that resume fails, Flow may fallback to `claude --continue` in the same cwd (TTY only)\n\n### Codex behavior\n\nFor Codex, Flow runs:\n\n```bash\ncodex resume <id> --dangerously-bypass-approvals-and-sandbox\n```\n\nNo fallback is applied on resume failure; Flow returns non-zero.\n\n### Codex open and resolve\n\nUse `open` when you want one Codex entrypoint that stays conservative about context:\n\n```bash\nf codex open\nf codex open \"continue the deploy work\"\nf codex open \"resume latest\"\nf codex open --path ~/work/example-project \"what was I doing here\"\nf codex resolve \"https://linear.app/fl2024008/project/llm-proxy-v1-6cd0a041bd76/overview\" --json\nf codex doctor --path ~/work/example-project\n```\n\nBehavior:\n\n- no query: start a fresh Codex session in the target repo\n- explicit session lookup queries like `latest`, `resume session`, ordinals, or session IDs: resume the matching Codex session\n- explicit recovery prompts like `what was I doing` or `continue the ... work`: build a compact recovery handoff and start a new session\n- matching reference resolvers: inject only compact resolver output, then append the user request\n- otherwise: start a new session with the raw query and no extra wrapper text\n\nThis keeps prompt cost flat unless Flow has a strong reason to recover or unroll context.\nUse `f codex doctor` to confirm whether wrapper transport, runtime skills, and context budgets are actually active for the current repo.\n\n### Codex sessions after a crash or restart\n\nIf your Mac restarts and you lose the live Codex terminals, use:\n\n```bash\nf ai codex sessions\nf ai codex sessions --path ~/repos/mark3labs/kit\n```\n\nBehavior:\n\n- lists recent Codex sessions for the current path\n- sorts by the last message timestamp descending\n- shows the stable session id plus a preview of the latest message\n- the numeric index matches `continue`, so you can reopen quickly\n\nExamples:\n\n```bash\nf ai codex continue 1 --path ~/repos/mark3labs/kit\nf ai codex continue 019cd046 --path ~/repos/mark3labs/kit\nf ai codex sessions --path ~/repos/mark3labs/kit --json\n```\n\n### Optional `flow.toml` resolver config\n\nYou can teach `f codex open` and `f codex resolve` to unroll repo-specific references:\n\n```toml\n[codex]\nauto_resolve_references = true\nprompt_context_budget_chars = 900\nmax_resolved_references = 1\n\n[[codex.reference_resolver]]\nname = \"linear\"\nmatch = [\"https://linear.app/*/issue/*\", \"https://linear.app/*/project/*\"]\ncommand = \"my-linear-tool inspect {{ref}} --json\"\ninject_as = \"linear\"\n```\n\nNotes:\n\n- configure this in repo `flow.toml` or global `~/.config/flow/flow.toml`\n- `{{ref}}`, `{{query}}`, and `{{cwd}}` are available in resolver commands\n- built-in Linear URL parsing works even without a custom resolver\n- resolver output is compacted before prompt injection\n- `prompt_context_budget_chars` hard-caps injected context before your request is appended\n- `max_resolved_references` prevents broad unrolling from bloating one turn\n\n### Optional runtime skill transport\n\nFlow can also materialize tiny per-launch runtime skills for current upstream Codex without forking Codex.\n\nEnable it globally with:\n\n```bash\nf codex enable-global --full\nf codex doctor --path ~/docs --assert-runtime --assert-schedule\n```\n\nOr configure it manually with:\n\n```toml\n[codex]\nruntime_skills = true\n\n[options]\ncodex_bin = \"~/code/flow/scripts/codex-flow-wrapper\"\n```\n\nCurrent first-slice behavior:\n\n- `f codex open \"write plan\"` can attach a tiny plan-writing runtime skill\n- the runtime skill is exposed only for the launched Codex process\n- Flow keeps the generated runtime state under `~/.config/flow/codex/runtime`\n\nInspect or clear runtime state:\n\n```bash\nf codex runtime show\nf codex runtime clear\nf codex memory status\nf codex memory query --path ~/code/flow \"codex control plane runtime skills\"\nf codex memory recent --path ~/docs\nf codex doctor\n```\n\nAssertive health checks:\n\n```bash\nf codex doctor --path ~/docs --assert-runtime\nf codex doctor --path ~/docs --assert-schedule\nf codex doctor --path ~/docs --assert-learning\nf codex doctor --path ~/docs --assert-autonomous\n```\n\n`--assert-learning` is intentionally strict: it fails until Flow has real\nlogged events, grounded outcome samples, and a non-empty scorecard for that\ntarget.\n\nBuilt-in plan writer:\n\n```bash\ncat <<'EOF' | f codex runtime write-plan --title \"Example Plan\"\n# Example Plan\n\n- item\nEOF\n```\n\n### Skill eval and background refresh\n\nFlow can learn which runtime skills are actually worth injecting from local\nCodex usage history without replaying Codex in the hot path.\n\nUseful commands:\n\n```bash\nf codex eval --path ~/work/example-project\nf codex memory sync --limit 400\nf codex memory recent --path ~/work/example-project --limit 12\nf codex skill-eval show --path ~/work/example-project\nf codex skill-eval run --path ~/work/example-project\nf codex skill-eval cron --limit 400 --max-targets 12 --within-hours 168\nf codex telemetry status\nf codex telemetry flush --limit 200\nf codex trace status\nf codex trace current-session --json\nf codex trace inspect <trace-id> --json\nf codex skill-source list --path ~/work/example-project\nf codex skill-source sync --path ~/work/example-project --skill find-skills\n```\n\nThe Codex memory mirror:\n\n- stores durable indexed memory under the Jazz2 root (`~/.jazz2/...` or `~/repos/garden-co/jazz2/.jazz2/...`)\n- mirrors Flow’s route/outcome history into SQLite with WAL enabled\n- extracts compact repo/code facts from repo capsules (summary, commands, important paths, docs hints)\n- adds bounded live code-path retrieval for explicit repo references, so prompts like `see ~/code/flow ...` can inject likely files such as `src/ai.rs` or `docs/...` without dumping raw source\n- indexes durable repo entrypoints and extracted symbols under the same Jazz2-rooted memory store, then supplements them with live symbol extraction from the top-ranked code files during `memory query` / `codex resolve`\n- adds tiny symbol snippets for the top code hits, so coding prompts can carry actual struct/function shape without inlining whole files\n- biases retrieval by intent: implementation/file-edit prompts prefer symbols, snippets, and `src/...` paths; summary/docs prompts prefer doc headings and docs paths\n- stays best-effort so failed memory writes do not block normal Codex coding turns\n- is refreshed again by `f codex skill-eval cron`, so the mirror heals even if a hot-path write is skipped\n- is queried automatically for explicit repo references during `f codex open` / `f codex resolve`\n\nWhat `cron` does:\n\n- scans only recent logged Flow Codex events\n- syncs recent skill-eval logs into the Jazz2-backed memory mirror\n- skips missing/moved repo paths\n- rebuilds scorecards for a bounded number of recent repos\n- never launches Codex or replays network work in the background\n\nFor your use case, this keeps learning cheap and safe enough to run regularly.\n\n### Trace inspection for Flow-managed Codex sessions\n\nFlow now assigns a trace envelope to all Flow-managed Codex launches, not just\nspecial workflows like `check <github-pr-url>`.\n\nThat means sessions started or resumed through:\n\n```bash\nj ...\nk <session-id>\nf codex open ...\nf codex resume ...\nf codex continue ...\n```\n\ncarry `FLOW_TRACE_*` env vars and emit at least one compact Flow telemetry\nevent, so the session becomes remotely inspectable.\n\nUseful commands:\n\n```bash\nf codex trace status\nf codex trace current-session --json\nf codex trace inspect <trace-id> --json\n```\n\nBehavior:\n\n- `trace status` checks whether Maple MCP reads are configured and reachable\n- `trace current-session` reads the active `FLOW_TRACE_ID` from the current\n Flow-managed Codex session, flushes recent Flow telemetry once, then attempts\n a remote trace read\n- if Maple reads are partially configured but tenant access is still blocked,\n Flow returns the current trace metadata plus `readError` instead of failing\n without context\n\nThis keeps the workflow autonomous from inside Codex itself: once the session\nwas started through Flow, you can inspect the current trace without manually\ncopying ids.\n\n`f codex eval --path ...` is the joined operator report:\n\n- current runtime/doctor state\n- recent route mix and context cost\n- grounded skill scorecard highlights\n- concrete “what to improve next” recommendations\n- commands to deepen or fix the current state\n\nIf `codexd` is running, it also keeps recent completion reconciliation warm and\nnow does a bounded background scorecard refresh, so the eval report does not go\nstale as quickly between manual runs.\n\nOptional telemetry export follows the same local-first pattern: Flow keeps\nlocal Codex logs canonical, and if `FLOW_CODEX_MAPLE_*` env vars are set it can\nexport redacted route/context/outcome spans to Maple without shipping raw\nprompts or full repo paths. Use:\n\n```bash\nf codex telemetry status\nf codex telemetry flush --limit 200\n```\n\nFor local-only secrets, prefer `f env set --personal ...`. On macOS you may\nneed `f env unlock` once per day for background reads. Flow-launched Codex\nsessions also inherit the same `FLOW_CODEX_MAPLE_*` values from the personal\nstore, while explicit shell env still wins for one-off tests.\n\nWhen `codexd` is running, the daemon also performs a bounded background export\npass so the external analytics view stays warm.\n\n### macOS launchd schedule for skill-eval\n\nIf you want scorecards to stay fresh automatically on macOS:\n\n```bash\nf codex-skill-eval-launchd-install\nf codex-skill-eval-launchd-status\nf codex-skill-eval-launchd-logs\n```\n\n`f codex enable-global --full` installs this schedule for you.\n\nDefault schedule:\n\n- every 30 minutes\n- scan up to 400 recent events\n- rebuild up to 12 recent repo scorecards\n- ignore repos not seen in the last 168 hours\n\nYou can tune install-time bounds:\n\n```bash\nf codex-skill-eval-launchd-install --minutes 20 --limit 600 --max-targets 16 --within-hours 72\nf codex-skill-eval-launchd-install --dry-run\n```\n\nRemove it with:\n\n```bash\nf codex-skill-eval-launchd-uninstall\n```\n\n### Cursor behavior\n\nCursor transcripts are read-only in Flow:\n\n- `f ai cursor list` opens a picker and copies the selected transcript\n- `f ai cursor copy` copies the latest Cursor transcript for this repo\n- `f ai cursor context ...` copies the last N exchanges\n- `f cursor ...` is a shortcut for the same provider-specific read commands\n\n### Cross-directory resume\n\nYou can target another repo without changing directory:\n\n```bash\nf ai codex resume --path ~/work/example-project\nf ai codex resume --path ~/work/example-project 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai codex continue --path ~/work/example-project\n```\n\n- `resume --path <repo>` resolves the requested session against that repo instead of the current cwd\n- `continue --path <repo>` resumes the latest session for that repo\n- explicit full Codex IDs still work directly even when your current cwd is different\n\n## Session Selectors\n\n`resume` accepts:\n\n- saved alias from `.ai/sessions/claude/index.json`\n- full session ID\n- ID prefix (8+ chars)\n- numeric index from list output (1-based)\n\nExamples:\n\n```bash\nf ai resume my-feature\nf ai resume a38cf8bf\nf ai claude resume 2\nf ai codex resume 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai cursor context 382ef1a3 /path/to/repo 2\n```\n\n## Content Copy Commands\n\n```bash\n# Copy full conversation to clipboard\nf ai copy\nf ai copy <session>\n\n# Copy last N prompt/response turns\nf ai context\nf ai context <session> <path> <count>\n```\n\nUse `-` as session placeholder to trigger fuzzy selection:\n\n```bash\nf ai claude context - /path/to/repo 3\nf ai cursor context - /path/to/repo 3\n```\n\n## Project Workflow (Recommended)\n\n1. Start from repo root and inspect tasks:\n `f tasks list`\n2. Resume exact session when continuing prior work:\n `f ai claude resume <id>` or `f ai codex resume <id>`\n3. Keep context current:\n `f skills sync` then `f skills reload`\n4. Validate through tasks:\n `f test-related` / `f test`\n5. Commit through Flow gates:\n `f commit`\n\nThis keeps sessions, tasks, skills, and commit quality checks in one loop.\n\n## Everruns Bridge Mode\n\nFlow also supports running a prompt through Everruns while routing client-side\n`seq_*` tool calls to local `seqd`:\n\n```bash\nf ai everruns \"open Safari and take a screenshot\"\n```\n\nKey points:\n\n- This path is additive. It does not replace `f ai claude ...` or `f ai codex ...`.\n- Flow now reuses Seq's canonical Everruns bridge for:\n - `seq_*` tool definitions injected into new sessions\n - tool-name normalization (`seq_open_app`, `seq.open_app`, `seq:open-app`)\n - request correlation IDs (`request_id`, `run_id`, `tool_call_id`)\n- Event transport is SSE-first (`/sse`) with automatic fallback to polling (`/events`) if SSE is unavailable.\n- Optional Maple telemetry export can dual-write runtime traces to local + hosted ingest endpoints when `SEQ_EVERRUNS_MAPLE_*` env vars are configured.\n- Existing Flow features remain unchanged (`f seq-rpc`, session resume/copy/context flows).\n\nSetup and validation details are documented in:\n\n- `docs/everruns-seq-bridge-integration.md`\n- `docs/everruns-maple-runbook.md`\n" }, { "path": "docs/commands/clone.md", "content": "# f clone\n\nClone a repository with git-like destination behavior.\n\n## Overview\n\n`f clone` behaves like `git clone` for destination paths:\n\n- `f clone <url>` clones into the current working directory using Git's default folder naming.\n- `f clone <url> <dir>` clones into an explicit destination directory.\n\nFor GitHub inputs, Flow normalizes clone URLs to SSH:\n\n- `https://github.com/owner/repo` -> `git@github.com:owner/repo.git`\n- `owner/repo` -> `git@github.com:owner/repo.git`\n\nThis command does not force clones into `~/repos` and does not auto-configure `upstream`.\n\n## Usage\n\n```bash\nf clone <url-or-owner/repo> [directory]\n```\n\n## Examples\n\n```bash\n# GitHub URL -> SSH clone URL\nf clone https://github.com/genxai/new\n\n# owner/repo shorthand -> SSH clone URL\nf clone genxai/new\n\n# explicit destination folder (same as git clone)\nf clone genxai/new my-local-new\n```\n\n## When To Use\n\n- Use `f clone` when you want standard `git clone` destination behavior.\n- Use [`f repos clone`](repos.md) when you want managed placement under `~/repos/<owner>/<repo>` plus optional upstream automation.\n" }, { "path": "docs/commands/commit.md", "content": "# f commit\n\nAI-powered commit with deferred Codex review and GitEdit sync.\n\n## Overview\n\nStages all changes, commits quickly by default, runs Codex deep review asynchronously in the background, pushes, and syncs AI sessions to gitedit.dev.\n\n## Quick Start\n\n```bash\n# Default flow: commit now, Codex review runs in background\nf commit\n\n# Blocking pre-commit review (legacy behavior)\nf commit --slow\n\n# Fast commit with custom message (no AI review, no Codex follow-up)\nf commit --fast \"fix typo\"\nf commit --fast # defaults to \".\" as message\n\n# Queue for review (no push) + create jj review bookmark\nf commit --queue\n\n# Commit without pushing\nf commit -n\n\n# Include AI context in review\nf commit --context\n\n# Custom message\nf commit -m \"Fixes #123\"\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--no-push` | `-n` | Skip pushing after commit |\n| `--queue` | | Queue the commit for review (no push) |\n| `--no-queue` | | Bypass queue and allow push |\n| `--sync` | | Run synchronously (don't delegate to hub) |\n| `--context` | | Include AI session context in code review |\n| `--dry` | | Dry run: show context without committing |\n| `--quick` | | Explicitly use fast commit + async Codex review (compat alias) |\n| `--slow` | | Run blocking pre-commit review before commit |\n| `--fast [MSG]` | | Fast commit with no AI review (defaults to \".\") |\n| `--codex` | | Use Codex instead of Claude for review |\n| `--review-model <MODEL>` | | Choose specific review model |\n| `--message <MSG>` | `-m` | Custom message appended to commit |\n| `--tokens <N>` | `-t` | Max tokens for AI context (default: 1000) |\n\n## Review Models\n\n| Model | Description |\n|-------|-------------|\n| `claude-opus` | Claude Opus 1 for review (default) |\n| `codex-high` | Codex high-capacity (gpt-5.1-codex-max) |\n| `codex-mini` | Codex mini (gpt-5.1-codex-mini) |\n\n```bash\n# Use Codex\nf commit --codex\n\n# Specific model\nf commit --review-model codex-high\n```\n\n---\n\n## Fast Commit + Deferred Codex Review\n\n`f commit` now uses this mode by default.\n\n### Default (`f commit`) / `--quick` — commit now, Codex reviews later\n\nCommits immediately (generates an AI commit message but skips the blocking code review), then spawns a background Codex review for that commit. The review result is queued and visible via `f commit-queue list`.\n\n```bash\nf commit\nf commit --quick\n```\n\nWhat happens:\n1. Stages all changes, generates commit message, commits, pushes\n2. Queues the commit SHA for async review\n3. Spawns a background Codex process that reviews the diff\n4. You keep working — check results later with `f commit-queue list`\n\n### `--slow` — run blocking review before commit\n\nRuns the pre-commit AI review before creating the commit.\n\n```bash\nf commit --slow\nf commit --slow --review-model codex-high\n```\n\n### `--fast` — instant commit, no review at all\n\nCommits with a provided message (or `\".\"` if omitted). No AI review, no async follow-up. Useful for trivial changes.\n\n```bash\nf commit --fast \"fix typo\"\nf commit --fast # message defaults to \".\"\n```\n\n### When to use which\n\n| Flag | AI message | Code review | Async review | Best for |\n|------|-----------|-------------|-------------|----------|\n| (none) | Yes | No | Yes (Codex background) | Default fast workflow |\n| `--quick` | Yes | No | Yes (Codex background) | Explicit fast mode |\n| `--slow` | Yes | Yes (blocking) | No | Pre-commit deep check |\n| `--fast` | No (you provide) | No | No | Trivial/WIP commits |\n\n### Opt Out Of Fast Default\n\nIf you want plain `f commit` to run blocking review by default, set:\n\n```toml\n[commit]\nquick-default = false\n```\n\nWith this set, plain `f commit` behaves like `f commit --slow` unless you explicitly pass `--quick`.\n\nRun deep review in batches:\n\n```bash\nf reviews-todo codex --all\nf reviews-todo list\n```\n\n### Myflow Fast + Deep Profile\n\nFor `~/code/myflow`, this profile gives a fast default loop while keeping deep Codex coverage:\n\n```toml\n[commit]\nquick-default = true\nqueue = false\nqueue_on_issues = false\n\n# Fast message generation path via zerg/ai (glm + cerebras), then fallbacks.\nmessage_fallbacks = [\n \"rise:zai:glm-5\",\n \"rise:cerebras:gpt-oss-120b\",\n \"remote\",\n \"openai\"\n]\n\n# When you explicitly run blocking review, prefer fast models first.\nreview_fallbacks = [\n \"glm5\",\n \"rise:cerebras:gpt-oss-120b\",\n \"codex-high\"\n]\n```\n\nThen operate with:\n\n```bash\nf commit\nf reviews-todo codex --all\n```\n\n---\n\n## What Happens\n\n1. **Safety Checks**\n - Warns about sensitive files (.env, .pem, keys, credentials)\n - Warns about files with large diffs (500+ lines)\n - Runs invariant checks from `[invariants]` when configured\n\n2. **Stage Changes**\n - Runs `git add -A` to stage all changes\n\n3. **Code Review**\n - Sends diff to AI for review\n - Checks for bugs, security issues, best practices\n - Optionally includes AI session context (`--context`)\n\n4. **Generate Message**\n - AI generates commit message from diff\n - Appends custom message if provided (`-m`)\n\n5. **Commit**\n - Creates commit with generated message\n\n6. **Queue (optional)**\n - Adds commit to the review queue (`f commit-queue list`)\n - Creates a jj review bookmark (e.g., `review/main-<sha>`)\n\n7. **Push**\n - Pushes to remote (unless `--no-push` or `--queue`)\n\n7. **GitEdit Sync**\n - Syncs AI session data to gitedit.dev\n\n## Invariant Gate\n\nIf your project defines `[invariants]` in `flow.toml`, `f commit` evaluates the staged diff against those rules (forbidden patterns, dependency allowlist policy, file line limits).\n\n- `mode = \"warn\"`: commit continues and findings are shown.\n- `mode = \"block\"`: commit is blocked on warning/critical findings.\n- Findings are injected into the AI review context.\n\n---\n\n## Usage Examples\n\n### Basic Commit\n\n```bash\n# Review, commit, and push\nf commit\n```\n\n### Local Commit Only\n\n```bash\n# Don't push to remote\nf commit -n\n```\n\n### With AI Context\n\nInclude recent AI session context in the review:\n\n```bash\nf commit --context\nf commit --context --tokens 2000 # More context\n```\n\n### Custom Message\n\nAppend additional context to the commit:\n\n```bash\nf commit -m \"Fixes #123\"\nf commit -m \"Co-authored-by: John <john@example.com>\"\n```\n\n### Dry Run\n\nSee what would be reviewed without committing:\n\n```bash\nf commit --dry\n```\n\n### Synchronous Mode\n\nRun directly without delegating to hub:\n\n```bash\nf commit --sync\n```\n\n---\n\n## Safety Warnings\n\n### Sensitive Files\n\nBefore committing, flow warns if staging files that look sensitive:\n\n```\n⚠ Warning: The following sensitive files are staged:\n - .env\n - credentials.json\n - private.key\n```\n\nSensitive patterns include:\n- `.env`, `.env.*`\n- `credentials.json`, `secrets.json`\n- `.pem`, `.key`, `id_rsa`, `id_ed25519`\n- Files containing `password`, `secret`, `token`\n\n### Secret Scan (Staged Diff)\n\nFlow scans staged diffs for likely secrets (API keys, tokens, passwords). If a match\nis detected, the commit is blocked. In an interactive terminal, flow offers to run\nan auto-fix using `ai` to mask or replace the values, then asks for approval to\ncontinue.\n\nYou can bypass the check for a single commit with:\n\n```\nFLOW_ALLOW_SECRET_COMMIT=1 f commit\n```\n\n### Large Diffs\n\nWarns about files with significant changes:\n\n```\n⚠ Warning: The following files have large diffs:\n - src/generated.rs (1523 lines)\n - data/fixtures.json (834 lines)\n```\n\nThreshold: 500+ lines added/removed.\n\n---\n\n## Related Commands\n\n| Command | Description |\n|---------|-------------|\n| `f commit` | Fast commit + deferred Codex review (default) |\n| `f commitWithCheck` | Review without GitEdit sync |\n| `f commitSimple` | No review, just AI commit message |\n\n### commitWithCheck (alias: cc)\n\nSame as `commit` but skips GitEdit sync:\n\n```bash\nf commitWithCheck\nf cc # Short alias\n```\n\n### commitSimple\n\nQuick commit without code review:\n\n```bash\nf commitSimple\n```\n\n---\n\n## Configuration\n\n### Hub Delegation\n\nBy default, `f commit` delegates to the hub daemon for async processing. Use `--sync` for direct execution:\n\n```bash\n# Async via hub (default)\nf commit\n\n# Sync (direct)\nf commit --sync\n```\n\n### Commit Message Tool\n\nOptionally force a specific commit-message generator:\n\n```toml\n[commit]\nmessage_tool = \"kimi\" # also supports: claude, rise, glm5, opencode, openrouter, remote, openai\nmessage_model = \"kimi-k2-thinking-turbo\" # optional, tool-specific\n```\n\nIf the forced tool fails, `f commit` now falls back through the configured/default chain.\n\n### Review Tool (Kimi CLI)\n\nUse Kimi Code CLI for code review:\n\n```toml\n[review]\ntool = \"kimi\"\nmodel = \"kimi-k2-thinking-turbo\" # optional; uses Kimi default if omitted\n```\n\nThis uses `kimi --quiet` (print mode) with your existing Kimi CLI auth/config.\n\n### Robust Fallbacks\n\n`f commit` now uses multi-attempt fallback chains for both review and commit-message generation.\n\nDefault behavior:\n- Review: primary selection, then `openrouter`, `claude`, `codex-high`\n- Message: review-aligned/override tool, then `remote` (myflow), `openai`, `openrouter`\n- If all message attempts fail and fail-open is enabled, Flow uses a deterministic local fallback message.\n\nConfiguration:\n\n```toml\n[commit]\nreview_fail_open = true\nmessage_fail_open = true\nreview_fallbacks = [\"openrouter\", \"claude\", \"codex-high\"]\nmessage_fallbacks = [\"remote\", \"openai\", \"openrouter\"]\n```\n\nEnvironment overrides:\n- `FLOW_COMMIT_REVIEW_FAIL_OPEN=0|1`\n- `FLOW_COMMIT_MESSAGE_FAIL_OPEN=0|1`\n- `FLOW_COMMIT_REVIEW_FALLBACKS=\"openrouter,claude,codex-high\"`\n- `FLOW_COMMIT_MESSAGE_FALLBACKS=\"remote,openai,openrouter\"`\n\nCodex -> GLM5 fallback example:\n\n```toml\n[commit]\nreview_fallbacks = [\"glm5\", \"openrouter\", \"claude\"]\nmessage_fallbacks = [\"glm5\", \"remote\", \"openai\"]\n```\n\n`glm5` maps to the Rise/internal route with model `zai:glm-5`.\n\n### Queue Policy\n\nQueue only when review finds issues (auto-push on a clean review):\n\n```toml\n[commit]\nqueue = true\nqueue_on_issues = true\n```\n\n`--queue` / `--no-queue` still override this behavior.\n\n### Commit Quality Gates (Testing + Required Skills)\n\nUse local gates to block commits that skip tests or required workflow skills:\n\n```toml\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\nWhen `mode = \"block\"`, `f commit` fails until the test/skill requirements are satisfied. \nFor Bun repos, run checks with `bun bd test ...` for debug-build validation. If no related tracked tests are found, Flow can run tests under `ai_scratch_test_dir` (default `.ai/test`) as a fallback signal.\n\n### AI Session Context\n\nWhen `--context` is enabled, includes recent Claude Code session context:\n\n```bash\n# Default: 1000 tokens of context\nf commit --context\n\n# More context\nf commit --context --tokens 3000\n```\n\n---\n\n## Examples\n\n### Quick Bug Fix\n\n```bash\n# Fix bug, commit with context\nvim src/lib.rs\nf commit --context -m \"Fixes null pointer in edge case\"\n```\n\n### Feature Branch\n\n```bash\n# Work on feature\ngit checkout -b feature/new-api\n# ... make changes ...\n\n# Commit without push\nf commit -n\n\n# More changes...\nf commit -n\n\n# Final push\ngit push -u origin feature/new-api\n```\n\n### Review Before Commit\n\n```bash\n# See what would be reviewed\nf commit --dry\n\n# If satisfied, commit\nf commit\n```\n\n---\n\n## Troubleshooting\n\n### \"Sensitive files staged\"\n\nEither:\n1. Add files to `.gitignore`\n2. Unstage with `git reset HEAD <file>`\n3. Proceed anyway if intentional\n\n### Review taking too long\n\nUse `--sync` to see progress directly:\n```bash\nf commit --sync\n```\n\n### Hub not responding\n\nFall back to sync mode:\n```bash\nf commit --sync\n```\n\n## See Also\n\n- [upstream](upstream.md) - Sync forks before committing\n- [publish](publish.md) - Publish after committing\n" }, { "path": "docs/commands/commits.md", "content": "# f commits\n\nBrowse commits with AI metadata and mark notable commits for quick access.\n\n## Usage\n\n```bash\nf commits\nf commits --limit 200\nf commits --all\nf commits top\nf commits mark <hash>\nf commits unmark <hash>\n```\n\n## Notable commits\n\nNotable commits are stored in `.ai/internal/commits/top.txt` in the repo root. Each line is:\n\n```\n<full-hash>\\t<label>\n```\n\n## Key bindings\n\nWhen using fzf:\n\n- `ctrl-t` — toggle notable for the selected commit.\n" }, { "path": "docs/commands/db.md", "content": "# db\n\nManage database workflows and backends (Jazz + Postgres).\n\n## Usage\n\n```bash\nf db <provider> <action>\n```\n\n## Jazz\n\nCreate Jazz2 app credentials and populate env vars for the current project.\n\n```bash\nf db jazz new --kind mirror --name gitedit-mirror\n```\n\nResolution order for the credential bootstrap helper:\n\n1. Local `jazz-tools` binary on `PATH`\n2. Pinned `npx --yes jazz-tools@0.20.14`\n\nFor deliberate experiments, override the pinned fallback with:\n\n```bash\nFLOW_JAZZ_TOOLS_PACKAGE_SPEC=jazz-tools@<version> f db jazz new --kind mirror\n```\n\n## Postgres\n\nRun Drizzle migrations for the default Postgres project (`~/org/la/la/server`).\n\n```bash\nf db postgres migrate\nf db postgres migrate --generate\nf db postgres generate\n```\n\nEnvironment resolution order for `DATABASE_URL`:\n\n1. `--database-url` flag\n2. `DATABASE_URL`\n3. `PLANETSCALE_DATABASE_URL` / `PSCALE_DATABASE_URL`\n4. `<project>/.env` (DATABASE_URL)\n\nUse `--project` to override the Postgres project directory.\n" }, { "path": "docs/commands/deploy.md", "content": "# f deploy\n\nDeploy projects to hosts and cloud platforms.\n\n## Overview\n\nThe `deploy` command handles deployment to multiple platforms:\n- **Linux hosts** via SSH (with systemd + nginx)\n- **Cloudflare Workers**\n- **Railway**\n\nAuto-detects the platform from your `flow.toml` configuration.\nIf `[flow].deploy_task` is set, `f deploy` runs that task first.\nIf no deployment config exists but a `deploy` task is defined, `f deploy` runs that task.\nUse `f prod` to deploy directly from `[host]`, `[cloudflare]`, `[railway]`, or `[web]` (it skips `[flow].deploy_task`).\n\n## Quick Start\n\n```bash\n# Auto-deploy based on flow.toml config\nf deploy\n\n# Production deploy (skips flow.deploy_task, uses deploy config or deploy-prod task)\nf prod\n\n# Run the project's release task (flow.release_task or fallback)\nf deploy release\n\n# Deploy to specific platform\nf deploy host\nf deploy cloudflare\nf deploy railway\n\n# Production deploy to specific platform\nf prod host\nf prod cloudflare\n\n# Configure deployment defaults\nf deploy config\n\n# Deploy web site\nf deploy web\n```\n\n## Subcommands\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `host` | `h` | Deploy to Linux host via SSH |\n| `cloudflare` | `cf` | Deploy to Cloudflare Workers |\n| `web` | | Deploy the web site (Cloudflare) |\n| `setup` | | Interactive deploy setup (Cloudflare) |\n| `railway` | | Deploy to Railway |\n| `config` | | Configure deployment defaults (Linux host) |\n| `release` | | Run the project's release task |\n| `status` | | Show deployment status |\n| `logs` | | View deployment logs |\n| `restart` | | Restart the deployed service |\n| `stop` | | Stop the deployed service |\n| `shell` | | SSH into the host |\n| `set-host` | `set` | Configure host for deployment |\n| `show-host` | | Show current host configuration |\n| `health` | | Check if deployment is healthy |\n\n---\n\n## Web Deployment\n\nDeploys the web site using Cloudflare and your project tasks. Flow will:\n- Ensure `[web]` exists in `flow.toml` (auto-fills `path` when possible).\n- Add the `web.route` (or `web.domain/*`) to your wrangler config.\n- Optionally create/update the Cloudflare DNS record for the domain/route.\n- Apply env vars from cloud if `web.env_source = \"cloud\"` is set.\n- Run `deploy-web` (or `deploy` as fallback).\n\n```bash\nf deploy web\n```\n\nIf the Cloudflare API token is missing, Flow will guide you to create one and\nstore it in your env store as `CLOUDFLARE_API_TOKEN`.\n\nIf `web.domain`/`web.route` or `web.path` is missing, Flow will prompt for them\nand update `flow.toml`.\n\nIf you opt into DNS management, Flow will prompt for record type/target and\ncreate or update the Cloudflare DNS record (default: `A` to `192.0.2.1`,\nproxied).\n\nIf cloud is unavailable, Flow can store envs locally when you choose\n`web.env_source = \"local\"`.\n\nExample `flow.toml`:\n\n```toml\n[web]\npath = \"packages/web\"\ndomain = \"example.com\"\nenv_source = \"cloud\"\nenv_apply = \"always\"\nenv_keys = [\"PUBLIC_API_URL\"]\nenv_vars = [\"PUBLIC_API_URL\"]\n```\n\n## Host Deployment (Linux via SSH)\n\nDeploy to any Linux server with SSH access. Flow handles:\n- File syncing via rsync\n- Systemd service creation\n- Nginx reverse proxy setup\n- SSL via Let's Encrypt\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[flow]\ndeploy_task = \"deploy-cli-release\"\n\n[host]\ndest = \"/opt/myapp\" # Remote destination path\nrun = \"./server\" # Command to run the service\nport = 3000 # Port the service listens on\nservice = \"myapp\" # Systemd service name (optional, defaults to folder name)\nsetup = \"./scripts/setup.sh\" # Setup script to run after first sync (optional)\nenv_file = \".env.production\" # Path to .env file for secrets (optional)\nenv_source = \"flow\" # Pull envs from Flow env store (optional)\nenv_keys = [\"API_KEY\"] # Keys to fetch when env_source=flow/cloud (optional)\ndomain = \"myapp.example.com\" # Public domain for nginx (optional)\nssl = true # Enable SSL via Let's Encrypt (optional)\n```\n\nTip: `f setup deploy` can scaffold the `[host]` section and create a remote setup script.\n\n### Setup Host\n\nFirst, configure your SSH connection:\n\n```bash\n# Set host (stored globally at ~/.config/flow/deploy.json)\nf deploy set-host user@host:port\nf deploy set-host deploy@myserver.com:22\nf deploy set-host root@192.168.1.100\n\n# Interactive config (prefills from ~/.config/infra/config.json if present)\nf deploy config\n\n# Verify connection\nf deploy shell\n```\n\n### Deploy\n\n```bash\n# Deploy to host\nf deploy host\n\n# Force re-run setup script\nf deploy host --setup\n\n# Build remotely instead of syncing local artifacts\nf deploy host --remote-build\n```\n\n### What Happens\n\n1. **Sync files** - rsync uploads project (excludes `target/`, `.git/`, `node_modules/`, `.env`, `*.log`)\n2. **Copy env file** - If `env_file` is specified, copies it to `{dest}/.env`\n (or, if `env_source = \"flow\"`, fetches from Flow env store and writes `{dest}/.env`)\n3. **Run setup** - Executes setup script on first deploy or with `--setup`\n4. **Create systemd service** - Generates and enables `/etc/systemd/system/{service}.service`\n5. **Configure nginx** - If `domain` is set, creates reverse proxy config\n6. **Setup SSL** - If `ssl = true`, runs certbot for Let's Encrypt certificate\n7. **Start service** - Runs `systemctl restart {service}`\n\n### Manage Service\n\n```bash\n# View logs\nf deploy logs # Since last deploy (host only)\nf deploy logs -f # Follow in real-time (since last deploy)\nf deploy logs --all # Full history (ignore deploy marker)\nf deploy logs --all -n 500 # Show last 500 lines without deploy filter\n\n# Restart/stop\nf deploy restart\nf deploy stop\n\n# Check status\nf deploy status\n\n# SSH into server\nf deploy shell\n\n# Health check\nf deploy health\nf deploy health --url https://myapp.example.com/health\nf deploy health --status 204 # Expect specific status code\n```\n\nNote: For host deploys, Flow records the last successful deploy time in `.flow/deploy-log.json` and uses it to scope `f deploy logs` output. Use `--all` to ignore it.\n\n---\n\n## Cloudflare Workers\n\nDeploy to Cloudflare's edge network.\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[cloudflare]\npath = \"worker\" # Path to worker directory (optional, defaults to project root)\nenvironment = \"production\" # Wrangler environment name (optional)\nenv_file = \".env.cloudflare\" # Path to .env file for secrets (optional)\nenv_source = \"cloud\" # Use cloud or local env store for secrets (optional)\nenv_keys = [\"API_KEY\", \"SECRET\"] # Specific keys to fetch from env store (optional)\nenv_vars = [\"PUBLIC_URL\"] # Keys to set as non-secret vars (optional)\ndeploy = \"wrangler deploy\" # Custom deploy command (optional)\ndev = \"wrangler dev\" # Custom dev command (optional)\nurl = \"https://my-worker.workers.dev\" # URL for health checks (optional)\n```\n\n### Prerequisites\n\n- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) installed\n- `wrangler.toml` in your worker directory\n- Authenticated with `wrangler login`\n\n### Deploy\n\n```bash\n# Deploy\nf deploy cloudflare\n\n# Deploy with secrets from env_file\nf deploy cloudflare --secrets\n\n# Run in dev mode\nf deploy cloudflare --dev\n```\n\n### Production domain (for `f prod`)\n\nUse `[prod]` to set a production domain or route for Workers. `f prod` will add\nthe route to your `wrangler.json/jsonc` before deploying.\n\n```toml\n[prod]\ndomain = \"anysynth.nikiv.com\" # Will be mapped to route \"anysynth.nikiv.com/*\"\n# route = \"anysynth.nikiv.com/*\" # Use this for explicit patterns\n```\n\n### Interactive Setup\n\nFor first-time setup, use the interactive wizard:\n\n```bash\nf deploy setup\n```\n\nThis walks you through:\n1. Selecting worker directory (auto-discovers `wrangler.toml`)\n2. Choosing .env file for secrets\n3. Selecting Cloudflare environment (production, staging, etc.)\n4. Picking which secrets to push\n5. Updating `flow.toml` with your choices\n\nIf your `flow.toml` lists service keys (for example Stripe keys), the setup flow\nwill offer to run the matching service onboarding before applying envs.\n\n### Secrets from cloud\n\nIf using cloud for secret management:\n\n```toml\n[cloudflare]\nenv_source = \"cloud\"\nenv_keys = [\"ANTHROPIC_API_KEY\", \"DATABASE_URL\"] # Fetched as secrets\nenv_vars = [\"PUBLIC_API_URL\"] # Fetched as non-secret vars\nenvironment = \"production\"\n```\n\nThen deploy:\n\n```bash\nf deploy cloudflare --secrets\n```\n\nIf you want to use local Flow envs instead:\n\n```toml\n[cloudflare]\nenv_source = \"local\"\nenv_keys = [\"ANTHROPIC_API_KEY\", \"DATABASE_URL\"]\nenv_vars = [\"PUBLIC_API_URL\"]\n```\n\nIf you need to fill missing values first:\n\n```bash\nf env guide\n```\n\n---\n\n## Railway\n\nDeploy to Railway's platform.\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[railway]\nproject = \"my-project\" # Railway project ID\nservice = \"api\" # Service name (optional)\nenvironment = \"production\" # Environment name (optional)\nstart = \"npm start\" # Start command (optional)\nenv_file = \".env.railway\" # Path to .env file (optional)\n```\n\n### Prerequisites\n\n- [Railway CLI](https://docs.railway.app/develop/cli) installed (`npm install -g @railway/cli`)\n- Authenticated with `railway login`\n\n### Deploy\n\n```bash\nf deploy railway\n```\n\nWhat happens:\n1. Links to Railway project if specified\n2. Sets environment variables from `env_file`\n3. Deploys with `railway up --detach`\n\n---\n\n## Health Checks\n\nCheck if your deployment is responding:\n\n```bash\n# Use domain from [host] or url from [cloudflare] config\nf deploy health\n\n# Custom URL\nf deploy health --url https://api.example.com/health\n\n# Expect specific status code\nf deploy health --status 204\n```\n\nReturns:\n- `Healthy (HTTP 200 in 0.15s)` on success\n- `Unhealthy: expected HTTP 200, got 500` on wrong status\n- `Unreachable: Connection refused` on network error\n\n---\n\n## Global Host Configuration\n\nHost connection is stored globally at `~/.config/flow/deploy.json`:\n\n```json\n{\n \"host\": {\n \"user\": \"deploy\",\n \"host\": \"myserver.com\",\n \"port\": 22\n }\n}\n```\n\nView/set:\n\n```bash\nf deploy show-host\nf deploy set-host deploy@newserver.com:2222\n```\n\n---\n\n## Examples\n\n### Full Host Setup\n\n```toml\n# flow.toml\n[host]\ndest = \"/opt/api\"\nrun = \"/opt/api/server\"\nport = 8080\nservice = \"myapi\"\nsetup = \"cargo build --release && cp target/release/server /opt/api/\"\nenv_file = \".env.production\"\ndomain = \"api.mycompany.com\"\nssl = true\n```\n\n```bash\n# First time setup\nf deploy set-host root@myserver.com\n\n# Deploy\nf deploy host\n\n# Check it's working\nf deploy health\nf deploy logs -f\n```\n\n### Full Cloudflare Setup\n\n```toml\n# flow.toml\n[cloudflare]\npath = \"packages/worker\"\nenvironment = \"production\"\nenv_source = \"cloud\"\nenv_keys = [\"OPENAI_API_KEY\", \"WEBHOOK_SECRET\"]\nurl = \"https://my-worker.mycompany.workers.dev\"\n```\n\n```bash\n# Store project secrets\nf env project set -e production OPENAI_API_KEY=sk-...\nf env project set -e production WEBHOOK_SECRET=whsec_...\n\n# Deploy with secrets\nf deploy cloudflare --secrets\n\n# Verify\nf deploy health\n```\n\n### CI/CD Integration\n\n```yaml\n# GitHub Actions\ndeploy:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Deploy\n run: |\n f deploy set-host ${{ secrets.DEPLOY_HOST }}\n f deploy host\n f deploy health\n```\n\n---\n\n## Troubleshooting\n\n### \"No host configured\"\n\nRun `f deploy set-host user@host:port` first.\n\n### \"No wrangler config found\"\n\nEnsure `wrangler.toml` exists in your worker directory, or run `wrangler init`.\n\n### SSH connection fails\n\nTest with `f deploy shell` to debug. Check:\n- SSH key is in `~/.ssh/` and added to server\n- Port is correct (default: 22)\n- Server is reachable\n\n### Secrets not updating\n\nFor Cloudflare, use `--secrets` flag: `f deploy cloudflare --secrets`\n\n### Health check fails\n\nCheck URL is correct and service is running:\n```bash\nf deploy logs -f # Check for errors\ncurl -v https://your-domain.com # Test manually\n```\n" }, { "path": "docs/commands/docs.md", "content": "# f docs\n\nManage documentation for a project. There are two doc systems:\n\n- `.ai/docs` for AI-maintained internal docs.\n- `docs/` for human-facing docs rendered by the docs hub.\n\n## Quick Start\n\n```bash\n# Create docs/ with starter files\nf docs new\n\n# Open docs for the current project (auto-starts the hub)\nf docs\n\n# Deploy the current project's docs to Cloudflare Pages\nf docs deploy\n```\n\n## Commands\n\n### f docs new\n\nCreates a `docs/` folder in the current project using the template in `~/new/docs`.\nIf `docs/` already exists, it merges in any missing template files and leaves\nexisting content untouched.\n\nOptions:\n\n- `--path <PATH>`: Target directory (defaults to current folder).\n- `--force`: Overwrite if `docs/` already exists.\n\n### f docs hub\n\nRuns a single dev server that aggregates docs from `~/code` and `~/org`.\nUse `FLOW_DOCS_FOCUS=1` to only index the current project for faster startup.\n\nOptions:\n\n- `--host <HOST>` (default: `127.0.0.1`)\n- `--port <PORT>` (default: `4410`)\n- `--hub-root <PATH>` (default: `~/.config/flow/docs-hub`)\n- `--template-root <PATH>` (default: `~/new/docs`)\n- `--code-root <PATH>` (default: `~/code`)\n- `--org-root <PATH>` (default: `~/org`)\n- `--no-ai`: Skip `.ai/docs`.\n- `--no-open`: Do not open the browser.\n- `--sync-only`: Sync docs content and exit.\n\n### f docs deploy\n\nDeploys the current project's docs to Cloudflare Pages (uses the docs hub template).\n\nOptions:\n\n- `--project <NAME>`: Pages project name (defaults to the flow.toml name).\n- `--domain <DOMAIN>`: Attach a custom domain (optional).\n- `--yes`: Skip confirmation prompts.\n\n### f docs sync\n\nSyncs `.ai/docs` metadata based on recent commits. Intended for AI doc upkeep.\n\n### f docs list\n\nLists `.ai/docs` files for the current project.\n\n### f docs status\n\nShows recent commits and `.ai/docs` file modification times.\n\n### f docs edit\n\nOpens a `.ai/docs` file in `$EDITOR`.\n\nExample:\n\n```bash\nf docs edit architecture\n```\n" }, { "path": "docs/commands/domains.md", "content": "# `f domains`\n\nManage shared local `*.localhost` routing with a single proxy on port `80`.\n\n## Why\n\nWithout this, each repo can start its own proxy and race for port `80`.\n`f domains` centralizes ownership with one engine at a time.\n\nState lives in:\n\n- `~/.config/flow/local-domains/routes.json`\n- runtime artifacts under `~/.config/flow/local-domains/`\n\n## Engines\n\n- `docker` (default): shared nginx container (`flow-local-domains-proxy`)\n- `native` (experimental): local C++ daemon (`domainsd-cpp`)\n\nSelect engine per command:\n\n```bash\nf domains --engine docker up\nf domains --engine native up\n```\n\nOr via env:\n\n```bash\nexport FLOW_DOMAINS_ENGINE=native\n```\n\n## Commands\n\n```bash\nf domains list\nf domains add linsa.localhost 127.0.0.1:3481\nf domains rm linsa.localhost\nf domains up\nf domains down\nf domains doctor\nf domains --engine native up\nf domains --engine native down\nf domains --engine native doctor\n```\n\n## Behavior\n\n- `f domains up`\n - starts shared proxy on `:80`\n - fails fast if another process/container owns port `80`\n- `f domains add`\n - validates `host` ends with `.localhost`\n - validates target format `host:port`\n - refuses overwrite unless `--replace`\n - reloads proxy if already running\n- `f domains doctor`\n - shows route count\n - shows current owner of port `80`\n - highlights conflict ownership\n\n## Native notes (experimental)\n\n- Requires `clang++` to build `tools/domainsd-cpp/domainsd.cpp`.\n- Current scope is HTTP/1.1 host routing with WebSocket upgrade passthrough and upstream keepalive pooling.\n- Native daemon has built-in overload shedding (`503`) and upstream timeout protection (`504` on connect timeout).\n- HTTP/2/TLS are not implemented yet.\n- See `docs/local-domains-domainsd-cpp-spec.md`.\n- myflow-specific setup: `docs/myflow-localhost-runbook.md`.\n- Lifecycle integration: configure `[lifecycle.domains]` and use `f up` / `f down`.\n\n### macOS no-docker bind to :80\n\nIf native startup fails with `Permission denied` on `127.0.0.1:80`, install launchd socket mode once:\n\n```bash\ncd ~/code/flow\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\nThen run:\n\n```bash\nf domains --engine native up\n```\n\nThis keeps routing fully native and avoids Docker overhead while still using port `80`.\n\n### Native tuning envs\n\nYou can tune the native daemon at startup via environment variables:\n\n```bash\nFLOW_DOMAINS_NATIVE_MAX_ACTIVE_CLIENTS=128\nFLOW_DOMAINS_NATIVE_UPSTREAM_CONNECT_TIMEOUT_MS=10000\nFLOW_DOMAINS_NATIVE_UPSTREAM_IO_TIMEOUT_MS=15000\nFLOW_DOMAINS_NATIVE_CLIENT_IO_TIMEOUT_MS=30000\nFLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_PER_KEY=8\nFLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_TOTAL=256\nFLOW_DOMAINS_NATIVE_POOL_IDLE_TIMEOUT_MS=15000\nFLOW_DOMAINS_NATIVE_POOL_MAX_AGE_MS=120000\n```\n## Recommended Repo Pattern\n\nInstead of per-repo docker proxy tasks:\n\n```toml\n[[tasks]]\nname = \"domains-up\"\ncommand = \"f domains add myapp.localhost 127.0.0.1:3000 && f domains up\"\n```\n\nThis keeps one proxy process for all repos and avoids accidental domain hijacking.\n" }, { "path": "docs/commands/down.md", "content": "# f down\n\nBring a project down using lifecycle conventions.\n\n## Quick Start\n\n```bash\n# Run lifecycle down task and optional domains teardown\nf down\n```\n\n## Behavior\n\n- Loads nearest `flow.toml` (or `--config` path).\n- Runs lifecycle task:\n - `[lifecycle].down_task` when configured\n - otherwise fallback: `down`\n- If no down task is found and `down_task` is not explicitly set, Flow falls back to killing all running Flow-managed processes for the current project (`f kill --all` behavior).\n- If `[lifecycle.domains]` is configured, optional teardown is applied:\n - `remove_on_down = true` -> removes configured host route\n - `stop_proxy_on_down = true` -> stops shared local domains proxy\n- On macOS launchd-managed native domains, stopping native proxy is handled by:\n - `sudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh`\n\nIf neither a down task nor lifecycle domain teardown is configured, command fails with guidance.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`, searches upward when default is missing) |\n| `ARGS...` | Extra args passed to the selected lifecycle task |\n" }, { "path": "docs/commands/env.md", "content": "# f env\n\nSync project environment and manage environment variables.\n\n## Overview\n\nManage environment variables via cloud or local storage. Supports:\n- Project-level environment variables\n- Personal/global variables\n- Multiple environments (dev, staging, production)\n- Direct injection into commands\n- Touch ID gating for cloud reads and keychain-backed personal local reads on macOS\n- Client-side sealed project env sharing in the cloud\n\n## Storage Backends\n\n| Backend | Location | Config |\n|---------|----------|--------|\n| `cloud` | Cloud (myflow.sh) | Default, requires login |\n| `local` | `~/.config/flow/env-local/` | No account needed |\n\nCloud behavior:\n- Personal cloud envs use Flow's existing server-managed secret storage.\n- Project cloud envs are sealed client-side before upload and decrypted locally on read.\n- If a host deploy is configured with `env_source = \"cloud\"` plus a `service_token`, Flow keeps a compatibility plaintext mirror for those project keys until the host fetch path is upgraded.\n\nForce local backend:\n\n```bash\n# Via environment variable\nexport FLOW_ENV_BACKEND=local\n\n# Or in ~/.config/flow/config.ts\nexport default {\n flow: { env: { backend: \"local\" } }\n}\n```\n\nIf the current project has an unambiguous deploy env source such as:\n\n```toml\n[host]\nenv_source = \"local\"\n```\n\nthen `f env` will also use the local backend automatically in that project.\n\n### Local Storage Structure\n\n```\n~/.config/flow/env-local/\n├── <project-name>/\n│ ├── production.env\n│ ├── staging.env\n│ └── dev.env\n└── personal/\n └── production.env\n```\n\nStorage behavior:\n- Project-local envs are private `.env` files under `~/.config/flow/env-local/`.\n- On macOS, personal-local env values are stored in Keychain by default; `personal/production.env` keeps Flow-managed references, not raw secret values.\n- If `FLOW_ENV_LOCAL_PLAINTEXT=1` is set, Flow falls back to plaintext personal local storage.\n- Local env paths are written with owner-only permissions.\n\n## Quick Start\n\n```bash\n# Store a personal secret\nf env set API_KEY=sk-xxx\n\n# List variables (default action when logged in)\nf env\n\n# Run command with env vars injected\nf env run -- npm start\n\n# Get a value\nf env get API_KEY -f value\n```\n\n## Linsa/TestFlight Example\n\nFor project-scoped keys used by local + ship flows (for example, assistant keys):\n\n```bash\n# Store in project space (recommended for app/server env)\nf env project set -e dev OPENROUTER_API_KEY=sk-...\nf env project set -e production OPENROUTER_API_KEY=sk-...\nf env project set -e dev OPENROUTER_MODEL=anthropic/claude-sonnet-4.5\nf env project set -e production OPENROUTER_MODEL=anthropic/claude-sonnet-4.5\n```\n\nNotes:\n- Do not commit secrets to docs or repository files.\n- Use `f env get -e production -f value OPENROUTER_API_KEY` at runtime when a ship script needs to inject a missing key.\n\n## Subcommands\n\n| Command | Description |\n|---------|-------------|\n| `login` | Authenticate with cloud |\n| `set` | Set a single env var |\n| `get` | Get specific env var(s) |\n| `list` | List env vars for this project |\n| `delete` | Delete env var(s) |\n| `pull` | Fetch env vars and write to .env |\n| `push` | Push local .env to cloud |\n| `apply` | Apply env vars to Cloudflare worker |\n| `setup` | Interactive wizard to push env vars |\n| `run` | Run command with env vars injected |\n| `status` | Show current auth status |\n| `keys` | Show configured env keys from flow.toml |\n| `sync` | Sync project settings and hub workflow |\n| `bootstrap` | Bootstrap Cloudflare secrets from flow.toml |\n| `unlock` | Unlock env reads (Touch ID on macOS) |\n\n---\n\n## Set\n\nStore a personal environment variable:\n\n```bash\n# Basic set\nf env set API_KEY=sk-xxx\n\n# Personal envs always use the production personal store\nf env set GITHUB_TOKEN=ghp_xxx\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--personal` | | Compatibility flag; `set` already targets personal envs |\n\n## Project Set\n\nStore a project-scoped environment variable:\n\n```bash\nf env project set -e dev DATABASE_URL=postgres://localhost/app\nf env project set -e production PUBLIC_API_BASE_URL=https://api.example.com\n```\n\nNotes:\n- Project cloud writes are sealed by default.\n- On a new device, the first project read/write auto-registers that device as a sealer.\n- If a key exists in cloud but was never shared to this device, Flow will ask you to re-save it from a device that already has access.\n\n---\n\n## Get\n\nRetrieve environment variables:\n\n```bash\n# Get as KEY=VALUE\nf env get API_KEY\n# API_KEY=sk-xxx\n\n# Get just the value\nf env get API_KEY -f value\n# sk-xxx\n\n# Get as JSON\nf env get API_KEY -f json\n# {\"API_KEY\": \"sk-xxx\"}\n\n# Get multiple\nf env get API_KEY DATABASE_URL\n\n# From personal store\nf env get --personal GITHUB_TOKEN -f value\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--environment <ENV>` | `-e` | Environment (default: production) |\n| `--format <FORMAT>` | `-f` | Output: `env`, `json`, or `value` (default: env) |\n| `--personal` | | Fetch from personal store |\n\n---\n\n## List\n\nList all environment variables:\n\n```bash\n# List production vars\nf env list\n\n# List staging vars\nf env list -e staging\n```\n\nOutput:\n```\nEnvironment: production\n\n API_KEY OpenAI API key\n DATABASE_URL PostgreSQL connection string\n REDIS_URL -\n```\n\n---\n\n## Run\n\nRun a command with environment variables injected:\n\n```bash\n# Inject all project env vars\nf env run -- npm start\n\n# Inject specific keys\nf env run -k API_KEY -k DATABASE_URL -- node server.js\n\n# From personal store\nf env run --personal -k GITHUB_TOKEN -- gh repo list\n\n# Multiple keys from personal\nf env run --personal -k TELEGRAM_BOT_TOKEN -k TELEGRAM_API_ID -- ./start.sh\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--environment <ENV>` | `-e` | Environment (default: production) |\n| `--keys <KEYS>` | `-k` | Specific keys to inject (repeatable) |\n| `--personal` | | Fetch from personal store |\n\n### Examples\n\n```bash\n# Start app with production secrets\nf env run -- npm run start\n\n# Run with staging environment\nf env run -e staging -- npm run dev\n\n# Telegram bot with personal tokens\nf env run --personal -k TELEGRAM_BOT_TOKEN -- pnpm tsx src/bot.ts\n```\n\n---\n\n## Pull\n\nFetch all env vars and write to `.env` file:\n\n```bash\n# Write to .env\nf env pull\n\n# Pull staging vars\nf env pull -e staging\n```\n\nCreates or overwrites `.env` in current directory with all project variables.\n\n---\n\n## Push\n\nUpload local `.env` file to cloud:\n\n```bash\nf env push\n```\n\nReads `.env` from current directory and stores all variables.\n\n---\n\n## Setup\n\nInteractive wizard for pushing env vars:\n\n```bash\nf env setup\n```\n\nIf `[cloudflare] env_source = \"cloud\"` is set in `flow.toml`, this runs a guided\nprompt based on `env_keys`/`env_vars`. Otherwise it guides you through:\n1. Reading your `.env` file\n2. Selecting which keys to push\n3. Confirming before upload\n\n---\n\n## Delete\n\nRemove environment variables:\n\n```bash\n# Delete single key\nf env delete API_KEY\n\n# Delete multiple\nf env delete API_KEY DATABASE_URL\n```\n\n---\n\n## Login\n\nAuthenticate with cloud:\n\n```bash\nf env login\n```\n\nPrompts for API base URL and token. On macOS, the token is stored in Keychain\nand Flow uses Touch ID to unlock env reads.\n\n---\n\n## Status\n\nCheck authentication status:\n\n```bash\nf env status\n```\n\nOutput:\n```\ncloud Status\n Token: stored in Keychain\n API: https://myflow.sh\n Project: myproject\n```\n\n---\n\n## Apply\n\nApply env vars to Cloudflare worker (uses `[cloudflare]` config in flow.toml):\n\n```bash\nf env apply\n```\n\nRequires `env_source = \"cloud\"` in your `[cloudflare]` config.\n\n## Keys\n\nShow env keys configured in `flow.toml` without printing values:\n\n```bash\nf env keys\n```\n\n## Unlock\n\nOn macOS, unlock env reads for the day (Touch ID):\n\n```bash\nf env unlock\n```\n\n---\n\n## Environments\n\nFlow supports three environments:\n\n| Environment | Description |\n|-------------|-------------|\n| `production` | Production secrets (default) |\n| `staging` | Staging/preview secrets |\n| `dev` | Development secrets |\n\nUse `-e` flag with project-scoped commands:\n\n```bash\nf env project set DATABASE_URL=postgres://staging... -e staging\nf env list -e dev\nf env run -e staging -- npm run preview\n```\n\n---\n\n## Personal vs Project Variables\n\n| Type | Flag | Scope | Use Case |\n|------|------|-------|----------|\n| Project | (default for `get`, `list`, `run`, `project ...`) | Current project | API keys, database URLs |\n| Personal | `--personal` | Global/user | GitHub token, Telegram bot token |\n\nPersonal variables are tied to your user account, not a specific project.\n`f env set` writes personal vars. Use `f env project set` for project vars.\n\n```bash\n# Use a personal token in any project\nf env run --personal -k ANTHROPIC_API_KEY -- ./my-script\n```\n\n---\n\n## Env Space Overrides\n\nYou can store project envs under a named cloud space by configuring `env_space`\nand `env_space_kind` in `flow.toml`.\n\n```toml\n# flow.toml\nenv_space = \"nikiv\"\nenv_space_kind = \"personal\"\n```\n\n- `env_space_kind = \"project\"` (default) uses the project name.\n- `env_space_kind = \"personal\"` routes project envs to your personal space.\n\nThis affects `f env pull`, `f env push`, `f env list`, `f env apply`, and service\ntoken creation.\n\n---\n\n## Examples\n\n### Typical Workflow\n\n```bash\n# 1. Authenticate\nf env login\n\n# 2. Set up secrets\nf env project set DATABASE_URL=postgres://... -e production\nf env project set API_KEY=sk-xxx -e production\n\n# 3. Verify\nf env list\n\n# 4. Run app\nf env run -- npm start\n```\n\n### Staging Deploy\n\n```bash\n# Set staging secrets\nf env project set DATABASE_URL=postgres://staging... -e staging\nf env project set API_KEY=sk-test-xxx -e staging\n\n# Test with staging env\nf env run -e staging -- npm run preview\n```\n\n### Personal Tokens for CLI Tools\n\n```bash\n# Store once\nf env set --personal GITHUB_TOKEN=ghp_xxx\nf env set --personal TELEGRAM_BOT_TOKEN=xxx\n\n# Use anywhere\nf env run --personal -k GITHUB_TOKEN -- gh repo list\n```\n\n### In flow.toml Tasks\n\n```toml\n[tasks.start]\ncommand = \"f env run -- npm start\"\n\n[tasks.bot]\ncommand = \"f env run --personal -k TELEGRAM_BOT_TOKEN -- node bot.js\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Not authenticated\"\n\nRun `f env login` to authenticate with cloud.\n\n### \"No env vars found\"\n\nCheck environment name - default is `production`:\n```bash\nf env list -e staging # Check staging instead\n```\n\n### Variables not injecting\n\nEnsure command comes after `--`:\n```bash\nf env run -k API_KEY -- npm start # Correct\nf env run -k API_KEY npm start # May not work\n```\n\n## See Also\n\n- [deploy](deploy.md) - Using env vars in deployments\n- [docs/how-to-use-env.md](../how-to-use-env.md) - Extended usage guide\n" }, { "path": "docs/commands/fast.md", "content": "# f fast\n\nRun AI tasks through the low-latency fast client path.\n\nThis command is optimized for hot-loop invocation and prefers `fai`/`ai-taskd-client` over full `f` task startup.\n\n## Usage\n\n```bash\nf fast ai:flow/noop\nf fast ai:flow/bench-cli -- --iterations 30\nf fast --root ~/code/flow ai:flow/dev-check\nf fast --no-cache ai:flow/dev-check\n```\n\n## Behavior\n\n1. Tries fast client dispatch (`fai`, local `target/.../ai-taskd-client`, or `ai-taskd-client` on PATH).\n2. If daemon is not running, starts `ai-taskd` and retries.\n3. Falls back to direct daemon dispatch if no fast client binary is found.\n\n## Options\n\n- `--root <PATH>`: root directory for `.ai/tasks` discovery (default `.`)\n- `--no-cache`: disable cached binary execution and use direct Moon run\n- `TASK`: required AI selector like `ai:flow/dev-check`\n- trailing args after `--` are passed to the task\n\n## Notes\n\n- `f fast` is intentionally for `ai:*` selectors only.\n- Install `fai` for best latency:\n\n```bash\nf install-ai-fast-client\nf tasks daemon start\nf fast ai:flow/noop\n```\n\nFor pooled burst execution and timings, use `fai` directly:\n\n```bash\nfai --timings ai:flow/noop\nprintf 'ai:flow/noop\\nai:flow/noop\\n' | fai --batch-stdin --timings\n```\n" }, { "path": "docs/commands/global.md", "content": "# f global\n\nRun tasks from your global flow config (`~/.config/flow/flow.toml`).\n\n## Quick Start\n\n```bash\n# List global tasks\nf global --list\nf global list\n\n# Run a global task from anywhere\nf global repos-clone-safari\nf global run repos-clone-safari\n\n# Match a query against global tasks\nf global match \"clone safari repo\"\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `<TASK>` | | Global task name (omit to list) |\n| `list` | | List global tasks |\n| `run <TASK>` | | Run a global task |\n| `match <QUERY>` | | Match a query against global tasks |\n| `--list` | `-l` | List global tasks |\n| `-- <ARGS...>` | | Pass extra args to the task |\n\n## Examples\n\n```bash\nf global repos-clone-safari https://github.com/0xPlaygrounds/rig\n```\n" }, { "path": "docs/commands/install.md", "content": "# f install\n\nInstall a CLI/tool binary into your PATH.\n\nDefault backend behavior (`--backend auto`):\n1. Flow registry (`myflow.sh` or `--registry`)\n2. GitHub releases via `parm`\n3. flox package install\n\n## Usage\n\n```bash\nf install <name>\n```\n\n## Options\n\n- `--registry <URL>`: registry base URL (defaults to `FLOW_REGISTRY_URL`).\n- `--backend <auto|registry|parm|flox>`: choose install backend explicitly.\n- `--version <VERSION>`: install a specific version (defaults to latest).\n- `--bin <NAME>`: binary name to install (defaults to manifest default or package name).\n- `--bin-dir <PATH>`: install directory (defaults to `~/bin`).\n- `--force`: overwrite an existing binary.\n- `--no-verify`: skip checksum verification.\n\n## Auto backend notes\n\n- `f install rise` can resolve through `parm` using built-in owner/repo mapping.\n- Built-in aliases:\n - `f install seqd` resolves registry package `seq` with binary `seqd`.\n - `f install lin` resolves registry package `flow` with binary `lin`.\n- If a package name is ambiguous for `parm`, set `FLOW_INSTALL_OWNER` (env or Flow personal env store) or pass `owner/repo` directly.\n\n## Bootstrap from installer\n\nThe hosted installer can bootstrap core tools after installing flow:\n\n- `FLOW_BOOTSTRAP_TOOLS=\"rise seq seqd\"` (default) installs those with `f install ... --backend auto`.\n- `FLOW_BOOTSTRAP_TOOLS=0` disables this.\n- `FLOW_BOOTSTRAP_INSTALL_PARM=1` (default) attempts to install `parm` for robust GitHub fallback.\n\n## Registry layout\n\nThe registry must expose:\n\n- `GET /packages/<name>/latest.json`\n- `GET /packages/<name>/<version>/manifest.json`\n- `GET /packages/<name>/<version>/<target>/<bin>`\n\n## Example\n\n```bash\nFLOW_REGISTRY_URL=https://myflow.sh f install flow\n```\n\n```bash\nf install rise\n```\n" }, { "path": "docs/commands/invariants.md", "content": "# f invariants\n\nValidate project invariants declared in `flow.toml`.\n\nThis command checks the `[invariants]` section and reports violations in changed code.\n\n## Usage\n\n```bash\n# Check all local changes vs HEAD\nf invariants\n\n# Check only staged changes\nf invariants --staged\n```\n\n## What It Checks\n\n1. `forbidden`: disallowed patterns in added diff lines.\n2. `deps.approved`: unapproved dependencies in `package.json` sections (`dependencies`, `devDependencies`, `peerDependencies`).\n3. `files.max_lines`: changed files exceeding the configured line limit.\n\n## Modes\n\nSet in `flow.toml`:\n\n- `mode = \"off\"`: disable checks.\n- `mode = \"warn\"`: print findings, exit success.\n- `mode = \"block\"`: fail command when blocking findings exist.\n\n## Example `flow.toml`\n\n```toml\n[invariants]\nmode = \"block\"\narchitecture_style = \"layered monorepo, event-driven core\"\nnon_negotiable = [\n \"no inline imports\",\n \"no any types unless justified\",\n]\nforbidden = [\n \"git add -A\",\n \"git reset --hard\",\n]\n\n[invariants.terminology]\n\"pi-ai\" = \"LLM abstraction layer\"\n\"pi-agent\" = \"stateful agent runtime\"\n\n[invariants.deps]\npolicy = \"approval_required\"\napproved = [\"@sinclair/typebox\", \"@reatom/core\"]\n\n[invariants.files]\nmax_lines = 300\n```\n\n## Commit Integration\n\n`f commit` runs the invariant gate during commit-with-check flow.\n\n- In `mode = \"block\"`, commits are blocked on invariant warnings/critical findings.\n- Invariant context and findings are injected into AI review prompts.\n\n" }, { "path": "docs/commands/jj.md", "content": "# jj\n\nFlow wraps common Jujutsu (jj) workflows so you can stay in jj while remaining fully Git-compatible.\n\n## Quick start\n\n```bash\n# Inspect workspace + home-branch state\nf status\n\n# Initialize jj (colocated with git when .git exists)\nf jj init\n\n# Create a feature bookmark and track origin\nf jj bookmark create feature-x --track\n\n# Fetch + rebase onto main + push bookmark\nf jj sync --bookmark feature-x\n```\n\n## Commands\n\n- `f status` — Show workflow-aware JJ status (workspace, home branch, leaf branches, working-copy summary, and next-step hints)\n- `f jj status` — Show raw `jj st`\n- `f jj fetch` — `jj git fetch`\n- `f jj rebase --dest <branch>` — Rebase onto `jj.default_branch` (or main/master)\n- `f jj push --bookmark <name>` — Push a single bookmark\n- `f jj push --all` — Push all bookmarks\n- `f jj sync --bookmark <name>` — Fetch, rebase, then push bookmark\n- `f jj workspace add <name> [--path <dir>] [--rev <rev>]` — Create a workspace (optionally anchored to a revision)\n- `f jj workspace lane <name> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch]` — Create an isolated parallel lane from trunk defaults\n- `f jj workspace review <branch> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch]` — Create or reuse a stable JJ review workspace for a branch without touching the current checkout\n- `f jj workspace list` — List workspaces\n- `f jj bookmark create <name> [--rev <rev>] [--track]` — Create bookmark\n- `f jj bookmark track <name> [--remote <remote>]` — Track remote bookmark\n\n## Status-first workflow\n\nUse `f status` before branch, workspace, commit, or publish operations.\n\nIt is the fast way to answer:\n\n- which workspace am I in?\n- am I on the long-lived home branch or a branch-specific leaf?\n- what review or codex branches currently sit on top of the home branch?\n- is the working copy clean enough to mutate safely?\n\nExample:\n\n```bash\ncd ~/code/org/project\nf status\n```\n\nUse `f jj status` only when you want the raw Jujutsu working-copy view.\n\n## Parallel lanes (no interleaving)\n\nUse lanes when you want multiple active tasks in one repo without stash/pop churn:\n\n```bash\n# In your current repo, create isolated lanes anchored from trunk\nf jj workspace lane fix-otp\nf jj workspace lane testflight\n\n# Work each lane independently\ncd ~/.jj/workspaces/<repo>/fix-otp\njj st\n```\n\n`f jj workspace lane` does:\n\n1. `jj git fetch` (unless `--no-fetch`)\n2. chooses base as `<default_branch>@<remote>` when tracked (fallback: `<default_branch>`)\n3. creates a dedicated workspace with its own `@` working-copy commit\n\n## Review workspaces\n\nUse a review workspace when you want an isolated JJ working copy for a review branch without\ntouching the current repo checkout:\n\n```bash\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/<repo>/review-alice-feature\njj st\n```\n\n`f jj workspace review` does:\n\n1. `jj git fetch` (unless `--no-fetch`)\n2. reuses the existing review workspace when present\n3. otherwise anchors the workspace at the local branch commit, then the remote branch commit, then trunk\n4. prints the stable workspace path plus the JJ bookmark command to publish later\n\nImportant:\n\n- The review workspace is JJ-native. Use `jj` or `f jj` inside it.\n- In colocated repos, plain `git` still points at the main checkout, so this command intentionally does not run `flow switch` for you.\n\n## Config\n\nAdd to `flow.toml`:\n\n```toml\n[git]\nremote = \"myflow-i\" # optional preferred writable remote\n\n[jj]\ndefault_branch = \"main\"\nhome_branch = \"alice\" # optional long-lived personal integration branch\nremote = \"origin\" # optional legacy fallback if [git].remote is unset\nauto_track = true\n```\n\nThis keeps jj aligned with Git remotes while you work locally in jj.\n\n## Home-branch model\n\nIf you keep a long-lived personal branch on top of trunk, set `jj.home_branch` and treat it as\nyour integration branch.\n\nThen use short-lived `review/*` or `codex/*` branches on top of that home branch for task-specific\nwork. `f status` is optimized to make that shape visible.\n\nRecommended flow:\n\n```bash\n# Default checkout stays on your home branch\ncd ~/code/org/project\nf status\n\n# Branch-specific work happens in isolated workspaces\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/project/review-alice-feature\nf status\n```\n\nSee also:\n\n- [`jj-review-workspaces.md`](../jj-review-workspaces.md)\n- [`jj-home-branch-workflow.md`](../jj-home-branch-workflow.md)\n" }, { "path": "docs/commands/migrate.md", "content": "# f migrate\n\nMove or copy a project folder to a new location, preserving symlinks and AI sessions.\n\n## Overview\n\nRelocates a project directory and automatically migrates Claude and Codex AI sessions so conversation history follows the project. Also relinks any `~/bin` symlinks that pointed into the old path (move only).\n\n## Quick Start\n\n```bash\n# Move current directory into ~/code/lang/cpp/stream\ncd ~/code/lang/cpp/stream\nf migrate code stream\n\n# Move current directory to an arbitrary path\nf migrate ~/code/stream\n\n# Move a specific source to a target\nf migrate ~/code/lang/cpp/stream ~/code/stream\n\n# Preview what would happen (no changes)\nf migrate --dry-run code stream\n\n# Copy instead of move (keeps original)\nf migrate --copy code stream\n```\n\n## Your case\n\nTo migrate `~/code/lang/cpp/stream` to `~/code/stream`:\n\n```bash\ncd ~/code/lang/cpp/stream\nf migrate code stream\n```\n\nOr without `cd`:\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\nPreview first with `--dry-run`:\n\n```bash\nf migrate --dry-run ~/code/lang/cpp/stream ~/code/stream\n```\n\n## Usage Forms\n\n### `f migrate code <relative>`\n\nMoves the current directory into `~/code/<relative>`. This is the most common form.\n\n```bash\ncd ~/old/location/myproject\nf migrate code myproject # -> ~/code/myproject\nf migrate code lang/rust/mylib # -> ~/code/lang/rust/mylib\n```\n\n### `f migrate <target>`\n\nMoves the current directory to `<target>` (any absolute or relative path).\n\n```bash\ncd ~/old/location/myproject\nf migrate ~/code/myproject\n```\n\n### `f migrate <source> <target>`\n\nMoves `<source>` to `<target>` without needing to `cd` first.\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--copy` | `-c` | Copy instead of move (keeps the original intact) |\n| `--dry-run` | | Show what would change without writing anything |\n| `--skip-claude` | | Skip migrating Claude Code sessions |\n| `--skip-codex` | | Skip migrating Codex sessions |\n\n## What Happens\n\n### Step 1: Move or copy the folder\n\nThe project directory is moved (or copied with `--copy`) to the target path. Parent directories are created automatically. Cross-device moves are handled transparently (copy + delete).\n\n### Step 2: Relink ~/bin symlinks (move only)\n\nAny symlinks in `~/bin` that pointed into the old path are updated to point to the new location. Skipped when using `--copy`.\n\n### Step 3: Migrate AI sessions\n\nClaude and Codex store project sessions keyed by filesystem path. Migrate updates these so conversation history is preserved at the new location.\n\n- **Claude sessions**: Project directories under `~/.claude/projects/` are renamed from the old path-based key to the new one.\n- **Codex sessions**: Legacy project directories are renamed, and `.jsonl` session files referencing the old path are updated in-place.\n\nA summary is printed showing how many session dirs/files were migrated.\n\n## Examples\n\n```bash\n# Move project into ~/code, nested path\ncd ~/downloads/cool-project\nf migrate code tools/cool-project\n\n# Copy a project (keeps original)\nf migrate --copy ~/code/app ~/backup/app\n\n# Dry run to preview\nf migrate --dry-run code stream\n\n# Move without migrating AI sessions\nf migrate --skip-claude --skip-codex ~/old/path ~/new/path\n\n# Move and only migrate Claude (skip Codex)\nf migrate --skip-codex code myproject\n```\n\n## Troubleshooting\n\n### \"Destination already exists\"\n\nThe target path must not exist. Remove or rename the existing directory first, or choose a different target.\n\n### \"Source and destination are the same path\"\n\nBoth paths resolve to the same location. Double-check your arguments.\n\n### Session migration warnings\n\nAfter a move, you may see warnings like:\n\n```\nWARN Claude session dir still present: ...\nWARN Codex sessions still reference the old path:\n /path/to/file.jsonl\n```\n\nThese mean some sessions couldn't be fully migrated. You can manually inspect or delete the referenced files.\n\n## See Also\n\n- [repos](repos.md) - Clone repositories into structured layout\n" }, { "path": "docs/commands/new.md", "content": "# f new\n\nCreate a new project from a local starter template under `~/new`.\n\n## Overview\n\n`f new` copies a directory from `~/new/<template>` into a destination path.\n\nThis is the native Flow way to work with local starters you keep in `~/new`.\n\n## Usage\n\n```bash\nf new [template] [path]\n```\n\n- `template`: folder name inside `~/new` (for example `app`, `docs`, `web`)\n- `path`: destination path (optional)\n\nIf `template` is omitted, Flow opens an `fzf` picker from templates in `~/new`.\n\n## Path Resolution Rules\n\nFlow resolves the destination path like this:\n\n```bash\nf new app # -> ./app\nf new app zerg # -> ~/code/zerg\nf new app ./xn # -> ./xn\nf new app ~/xn # -> ~/xn\n```\n\nNotes:\n- Plain names (no `./`, `../`, `/`, `~`) are treated as `~/code/<name>`.\n- Use `~/...` or absolute paths for custom locations outside `~/code`.\n\n## Dry Run\n\nPreview copy behavior without writing files:\n\n```bash\nf new app ~/xn --dry-run\n```\n\n## Starter Workflow\n\n1. Create or update starter in `~/new/<template>`.\n2. Generate a new project with `f new <template> <target>`.\n3. Enter the new project and run its setup/dev tasks with Flow.\n\nExample:\n\n```bash\nf new app ~/xn\ncd ~/xn\nf tasks\n```\n\n## Common Errors\n\n- `Template not found`: `~/new/<template>` does not exist.\n- `Destination already exists`: remove/rename target path or choose a new destination.\n" }, { "path": "docs/commands/pr.md", "content": "# f pr\n\nCreate or open GitHub pull requests, edit PR text locally, and pull review feedback.\n\n## Quick Start\n\n```bash\n# Create/update PR from current changes (default base: main)\nf pr \"assistant improvements\"\n\n# Open current branch PR in browser\nf pr open\n\n# Edit PR title/body in local markdown and sync on save\nf pr open edit\n\n# Pull actionable review feedback for current PR\nf pr feedback\n\n# Pull feedback for specific PR and store as local todos\nf pr feedback 8 --todo\nf pr feedback https://github.com/owner/repo/pull/8 --todo\n\n# Full inline diff/review context is now the default\nf pr feedback 8\n\n# Use terse terminal output if needed\nf pr feedback 8 --compact\n```\n\n## Feedback Workflow\n\n`f pr feedback` fetches:\n\n- PR reviews (`/pulls/<n>/reviews`)\n- Inline review comments (`/pulls/<n>/comments`)\n- Top-level PR comments (`/issues/<n>/comments`)\n\nIt then:\n\n1. Prints an actionable list in terminal with inline review state and diff hunk context by default.\n2. Writes a markdown snapshot to `.ai/reviews/pr-feedback-<pr>.md`.\n3. Writes a machine-readable JSON snapshot to `.ai/reviews/pr-feedback-<pr>.json`.\n4. Writes a human review plan to `~/plan/review/<repo>-pr-<pr>-feedback.md`.\n5. Writes a PR-local execution artifact to `~/plan/review/<repo>-pr-<pr>-review-rules.md`.\n6. Writes a Kit system prompt to `~/plan/review/<repo>-pr-<pr>-kit-system.md`.\n7. Optionally (`--todo`) records feedback into `.ai/todos/todos.json` with dedupe via external refs.\n\nThe review plan includes ready-to-run `kit` commands for:\n\n- deterministic repo review via `kit review`\n- preventative lint/review rule synthesis from the fetched GitHub feedback set\n\nThe generated `*-review-rules.md` artifact contains the per-item resolution loop,\nprompt template, required response sections, and Kit-upgrade decision order so\nthe workflow can be reopened without extra instructions.\n\n## Notes\n\n- If no selector is passed, Flow resolves the PR from the current branch.\n- `f pr feedback --todo` is safe to re-run; existing feedback refs are not duplicated.\n- `f pr feedback` is full-context by default. Use `--compact` if you want the older terse terminal view.\n- `f pr feedback` now emits a Kit-ready handoff, so the same feedback set can drive a future review bot instead of staying trapped in GitHub comments.\n- `f pr open edit` remains the quickest path to tweak PR title/body from local editor.\n" }, { "path": "docs/commands/publish.md", "content": "# f publish\n\nPublish projects to GitHub.\n\n## Overview\n\nCreates a new GitHub repository and pushes the current project. Automatically infers the repo name from the folder name and handles both new repos and existing ones.\n\n## Quick Start\n\n```bash\n# Interactive mode - prompts for name and visibility\nf publish\n\n# Skip prompts, use folder name, default to private\nf publish -y\n\n# Create public repo\nf publish --public\n\n# Create with specific name\nf publish --name my-awesome-project\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--name <NAME>` | `-n` | Repository name (defaults to folder name) |\n| `--public` | | Create as public repository |\n| `--private` | | Create as private repository |\n| `--description <DESC>` | `-d` | Repository description |\n| `--yes` | `-y` | Skip prompts, use defaults (private, folder name) |\n\n## Prerequisites\n\n- [GitHub CLI](https://cli.github.com/) installed (`gh`)\n- Authenticated with `gh auth login`\n\n## Usage\n\n### Interactive Mode\n\nWithout flags, prompts for configuration:\n\n```bash\n$ f publish\n\nRepository name [my-project]:\nVisibility (public/private) [private]: public\n\nCreate repository:\n Name: username/my-project\n Visibility: public\n\nProceed? [Y/n]:\n```\n\n### Non-Interactive Mode\n\n```bash\n# Use all defaults (private, folder name as repo name)\nf publish -y\n\n# Public repo with defaults\nf publish -y --public\n\n# Specific name and description\nf publish -n cool-tool -d \"A cool CLI tool\" --public\n```\n\n### Existing Repositories\n\nIf the repository already exists on GitHub:\n\n1. Checks current visibility\n2. Updates visibility if different from requested\n3. Adds origin remote if missing\n4. Pushes current branch\n\n```bash\n$ f publish --public\nRepository username/my-repo already exists (private).\nUpdating visibility to public...\n✓ Updated to public\n\n✓ https://github.com/username/my-repo\n```\n\n## What Happens\n\n1. **Check gh CLI** - Verifies GitHub CLI is installed\n2. **Check authentication** - Ensures you're logged in to GitHub\n3. **Get username** - Fetches your GitHub username\n4. **Determine repo name** - Uses `--name`, folder name, or prompts\n5. **Determine visibility** - Uses `--public`/`--private` or prompts\n6. **Check if exists** - If repo exists, updates visibility if needed\n7. **Initialize git** - If not a git repo, runs `git init`\n8. **Create initial commit** - If no commits, stages all and commits\n9. **Create repository** - Uses `gh repo create` with `--source=. --push`\n10. **Output URL** - Prints the GitHub URL\n\n## Examples\n\n### Quick Publish New Project\n\n```bash\ncd my-new-project\nf publish -y --public\n# ✓ Published to https://github.com/username/my-new-project\n```\n\n### Publish with Description\n\n```bash\nf publish -n api-server -d \"REST API for my app\" --private\n```\n\n### Update Existing Repo Visibility\n\n```bash\n# Repo exists as private, make it public\nf publish --public\n# Repository username/my-repo already exists (private).\n# Updating visibility to public...\n# ✓ Updated to public\n```\n\n### In Scripts/CI\n\n```bash\n#!/bin/bash\ncd /path/to/project\nf publish -y --public -n release-candidate\n```\n\n## Troubleshooting\n\n### \"GitHub CLI (gh) is not installed\"\n\nInstall from https://cli.github.com:\n\n```bash\n# macOS\nbrew install gh\n\n# Linux\nsudo apt install gh # or equivalent\n```\n\n### \"GitHub authentication required\"\n\nRun `gh auth login` and follow the prompts.\n\n### \"Could not determine GitHub username\"\n\nEnsure you're authenticated: `gh auth status`\n\n### Repository exists but can't update visibility\n\nSome visibility changes may require specific permissions or GitHub plan features.\n\n## See Also\n\n- [deploy](deploy.md) - Deploy after publishing\n- [upstream](upstream.md) - Managing forks\n" }, { "path": "docs/commands/readme.md", "content": "# Flow Commands Reference\n\nComplete documentation for all `f` (flow) commands.\n\n## Quick Reference\n\n| Command | Description |\n|---------|-------------|\n| [`deploy`](deploy.md) | Deploy to Linux hosts, Cloudflare Workers, or Railway |\n| [`release`](release.md) | Publish a release to registry or GitHub |\n| [`publish`](publish.md) | Publish project to GitHub |\n| [`install`](install.md) | Install a CLI/tool via registry, parm, or flox |\n| [`clone`](clone.md) | Clone repositories with git-like destination behavior |\n| [`repos`](repos.md) | Clone repositories into ~/repos |\n| [`new`](new.md) | Create a project from a local template in ~/new |\n| [`commit`](commit.md) | AI-powered commit with code review |\n| [`pr`](pr.md) | Create/open PRs and ingest GitHub feedback |\n| [`upstream`](upstream.md) | Manage upstream fork workflow |\n| [`env`](env.md) | Sync project environment and manage env vars |\n| [`invariants`](invariants.md) | Validate project invariants from `flow.toml` |\n| [`fast`](fast.md) | Low-latency AI task invocation via fast client |\n| [`up`](up.md) | Bring a project up with lifecycle conventions |\n| [`down`](down.md) | Bring a project down with lifecycle conventions |\n| [`domains`](domains.md) | Shared local `*.localhost` route manager on port 80 |\n| [`tasks`](tasks.md) | List and run project tasks |\n| [`global`](global.md) | Run tasks from global flow config |\n| [`setup`](setup.md) | Print aliases or run setup task |\n| [`ai`](ai.md) | Manage AI coding sessions (Claude + Codex) |\n| [`daemon`](daemon.md) | Manage background daemons |\n| [`parallel`](parallel.md) | Run tasks in parallel |\n| [`docs`](docs.md) | Manage auto-generated documentation |\n| [`web`](web.md) | Open the Flow web UI for a project |\n| [`url`](url.md) | Inspect or crawl URLs into compact AI-friendly summaries |\n\n## Getting Started\n\n```bash\n# Show all commands\nf --help\n\n# Get help for a specific command\nf deploy --help\nf commit --help\n```\n\n## Command Categories\n\n### Deployment\n\n- **[deploy](deploy.md)** - Deploy to hosts and cloud platforms\n- **[release](release.md)** - Publish releases to registries\n- **[publish](publish.md)** - Publish project to GitHub\n\n### Version Control\n\n- **[commit](commit.md)** - AI-powered commits with review\n- **[pr](pr.md)** - PR creation/editing plus review feedback ingestion\n- **[clone](clone.md)** - Clone with git-like destination behavior\n- **[repos](repos.md)** - Clone repos into a structured directory\n- **[upstream](upstream.md)** - Fork management and sync\n- **[fixup](fixup.md)** - Fix common TOML syntax errors\n\n### Task Management\n\n- **[tasks](tasks.md)** - List project tasks\n- **[fast](fast.md)** - Run AI tasks through the low-latency fast client path\n- **[up](up.md)** - Start project lifecycle (`up`/`dev`) with optional domains setup\n- **[down](down.md)** - Stop project lifecycle with optional domains teardown\n- **[global](global.md)** - Run tasks from ~/.config/flow/flow.toml\n- **[setup](setup.md)** - Print aliases or run setup task\n- **[run](run.md)** - Run a specific task\n- **[parallel](parallel.md)** - Run tasks in parallel\n- **[rerun](rerun.md)** - Re-run last task\n- **[search](search.md)** - Fuzzy search global commands\n\n### Process Management\n\n- **[ps](ps.md)** - List running flow processes\n- **[kill](kill.md)** - Stop running processes\n- **[logs](logs.md)** - View task logs\n- **[daemon](daemon.md)** - Manage background daemons\n\n### AI & Development\n\n- **[ai](ai.md)** - Manage AI coding sessions\n- **[url](url.md)** - Inspect or crawl URLs into compact summaries for AI use\n- **[agent](agent.md)** - Invoke AI subagents\n- **[match](match.md)** - Match natural language to tasks\n- **[sessions](sessions.md)** - Search AI sessions across projects\n\n### Environment & Configuration\n\n- **[env](env.md)** - Manage environment variables\n- **[invariants](invariants.md)** - Validate invariant policies in `flow.toml`\n- **[domains](domains.md)** - Shared local domain proxy ownership and route management\n- **[init](init.md)** - Scaffold a new flow.toml\n- **[doctor](doctor.md)** - Verify tools and integrations\n\n### Project Management\n\n- **[new](new.md)** - Create a project from a local starter in `~/new`\n- **[projects](projects.md)** - List registered projects\n- **[active](active.md)** - Show or set active project\n- **[hub](hub.md)** - Ensure hub daemon is running\n\n### Documentation\n\n- **[docs](docs.md)** - Manage auto-generated documentation\n- **[commits](commits.md)** - Browse commits with AI metadata\n\n### Legacy Compatibility\n\n- **[recipe](recipe.md)** - Legacy recipe command (hidden; prefer `tasks` + `.ai/tasks/*.mbt`)\n\n### Other\n\n- **[skills](skills.md)** - Manage Codex skills\n- **[install](install.md)** - Install binaries via registry/parm/flox\n- **[db](db.md)** - Manage databases and providers\n- **[tools](tools.md)** - Manage AI tools\n- **[notify](notify.md)** - Send proposal notifications\n- **[server](server.md)** - Start HTTP server for logs\n\n## Global Options\n\n```bash\n-h, --help Print help\n-V, --version Print version\n```\n\n## Configuration\n\nFlow uses `flow.toml` for project configuration. See [flow.toml reference](../flow-toml.md) for full documentation.\n\n## See Also\n\n- [Getting Started Guide](../getting-started.md)\n- [flow.toml Reference](../flow-toml.md)\n" }, { "path": "docs/commands/recipe.md", "content": "# f recipe\n\nLegacy compatibility command.\n\nPreferred model:\n\n- Put shell tasks in `flow.toml` under `[[tasks]]`.\n- Put AI/native tasks in `.ai/tasks/*.mbt`.\n- Run via `f <task>` or `f ai:<selector>`.\n\n`f recipe` remains for older repos that still use `.ai/recipes`.\n\n## Usage\n\n```bash\nf recipe list # legacy listing\nf recipe run <selector> # legacy execution\n```\n\n## Options\n\n- `--scope <project|global|all>`: recipe source scope (default `all`)\n- `--global-dir <PATH>`: override global recipes directory\n- `--cwd <PATH>` (run only): working directory for execution\n- `--dry-run` (run only): print command without executing\n\n## Legacy Recipe Locations\n\n- Project recipes: `.ai/recipes/project` (fallback `.ai/recipes`).\n- Global recipes: `~/.config/flow/recipes`.\n\nSupported extensions: `.md`, `.markdown`, `.mbt`\n\nMoonBit recipe metadata is optional and can be declared in top comment lines:\n\n```mbt\n// title: My Fast Recipe\n// description: Run a moonbit action quickly\n// tags: [moonbit, fast]\n```\n\n## Migration\n\n```bash\n# Old\nf recipe run project:my-recipe\n\n# New\nf tasks init-ai\nf ai:my-task\n```\n" }, { "path": "docs/commands/release.md", "content": "# f release\n\nRelease a project based on `flow.toml` defaults or explicit subcommands.\n\n## Usage\n\n```bash\nf release\nf release registry\nf release gh\n```\n\n## Registry releases\n\n```bash\nf release registry\n```\n\n### flow.toml\n\n```toml\n[release]\ndefault = \"registry\"\nversioning = \"calver\"\n\n[release.registry]\nurl = \"https://myflow.sh\"\npackage = \"flow\"\nbins = [\"flow\", \"f\", \"lin\"]\ndefault_bin = \"flow\"\ntoken_env = \"FLOW_REGISTRY_TOKEN\"\nlatest = true\n```\n\n### Options\n\n- `--version <VERSION>`: publish a specific version.\n- `--registry <URL>`: override the registry base URL.\n- `--bin <NAME>`: override the binaries to upload (repeatable).\n- `--no-build`: skip building binaries.\n- `--latest` / `--no-latest`: control latest pointer updates.\n\n## GitHub releases\n\n```bash\nf release gh\n```\n" }, { "path": "docs/commands/repos.md", "content": "# f repos\n\nClone repositories into a structured local directory or create new ones.\n\nIf you want standard `git clone` destination behavior, use [`f clone`](clone.md) instead.\n\n## Overview\n\n`f repos clone` clones GitHub repositories into `~/repos/<owner>/<repo>` using SSH URLs. By default it does a shallow clone for speed, then fetches full history in the background. It always sets up an `upstream` remote and local tracking branch unless you pass `--no-upstream`.\n`f repos create` creates a GitHub repository from the current folder and pushes it.\n\nBy default, Flow treats `~/repos` as an immutable managed root. Use `FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1` if you need to point `--root` somewhere else.\n\n## Quick Start\n\n```bash\n# Clone a GitHub repo into ~/repos/<owner>/<repo>\nf repos clone https://github.com/owner/repo\n\n# Short form\nf repos clone owner/repo\n\n# Skip upstream auto-setup\nf repos clone owner/repo --no-upstream\n\n# Full clone (skip background history fetch)\nf repos clone owner/repo --full\n\n# Create a new repo from the current folder (prompts for name/visibility)\nf repos create\n```\n\n## Options\n\n### f repos clone\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `<URL>` | | Repository URL or `owner/repo` |\n| `--root <PATH>` | | Root directory for clones (default: `~/repos`, override requires `FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1`) |\n| `--full` | | Full clone (skip shallow clone + background history fetch) |\n| `--no-upstream` | | Skip upstream setup |\n| `--upstream-url <URL>` | `-u` | Upstream URL override (skips GitHub lookup) |\n\n### f repos create\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--name <NAME>` | `-n` | Repository name (defaults to current folder) |\n| `--public` | | Create as public repository |\n| `--private` | | Create as private repository |\n| `--description <TEXT>` | `-d` | Description for the repository |\n| `--yes` | `-y` | Skip confirmation prompts |\n\n## Upstream Automation\n\nFlow will:\n\n1. Query GitHub via `gh api repos/<owner>/<repo>`\n2. Detect the parent repository\n3. Run `f upstream setup --url <parent>` inside the cloned repo\n\nIf the repo is not a fork (or `gh` is unavailable), flow sets `upstream` to the `origin` URL.\n\n## Background History Fetch\n\nWhen cloning in fast mode (default), flow spawns a background fetch:\n\n- `git fetch --unshallow --tags origin`\n- `git fetch --tags upstream` (if upstream was configured)\n\n## Examples\n\n```bash\n# Clone into a custom root (requires override)\nFLOW_REPOS_ALLOW_ROOT_OVERRIDE=1 f repos clone https://github.com/owner/repo --root ~/work/repos\n\n# Override upstream manually\nf repos clone https://github.com/your-user/repo -u git@github.com:upstream-org/repo.git\n```\n" }, { "path": "docs/commands/reviews-todo.md", "content": "# f reviews-todo\n\nManage deferred deep-review todos for queued commits.\n\nThis command is a workflow wrapper over `f commit-queue` for the fast-commit + deep-Codex-review loop.\n\n## Quick Start\n\n```bash\n# List pending deep-review todos (queued commits)\nf reviews-todo list\n\n# Run Codex deep review for all queued commits\nf reviews-todo codex --all\n\n# Inspect one queued review todo\nf reviews-todo show <commit-sha>\n\n# Approve all queued commits after issues are addressed\nf reviews-todo approve-all\n```\n\n## Why use this\n\n- Keep `f commit` fast.\n- Batch expensive Codex reviews later.\n- Keep one place to track deep-review backlog.\n\n## Notes\n\n- `codex --all` maps to `f commit-queue review --all`.\n- Queue entries live under `.ai/internal/commit-queue/`.\n- Review findings are still recorded into `.ai/todos/todos.json` and commit review reports.\n- If `[options].myflow_mirror = true` is enabled, queued Codex reviews from the quick path are mirrored to myflow as `commit_queue_review` events.\n- For a full speed-first operating loop in `~/code/myflow`, see [`../fast-commit-deep-review-loop.md`](../fast-commit-deep-review-loop.md).\n" }, { "path": "docs/commands/seq-rpc.md", "content": "# `f seq-rpc`\n\nNative `seqd` RPC bridge for Flow.\n\nUse this when an agent/workflow needs OS-level actions and you want a typed, low-overhead path.\nThis command talks to `seqd` over Unix socket directly from Rust (no `seq rpc` subprocess).\n\n## Why this command exists\n\n- Keeps protocol handling in Rust.\n- Avoids shell output parsing drift.\n- Gives stable response envelope fields (`ok`, `op`, `dur_us`, ids).\n- Matches hard policy in `docs/seq-agent-rpc-contract.md`.\n\n## Usage\n\n```bash\nf seq-rpc [--socket PATH] [--timeout-ms 5000] [--pretty] <action> ...\n```\n\nActions:\n\n- `ping`\n- `app-state`\n- `perf`\n- `open-app <name>`\n- `open-app-toggle <name>`\n- `screenshot <path>`\n- `rpc <op> [--args-json '{...}']`\n\nCommon id fields (recommended on every call):\n\n- `--request-id`\n- `--run-id`\n- `--tool-call-id`\n\nExample:\n\n```bash\nf seq-rpc open-app \"Safari\" \\\n --request-id req-42 \\\n --run-id run-a12 \\\n --tool-call-id tool-7 \\\n --pretty\n```\n\n## Socket resolution\n\n1. `--socket <path>`\n2. `SEQ_SOCKET_PATH`\n3. `SEQD_SOCKET`\n4. `/tmp/seqd.sock`\n\n## Output\n\nPrints JSON response envelope from `seqd`.\n\nOn `ok=false`, command exits non-zero after printing the response JSON.\n" }, { "path": "docs/commands/services.md", "content": "# f services\n\nGuided setup flows for third-party services. These commands prompt for required\nenv vars, store them in cloud, and can optionally apply them to Cloudflare.\n\n## Stripe\n\n```bash\nf services stripe\n```\n\n### Options\n\n- `--path <PATH>`: target project root (defaults to current directory).\n- `--environment <ENV>`: env store to write (default: flow.toml or `production`).\n- `--mode <test|live>`: Stripe mode (default: `test`).\n- `--force`: prompt even if keys are already set.\n- `--apply` / `--no-apply`: apply envs to Cloudflare after setup.\n\n### What it prompts for\n\nThe command inspects `flow.toml` `[cloudflare].env_keys` and asks for Stripe\nkeys found there (fallback order):\n\n- `STRIPE_SECRET_KEY`\n- `STRIPE_WEBHOOK_SECRET`\n- `STRIPE_PRO_PRICE_ID`\n- `STRIPE_REFILL_PRICE_ID`\n- `VITE_STRIPE_PUBLISHABLE_KEY`\n\n### Helpful Stripe sources\n\n- Secret/Publishable keys: Stripe Dashboard -> Developers -> API keys\n- Webhook signing secret: Stripe Dashboard -> Developers -> Webhooks (or `stripe listen --print-secret`)\n- Price IDs: Stripe Dashboard -> Products -> Price (starts with `price_`)\n\n### Example\n\n```bash\ncd ~/org/gen/new\nf services stripe --mode test --apply\n```\n" }, { "path": "docs/commands/setup.md", "content": "# f setup\n\nBootstrap the project if needed, generate a `flow.toml` if missing, then run the `setup` task or print shell aliases.\n\n## Quick Start\n\n```bash\n# Bootstrap if missing, generate flow.toml if missing, then run setup task or print aliases\nf setup\n\n# Configure host deployment (Linux)\nf setup deploy\n\n# Configure release hosting for server projects\nf setup release\n\n# Use a specific config file\nf setup --config ./flow.toml\n```\n\n## Behavior\n\n- If the project is not bootstrapped, it runs the bootstrap flow (`.ai/`, `.gitignore`).\n- If `flow.toml` is missing, it prompts to generate `setup` + `dev` tasks (AI via `gen` if available, otherwise manual prompts).\n- If `flow.toml` already exists, Flow non-destructively appends missing Codex baseline sections (`[skills]`, `[skills.codex]`, commit skill gate, and Bun testing gate in Bun contexts).\n- After baseline upgrades, Flow triggers a Codex skills reload (respecting `[skills.codex].force_reload_after_sync`) so open sessions pick up changes immediately.\n- If `flow.toml` defines a `setup` task, `f setup` runs that task.\n- After the `setup` task exits, Flow re-reads `flow.toml`, re-syncs task skills to `.ai/skills`, and reloads Codex skills (when configured). This makes setup-generated task changes visible to Claude/Codex immediately.\n- Otherwise, it prints shell aliases from `[alias]` in `flow.toml`.\n- After successful completion, Flow writes a setup checkpoint to `.rise/setup.json` in the repo root.\n- `f setup deploy` adds a `[host]` section, creates a remote setup script, copies env templates, and optionally stores the deploy host.\n- `f setup release` detects server projects and offers Linux host deployment defaults.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`) |\n| `TARGET` | Optional setup target (e.g., `deploy`, `release`) |\n\n### Global Server Setup Defaults\n\nYou can provide a server template in your global config at `~/.config/flow/flow.toml`:\n\n```toml\n[setup.server]\ntemplate = \"~/infra/flow.toml\"\n```\n\nOr inline host defaults:\n\n```toml\n[setup.server.host]\nsetup = \"\"\"#!/usr/bin/env bash\nset -euo pipefail\n...\"\"\"\nenv_file = \".env.host\"\nport = 3000\n```\n" }, { "path": "docs/commands/skills.md", "content": "# f skills\n\nManage Codex/Claude skills for the current project.\n\nSkills live in `.ai/skills/` and are symlinked to `.codex/skills` and `.claude/skills` so active agent sessions can discover them.\n\n## Core Commands\n\n```bash\n# List local skills\nf skills\n\n# Create/edit/remove skills\nf skills new <name> -d \"description\"\nf skills edit <name>\nf skills remove <name>\n\n# Install curated skills\nf skills install <name>\n\n# Generate one skill per flow.toml task\nf skills sync\n\n# Force Codex app-server to rescan skills for this cwd\nf skills reload\n```\n\n## Codex Tight Feedback Loop\n\nUse this loop when coding with Codex/Claude:\n\n1. Make code changes.\n2. Run focused tests quickly (in Bun repos: `bun bd test ...`).\n3. Refresh skill context:\n\n```bash\nf skills sync\nf skills reload\n```\n\n4. Commit via quality gates:\n\n```bash\nf commit\n```\n\n`f skills reload` is useful for already-open Codex sessions; it refreshes the app-server skill cache without creating a new session.\n\n## `flow.toml` Settings\n\n```toml\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n```\n\n## Built-in Default Skills\n\nFlow auto-materializes a small baseline set of project-local skills in `.ai/skills/`:\n\n- `env`\n- `quality-bun-feature-delivery`\n- `pr-markdown-body-file`\n\nThese are symlinked into `.codex/skills` and `.claude/skills` and can be reloaded with:\n\n```bash\nf skills reload\n```\n\n### `skills.codex` fields\n\n- `generate_openai_yaml`: writes `.ai/skills/<task>/agents/openai.yaml` for task-synced skills.\n- `force_reload_after_sync`: after `f skills sync` or `f skills install`, force Codex app-server `skills/list` with `forceReload: true`.\n- `task_skill_allow_implicit_invocation`: default `policy.allow_implicit_invocation` value in generated `agents/openai.yaml`.\n\n## Recommended Enforcement\n\n```toml\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\nThis blocks commits that skip required Bun-oriented testing/skill policy.\n" }, { "path": "docs/commands/sync.md", "content": "# f sync\n\nSync git repo: pull from tracking remote, merge upstream changes, optionally push.\n\n## Overview\n\nSingle command to bring a repository up to date. Pulls from the tracking branch, syncs upstream if configured (fork workflow), and optionally pushes. Works with both plain git and jj (jujutsu) colocated repos.\n\n## Context Card\n\nUse this block when passing `f sync` behavior to another agent:\n\n- Default behavior: pull/sync only; push is off unless `--push`.\n- Defaults: `--stash=true`, `--fix=true`.\n- Modes: uses jj flow in healthy colocated workspaces, falls back to plain git when needed.\n- Push target: configured `[git].remote` first, then standard fallback behavior.\n- Clipboard output: synced commit list is copied only when remote commit ranges are detected (typically jj fetch path).\n- Conflict note: jj can finish with unresolved conflicts and prints `jj resolve` guidance.\n\n## Quick Start\n\n```bash\n# Pull latest from remote (no push by default)\nf sync\n\n# Pull and push\nf sync --push\n\n# Pull with rebase instead of merge\nf sync -r\n\n# Pull with rebase and push\nf sync -r --push\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--rebase` | `-r` | Use rebase instead of merge when pulling |\n| `--push` | | Push to configured git remote after sync (default: off) |\n| `--no-push` | | Skip pushing (legacy; already the default) |\n| `--stash` | `-s` | Auto-stash uncommitted changes (default: true) |\n| `--stash-commits` | | Stash local JJ commits to a bookmark before syncing (jj only) |\n| `--allow-queue` | | Allow sync even when commit queue is non-empty |\n| `--create-repo` | | Create origin repo on GitHub if it doesn't exist |\n| `--fix` | `-f` | Auto-fix conflicts using Claude (default: true) |\n| `--no-fix` | | Disable auto-fix |\n| `--max-fix-attempts <N>` | | Maximum auto-fix attempts (default: 3) |\n| `--allow-review-issues` | | Allow push even if P1/P2 review todos are open |\n| `--compact` | | Legacy noise-reduction flag (jj fetch output is already compact by default) |\n\n## What Happens\n\n### Step 1: Pre-flight checks\n\n1. Detects if jj is available and healthy; falls back to git if not\n2. Checks for unmerged files and resolves them (or prompts)\n3. Handles in-progress rebase/merge\n4. Stashes uncommitted changes if `--stash` is set\n\n### Step 2: Pull from tracking branch\n\nPulls from the tracking remote/branch (e.g. `origin/main`). If the branch has no tracking info but the push remote has a matching branch, auto-configures tracking.\n\n- With `--rebase`: runs `git pull --rebase`\n- Without: runs `git pull --no-rebase --no-edit` (merge without opening an editor)\n- Auto-resolves conflicts when `--fix` is enabled\n\n### Step 3: Sync upstream\n\nIf an `upstream` remote exists (fork workflow), fetches and merges upstream changes into the current branch.\n\nIf no `upstream` remote but on a feature branch, syncs from `origin/<default-branch>` (e.g. `origin/main`) into the current branch.\n\n### Step 4: Push (optional)\n\nOnly when `--push` is passed:\n\n- Detects fork push targets (redirects to private fork remote if configured)\n- Checks review-todo gate (blocks if P1/P2 issues are open unless `--allow-review-issues`)\n- Skips push if the push remote equals upstream (read-only clone)\n- Creates repo with `--create-repo` if origin doesn't exist\n\n### Step 5: Restore stash\n\nRestores auto-stashed changes if any were stashed in step 1.\n\n### Step 6: Synced commit list + clipboard\n\nWhen remote commit ranges are discovered (typically during jj fetch), Flow prints a deduplicated\nlist of newly synced commits (hash + subject) and copies that same list to your clipboard.\n\nIf no synced commit ranges were detected, this section is skipped.\n\nSet `FLOW_NO_CLIPBOARD=1` to disable clipboard copy.\n\n## JJ (Jujutsu) Support\n\nWhen a `.jj` directory is present and healthy, sync uses the jj flow instead of plain git. Falls back to git if:\n\n- Configured `git.remote` is not `origin`/`upstream`\n- Tracking remote is a custom remote\n- jj workspace is unhealthy or corrupt\n\nUse `--stash-commits` to bookmark local jj commits before syncing.\n\njj fetch output is compact by default; synced commit details are emitted once at the end for clipboard use.\n\n## Commit Queue Guard\n\nIf the commit queue has pending entries and sync would rebase (rewriting SHAs), sync refuses to proceed. Use `--allow-queue` to override, or process the queue first with `f commit-queue list`.\n\n## Configuration\n\n### Push remote\n\nSet in `flow.toml` under `[git]`:\n\n```toml\n[git]\nremote = \"origin\" # default push remote\n```\n\n### Fork push\n\nWhen a fork push target is configured, sync redirects push to the fork remote automatically.\n\n## Examples\n\n```bash\n# Basic sync (pull only)\nf sync\n\n# Sync and push\nf sync --push\n\n# Rebase workflow\nf sync -r --push\n\n# Sync a fork (has upstream remote)\nf sync --push\n\n# Create missing origin and push\nf sync --push --create-repo\n\n# Skip auto-fix for conflicts\nf sync --no-fix\n\n# Allow sync with pending commit queue\nf sync --allow-queue\n```\n\n## Troubleshooting\n\n### \"Unmerged files detected\"\n\nSync found files with unresolved merge conflicts. By default (`--fix`), it tries to auto-resolve. If that fails, resolve manually:\n\n```bash\ngit status # see conflicted files\n# edit and fix conflicts\ngit add <files>\nf sync # retry\n```\n\n### \"Commit queue is not empty\"\n\nRebase-based sync can rewrite commit SHAs, breaking queued commits. Either:\n\n```bash\nf commit-queue list # review the queue\nf sync --allow-queue # override the guard\n```\n\n### \"Remote unreachable\"\n\nThe push remote doesn't exist or auth/network failed. For missing origin:\n\n```bash\nf sync --push --create-repo\n```\n\n### jj corruption fallback\n\nIf jj sync fails due to workspace/store issues, sync automatically retries with plain git. Fix jj with:\n\n```bash\njj git import\n# or if still broken:\nrm -rf .jj && jj git init --colocate\n```\n\n### \"Sync complete (jj) but conflicts remain\"\n\nThis means sync/rebase completed but conflict revisions still exist in jj.\n\n```bash\njj resolve\n```\n\n## See Also\n\n- [upstream](upstream.md) - Manage upstream fork workflow\n- [commit](commit.md) - Commit changes\n- [jj](jj.md) - Jujutsu workflow helpers\n" }, { "path": "docs/commands/tasks.md", "content": "# f tasks\n\nList and discover project tasks from:\n\n- `flow.toml` (`[[tasks]]`)\n- `.ai/tasks/*.mbt` (AI MoonBit tasks)\n\nYou can run tasks directly with `f <task>`.\n\n## Usage\n\n```bash\nf tasks\nf tasks list\nf tasks dupes\nf tasks init-ai\nf tasks build-ai ai:flow/dev-check\nf tasks run-ai ai:flow/dev-check\nf tasks run-ai --daemon ai:flow/dev-check\nf tasks daemon start\nf tasks daemon status\nf tasks daemon stop\nf ai-taskd-launchd-install\nf ai-taskd-launchd-status\ncargo build --release -p ai-taskd-client --bin ai-taskd-client\n./target/release/ai-taskd-client ai:flow/dev-check\nf install-ai-fast-client\nf fast ai:flow/dev-check\nf bench-ai-runtime --iterations 80 --warmup 10\nf bench-ffi-boundary --iters 10000000\nf bench-ffi-boundary --iters 10000000 --native-opt\n```\n\n## AI Task Workflow\n\nInitialize a starter MoonBit task:\n\n```bash\nf tasks init-ai\n```\n\nThis creates:\n\n```text\n.ai/tasks/starter.mbt\n```\n\nRun it:\n\n```bash\nf starter\nf ai:starter\n```\n\nAdd more tasks as `.mbt` files under `.ai/tasks/` and run by name or selector:\n\n```bash\nf release-flow\nf ai:project/release-flow\n```\n\n## Notes\n\n- Default execution mode is cached native binary:\n 1) `moon build --target native --release` once per content hash\n 2) run cached artifact from `~/Library/Caches/flow/ai-tasks/...`\n- Use `f tasks run-ai --no-cache ...` (or `FLOW_AI_TASK_RUNTIME=moon-run`) to force direct `moon run`.\n- Set `FLOW_AI_TASK_MODE=release` for release builds (`--release`).\n- Set `FLOW_AI_TASK_MODE=js` to run with JS target.\n- `f tasks daemon` runs a lightweight local `ai-taskd` over Unix socket for warm repeated runs.\n- For lowest invocation overhead, use the tiny client binary against the daemon:\n- `cargo build --release -p ai-taskd-client --bin ai-taskd-client`\n - `./target/release/ai-taskd-client ai:<selector>`\n - or `f install-ai-fast-client` then use `fai ai:<selector>`\n - This bypasses full `f` startup for hot-loop calls.\n- `fai` supports:\n - `--protocol msgpack|json` (msgpack default)\n - `--timings` (server-side phase timings)\n - `--batch-stdin` (pooled burst mode in one client process)\n- For stable startup/jitter, prefer always-on daemon via launchd:\n - `f ai-taskd-launchd-install`\n - `f ai-taskd-launchd-status`\n - `f ai-taskd-launchd-logs`\n- Automatic preference for latency-critical AI selectors:\n - Opt in with `FLOW_AI_TASK_FAST_CLIENT=1` (typically together with `FLOW_AI_TASK_DAEMON=1`).\n - Then `f` will auto-prefer fast client dispatch for AI tasks tagged `fast`, `latency`, `hot`, or `hotkey`.\n - Override selector matching with `FLOW_AI_TASK_FAST_SELECTORS` (comma-separated patterns, supports `*` prefix/suffix).\n - Override client binary with `FLOW_AI_TASK_FAST_CLIENT_BIN=/path/to/fai`.\n- `f recipe` still exists for legacy compatibility, but task-centric workflow is preferred.\n" }, { "path": "docs/commands/up.md", "content": "# f up\n\nBring a project up using lifecycle conventions.\n\n## Quick Start\n\n```bash\n# Run lifecycle up (tries task \"up\", then \"dev\")\nf up\n\n# Pass args through to the selected task\nf up -- --port 3001\n```\n\n## Behavior\n\n- Loads nearest `flow.toml` (or `--config` path).\n- If `[lifecycle.domains]` is configured:\n - runs `f domains add <host> <target> --replace`\n - runs `f domains up` (with configured engine when set)\n- Runs lifecycle task:\n - `[lifecycle].up_task` when configured\n - otherwise fallback order: `up`, then `dev`\n\nIf no up task is found, command fails with guidance.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`, searches upward when default is missing) |\n| `ARGS...` | Extra args passed to the selected lifecycle task |\n\n## Recommended myflow config\n\n```toml\n[lifecycle]\nup_task = \"dev\"\n\n[lifecycle.domains]\nhost = \"myflow.localhost\"\ntarget = \"127.0.0.1:3000\"\nengine = \"native\"\nremove_on_down = false\nstop_proxy_on_down = false\n```\n" }, { "path": "docs/commands/upstream.md", "content": "# f upstream\n\nManage upstream fork workflow.\n\n## Overview\n\nSet up and sync forks with their upstream repositories. Creates a local `upstream` branch to cleanly track the original repo, making merges easier.\n\n## Quick Start\n\n```bash\n# Set up upstream tracking\nf upstream setup --upstream-url https://github.com/original/repo\n\n# Pull latest from upstream\nf upstream pull\n\n# Full sync: pull, merge, push\nf upstream sync\n```\n\n## Subcommands\n\n| Command | Description |\n|---------|-------------|\n| `status` | Show current upstream configuration |\n| `setup` | Set up upstream remote and local tracking branch |\n| `pull` | Pull changes from upstream into local 'upstream' branch |\n| `sync` | Full sync: pull upstream, merge to dev/main, push to origin |\n\n---\n\n## Setup\n\nConfigure upstream tracking for a forked repository:\n\n```bash\n# Basic setup\nf upstream setup --upstream-url https://github.com/original/repo\n\n# Specify branch (if not main)\nf upstream setup --upstream-url https://github.com/original/repo --upstream-branch master\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--upstream-url <URL>` | `-u` | URL of the upstream repository |\n| `--upstream-branch <BRANCH>` | `-b` | Branch name on upstream (default: auto-detected) |\n\n### What Happens\n\n1. Adds `upstream` remote pointing to original repo\n2. Fetches upstream branches\n3. Creates local `upstream` branch tracking the upstream's default branch\n4. Stores configuration in `.git/config`\n\n---\n\n## Pull\n\nPull latest changes from upstream into local `upstream` branch:\n\n```bash\n# Pull into upstream branch\nf upstream pull\n\n# Pull and also merge into specific branch\nf upstream pull --branch main\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--branch <BRANCH>` | `-b` | Also merge into this branch after pulling |\n\n---\n\n## Sync\n\nFull sync workflow - pulls upstream, merges to your branch, and pushes:\n\n```bash\n# Full sync (pull, merge, push)\nf upstream sync\n\n# Sync without pushing (for review first)\nf upstream sync --no-push\n```\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `--no-push` | Skip pushing to origin |\n\n### What Happens\n\n1. Stashes any uncommitted changes\n2. Fetches latest from upstream\n3. Updates local `upstream` branch\n4. Merges upstream into your current branch (e.g., `main`)\n5. Pushes to origin (unless `--no-push`)\n6. Restores stashed changes\n\n### Branch Detection\n\nFlow auto-detects the upstream default branch:\n- Checks `refs/remotes/upstream/HEAD`\n- Falls back to checking if `upstream/main` or `upstream/master` exists\n- Uses `main` as final fallback\n\n---\n\n## Status\n\nShow current upstream configuration:\n\n```bash\nf upstream status\n```\n\nOutput:\n```\nUpstream Configuration\n Remote: https://github.com/original/repo\n Branch: main\n Local tracking: upstream -> upstream/main\n Last sync: 2 hours ago\n```\n\n---\n\n## Workflow Example\n\n### Initial Fork Setup\n\n```bash\n# 1. Clone your fork\ngit clone https://github.com/youruser/project\ncd project\n\n# 2. Set up upstream tracking\nf upstream setup --upstream-url https://github.com/original/project\n\n# 3. Verify\nf upstream status\n```\n\n### Regular Sync\n\n```bash\n# When you want to sync with upstream:\nf upstream sync\n\n# Or if you want to review before pushing:\nf upstream sync --no-push\ngit log --oneline main..upstream # See what's new\ngit push # Push when ready\n```\n\n### Handling Conflicts\n\nIf sync encounters merge conflicts:\n\n```bash\n$ f upstream sync\nMerging upstream into main...\nCONFLICT (content): Merge conflict in src/lib.rs\n\n# Fix conflicts manually\nvim src/lib.rs\ngit add src/lib.rs\ngit commit\n\n# Then push\ngit push\n```\n\n---\n\n## Configuration\n\nUpstream configuration is stored in `.git/config`:\n\n```ini\n[remote \"upstream\"]\n url = https://github.com/original/repo\n fetch = +refs/heads/*:refs/remotes/upstream/*\n\n[branch \"upstream\"]\n remote = upstream\n merge = refs/heads/main\n```\n\nYou can also manually configure:\n\n```bash\ngit remote add upstream https://github.com/original/repo\ngit fetch upstream\ngit branch upstream upstream/main\n```\n\n---\n\n## Troubleshooting\n\n### \"upstream remote not found\"\n\nRun `f upstream setup` first with the upstream URL.\n\n### \"git stash pop failed\"\n\nThis can happen if there were no changes to stash. Flow handles this automatically by tracking stash state.\n\n### Upstream uses master instead of main\n\nFlow auto-detects the default branch. If detection fails, specify explicitly:\n\n```bash\nf upstream setup --upstream-url https://github.com/original/repo --upstream-branch master\n```\n\n### Merge conflicts\n\nResolve conflicts manually:\n1. Fix conflicting files\n2. `git add <files>`\n3. `git commit`\n4. `git push`\n\n## See Also\n\n- [commit](commit.md) - Commit changes after sync\n- [publish](publish.md) - Publish to GitHub\n" }, { "path": "docs/commands/url.md", "content": "# `f url`\n\nInspect or crawl URLs into compact AI-friendly summaries.\n\n## Quick Start\n\n```bash\n# Thin single-page summary\nf url inspect https://developers.cloudflare.com/changelog/post/2026-03-10-br-crawl-endpoint/\n\n# Force Cloudflare Browser Rendering markdown\nf url inspect --provider cloudflare https://developers.cloudflare.com/changelog/post/2026-03-10-br-crawl-endpoint/\n\n# Machine-readable output\nf url inspect --json https://linear.app/fl2024008/project/llm-proxy-v1-6cd0a041bd76/overview\n\n# Explicit site crawl (Cloudflare Browser Rendering)\nf url crawl https://developers.cloudflare.com/browser-rendering/rest-api/crawl-endpoint/ --limit 3 --records 2\n```\n\n## `inspect`\n\n`f url inspect <url>` uses this provider order:\n\n1. Cloudflare Browser Rendering markdown\n2. configured scraper backend from `[skills.seq]`\n3. direct fetch fallback\n\nDefault output is intentionally compact:\n\n- title\n- URL\n- content type\n- short description\n- short excerpt\n\nUse `--full` to include the full markdown/content body.\n\n## `crawl`\n\n`f url crawl <url>` is the explicit multi-page path.\n\nIt currently uses Cloudflare Browser Rendering crawl and polls until the job completes or the wait timeout is reached.\n\nUseful flags:\n\n```bash\nf url crawl <url> --limit 10 --records 5\nf url crawl <url> --depth 2 --render\nf url crawl <url> --include-pattern \"https://developers.cloudflare.com/browser-rendering/*\"\nf url crawl <url> --exclude-pattern \"*/changelog/*\"\nf url crawl <url> --json\n```\n\nDefaults are tuned to stay small:\n\n- `--limit 10`\n- `--depth 2`\n- `--records 5`\n- `--render false`\n\n## Auth\n\nCloudflare auth is read from:\n\n1. shell env\n2. Flow personal env store fallback\n\nRequired keys:\n\n- `CLOUDFLARE_ACCOUNT_ID`\n- `CLOUDFLARE_API_TOKEN`\n\nNo daemon is required.\n\n## Config\n\nIf you have a local scraper backend, `f url inspect` reuses `[skills.seq]` settings from repo `flow.toml` or global `~/.config/flow/flow.toml`:\n\n```toml\n[skills.seq]\nscraper_base_url = \"http://127.0.0.1:7444\"\nscraper_api_key = \"...\"\ncache_ttl_hours = 2\nallow_direct_fallback = true\n```\n" }, { "path": "docs/commands/web.md", "content": "# web\n\nOpen the Flow web UI for the current project.\n\n## Usage\n\n```bash\nf web\n```\n\n## What it does\n\n- Serves the `.ai/web` UI for the current project.\n- Exposes `/api/projects` for project metadata and top-level `.ai` entries.\n- Exposes `/api/ai` for the full `.ai` tree (paths + kinds).\n- Exposes `/api/sessions` for Claude/Codex session summaries and transcripts.\n- Exposes `/api/openapi` when an OpenAPI spec is detected.\n\n## Options\n\n```bash\n--host <host> Host to bind (default: 127.0.0.1)\n--port <port> Port to serve the UI on (default: 9310)\n```\n\n## Notes\n\n- `f web` serves `.ai/web/dist` when it exists (Vite default output).\n- The Vite app source lives in `.ai/web`.\n- `.ai/web` is gitignored by default so AI can freely rewrite it.\n- If no build exists, `f web` shows a minimal placeholder.\n- Example build: `vite build` from `.ai/web`.\n- `f web` now runs `bun install` (once) and `bun run build` automatically when a Vite app is present.\n" }, { "path": "docs/commits/.gitkeep", "content": "\n" }, { "path": "docs/commits/readme.md", "content": "# Commit Explanations (Generated)\n\n`f explain-commits` writes generated artifacts into this folder by default:\n\n- `*.md`: human-readable commit explanations\n- `*.json`: machine-readable sidecars\n- `.index.json`: digest/index cache\n\nPolicy:\n\n- This directory is treated as local generated output by default.\n- Generated files are gitignored to keep normal commits clean.\n- If you want tracked artifacts, set `[explain-commits].output_dir` in `flow.toml` to a different directory and commit that directory intentionally.\n" }, { "path": "docs/dependency-vendoring.md", "content": "# Dependency Vendoring (Cargo-First)\n\nThis project uses a Cargo-first vendoring model:\n\n- Cargo remains the resolver, lockfile authority, and build system.\n- Vendored source is owned in `nikivdev/flow-vendor`.\n- `flow` pins vendored state by commit in `vendor.lock.toml`.\n- `flow` uses `[patch.crates-io]` path overrides into `lib/vendor/*`.\n\nThis gives direct dependency control without giving up Cargo behavior.\n\n## Why This Model\n\n### Problem\n\n- crates.io + transitive dependency growth hurts compile times and iteration speed.\n- upstream crates can pull convenience dependencies, macros, and features we do not need.\n- editing third-party code in-place inside the main repo pollutes history and makes updates hard.\n\n### Requirements\n\n- keep Cargo benefits (resolver correctness, lock semantics, ecosystem compatibility),\n- gain direct control over dependency source and shape,\n- keep upstream sync fast and automatable,\n- keep repository history readable.\n\n### Result\n\n- dependency source churn lives in `flow-vendor`,\n- application-level pin and wiring lives in `flow`,\n- updates are reproducible and lock-pinned,\n- trim/refactor opportunities are local and fast.\n\n## Nix-Inspired Discipline\n\nThis model borrows the parts of Nix that matter most for dependency control:\n\n- pinned inputs (`vendor.lock.toml`, `Cargo.lock`),\n- deterministic materialization (`vendor-repo.sh hydrate`),\n- provenance/checksum verification (`vendor-manifest`, strict verify),\n- transactional updates with rollback safety (`vendor-control.sh inhouse`),\n- closure-size reduction by trimming unused dependency surface.\n\nReference:\n\n- `docs/vendor-nix-inspiration.md`\n\n## Benefits\n\n- Faster local iteration by removing unneeded dependency surface area.\n- Ability to aggressively trim crates to exactly what `flow` uses.\n- Deterministic hydration in CI and local environments from a pinned vendor commit.\n- Clean `flow` history: metadata/pins in `flow`, source churn in `flow-vendor`.\n- Upstream updates remain scriptable and reviewable.\n\n## Core Files and Their Roles\n\n- `vendor.lock.toml`\n - Source of truth for vendor remote, branch, checkout, pinned commit, and crate map.\n- `Cargo.toml`\n - `[patch.crates-io]` points selected crates to `lib/vendor/<crate>`.\n- `Cargo.lock`\n - Must resolve vendored crates by path (no registry source for vendored entries).\n- `lib/vendor/<crate>`\n - Materialized source tree used by Cargo path patches.\n- `lib/vendor-manifest/<crate>.toml`\n - Per-crate metadata for version/provenance/sync and verification.\n- `scripts/vendor/*`\n - Toolkit for inhouse, hydrate, status, sync, and vendor-repo operations.\n\n## Repositories\n\n### `flow` repo\n\n- owns pins, manifests, trim logic hooks, and Cargo wiring.\n- should not include full vendored source history churn.\n\n### `flow-vendor` repo\n\n- canonical storage for vendored crate source (`crates/<crate>`),\n- vendored crate manifests (`manifests/<crate>.toml`),\n- profile metadata used during hydration.\n\n## Operating Principle: Cargo First\n\nDo not replace Cargo. Use Cargo as the system of record:\n\n- resolve versions through `Cargo.lock`,\n- use `cargo update -p <crate> --precise <version>` for deterministic lock rewrites,\n- build and validate with normal Cargo commands (`cargo check`, `cargo test --no-run`),\n- use vendoring only as controlled source substitution via patches.\n\n## Standard Workflow (One Crate)\n\nRecommended entrypoint:\n\n```bash\n~/code/rise/scripts/vendor-control.sh inhouse --project ~/code/flow <crate> [version]\n```\n\nWhat this does:\n\n1. Ensures lock entry and Cargo patch wiring.\n2. Materializes crate from Cargo cache into `lib/vendor/<crate>`.\n3. Stores crate history in `lib/vendor-history/<crate>.git`.\n4. Writes `lib/vendor-manifest/<crate>.toml` + `UPSTREAM.toml`.\n5. Re-syncs `Cargo.lock` to exact vendored version.\n6. Applies trim hooks (`scripts/vendor/apply-trims.sh`).\n7. Imports local materialized source into `.vendor/flow-vendor`.\n8. Pins `vendor.lock.toml` to new vendor commit.\n\n## Verification and Safety Gates\n\nRun after each vendoring step:\n\n```bash\nf update-deps --important\nf vendor-trims\n~/code/rise/scripts/vendor-control.sh verify --project ~/code/flow\npython3 ./scripts/vendor/rough_edges_audit.py --project . --strict-warnings\ncargo check -q\nscripts/vendor/sync-all.sh --important --dry-run\n```\n\nFor full dependency refresh (latest allowed by policy), run:\n\n```bash\nf update-deps\n```\n\nUseful flags:\n\n```bash\nf update-deps --dry-run\nf update-deps --no-major\nf update-deps --push-vendor\n```\n\n`verify` enforces:\n\n- crate exists in `vendor.lock.toml`,\n- crate exists in `Cargo.lock`,\n- no registry source for vendored crate in `Cargo.lock`,\n- one resolved version per vendored crate,\n- patch path matches lock materialized path,\n- manifest version matches lock version.\n\n`vendor-rough-audit --strict-warnings` additionally enforces warning-hygiene\nregressions for known vendored crate hot spots (`crossterm`, `portable-pty`,\n`x25519-dalek`, `ratatui`) so release builds stay quiet.\n\n## Provenance and Hardening\n\n`inhouse` now records provenance fields in crate manifests:\n\n- `registry_index`\n- `cargo_registry_checksum`\n- `crate_archive_sha256`\n- `checksum_match`\n- `upstream_repository`\n- `upstream_homepage`\n- `history_head`\n\nUse report mode:\n\n```bash\n~/code/rise/scripts/vendor-control.sh provenance --project ~/code/flow\n```\n\nUse stricter mode when migrating fully:\n\n```bash\n~/code/rise/scripts/vendor-control.sh verify --project ~/code/flow --strict-provenance\n```\n\n## Transactional Failure Behavior\n\n`vendor-control.sh inhouse` includes rollback protection by default:\n\n- snapshot relevant files before mutation,\n- on failure, restore pre-run `Cargo.toml`, `Cargo.lock`, `vendor.lock.toml`,\n- remove newly created manifest/source/history artifacts for failed crate,\n- restore prior vendor lock pin.\n\nEscape hatch (not recommended except debugging):\n\n```bash\n~/code/rise/scripts/vendor-control.sh inhouse --project ~/code/flow <crate> --no-rollback\n```\n\n## Upstream Sync Loop\n\nTrack updates:\n\n```bash\nscripts/vendor/check-upstream.sh --important\nscripts/vendor/sync-all.sh --important --dry-run\n```\n\nApply updates intentionally:\n\n```bash\nscripts/vendor/sync-all.sh --important\nscripts/vendor/vendor-repo.sh import-local\ngit -C .vendor/flow-vendor push origin main\n```\n\nPolicy:\n\n- patch updates can be frequent,\n- minor/major updates happen in explicit review windows (`--allow-minor`, `--allow-major`).\n\n## Code Intelligence Loop (opensrc-style, crates-focused)\n\nTo make vendored code practical at scale, we index first-party + vendored sources into\nTypesense and query them fast during refactors and trim work.\n\nThis follows the same high-level pattern as `opensrc`:\n\n- keep a local source inventory (`.vendor/typesense/sources.json`),\n- keep local source materialized (already done by vendor hydrate/inhouse),\n- index/search against local code state, not remote assumptions.\n\nFlow entrypoints:\n\n```bash\nf vendor-typesense-setup # one-time if Typesense is not installed locally\nf vendor-typesense-up\nf vendor-code-index\nf vendor-code-search \"Router\"\nf vendor-code-search \"serde\" --scope vendor --crate axum\nf vendor-code-search-sources \"ratatui\"\n```\n\nScript used by tasks:\n\n```bash\npython3 ./scripts/vendor/typesense_code_index.py --help\n```\n\nDesign goals:\n\n- search by vendored crate boundary (`--crate <name>`),\n- search by ownership boundary (`--scope vendor|firstparty`),\n- keep source provenance in inventory (`version`, `checksum`, `history_head`),\n- make trim/upstream update work faster by removing \"where is this code?\" overhead.\n\nReference:\n\n- `docs/vendor-code-intelligence.md` for architecture, commands, and operating loop.\n\n## CI Contract\n\nCI must hydrate vendored source from `vendor.lock.toml` before Cargo build:\n\n```bash\nscripts/vendor/vendor-repo.sh hydrate\n```\n\nAny CI build skipping hydrate can fail with missing `lib/vendor/*` path deps.\n\n## Optimization Strategy (Compile-Time Focus)\n\nFor each vendored crate:\n\n1. inspect real usage in `flow` (APIs/types called),\n2. remove optional features not used,\n3. delete convenience-only dependencies,\n4. remove proc-macro convenience layers where reasonable,\n5. reduce duplicate major versions where possible,\n6. keep trim hooks deterministic and replayable.\n\nUse:\n\n```bash\nscripts/vendor/offenders.sh\ncargo tree -d\n```\n\nto rank impact and watch duplicate-version pressure.\n\nOperational tooling for this loop:\n\n- `f vendor-rough-audit`\n- `f vendor-offenders`\n- `f vendor-bench-iter -- --mode incremental --samples 3`\n- `f vendor-optimize-loop`\n\nReference:\n\n- `docs/vendor-optimization-loop.md`\n\n## Commit Policy\n\n- In `flow`: commit only lock/manifest/patch/docs/script changes.\n- In `flow-vendor`: commit source churn.\n- Push `flow-vendor` first, then push `flow` pin updates.\n- Prefer one crate per commit for auditability.\n\n## Recovery Playbook\n\nInspect state:\n\n```bash\nscripts/vendor/vendor-repo.sh status\n```\n\nRe-hydrate local materialization from pinned commit:\n\n```bash\nscripts/vendor/vendor-repo.sh hydrate\n```\n\nRe-pin to known commit:\n\n```bash\nscripts/vendor/vendor-repo.sh pin <commit>\n```\n\n## FAQ\n\n### Are we replacing Cargo?\n\nNo. Cargo remains central. Vendoring is an ownership layer on top.\n\n### Why separate repo for vendored source?\n\nTo keep main repo history focused on product changes while retaining full dependency source control.\n\n### Can we still pull upstream changes quickly?\n\nYes. `check-upstream` + `sync-*` + locked import flow is designed for repeatable upstream ingestion.\n" }, { "path": "docs/dev-server-management.md", "content": "# Dev Server Management\n\nFlow's supervisor manages dev server lifecycle declaratively. Define servers in `config.ts`, Flow handles starting, stopping, port cleanup, and restart on failure.\n\n## Config Chain\n\n```\n~/config/i/lin/config.ts (source of truth: devServers array)\n ↓ lin daemon watches, runs `bun ./config.ts`\n~/.config/flow/flow.toml (generated [[server]] entries)\n ↓ supervisor polls mtime every 2s\nsupervisor (starts/stops/restarts processes)\n ↓\nrunning processes (bash → rise dev, wrangler, etc.)\n```\n\n## Lifecycle\n\n### On Mac Reboot\n\n1. macOS launchd starts the Flow supervisor (if installed via `f supervisor install --boot`)\n2. Supervisor reads `~/.config/flow/flow.toml`\n3. Starts daemons with `autostart = true` or `boot = true`\n4. Servers with `autostart = false` wait for `f daemon start <name>`\n\n### Starting Dev Servers After Reboot\n\n```bash\n# See what's defined vs running\nf daemon status\n\n# Start a specific server\nf daemon start myflow-web\n\n# Start multiple\nf daemon start myflow-web && f daemon start myflow-api\n```\n\n### Day-to-Day\n\n```bash\nf daemon status # what's running\nf daemon start myflow-web # start\nf daemon stop myflow-web # stop\nf daemon restart myflow-web # restart\nf daemon logs myflow-web # view logs\n```\n\n## How Servers Are Defined\n\n### Source: `~/config/i/lin/config.ts`\n\n```typescript\nconst devServers = [\n {\n name: \"myflow-web\",\n command: \"bash\",\n args: [\"-c\", \"bash ./scripts/patch-rise-root.sh && cd web && RISE_WEB_PORT=3000 VITE_API_URL=http://localhost:8780 rise dev --root .. --platform web\"],\n working_dir: \"~/code/myflow\",\n port: 3000,\n },\n {\n name: \"myflow-api\",\n command: \"bash\",\n args: [\"-c\", \"cd api/ts && npx wrangler dev --port 8780\"],\n working_dir: \"~/code/myflow\",\n port: 8780,\n },\n] as const\n```\n\n### Generated: `~/.config/flow/flow.toml`\n\nThe lin config watcher runs `bun ./config.ts` which generates:\n\n```toml\n[[server]]\nname = \"myflow-web\"\ncommand = \"bash\"\nargs = [\"-c\", \"bash ./scripts/patch-rise-root.sh && cd web && RISE_WEB_PORT=3000 VITE_API_URL=http://localhost:8780 rise dev --root .. --platform web\"]\nworking_dir = \"~/code/myflow\"\nport = 3000\nautostart = false\n```\n\n### Conversion: `[[server]]` → Daemon\n\n`ServerConfig::to_daemon_config()` in `src/config.rs` converts each server to a daemon with:\n- `restart = \"on-failure\"` (auto-restart on crash)\n- `retry = 3` (max 3 restart attempts)\n- `boot = false`, `autostop = false`\n\n## `[[server]]` vs `[[daemon]]`\n\n- **`[[server]]`** — dev-time HTTP servers. Auto-get `restart = on-failure` + port eviction.\n- **`[[daemon]]`** — any long-running process. Full control over restart/boot/health.\n\nBoth are managed the same way by the supervisor.\n\n## Port Eviction\n\nBefore starting any server, Flow kills any existing process on the target port:\n\n```\nlsof -ti :3000 | xargs kill\n```\n\nThis prevents \"port already in use\" errors after crashes or unclean shutdowns.\n\n## autostart vs boot vs on-demand\n\n| Field | When it starts | Use case |\n|-------|---------------|----------|\n| `autostart = true` | When supervisor starts | Always-on services (AI proxy, watchers) |\n| `boot = true` | On system boot only | System services |\n| Both false | `f daemon start <name>` | Dev servers (start when needed) |\n\nDev servers default to `autostart = false` because you don't always need every project running.\n\n## Supervisor\n\nThe supervisor is the long-running process that manages all daemons.\n\n```bash\nf supervisor status # is it running?\nf supervisor start # start it\nf supervisor install --boot # install launchd agent (survives reboot)\n```\n\nIt polls `~/.config/flow/flow.toml` every 2 seconds. When the file changes:\n1. Loads new config\n2. Starts newly added daemons (if autostart)\n3. Stops removed daemons\n4. Restarts daemons whose config changed\n\n## PID and Log Locations\n\n| What | Where |\n|------|-------|\n| PID files | `~/.config/flow/{name}.pid` |\n| Daemon logs | `~/.config/flow-state/daemons/{name}/stdout.log` |\n| Supervisor socket | `~/.config/flow-state/supervisor.sock` |\n\n## Troubleshooting\n\n**Server shows \"started\" but port not responding:**\n- Dev servers need 10-20s to compile and start (patch → rise compile → vite)\n- Check with: `curl -sf http://localhost:3000 | head -5`\n- Check process tree: `pgrep -P $(cat ~/.config/flow/myflow-web.pid)`\n\n**\"health check failed\" warning on start:**\n- Normal for dev servers — they take time to boot. Flow will check again.\n- If it never comes up, check the command runs manually:\n ```bash\n cd ~/code/myflow && bash ./scripts/patch-rise-root.sh && cd web && RISE_WEB_PORT=3000 rise dev --root .. --platform web\n ```\n\n**Server not in `f daemon status`:**\n- Check flow.toml has the entry: `grep myflow ~/.config/flow/flow.toml`\n- If missing, the lin daemon may be stopped: check `f daemon status` for `lin`\n- Regenerate manually: `cd ~/config/i/lin && bun ./config.ts`\n\n**Port not freed after removing a server:**\n- Check if `flow.toml` was regenerated\n- Check supervisor is running: `f supervisor status`\n- Manual cleanup: `lsof -ti :PORT | xargs kill`\n\n**Process restarting in a loop:**\n- Servers use `on-failure` restart with max 3 retries and exponential backoff (2s, 4s, 8s, ... 60s)\n- After 3 failures, supervisor gives up. Fix the issue and `f daemon restart <name>`\n" }, { "path": "docs/env-security-roadmap.md", "content": "# Env Security Roadmap\n\nThis document defines the hardening path for Flow env storage so it is usable in\nlarge orgs with strict secret-handling rules.\n\n## Current State\n\n- `f env set KEY=VALUE` writes to personal scope.\n- `f env project set KEY=VALUE -e <env>` writes to project scope.\n- Personal cloud env values are still stored in Flow's server-managed secret\n store and fetched over authenticated API calls.\n- Project cloud env values are now sealed client-side before upload and\n decrypted locally after fetch.\n- Project cloud reads auto-register the local device sealer when needed.\n- Legacy plaintext project cloud values are still read as a compatibility\n fallback during migration.\n- Local env values live under `~/.config/flow/env-local/`.\n- On macOS, personal local env values are now stored in Keychain by default and\n Flow keeps only local references on disk.\n- Project-local envs still use private `.env` files on disk because apps and\n deploy flows often need direct file materialization.\n- Host deploys that still fetch project envs via service tokens keep an\n explicit plaintext cloud mirror until the host fetch path is upgraded.\n\n## Security Goals\n\n- No tracked repo file should ever be required for secret storage.\n- Secret values should be encrypted or OS-protected at rest by default.\n- Metadata should be separable from secret material.\n- Cloud sharing must not require trusting the server with plaintext values.\n- Reads should be auditable and scoped.\n- Rotation and revocation must be first-class.\n\n## Secret Model\n\nUse three classes:\n\n1. Secret value\n Examples: API keys, signing material, service tokens.\n2. Sensitive metadata\n Examples: project IDs, team IDs, URLs that should not be public broadly.\n3. Non-secret metadata\n Examples: team key `IDE`, environment name, feature flags safe to commit.\n\nRule:\n- Secret values belong in Flow env storage.\n- Non-secret metadata should prefer checked-in config.\n- Sensitive metadata can live in Flow env storage if the repo should not carry it.\n\n## Immediate Policy\n\nFor a Linear integration:\n\n- `DESIGNER_LINEAR_API_KEY` is a secret and should stay in Flow personal env\n storage.\n- `DESIGNER_LINEAR_TEAM_KEY=IDE` is not a secret and should move into forge\n config when the integration is wired.\n\n## Phase 0\n\n- Fix CLI/docs mismatches so users do not get fake command examples.\n- Make personal vs project scope explicit in docs and examples.\n- Enforce private local file permissions in code.\n\n## Phase 1\n\n- Use OS secure storage for local personal secrets by default.\n- Keep only local references or metadata on disk.\n- Add read gating for local secure-secret reads on macOS.\n- Add migration for legacy plaintext personal local env files.\n\n## Phase 2\n\n- Add explicit secret classification:\n - `secret`\n - `sensitive`\n - `public`\n- Store descriptions/metadata separately from values.\n- Add a local inspection command that shows where each key is stored without\n printing the value.\n\n## Phase 3\n\nCompleted for project envs:\n- client-side envelope encryption for cloud-shared project values\n- reuse of Flow's existing sealing primitives used by SSH key storage\n- device/user recipient fanout based on registered project sealers\n- ciphertext-only project env storage on the server\n\nStill open:\n- group recipients\n- richer classification/policy enforcement at write time\n- better device recovery/re-share workflows\n- eliminating the temporary plaintext compatibility mirror for service-token\n host fetches\n\n## Phase 4\n\n- Add org-grade controls:\n - scoped service tokens\n - access logs\n - rotation workflows\n - revocation\n - break-glass recovery\n - policy checks for forbidden repo-local secret paths\n\n## Constraints\n\n- Project envs that must become `.env` files for local runtime or deploys still\n need a materialization path.\n- Cloud sharing security should not regress existing deploy workflows.\n- Compatibility escape hatches are acceptable, but secure defaults must win.\n" }, { "path": "docs/everruns-maple-runbook.md", "content": "# Everruns + Maple Runbook\n\nThis is the fastest path to use the new Everruns telemetry export now.\n\nIt sends `f ai everruns` traces to:\n\n- local Maple (dev visualization)\n- hosted Maple (shared/history visualization)\n\n## What gets exported\n\nWhen enabled, Flow exports:\n\n- `everruns.tool_call` spans for each `seq_*` tool execution\n- runtime spans such as:\n - `everruns.tool_call_requested`\n - `everruns.output_message_completed`\n - `everruns.turn_failed`\n\n## Prerequisites\n\n1. `seqd` is running and reachable at your socket (`/tmp/seqd.sock` by default).\n2. Everruns API is reachable (`http://127.0.0.1:9300/api` by default).\n3. You have Maple ingest keys for local and/or hosted endpoint.\n\n## 1) Configure env (now)\n\nFrom `~/code/flow`, set the endpoints + keys:\n\n```bash\nf env set SEQ_EVERRUNS_MAPLE_LOCAL_ENDPOINT=http://ingest.maple.localhost/v1/traces\nf env set SEQ_EVERRUNS_MAPLE_LOCAL_INGEST_KEY=maple_pk_local_xxx\nf env set SEQ_EVERRUNS_MAPLE_HOSTED_ENDPOINT=https://ingest.1focus.ai/v1/traces\nf env set SEQ_EVERRUNS_MAPLE_HOSTED_INGEST_KEY=maple_pk_hosted_xxx\n```\n\nOptional tuning:\n\n```bash\nf env set SEQ_EVERRUNS_MAPLE_QUEUE_CAPACITY=4096\nf env set SEQ_EVERRUNS_MAPLE_MAX_BATCH_SIZE=128\nf env set SEQ_EVERRUNS_MAPLE_FLUSH_INTERVAL_MS=50\nf env set SEQ_EVERRUNS_MAPLE_CONNECT_TIMEOUT_MS=400\nf env set SEQ_EVERRUNS_MAPLE_REQUEST_TIMEOUT_MS=800\n```\n\nFor optimized mirror (remote ClickHouse + durable local spool), also set:\n\n```bash\nf env set SEQ_CH_MODE=mirror\nf env set SEQ_CH_MEM_PATH=~/.config/flow/rl/seq_mem.jsonl\nf env set SEQ_CH_LOG_PATH=~/.config/flow/rl/seq_trace.jsonl\n```\n\n## 2) Run with env injected\n\nUse `f env run` so runtime sees configured values:\n\n```bash\nf env run -- f ai everruns \"open Safari and take a screenshot\"\n```\n\nIf you already export envs another way, this also works:\n\n```bash\nf ai everruns \"open Safari and take a screenshot\"\n```\n\nOn startup, if telemetry is enabled, Flow prints:\n\n`maple dual-ingest telemetry enabled`\n\n## 3) Verify in Maple\n\nIn Maple (local and hosted), filter by:\n\n- `service.name = seq-everruns-bridge`\n\nLook for span names:\n\n- `everruns.tool_call`\n- `everruns.tool_call_requested`\n- `everruns.output_message_completed`\n\n## Troubleshooting\n\n1. Error: `invalid SEQ_EVERRUNS_MAPLE_* configuration`\n - You set only endpoint or only key for local/hosted pair.\n - Fix by setting both or removing both for that pair.\n2. Everruns command works but no spans in Maple\n - Confirm ingest endpoint includes `/v1/traces`.\n - Confirm ingest key is valid for that endpoint.\n - Confirm you ran through `f env run -- ...` (or equivalent env injection).\n3. Temporary Maple outage\n - Tool execution continues.\n - Export is best-effort and non-blocking.\n" }, { "path": "docs/everruns-seq-bridge-integration.md", "content": "# Everruns + Seq Bridge Integration\n\nThis document describes the Flow integration that runs Everruns sessions and executes\nclient-side `seq_*` tool calls via `seqd` without duplicating Seq mapping logic.\n\n## Why This Was Added\n\n`f ai everruns` already existed, but duplicated three things now maintained in `~/code/seq`:\n\n- Everruns `seq_*` client-side tool catalog\n- tool-name normalization rules\n- request correlation ID shaping for seq RPC (`request_id`, `run_id`, `tool_call_id`)\n\nFlow now imports the shared bridge crate instead of carrying its own copy.\n\n## What Changed\n\nCode path changed only in Everruns tool-bridge internals:\n\n- `src/ai_everruns.rs`\n- `Cargo.toml` dependency on `seq_everruns_bridge`\n\nFlow still owns and keeps unchanged:\n\n- Everruns prompt/session/message/event loop\n- Flow config/env resolution for Everruns (`[everruns]`, `FLOW_EVERRUNS_*`)\n- `f seq-rpc` command and other AI session commands\n\nFlow now additionally supports Maple dual-ingest telemetry export from the Everruns runtime\nwhen `SEQ_EVERRUNS_MAPLE_*` env vars are set.\n\nRuntime path is now SSE-first for lower latency:\n\n- primary: `GET /v1/sessions/{id}/sse` (push events, reconnect with `since_id`)\n- fallback: `GET /v1/sessions/{id}/events` polling when SSE endpoint is unavailable\n\n## No-Overlap Contract\n\nThis integration is intentionally scoped to avoid feature overlap:\n\n- Flow does not reimplement `seq_*` tool schema/mapping anymore.\n- Flow does not add a second Everruns runtime.\n- Existing `f ai claude` / `f ai codex` / `f seq-rpc` behavior remains unchanged.\n\n## Maple Dual Ingest (Local + Hosted)\n\nWhen enabled, Flow emits:\n\n- tool call spans (`everruns.tool_call`)\n- runtime event spans (`everruns.tool_call_requested`, `everruns.output_message_completed`, etc.)\n\nusing `seq_everruns_bridge::maple::MapleTraceExporter` and non-blocking background batching.\n\nRequired env keys:\n\n- `SEQ_EVERRUNS_MAPLE_LOCAL_ENDPOINT` (example: `http://ingest.maple.localhost/v1/traces`)\n- `SEQ_EVERRUNS_MAPLE_LOCAL_INGEST_KEY`\n- `SEQ_EVERRUNS_MAPLE_HOSTED_ENDPOINT` (example: `https://ingest.1focus.ai/v1/traces`)\n- `SEQ_EVERRUNS_MAPLE_HOSTED_INGEST_KEY`\n\nOperational setup/run instructions:\n\n- `docs/everruns-maple-runbook.md`\n\n## Dependency Setup\n\nCurrent local setup in `Cargo.toml`:\n\n```toml\nseq_everruns_bridge = { path = \"../seq/api/rust/seq_everruns_bridge\" }\n```\n\nThis matches a sibling checkout layout:\n\n- `~/code/flow`\n- `~/code/seq`\n\n### Submodule Option (recommended for portability)\n\nIf you want reproducible CI/clone behavior, replace the sibling path with a submodule path:\n\n1. add seq as submodule (example): `third_party/seq`\n2. update dep path to:\n\n```toml\nseq_everruns_bridge = { path = \"third_party/seq/api/rust/seq_everruns_bridge\" }\n```\n\n## Validation (Real Results)\n\nRun from `~/code/flow`:\n\n```bash\ncargo check\ncargo run --release --bin f -- ai everruns --help\nrg \"bridge_tool_definitions|parse_tool_call_requested|bridge_build_request\" src/ai_everruns.rs\nrg \"map_seq_operation|seq_client_tool_definitions\" src/ai_everruns.rs\nrg \"MapleTraceExporter|MapleSpan::for_runtime_event\" src/ai_everruns.rs\n```\n\nEnd-to-end smoke (requires local Everruns + seqd):\n\n```bash\nf ai everruns \"ping\"\n```\n\nExpected evidence of integration:\n\n- successful compile with shared bridge dependency\n- bridge call-sites present in Flow Everruns runtime\n- Maple exporter call-sites present (tool + runtime spans)\n- no duplicated tool catalog/mapping in `src/ai_everruns.rs`\n- SSE-first event consumption active in `src/ai_everruns.rs`\n\n## When To Keep It / When To Revert\n\nKeep this integration if:\n\n- you want one source of truth for Everruns `seq_*` tool behavior\n- Flow and Seq should stay protocol-aligned with less maintenance drift\n\nRevert if:\n\n- Flow must build in environments where seq bridge path is unavailable\n- you intentionally want Flow and Seq to diverge in tool mapping behavior\n" }, { "path": "docs/fast-commit-deep-review-loop.md", "content": "# Fast Commit + Deep Codex Review Loop\n\nThis guide configures a speed-first commit workflow with deferred deep review:\n\n- Fast lane now: commit immediately with low-latency model fallbacks (GLM/Cerebras via `zerg/ai`).\n- Deep lane later: batch Codex reviews across queued commits.\n\n## 1) Configure `~/code/myflow/flow.toml`\n\n```toml\n[commit]\nqueue = false\nqueue_on_issues = false\n\nmessage_fallbacks = [\n \"rise:zai:glm-5\",\n \"rise:cerebras:gpt-oss-120b\",\n \"remote\",\n \"openai\"\n]\n\nreview_fallbacks = [\n \"glm5\",\n \"rise:cerebras:gpt-oss-120b\",\n \"codex-high\"\n]\n\n[options]\n# Optional: mirror commit + queued-review results to myflow.\nmyflow_mirror = true\n# myflow_url = \"https://myflow.sh\"\n# myflow_token = \"...\"\n\n# Optional: route Codex review through a wrapper transport binary.\n# Must implement `app-server` JSON-RPC compatibility.\n# codex_bin = \"~/code/flow/scripts/codex-jazz-wrapper\"\n```\n\n## 2) Daily loop\n\n```bash\n# Fast default commit path (quick lane)\nf commit\n\n# Later, run deep Codex review across backlog\nf reviews-todo codex --all\n\n# Inspect pending/updated deep-review todos\nf reviews-todo list\n\n# Approve once issues are addressed\nf reviews-todo approve-all\n```\n\n## 3) Fixing attached issues without copy/paste\n\n- Each reviewed commit writes a report under `~/.flow/commits/`.\n- Use that report directly:\n\n```bash\nf fix ~/.flow/commits/<report>.md\n```\n\nThis replaces manual “copy `f commit` output into Codex and ask to address all issues”.\n\n## Notes\n\n- Plain `f commit` already uses the fast lane (`--quick`) by default. Set `quick-default = false` only if you want blocking review as the default.\n- Async queued Codex reviews now emit `commit_queue_review` mirror sync events to myflow/gitedit when the reviewed commit is current `HEAD` (the default `f commit --quick` flow).\n- `f reviews-todo codex --all` is a workflow alias over commit queue deep review.\n" }, { "path": "docs/features.md", "content": "# Flow Features\n\nFlow is a CLI tool for managing project tasks, AI coding sessions, and development workflows.\n\n## Quick Reference\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `f <task>` | - | Run a task directly |\n| `f search` | `f s` | Fuzzy search global tasks |\n| `f commit` | `f c` | AI-powered git commit |\n| `f commitWithCheck` | `f cc` | Commit with Codex code review |\n| `f ai` | - | Manage AI sessions (Claude/Codex) |\n| `f skills` | - | Manage Codex skills |\n| `f daemon` | `f d` | Manage background daemons |\n| `f env` | - | Manage environment variables |\n| `f match` | `f m` | Natural language task matching |\n\n---\n\n## Task Management\n\n### Running Tasks\n\n```bash\n# Run a task directly (most common usage)\nf <task-name> [args...]\n\n# Example: run 'dev' task with arguments\nf dev --port 3000\n\n# Fuzzy search global tasks (outside project directories)\nf search\nf s\n```\n\n### Task History\n\n```bash\n# Show the last task input and output\nf last-cmd\n\n# Show full details of last task run\nf last-cmd-full\n\n# Re-run the last executed task\nf rerun\n```\n\n### Process Management\n\n```bash\n# List running flow processes for current project\nf ps\nf ps --all # List across all projects\n\n# Stop running processes\nf kill <task-name>\nf kill <pid>\nf kill --all\n```\n\n### Task Logs\n\n```bash\n# View logs from running or recent tasks\nf logs <task-name>\nf logs -f # Follow in real-time\n```\n\n### Task Failure Hooks\n\nFlow can run a hook automatically when a task fails. This is useful for opening\nan AI prompt, collecting diagnostics, or running cleanup scripts.\n\nSee `docs/task-failure-hooks.md` for configuration, environment variables, and\ndefault behavior.\n\n---\n\n## AI Session Management\n\nManage Claude Code and Codex sessions with fuzzy search and session tracking.\n\n### Listing Sessions\n\n```bash\n# List all AI sessions for current project (Claude + Codex)\nf ai\nf ai list\n\n# List only Claude sessions\nf ai claude\nf ai claude list\n\n# List only Codex sessions\nf ai codex\nf ai codex list\n```\n\n### Resuming Sessions\n\n```bash\n# Resume a session (fuzzy search)\nf ai resume\n\n# Resume a specific session by name or ID\nf ai resume my-session\n\n# Resume Claude-only sessions\nf ai claude resume\n\n# Search Codex sessions globally by prompt text and resume the best match\nf ai codex find \"make plan to get designer\"\n\n# Search Codex sessions globally by prompt text and copy the best match\nf ai codex findAndCopy \"make plan to get designer\"\n\n# Narrow the Codex search to a repo path or workspace subtree\nf ai codex find --path ~/repos/acme/app \"arranged tooling\"\n```\n\nImportant resume rules:\n- `f ai claude resume <explicit-id-or-name>` is strict (fails instead of opening a different session).\n- `f ai codex resume ...` requires an interactive TTY.\n- For full details, see `commands/ai.md`.\n\n### Copying Session Content\n\n```bash\n# Copy full session history to clipboard (fuzzy search)\nf ai copy\n\n# Copy last exchange (prompt + response) to clipboard\nf ai context\n\n# Copy last 3 exchanges from a specific project\nf ai claude context - /path/to/project 3\n\n# Copy from a specific session\nf ai context my-session /path/to/project 2\n```\n\nThe `-` placeholder triggers fuzzy search for session selection.\n\n### Saving & Managing Sessions\n\n```bash\n# Save/bookmark a session with a name\nf ai save my-feature-work\nf ai save bugfix --id <session-id>\n\n# Open or create notes for a session\nf ai notes my-session\n\n# Remove a saved session from tracking\nf ai remove my-session\n\n# Initialize .ai folder structure\nf ai init\n\n# Import existing sessions for this project\nf ai import\n```\n\n---\n\n## AI-Powered Git Commits\n\n### Standard Commit\n\n```bash\n# Stage all changes, generate AI commit message, commit, and push\nf commit\nf c\n\n# Skip pushing after commit\nf commit --no-push\n```\n\n### Commit with Code Review\n\n```bash\n# Run Codex code review before committing\nf commitWithCheck\nf cc\n\n# Review checks for:\n# - Bugs\n# - Security vulnerabilities\n# - Performance issues\n#\n# Optional config:\n# [options]\n# commit_with_check_async = false # force local sync execution\n# commit_with_check_use_repo_root = false # only stage/commit from current subdir\n# commit_with_check_timeout_secs = 300 # abort review if it hangs (default 300)\n# commit_with_check_review_retries = 2 # retry timed-out review runs (default 2)\n#\n# Optional env overrides:\n# FLOW_COMMIT_WITH_CHECK_TIMEOUT_SECS=600\n# FLOW_COMMIT_WITH_CHECK_REVIEW_RETRIES=3\n# FLOW_COMMIT_WITH_CHECK_RETRY_BACKOFF_SECS=5\n\n# If issues found, prompts for confirmation before proceeding\n```\n\n---\n\n## Background Daemons\n\nManage long-running processes defined in `flow.toml`.\n\n```bash\n# Start a daemon\nf daemon start <name>\n\n# Stop a daemon\nf daemon stop <name>\n\n# Check daemon status\nf daemon status\n\n# List available daemons\nf daemon list\nf daemon ls\n```\n\nDaemon config supports autostart, boot-only daemons, restart policies, and\nreadiness checks:\n\n```toml\n[[daemon]]\nname = \"lin\"\nbinary = \"lin\"\ncommand = \"daemon\"\nargs = [\"--host\", \"127.0.0.1\", \"--port\", \"9050\"]\nhealth_url = \"http://127.0.0.1:9050/health\"\nautostart = true\nautostop = true\nboot = true\nrestart = \"on-failure\"\nretry = 3\nready_output = \"ready\"\nready_delay = 500\n```\n\n---\n\n## Environment Variables\n\nManage environment variables via cloud integration.\n\n### Authentication\n\n```bash\n# Login to cloud\nf env login\n\n# Check auth status\nf env status\n```\n\n### Managing Variables\n\n```bash\n# Pull env vars to .env file\nf env pull\nf env pull -e staging\n\n# Push local .env to cloud\nf env push\nf env push -e production\n\n# Apply cloud envs to Cloudflare\nf env apply\n\n# Interactive setup (select env file + keys)\nf env setup\nf env setup -e staging -f .env.staging\n\n# List env vars\nf env list\nf env ls\n\n# Set a single variable\nf env set KEY=value\nf env set API_KEY=secret -e production\n\n# Delete variable(s)\nf env delete KEY1 KEY2\n```\n\n---\n\n## Codex Skills\n\nManage Codex skills stored in `.ai/skills/` (gitignored by default). Skills help Codex understand project-specific workflows.\n\n### Managing Skills\n\n```bash\n# List all skills\nf skills\nf skills ls\n\n# Create a new skill\nf skills new deploy-worker\nf skills new deploy-worker -d \"Deploy to Cloudflare Workers\"\n\n# Show skill details\nf skills show deploy-worker\n\n# Edit a skill in your editor\nf skills edit deploy-worker\n\n# Remove a skill\nf skills remove deploy-worker\n```\n\n### Installing Curated Skills\n\n```bash\n# Install from Codex skill registry\nf skills install linear\nf skills install github-pr\n```\n\n### Syncing from flow.toml\n\n```bash\n# Generate skills from flow.toml tasks\nf skills sync\n\n# Force Codex to rescan skills for the current cwd\nf skills reload\n```\n\nThis creates a skill for each task in `flow.toml`, so Codex automatically knows about your project's workflows.\n\nTo auto-sync tasks or auto-install curated skills on demand, add a `[skills]` section to `flow.toml`:\n\n```toml\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n```\n\n`[skills.codex]` keeps agent context tight by generating `agents/openai.yaml` for task skills and automatically refreshing Codex’s skill cache after sync/install.\n\nFor strict local quality enforcement on commit:\n\n```toml\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\n### Fetching Dependency Skills via seq\n\n```bash\n# Fetch by dependency name\nf skills fetch dep react\n\n# Auto-discover dependencies and fetch top N per ecosystem\nf skills fetch auto --top 3\n\n# Fetch from URLs\nf skills fetch url https://docs.python.org/3/library/asyncio.html --name asyncio\n```\n\nOptional defaults in `flow.toml`:\n\n```toml\n[skills.seq]\nseq_repo = \"~/code/seq\"\nout_dir = \".ai/skills\"\nscraper_base_url = \"http://127.0.0.1:7444\"\nallow_direct_fallback = true\ntop = 3\necosystems = \"npm,pypi,cargo,swift\"\n```\n\n### Skill Structure\n\n`.ai/skills/` is generated locally and should not be committed.\n\n```\n.ai/skills/\n└── deploy-worker/\n └── SKILL.md\n```\n\nEach `SKILL.md` contains:\n\n```markdown\n---\nname: deploy-worker\ndescription: Deploy to Cloudflare Workers\n---\n\n# deploy-worker\n\n## Instructions\n\nRun this task with `f deploy-worker`\n\n## Examples\n\n...\n```\n\n---\n\n## Natural Language Task Matching\n\nMatch tasks using natural language via local LM Studio.\n\n```bash\n# Match a query to a task\nf match \"run the tests\"\nf m \"start development server\"\n\n# Requires LM Studio running on localhost:1234\n```\n\n---\n\n## Project Management\n\n### Projects\n\n```bash\n# List registered projects\nf projects\n\n# Show or set active project\nf active\nf active set my-project\n```\n\n### Initialization\n\n```bash\n# Create a new flow.toml in current directory\nf init\n\n# Fix common TOML syntax errors\nf fixup\n```\n\n`f init` now seeds a Codex-first baseline (`[skills]`, `[skills.codex]`, and commit skill-gate sections) so task sync + skill enforcement are enabled from day one.\n\n### Health Check\n\n```bash\n# Verify required tools and shell integrations\nf doctor\n```\n\n---\n\n## Hub (Background Daemon)\n\nThe hub manages background task execution and log aggregation.\n\n```bash\n# Ensure hub daemon is running\nf hub\n\n# Start the HTTP server for log ingestion\nf server\n```\n\n---\n\n## flow.toml Configuration\n\n### Basic Task Definition\n\n```toml\n[[tasks]]\nname = \"dev\"\ndescription = \"Start development server\"\ncommand = \"npm run dev\"\n\n[[tasks]]\nname = \"test\"\ndescription = \"Run tests\"\ncommand = \"cargo test\"\ndependencies = [\"cargo\"]\n```\n\n### Task with File Watching (Auto-rerun)\n\n```toml\n[[tasks]]\nname = \"build\"\ncommand = \"cargo build\"\nrerun_on = [\"src/**/*.rs\", \"Cargo.toml\"]\nrerun_debounce_ms = 300\n```\n\n### Daemons (Background Services)\n\n```toml\n[[daemons]]\nname = \"api\"\ncommand = \"cargo run --bin server\"\ndescription = \"API server\"\n\n[[daemons]]\nname = \"worker\"\ncommand = \"node worker.js\"\n```\n\n### Dependencies\n\n```toml\n[deps]\ngit = \"git\"\nnode = \"node\"\ncargo = \"cargo\"\n```\n\n---\n\n## Shell Integration\n\n### Direnv Integration\n\nAdd to `.envrc` for automatic project daemon startup:\n\n```sh\nif command -v flow >/dev/null 2>&1; then\n flow project start --detach >/dev/null 2>&1\nfi\n```\n\n### Aliases (Recommended)\n\n```bash\nalias f=\"flow\"\n```\n\n---\n\n## File Structure\n\n```\n~/.config/flow/\n├── flow.toml # Global config\n└── config.toml # Flow settings\n\n~/.flow/\n└── projects/ # Per-project daemon data\n └── <hash>/\n ├── pid\n └── logs/\n\n<project>/\n├── flow.toml # Project tasks\n└── .ai/\n ├── sessions/\n │ └── claude/\n │ └── index.json\n └── skills/ # Codex skills (gitignored, materialized locally)\n └── <skill-name>/\n └── SKILL.md\n```\n" }, { "path": "docs/flow-toml-spec.md", "content": "# flow.toml Specification\n\nMinimal schema for Flow CLI tasks and managed dependencies. Designed for easy refactors and LLM prompting.\n\n## File Layout\n\n```toml\nversion = 1\nname = \"my-project\" # optional human-friendly project name\n\n[deps] # optional: command deps or managed pkg specs\n# key = \"cmd\" # single command on PATH\n# key = [\"cmd1\",\"cmd2\"] # multiple commands\n# key = { pkg-path = \"ripgrep\", version = \"14\" } # managed pkg descriptor\n\n[flox] # optional: install set for managed env (applies to all tasks)\n[flox.install]\n# name.pkg-path = \"ripgrep\"\n# name.version = \"14.1.1\"\n# name.pkg-group = \"tools\" # optional grouping\n# name.systems = [\"x86_64-darwin\"] # optional target systems\n# name.priority = 10 # optional ordering hint\n\n[[tasks]] # project tasks\nname = \"setup\" # required, unique\ncommand = \"cargo check\"\ndescription = \"Compile workspace\" # optional\nactivate_on_cd_to_root = true # optional, default false\ndependencies = [\"fast\"] # optional, names from [deps] or [flox.install]\nshortcuts = [\"s\"] # optional aliases for task lookup\n\n[skills] # optional: skill enforcement (gitignored by default)\nsync_tasks = true # optional: generate skills for tasks\ninstall = [\"linear\"] # optional: ensure skills are installed (local ~/.codex/skills preferred, else registry)\n[skills.codex] # optional: Codex-specific skill metadata/reload behavior\n# generate_openai_yaml = true\n# force_reload_after_sync = true\n# task_skill_allow_implicit_invocation = false\n[codex] # optional: Codex-first open/resolve behavior\n# auto_resolve_references = true\n# prompt_context_budget_chars = 1200\n# max_resolved_references = 2\n[[codex.reference_resolver]]\n# name = \"linear\"\n# match = [\"https://linear.app/*/issue/*\", \"https://linear.app/*/project/*\"]\n# command = \"my-linear-tool inspect {{ref}} --json\"\n# inject_as = \"linear\"\n[skills.seq] # optional: seq-backed dependency skill fetching defaults\n# seq_repo = \"~/code/seq\"\n# out_dir = \".ai/skills\"\n# scraper_base_url = \"http://127.0.0.1:7444\"\n# allow_direct_fallback = true\n\n[commit] # optional: commit workflow defaults\n# quick-default = false # optional override: make plain `f commit` run blocking review (`--slow`)\n# queue = false # keep fast path pushing by default\n# queue_on_issues = false # do not force queue-only flow on review issues\n# message-fallbacks = [\"rise:zai:glm-5\", \"rise:cerebras:gpt-oss-120b\", \"remote\", \"openai\"]\n# review-fallbacks = [\"glm5\", \"rise:cerebras:gpt-oss-120b\", \"codex-high\"]\n\n[task_resolution] # optional: nested-task disambiguation policy\n# preferred_scopes = [\"mobile\", \"root\"] # used when plain task name is ambiguous\n# warn_on_implicit_scope = true # print note when fallback routing is applied\n[task_resolution.routes]\n# dev = \"mobile\" # route ambiguous task name -> scope\n# test = \"root\"\n\n[lifecycle] # optional: `f up` / `f down` defaults\n# up_task = \"dev\" # default fallback order: up -> dev\n# down_task = \"stop\" # default fallback: down\n[lifecycle.domains] # optional: auto `f domains` wiring for `f up` / `f down`\n# host = \"myflow.localhost\"\n# target = \"127.0.0.1:3000\"\n# engine = \"native\" # \"native\" | \"docker\"\n# remove_on_down = false\n# stop_proxy_on_down = false\n\n[options] # optional: transport/runtime integrations\n# myflow_mirror = true # mirror commit + queue review events to myflow\n# myflow_url = \"https://myflow.sh\"\n# myflow_token = \"...\"\n# codex_bin = \"/path/to/codex-wrapper\" # must support `app-server` JSON-RPC\n# codex_bin = \"~/code/flow/scripts/codex-jazz-wrapper\"\n# You can set this in repo flow.toml or global ~/.config/flow/flow.toml\n\n[commit.testing] # optional: local commit-time test gate\n# mode = \"warn\" # \"warn\" | \"block\" | \"off\"\n# runner = \"bun\" # currently optimized for bun in Bun repos\n# bun_repo_strict = true\n# require_related_tests = true\n# ai_scratch_test_dir = \".ai/test\"\n# run_ai_scratch_tests = true\n# allow_ai_scratch_to_satisfy_gate = false\n# max_local_gate_seconds = 20\n\n[commit.skill_gate] # optional: require specific local skills before commit\n# mode = \"warn\" # \"warn\" | \"block\" | \"off\"\n# required = [\"quality-bun-feature-delivery\"]\n[commit.skill_gate.min_version]\n# quality-bun-feature-delivery = 2\n\n[invariants] # optional: AI-driven invariant enforcement\n# mode = \"warn\" # \"warn\" | \"block\" | \"off\"\n# architecture_style = \"layered monorepo\"\n# non_negotiable = [\"no inline imports\", \"no any without justification\"]\n# forbidden = [\"git add -A\", \"git reset --hard\"]\n[invariants.terminology]\n# \"pi-ai\" = \"LLM abstraction layer\"\n# \"pi-agent\" = \"stateful agent runtime\"\n[invariants.deps]\n# policy = \"approval_required\" # \"approval_required\" | \"open\"\n# approved = [\"@sinclair/typebox\", \"@reatom/core\"]\n[invariants.files]\n# max_lines = 300\n\n[git] # optional: git remote defaults for commit/sync\n# remote = \"origin\" # e.g. \"myflow-i\" for contributor mirror repos\n\n[[alias]] # optional shell aliases (or use [aliases] table)\nfr = \"f run\" # key/value pairs of alias -> command\n\n[aliases] # optional table alternative to [[alias]]\nfr = \"f run\"\n```\n\n## Semantics\n\n- `version`: currently `1`.\n- `name`: optional display name for the project (useful in history/metadata).\n- `[deps]`: map of dependency names to either:\n - string (single command to check on PATH),\n - string array (multiple commands),\n - table with `pkg-path` (+ optional `version`, `pkg-group`, `systems`, `priority`) for managed pkg.\n- `[flox.install]`: global managed packages always included when any task runs inside the managed env.\n- `tasks.dependencies`: names resolved against `[deps]` first, then `[flox.install]`.\n- Tasks run inside the managed env when any managed deps are present; otherwise they use host PATH.\n- `activate_on_cd_to_root`: tasks flagged run automatically when Flow is invoked via `activate` hooks.\n- `shortcuts`: case-insensitive aliases and abbreviations (auto-generated from task names) resolve tasks.\n- `alias`/`aliases`: emitted by `f setup` as shell `alias` lines.\n- `[skills]`: optional skill enforcement; `sync_tasks` generates `.ai/skills` from tasks and `install` ensures registry skills are present (skills are gitignored by default).\n- `[skills.codex]`: optional Codex tuning; task skill `agents/openai.yaml` generation, post-sync force reload, and implicit invocation policy defaults.\n- `[codex]`: optional Codex-first control-plane settings for `f codex open` / `f codex resolve`.\n - `auto_resolve_references`: when true, matched resolver output is compacted and injected into new-session prompts.\n - `prompt_context_budget_chars`: hard cap for injected context before the raw user request is appended.\n - `max_resolved_references`: maximum number of resolved references Flow may inject into one prompt.\n - `runtime_skills`: when true, `f codex open` may materialize Flow-managed per-launch runtime skills for wrapper transports.\n - `[[codex.reference_resolver]]`: repo-specific reference unrollers with wildcard `match` patterns and a shell `command` template.\n - command templates support `{{ref}}`, `{{query}}`, and `{{cwd}}`.\n - `f codex enable-global --full` writes the global wrapper/runtime baseline into `~/.config/flow/flow.toml` for you.\n- `[skills.seq]`: optional defaults for `f skills fetch ...` (local seq scraper integration).\n- `[commit]`: optional commit workflow defaults; plain `f commit` uses fast commit + deferred Codex deep review by default. Set `quick-default = false` to make plain `f commit` run blocking review instead.\n- `[task_resolution]`: optional policy for nested task discovery (`f <scope>:<task>`, preferred scopes, and per-task routes when plain names collide).\n- `[lifecycle]`: optional project boot/shutdown orchestration for `f up` and `f down`; can auto-wire shared local domain routes via `[lifecycle.domains]`.\n - `f up` task fallback order: `up`, then `dev` (unless `up_task` is set).\n - `f down` task fallback: `down`; if missing and `down_task` is unset, Flow falls back to project-wide `f kill --all`.\n- `[options]`: optional integration/runtime toggles; use `myflow_mirror` for mirror sync and `codex_bin` to route review calls through a wrapper transport.\n- `[commit.testing]`: optional local testing gate evaluated during `f commit`; supports Bun-first strict mode plus optional AI scratch-test fallback (`.ai/test` by default).\n- `[commit.skill_gate]`: optional required-skill policy for `f commit`; can enforce presence and minimum skill versions.\n- `[invariants]`: optional policy checks for forbidden patterns, dependency allowlists, terminology context, and file-size limits. `mode = \"block\"` makes invariant warnings fail `f invariants` and commit-time invariant gate checks.\n- `[git].remote`: preferred writable remote used by `f commit`/`f sync --push` (and jj remote defaults). Fallback order is `[git].remote`, then legacy `[jj].remote`, then `origin`.\n\n## Notes\n\n- Unsupported keys are ignored or will error; keep to this schema.\n- Managed env tooling currently assumes `flox` is installed.\n- Paths in commands are executed via `/bin/sh -c` in the config’s directory unless overridden.\n\n## Codex-First Baseline\n\nUse this baseline when optimizing for Codex/Claude sessions and tight feedback loops:\n\n```toml\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n\n[codex]\nauto_resolve_references = true\nprompt_context_budget_chars = 900\nmax_resolved_references = 1\nruntime_skills = true\n\n[[codex.reference_resolver]]\nname = \"linear\"\nmatch = [\"https://linear.app/*/issue/*\", \"https://linear.app/*/project/*\"]\ncommand = \"my-linear-tool inspect {{ref}} --json\"\ninject_as = \"linear\"\n\n[options]\ncodex_bin = \"~/code/flow/scripts/codex-flow-wrapper\"\n\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n" }, { "path": "docs/how-api-expects-logs-errors-for-automatic-fixes.md", "content": "# Error Log Format for Automatic Fixes\n\nThe flow server streams errors via SSE for automatic fix agents to consume. Structure your error logs with rich context to enable effective automatic fixes.\n\n## Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/logs/ingest` | POST | Ingest single or batch logs |\n| `/logs/query` | GET | Query logs with filters |\n| `/logs/errors/stream` | GET | SSE stream of new errors |\n\n## Error Log Schema\n\n```typescript\ninterface ErrorLog {\n project: string // Project identifier (e.g., \"web\", \"api\", \"cli\")\n content: string // Error message - be descriptive\n timestamp: number // Unix timestamp in milliseconds\n type: \"error\" // Must be \"error\" for fix agents\n service: string // Service/component name (e.g., \"auth\", \"database\")\n stack?: string // Stack trace - critical for automatic fixes\n format: \"text\" | \"json\"\n}\n```\n\n## Best Practices for Automatic Fixes\n\n### 1. Include Full Stack Traces\n\nStack traces are essential for locating the error source:\n\n```typescript\n// Good - includes file, line, column\n{\n \"content\": \"TypeError: Cannot read property 'email' of undefined\",\n \"stack\": \"TypeError: Cannot read property 'email' of undefined\\n at getUser (/app/src/services/user.ts:42:15)\\n at handleRequest (/app/src/routes/api.ts:18:10)\",\n ...\n}\n\n// Bad - no stack trace, agent can't locate the error\n{\n \"content\": \"TypeError: Cannot read property 'email' of undefined\",\n ...\n}\n```\n\n### 2. Use Absolute File Paths\n\nPrefer absolute paths in stack traces:\n\n```\nat getUser (/Users/dev/myapp/src/services/user.ts:42:15) ✓\nat getUser (src/services/user.ts:42:15) ✓ (relative ok)\nat getUser (user.ts:42:15) ✗ (ambiguous)\n```\n\n### 3. Descriptive Error Messages\n\nInclude context in the error message:\n\n```typescript\n// Good\n\"Failed to parse user response: expected 'email' field but got undefined. Input: {id: 123, name: 'test'}\"\n\n// Bad\n\"undefined error\"\n```\n\n### 4. Structured JSON Format (Optional)\n\nFor complex errors, use `format: \"json\"` with structured content:\n\n```typescript\n{\n \"project\": \"api\",\n \"content\": JSON.stringify({\n \"error\": \"ValidationError\",\n \"message\": \"Invalid user data\",\n \"field\": \"email\",\n \"received\": null,\n \"expected\": \"string\",\n \"context\": {\n \"endpoint\": \"/api/users\",\n \"method\": \"POST\",\n \"requestId\": \"abc123\"\n }\n }),\n \"timestamp\": Date.now(),\n \"type\": \"error\",\n \"service\": \"validation\",\n \"stack\": \"...\",\n \"format\": \"json\"\n}\n```\n\n## Error Categories the Fix Agent Handles\n\n| Category | Example | Auto-Fix Capability |\n|----------|---------|---------------------|\n| `TypeError` | Cannot read property 'x' of undefined | High - adds optional chaining |\n| `ReferenceError` | x is not defined | Medium - suggests imports |\n| `SyntaxError` | Unexpected token | Low - needs manual review |\n| `Import errors` | Cannot find module 'x' | High - suggests npm install |\n| `Validation` | Invalid field type | Medium - adds type guards |\n| `Connection` | ECONNREFUSED | Low - infrastructure issue |\n\n## Sending Errors from Your App\n\n### TypeScript/JavaScript\n\n```typescript\ninterface ErrorPayload {\n project: string\n content: string\n timestamp: number\n type: \"error\"\n service: string\n stack?: string\n format: \"text\" | \"json\"\n}\n\nasync function reportError(error: Error, service: string) {\n const payload: ErrorPayload = {\n project: process.env.PROJECT_NAME || \"unknown\",\n content: error.message,\n timestamp: Date.now(),\n type: \"error\",\n service,\n stack: error.stack,\n format: \"text\"\n }\n\n await fetch(\"http://127.0.0.1:9060/logs/ingest\", {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify(payload)\n })\n}\n\n// Global error handler\nprocess.on(\"uncaughtException\", (error) => {\n reportError(error, \"process\")\n})\n\n// Express/Hono middleware\napp.use((err, req, res, next) => {\n reportError(err, \"http\")\n res.status(500).json({ error: \"Internal error\" })\n})\n```\n\n### React Error Boundary\n\n```typescript\nclass ErrorBoundary extends React.Component {\n componentDidCatch(error: Error, info: React.ErrorInfo) {\n fetch(\"http://127.0.0.1:9060/logs/ingest\", {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n project: \"web\",\n content: error.message,\n timestamp: Date.now(),\n type: \"error\",\n service: \"react\",\n stack: error.stack + \"\\n\\nComponent Stack:\\n\" + info.componentStack,\n format: \"text\"\n })\n })\n }\n}\n```\n\n## Consuming the Error Stream\n\nConnect to the SSE endpoint to receive errors in real-time:\n\n```typescript\nconst events = new EventSource(\"http://127.0.0.1:9060/logs/errors/stream\")\n\nevents.onmessage = (e) => {\n const error = JSON.parse(e.data)\n console.log(`New error in ${error.project}/${error.service}:`, error.content)\n\n // Trigger fix agent\n attemptFix(error)\n}\n\nevents.onerror = (e) => {\n console.error(\"SSE connection error:\", e)\n}\n```\n\n## Testing\n\n1. Start the flow server:\n ```bash\n f server\n ```\n\n2. Send a test error:\n ```bash\n curl -X POST http://127.0.0.1:9060/logs/ingest \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"project\": \"test\",\n \"content\": \"TypeError: Cannot read property '\\''foo'\\'' of undefined\",\n \"timestamp\": '$(date +%s000)',\n \"type\": \"error\",\n \"service\": \"test\",\n \"stack\": \"TypeError: Cannot read property '\\''foo'\\'' of undefined\\n at test (/app/src/index.ts:10:5)\",\n \"format\": \"text\"\n }'\n ```\n\n3. Watch the stream:\n ```bash\n curl -N http://127.0.0.1:9060/logs/errors/stream\n ```\n" }, { "path": "docs/how-flow-daemon-manages-macos-services.md", "content": "# How Flow Daemon Manages macOS Services\n\nFlow provides a declarative alternative to macOS launchd for managing background services. Instead of scattered `.plist` files, all services are defined in a single `flow.toml` configuration.\n\n## Why Use Flow Instead of launchd?\n\n| launchd | Flow |\n|---------|------|\n| Plist files scattered across ~/Library/LaunchAgents | Single `~/.config/flow/flow.toml` |\n| Services auto-start on login (hidden cost) | Explicit control: autostart or on-demand |\n| Hard to audit what's running | `f daemon status` shows everything |\n| XML format, verbose | TOML format, readable |\n| No easy way to temporarily disable | `f daemon stop <name>` |\n\n## Quick Start\n\n```bash\n# See what's running\nf daemon status\n\n# Start a service\nf daemon start glm4\n\n# Stop a service\nf daemon stop glm4\n\n# Audit macOS launchd services\nf macos audit\n\n# Disable a launchd service and migrate to Flow\nf macos disable com.example.service\n# Then add [[daemon]] entry to flow.toml\n```\n\n## Migrating from launchd to Flow\n\n### Step 1: Audit Your Current Services\n\n```bash\n# List all non-Apple launchd services\nf macos list\n\n# See what's currently running\nf macos status\n\n# Get recommendations\nf macos audit\n```\n\n### Step 2: Get Service Details\n\n```bash\n# View plist contents for a service\nf macos info com.example.service\n```\n\nThis shows the binary, arguments, working directory, and environment variables needed to recreate the service in Flow.\n\n### Step 3: Disable launchd Service\n\n```bash\nf macos disable com.example.service\n```\n\nThis runs `launchctl bootout` and `launchctl disable` to prevent the service from starting.\n\n### Step 4: Add to flow.toml\n\n```toml\n[[daemon]]\nname = \"example\"\nbinary = \"/path/to/binary\"\nargs = [\"--port\", \"8080\"]\nworking_dir = \"/path/to/workdir\"\nport = 8080\nhealth_url = \"http://127.0.0.1:8080/health\"\nautostart = false # true = starts on login\nboot = false # true = starts on system boot\nrestart = \"on-failure\" # \"never\", \"on-failure\", \"always\"\ndescription = \"Example service\"\n\n# Optional: environment variables\n[daemon.env]\nAPI_KEY = \"secret\"\n```\n\n### Step 5: Start the Service\n\n```bash\nf daemon start example\n```\n\n## Daemon Configuration Reference\n\n### Required Fields\n\n| Field | Description |\n|-------|-------------|\n| `name` | Unique identifier for the daemon |\n| `binary` | Path to executable |\n\n### Optional Fields\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `command` | - | Subcommand to run (e.g., \"server\") |\n| `args` | `[]` | Arguments passed to binary/command |\n| `working_dir` | - | Working directory for the process |\n| `port` | - | Port the service listens on |\n| `host` | `127.0.0.1` | Host the service binds to |\n| `health_url` | - | URL to check if service is healthy |\n| `autostart` | `false` | Start automatically when Flow starts |\n| `boot` | `false` | Start on system boot |\n| `autostop` | `false` | Stop when leaving project |\n| `restart` | - | Restart policy: `never`, `on-failure`, `always` |\n| `retry` | - | Max restart attempts |\n| `ready_delay` | - | Ms to wait before considering ready |\n| `ready_output` | - | Output pattern to match for readiness |\n| `description` | - | Human-readable description |\n| `env` | `{}` | Environment variables |\n\n## Example Configurations\n\n### Local LLM Server (On-Demand)\n\n```toml\n[[daemon]]\nname = \"glm4\"\nbinary = \"/path/to/venv/bin/python\"\nargs = [\"-m\", \"mlx_lm.server\", \"--model\", \"mlx-community/Qwen2.5-7B-Instruct-4bit\", \"--port\", \"8080\"]\nworking_dir = \"/path/to/mlx-lm\"\nport = 8080\nhealth_url = \"http://127.0.0.1:8080/health\"\nautostart = false\ndescription = \"MLX local LLM server\"\n```\n\n### File Watcher (Always Running)\n\n```toml\n[[daemon]]\nname = \"watchman\"\nbinary = \"/opt/homebrew/bin/watchman\"\nargs = [\"--foreground\", \"--logfile=/path/to/log\"]\nautostart = true\nboot = true\nrestart = \"on-failure\"\ndescription = \"Facebook Watchman file watcher\"\n```\n\n### Node.js Service with Environment\n\n```toml\n[[daemon]]\nname = \"api\"\nbinary = \"/path/to/node\"\nargs = [\"/path/to/server.js\"]\nworking_dir = \"/path/to/project\"\nport = 3000\nhealth_url = \"http://127.0.0.1:3000/health\"\nautostart = false\nrestart = \"on-failure\"\nretry = 3\ndescription = \"API server\"\n\n[daemon.env]\nNODE_ENV = \"production\"\nDATABASE_URL = \"postgres://localhost/db\"\n```\n\n## macOS Service Audit Configuration\n\nConfigure which services are allowed or should be blocked in your `flow.toml`:\n\n```toml\n[macos]\n# Services matching these patterns won't be flagged\nallowed = [\n \"com.nikiv.*\",\n \"com.github.facebook.watchman\",\n \"limit.maxfiles\",\n]\n\n# Services matching these patterns will be recommended for removal\nblocked = [\n \"com.google.*\", # Google updaters\n \"com.adobe.*\", # Adobe background services\n \"us.zoom.*\", # Zoom daemon\n \"com.microsoft.update.*\",\n \"com.dropbox.*\",\n \"com.spotify.webhelper\",\n]\n```\n\n## Commands Reference\n\n### Daemon Management\n\n```bash\nf daemon status # Show all daemon status\nf daemon start <name> # Start a daemon\nf daemon stop <name> # Stop a daemon\nf daemon restart <name> # Restart a daemon\nf daemon logs <name> # View daemon logs\n```\n\n### macOS Service Audit\n\n```bash\nf macos list [--user] [--system] [--json] # List launchd services\nf macos status # Show running non-Apple services\nf macos audit [--json] # Audit with recommendations\nf macos info <service> # Show service details\nf macos disable <service> [-y] # Disable a service\nf macos enable <service> # Re-enable a service\nf macos clean [--dry-run] [-y] # Disable known bloatware\n```\n\n## Best Practices\n\n1. **Start with audit**: Run `f macos audit` to see what's running unnecessarily\n2. **Disable bloatware first**: Run `f macos clean` to disable known bloatware\n3. **Migrate essential services**: Add services you need to `flow.toml`\n4. **Use autostart sparingly**: Only set `autostart = true` for truly essential services\n5. **Set health URLs**: Enables Flow to verify services are actually running\n6. **Use restart policies**: `restart = \"on-failure\"` for production services\n\n## Troubleshooting\n\n### Service Won't Start\n\n```bash\n# Check if binary exists\nls -la /path/to/binary\n\n# Try running manually\n/path/to/binary --args\n\n# Check logs\nf daemon logs <name>\n```\n\n### launchd Service Still Running\n\n```bash\n# Force disable\nf macos disable <service> -y\n\n# Verify\nlaunchctl list | grep <service>\n\n# Manual removal if needed\nlaunchctl bootout gui/$(id -u)/<service>\nlaunchctl disable gui/$(id -u)/<service>\n```\n\n### Finding the Right Binary Path\n\n```bash\n# Get details from plist\nf macos info <service>\n\n# Or manually\nplutil -convert json -o - ~/Library/LaunchAgents/<service>.plist | jq\n```\n" }, { "path": "docs/how-to-make-a-project-flow-project.md", "content": "# How To Make A Project A Flow Project\n\nThis guide is for both:\n\n- a brand-new repository\n- an existing repository that already has scripts/tooling\n\nThe goal is to make `flow.toml` the project control plane so local development, AI workflows, quality gates, and deploy operations all run through `f`.\n\n---\n\n## What \"Flow Project\" Means\n\nA project is Flow-managed when it has:\n\n1. A `flow.toml` at repo root.\n2. Core workflows exposed as `[[tasks]]` in `flow.toml`.\n3. Secrets/environment managed by `f env` instead of committed `.env` files.\n4. Commits made through `f commit` with explicit quality/testing policy.\n5. Optional AI task and skills wiring (`.ai/tasks`, `.ai/skills`, `[skills]`).\n\nIf your team can run `f tasks`, `f <task>`, `f env`, and `f commit` end-to-end from repo root, the project is Flow-native.\n\n---\n\n## Step 0: Machine Prerequisites\n\nOn each developer machine:\n\n```bash\nf doctor\nf auth login\nf latest\n```\n\nWhy:\n\n- `f doctor` catches missing tooling and shell issues early.\n- `f auth login` enables cloud-backed features (`f env`, remote flows).\n- `f latest` avoids inconsistent command behavior across team members.\n\n---\n\n## Step 1: Bootstrap The Repo\n\nFrom repository root:\n\n```bash\ncd /path/to/repo\nf setup\n```\n\n`f setup` will:\n\n- bootstrap project metadata (`.ai/`, `.gitignore` integration)\n- generate `flow.toml` if missing\n- append missing Codex baseline sections in existing `flow.toml` files\n- run `setup` task if one exists\n\nIf `flow.toml` does not exist yet, `f setup` is the fastest way to initialize safely.\n\n---\n\n## Step 2: Define A Strong `flow.toml` Baseline\n\nUse this as a practical starter and replace commands with your real project commands.\n\n```toml\nversion = 1\nname = \"my-project\"\n\n[skills]\nsync_tasks = true\ninstall = [\"quality-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n\n[[tasks]]\nname = \"setup\"\ncommand = \"echo 'project setup checks here'\"\ndescription = \"Prepare local environment and verify prerequisites\"\n\n[[tasks]]\nname = \"dev\"\ncommand = \"npm run dev\"\ndescription = \"Start local development server\"\n\n[[tasks]]\nname = \"test\"\ncommand = \"npm test\"\ndescription = \"Run test suite\"\n\n[[tasks]]\nname = \"test-related\"\ncommand = \"npm run test:related\"\ndescription = \"Run smallest useful tests for current diff\"\n\n[[tasks]]\nname = \"lint\"\ncommand = \"npm run lint\"\ndescription = \"Lint source code\"\n\n[[tasks]]\nname = \"build\"\ncommand = \"npm run build\"\ndescription = \"Build production artifacts\"\n\n[commit]\nreview_instructions_file = \".ai/commit-review-instructions.md\"\n\n[commit.testing]\nmode = \"block\"\nrequire_related_tests = true\nmax_local_gate_seconds = 30\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-feature-delivery\"]\n\n[invariants]\nmode = \"warn\"\narchitecture_style = \"layered architecture with task-based workflows\"\nnon_negotiable = [\n \"do not bypass Flow tasks for standard workflows\",\n \"keep user-visible changes documented\"\n]\nforbidden = [\"git reset --hard\", \"git add -A .env\"]\n\n[invariants.files]\nmax_lines = 600\n```\n\nNotes:\n\n- Keep task names short and stable (`dev`, `test`, `build`, `deploy`) so AI sessions stay consistent.\n- Prefer one canonical task per workflow. Avoid duplicate aliases with different behavior.\n\n---\n\n## Step 3: Migrate Existing Scripts Into Tasks\n\nIf you already have scripts in `package.json`, `Makefile`, shell scripts, or CI configs:\n\n1. Map each workflow to one Flow task in `flow.toml`.\n2. Keep script internals if needed, but make `f <task>` the public entrypoint.\n3. Update docs/README to reference `f` commands first.\n\nExample mapping:\n\n- `npm run dev` -> `[[tasks]] name = \"dev\"`\n- `make test` -> `[[tasks]] name = \"test\"`\n- `./scripts/release.sh` -> `[[tasks]] name = \"release\"`\n\nThis prevents \"works on my machine\" command drift.\n\n---\n\n## Step 4: Move Secrets To `f env`\n\nDo not commit secrets in repo files.\n\nUse project-scoped env values:\n\n```bash\nf env project set -e dev API_KEY=sk-...\nf env project set -e production API_KEY=sk-...\nf env list -e dev\nf env get -e production API_KEY -f value\n```\n\nRun commands with injected env:\n\n```bash\nf env run -e dev -- f dev\n```\n\nIf your project deploys to Cloudflare, declare env policy in `flow.toml` and use `f env apply` / `f deploy cf`.\n\n---\n\n## Step 5: Make Commit Quality Non-Optional\n\nOnce baseline tasks and env are ready, enforce commit behavior:\n\n```bash\nf commit\n```\n\nRecommended:\n\n- `f commit` for normal flow (fast commit + deferred deep review)\n- `f commit --slow` when you want blocking review before commit\n\nPolicy lives in `flow.toml`:\n\n- `[commit.testing]` for local test gate\n- `[commit.skill_gate]` for required skills\n- `[invariants]` for project-specific guardrails\n\nTreat `--skip-tests` / `--skip-quality` as emergency-only.\n\n---\n\n## Step 6: Add AI Tasks (Optional, High Leverage)\n\nInitialize AI task pack:\n\n```bash\nf tasks init-ai\nf tasks list\nf ai:starter\n```\n\nThis creates `.ai/tasks/*.mbt` entries that can be run like normal tasks.\n\nUse this for:\n\n- structured automation\n- repo-specific AI workflows\n- low-latency repeatable helper routines\n\n---\n\n## Step 7: Wire Deploy Through Flow\n\nChoose one deploy target in `flow.toml`:\n\n- `[host]` for Linux SSH deploys\n- `[cloudflare]` for Workers\n- `[railway]` for Railway\n\nThen run:\n\n```bash\nf deploy\n```\n\nAvoid ad hoc deploy commands in docs/CI when equivalent `f deploy` flow exists.\n\n---\n\n## Step 8: Update Team And CI Entry Points\n\nMake team defaults explicit:\n\n1. README Quick Start uses `f setup`, `f dev`, `f test`, `f commit`.\n2. CI scripts call Flow tasks (`f test`, `f build`) instead of bespoke command chains.\n3. Contributors run from repo root to avoid task resolution surprises.\n\nSimple CI shape:\n\n```bash\nf setup\nf test\nf build\n```\n\n---\n\n## Validation Checklist\n\nRun this from repo root:\n\n```bash\nf setup\nf tasks list\nf test\nf env list -e dev\nf commit --dry\n```\n\nYou are done when:\n\n1. `flow.toml` defines all core workflows as tasks.\n2. Secrets are in `f env`, not committed files.\n3. `f commit` runs with your intended testing/quality policy.\n4. New contributors can get productive with `f setup` + `f tasks list`.\n5. CI and deploy flows run through Flow entrypoints.\n\n---\n\n## Common Migration Mistakes\n\n1. Keeping parallel command paths (`npm run ...` in docs and `f ...` in flow): pick Flow as canonical.\n2. Defining tasks without descriptions: hurts discoverability for humans and AI.\n3. Leaving commit policy at defaults: set `[commit.testing]`, `[commit.skill_gate]`, and invariants intentionally.\n4. Treating `flow.toml` as static: update it whenever workflow changes.\n\n---\n\n## Recommended Next Reads\n\n- `docs/flow-toml-spec.md`\n- `docs/commands/setup.md`\n- `docs/commands/tasks.md`\n- `docs/commands/env.md`\n- `docs/commands/commit.md`\n- `docs/how-to-use-flow-to-deploy.md`\n\n" }, { "path": "docs/how-to-use-flow-ai-to-manage-claude-code-sessions.md", "content": "# Managing Claude and Codex Sessions with Flow\n\nFlow treats Claude and Codex as first-class coding runtimes in the same project loop: tasks, sessions, skills, and commit gates all live together.\n\n## Core Workflow\n\n```bash\n# 1) Enter repo and inspect runnable workflows\ncd <repo>\nf tasks list\n\n# 2) Resume exact prior AI context\nf ai claude resume <session-id>\n# or\nf ai codex resume <session-id>\n\n# 3) Keep skills synced to current tasks\nf skills sync\nf skills reload\n\n# 4) Run the smallest meaningful validation\nf test-related\n\n# 5) Commit through flow's review/testing gates\nf commit\n```\n\nThis is the fastest way to keep context stable and avoid drift across sessions.\n\n## Session Operations\n\n```bash\n# Fuzzy-select and resume (all providers)\nf ai\n\n# Provider-specific listing\nf ai claude list\nf ai codex list\n\n# Resume by exact ID / prefix / alias\nf ai claude resume a38cf8bf-f4e2-4308-8b27-0254f89c4385\nf ai codex resume 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai resume my-feature\n\n# Search Codex sessions globally by prompt text and resume the best match\nf ai codex find \"make plan to get designer\"\n\n# Search Codex sessions globally by prompt text and copy the best match\nf ai codex findAndCopy \"make plan to get designer\"\n\n# Save alias\nf ai save my-feature --id <session-id>\n\n# Copy context/history for handoff\nf ai context\nf ai copy\n```\n\n## Resume Semantics You Should Rely On\n\n### Exact Claude resumes are strict\n\nWhen you pass an explicit session (`name` or `id`), Flow will not auto-open a different conversation if that ID fails.\n\n- tries `claude --resume <id>`\n- if failed, exits non-zero\n- no automatic `--continue` fallback for explicit IDs\n\nThis prevents restoring into the wrong session.\n\n### Claude no-arg resume can fallback\n\n`f ai claude resume` (no argument) resumes the most recent Claude session for this repo. If that fails, Flow can fallback to `claude --continue` in the same cwd.\n\n### Codex resume is direct\n\nFlow resumes Codex by session ID and returns failure if resume fails. No fallback to another session is applied.\n\n### TTY is required\n\nBoth Claude and Codex resume commands require an interactive terminal (TTY). In non-interactive shells, Flow fails fast with a clear error.\n\n## Choosing Claude vs Codex in Flow\n\n- Use Claude sessions when you want broader planning + deep repo narrative continuity.\n- Use Codex sessions when you want tight code-edit and review loops with strong tool execution.\n- Keep both available in the same repo; switch by resuming the exact session you need.\n\n## Task-Driven AI Coding (Important)\n\nAI sessions are most reliable when code execution goes through `flow.toml` tasks.\n\nIf a task prompts for input (like `Y/n/a/q` workflows), mark it:\n\n```toml\n[[tasks]]\nname = \"reclaim\"\ncommand = \"./mole reclaim\"\ninteractive = true\n```\n\nThis keeps TTY passthrough correct for both humans and AI-assisted loops.\n\n## Related Docs\n\n- `commands/ai.md` for command-level semantics and examples\n- `commands/skills.md` for skill sync/reload loop\n- `commands/commit.md` for commit quality/testing gates\n- `use-flow-to-write-software-better.md` for the full operating model\n" }, { "path": "docs/how-to-use-flow-to-deploy.md", "content": "# How to Deploy with Flow\n\nFlow provides a unified `f deploy` command to deploy your projects to Linux hosts, Cloudflare Workers, or Railway.\n\n## Quick Start\n\n```bash\n# Set up your deployment target (one-time)\nf deploy set-host root@your-server.com:22\n\n# Add [host] config to your flow.toml (see below)\n\n# Deploy\nf deploy\n```\n\n## Deployment Targets\n\nFlow auto-detects the deployment target from your `flow.toml`:\n- `[host]` → Linux server via SSH\n- `[cloudflare]` → Cloudflare Workers\n- `[railway]` → Railway\n\n## Linux Host Deployment\n\n### Prerequisites\n\n- SSH access to your server (key-based auth recommended)\n- `rsync` installed locally\n- Server should have: systemd, nginx (optional), certbot (for SSL)\n\n### Configuration\n\n```toml\n[host]\ndest = \"/opt/myapp\" # Where to deploy on server\nsetup = \"\"\"\ncargo build --release\n\"\"\"\nrun = \"/opt/myapp/target/release/server\" # Command to start service\nport = 3000 # Port your app listens on\nservice = \"myapp\" # Systemd service name\nenv_file = \".env.production\" # Local .env to copy to server\ndomain = \"myapp.example.com\" # Public domain (optional)\nssl = true # Enable Let's Encrypt SSL\n```\n\n### Setup Flow\n\n```bash\n# Configure target host (stored in ~/.config/flow/deploy.json)\nf deploy set-host root@your-server.com:22\n\n# Verify connection\nf deploy shell\n```\n\n### Deploy\n\n```bash\n# Full deployment\nf deploy\n\n# Or explicitly\nf deploy host\n\n# Force re-run setup script\nf deploy host --setup\n```\n\n### What Happens\n\n1. **Sync files** via rsync (excludes: target/, .git/, node_modules/)\n2. **Copy .env** from `env_file` to server\n3. **Run setup** script (only on first deploy or with `--setup`)\n4. **Create systemd service** with your `run` command\n5. **Configure nginx** reverse proxy (if `domain` specified)\n6. **Set up SSL** via certbot (if `ssl = true`)\n7. **Start/restart** the service\n\n### Management Commands\n\n```bash\nf deploy status # Check if service is running\nf deploy logs # View recent logs\nf deploy logs -f # Follow logs in real-time\nf deploy restart # Restart the service\nf deploy stop # Stop the service\nf deploy shell # SSH into the server\n```\n\n## Cloudflare Workers\n\n### Prerequisites\n\n- Wrangler CLI: `npm install -g wrangler`\n- Authenticated: `wrangler login`\n\n### Configuration\n\n```toml\n[cloudflare]\npath = \"worker\" # Path to worker directory\nenv_file = \".env.cloudflare\" # Secrets to set\nenv_source = \"cloud\" # Use cloud as env source (optional)\nenv_keys = [\"API_KEY\"] # Keys to fetch from cloud (optional)\nenv_vars = [\"APP_BASE_URL\"] # Keys to set as non-secret vars (optional)\nenvironment = \"staging\" # Optional wrangler environment\ndeploy = \"wrangler deploy\" # Custom deploy command (optional)\ndev = \"wrangler dev\" # Custom dev command (optional)\n```\n\n### Setup (TUI)\n\n```bash\n# Interactive Cloudflare setup (detects wrangler config + env files)\nf deploy setup\n```\n\n### Deploy\n\n```bash\n# Deploy to production\nf deploy cf\n\n# Set secrets and deploy\nf deploy cf --secrets\n\n# Run in dev mode\nf deploy cf --dev\n```\n\n### Secrets\n\nIf you specify `env_file`, flow will set each variable as a Cloudflare secret:\n\n```env\n# .env.cloudflare\nAPI_KEY=secret123\nDATABASE_URL=postgres://...\n```\n\n```bash\nf deploy cf --secrets\n# Sets API_KEY and DATABASE_URL via `wrangler secret put`\n```\n\nIf you set `env_source = \"cloud\"`, flow will fetch env vars from cloud instead of a local file:\n\n```bash\nf env apply\n```\n\nIf `environment` is set, Flow appends `--env <name>` for secrets and deploys.\n\n## Railway\n\n### Prerequisites\n\n- Railway CLI: `npm install -g @railway/cli`\n- Authenticated: `railway login`\n\n### Configuration\n\n```toml\n[railway]\nproject = \"your-project-id\" # Railway project ID\nenvironment = \"production\" # Environment name\nenv_file = \".env.railway\" # Environment variables\n```\n\n### Deploy\n\n```bash\nf deploy railway\n```\n\n## Examples\n\n### Rust Server\n\n```toml\n[host]\ndest = \"/opt/api\"\nsetup = \"\"\"\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y\nsource ~/.cargo/env\ncargo build --release\n\"\"\"\nrun = \"/opt/api/target/release/server\"\nport = 8080\nservice = \"api-server\"\nenv_file = \".env.production\"\ndomain = \"api.example.com\"\nssl = true\n```\n\n### Node.js App\n\n```toml\n[host]\ndest = \"/opt/webapp\"\nsetup = \"\"\"\ncurl -fsSL https://deb.nodesource.com/setup_20.x | bash -\napt-get install -y nodejs\nnpm ci --production\nnpm run build\n\"\"\"\nrun = \"node /opt/webapp/dist/server.js\"\nport = 3000\nservice = \"webapp\"\nenv_file = \".env\"\ndomain = \"app.example.com\"\nssl = true\n```\n\n### Python/FastAPI\n\n```toml\n[host]\ndest = \"/opt/api\"\nsetup = \"\"\"\napt-get install -y python3 python3-pip python3-venv\npython3 -m venv venv\n./venv/bin/pip install -r requirements.txt\n\"\"\"\nrun = \"/opt/api/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000\"\nport = 8000\nservice = \"fastapi\"\nenv_file = \".env\"\n```\n\n### Cloudflare Worker with Hono\n\n```toml\n[cloudflare]\npath = \"worker\"\nenv_file = \".env.cf\"\n```\n\n```bash\n# In worker/ directory, have wrangler.toml:\n# name = \"my-api\"\n# main = \"src/index.ts\"\n\nf deploy cf --secrets\n```\n\n## Tips\n\n### Multiple Environments\n\nUse different env files for staging vs production:\n\n```bash\n# Deploy to staging\nFLOW_ENV=staging f deploy\n\n# Or use different flow.toml sections (coming soon)\n```\n\n### CI/CD Integration\n\n```yaml\n# GitHub Actions\n- name: Deploy\n run: |\n echo \"${{ secrets.DEPLOY_KEY }}\" > ~/.ssh/id_ed25519\n chmod 600 ~/.ssh/id_ed25519\n f deploy set-host ${{ secrets.DEPLOY_HOST }}\n f deploy\n```\n\n### Viewing Deployed Service\n\n```bash\n# Check status\nf deploy status\n\n# View logs\nf deploy logs -n 200\n\n# Follow logs\nf deploy logs -f\n\n# SSH in for debugging\nf deploy shell\n```\n\n### Rollback\n\nCurrently manual - SSH in and use git:\n\n```bash\nf deploy shell\ncd /opt/myapp\ngit checkout HEAD~1\nsystemctl restart myapp\n```\n\n## Troubleshooting\n\n### \"No host configured\"\n\n```bash\nf deploy set-host user@host:port\n```\n\n### \"Permission denied\"\n\nEnsure SSH key is set up:\n```bash\nssh-copy-id user@host\n```\n\n### \"nginx: command not found\"\n\nInstall nginx on the server:\n```bash\nf deploy shell\napt-get install -y nginx\n```\n\n### \"certbot: command not found\"\n\nInstall certbot for SSL:\n```bash\nf deploy shell\napt-get install -y certbot python3-certbot-nginx\n```\n\n### Service won't start\n\nCheck logs:\n```bash\nf deploy logs\nf deploy shell\njournalctl -u myservice -e\n```\n" }, { "path": "docs/how-to-use-flow-to-store-and-work-with-env.md", "content": "# How to Use Flow Env Store (Project + Personal)\n\nThis is the context-optimized workflow for current Flow behavior.\n\n## Important Scope Rule\n\n- `f env set KEY=VALUE` writes to **personal** env scope.\n- `f env project set KEY=VALUE` writes to **project** env scope.\n\nIf you need deploy/runtime envs for a project, use `f env project ...`.\n\n## Backend Choice\n\nFlow supports:\n\n- `cloud` (myflow.sh): shared/team-friendly.\n- `local` (`~/.config/flow/env-local/`): offline/no-account.\n\nCloud behavior:\n- Project env values are sealed client-side before upload and decrypted locally\n on read.\n- Personal cloud values still use the existing server-managed secret store.\n- If a host deploy still relies on `env_source = \"cloud\"` plus a service token,\n Flow keeps a compatibility plaintext mirror for those project keys until the\n host fetch path is upgraded.\n\nSet backend in `~/.config/flow/config.ts`:\n\n```ts\nexport default {\n flow: { env: { backend: \"cloud\" } } // or \"local\"\n}\n```\n\nOr per shell:\n\n```bash\nexport FLOW_ENV_BACKEND=local\n```\n\n## Fast Path (Project Env, Production)\n\n```bash\n# 1) Login once if using cloud\nf env login\n\n# 2) Set project env vars (not personal)\nf env project set DATABASE_URL=postgres://... -e production\nf env project set RESEND_API_KEY=re_... -e production\n\n# 3) Verify (masked)\nf env project list -e production\n\n# 4) Run app with injected project envs\nf env run -e production -- pnpm start\n\n# 5) Optional: write current project envs to local .env\nf env pull -e production\n```\n\n## Personal Tokens (User Scope)\n\nUse for developer-specific tokens (GitHub, CLI auth, etc.):\n\n```bash\nf env set GITHUB_TOKEN=ghp_...\nf env get --personal GITHUB_TOKEN -f value\nf env run --personal -k GITHUB_TOKEN -- gh auth status\n```\n\nDeepgram example (keep value in Flow store, never in docs):\n\n```bash\n# Set once (personal scope)\nf env set --personal DEEPGRAM_API_KEY=<redacted>\n\n# Read when needed\nf env get --personal DEEPGRAM_API_KEY -f value\n```\n\nOn macOS with the `local` backend, personal env values are stored in Keychain by\ndefault and Flow keeps only references under `~/.config/flow/env-local/personal/`.\nUse `FLOW_ENV_LOCAL_PLAINTEXT=1` only as a compatibility escape hatch.\n\n## Environment Names\n\nSupported environments:\n\n- `production` (default)\n- `staging`\n- `dev`\n\nExample:\n\n```bash\nf env project set API_URL=https://staging.example.com -e staging\nf env run -e staging -- pnpm dev\n```\n\n## Guided Flows\n\nUse these when `flow.toml` already declares required keys:\n\n```bash\nf env keys\nf env guide -e production\nf env setup\n```\n\n## Deploy Integration\n\n### Cloudflare Workers\n\nIn `flow.toml`:\n\n```toml\n[cloudflare]\nenv_source = \"cloud\" # or \"local\" for local backend reads\nenv_keys = [\"DATABASE_URL\", \"BETTER_AUTH_SECRET\", \"APP_BASE_URL\"]\nenv_vars = [\"APP_BASE_URL\"] # non-secret vars\nenvironment = \"production\"\n```\n\nApply:\n\n```bash\nf env apply\n```\n\n### Host Deploys\n\nIn `flow.toml`:\n\n```toml\n[host]\nenv_source = \"flow\" # or \"local\"\nenv_keys = [\"DATABASE_URL\", \"RESEND_API_KEY\"]\nenvironment = \"production\"\n```\n\nThen:\n\n```bash\nf deploy\n```\n\n## Local Backend Storage Layout\n\nWhen backend is `local`, Flow uses this layout:\n\n```\n~/.config/flow/env-local/\n├── <project-or-space>/\n│ ├── production.env\n│ ├── staging.env\n│ └── dev.env\n└── personal/\n └── production.env\n```\n\nBehavior:\n- Project-local envs remain private `.env` files on disk.\n- On macOS, personal-local env values are Keychain-backed by default; the file stores Flow-managed references instead of raw secret values.\n- Flow writes local env dirs/files with owner-only permissions.\n\n## Quick Troubleshooting\n\n- \"Not logged in\": run `f env login` (or force local backend).\n- Values not found: check environment (`-e staging` vs `production`).\n- Command injection not working: keep `--` before command.\n - Correct: `f env run -k API_KEY -- node app.js`\n - Wrong: `f env run -k API_KEY node app.js`\n" }, { "path": "docs/ideas.toml", "content": "# f = fuzzy search through commands (builtin and project)\n# f <cmd> = does command\n[[alias]]\nfe = \"f dev\" # dev\nfd = \"f deploy\" # deploy\nfa = \"f ai\" # ai chat\nfc = \"f commit\" # commit\n" }, { "path": "docs/index.mdx", "content": "---\ntitle: Docs\n---\n\n# Flow Docs\n\nHigh-signal docs for the Codex/Claude workflow:\n\n- [`commands/ai.md`](commands/ai.md): exact Claude/Codex session behavior (`resume`, TTY requirements, strict-ID semantics).\n- [`commands/skills.md`](commands/skills.md): `f skills sync`, `f skills reload`, and Codex skill metadata behavior.\n- [`commands/commit.md`](commands/commit.md): commit-time testing + skill-gate enforcement.\n- [`commands/invariants.md`](commands/invariants.md): invariant policy checks (`f invariants`) and commit-time enforcement behavior.\n- [`commands/fast.md`](commands/fast.md): low-latency AI task dispatch (`f fast`) via fast daemon client path.\n- [`commands/seq-rpc.md`](commands/seq-rpc.md): native `seqd` RPC bridge (`f seq-rpc`) for OS-level agent actions.\n- [`ci-cd-runbook.md`](ci-cd-runbook.md): CI/CD architecture, runner-mode operations, and failure debug checklist for canary/release pipelines.\n- [`install-script-latest-release-verification.md`](install-script-latest-release-verification.md): exact runbook for proving `curl -fsSL https://myflow.sh/install.sh | sh` installs the current latest stable release.\n- [`rise.md`](rise.md): full integration guide for installing and operating Rise via Flow (`f install rise`) across adopt/sync/dev/mobile/schema/sandbox workflows.\n- [`commands/domains.md`](commands/domains.md): shared local `*.localhost` proxy ownership via `f domains` (prevents per-repo port-80 collisions).\n- [`commands/clone.md`](commands/clone.md): git-like cloning (`f clone`) with GitHub URL/shorthand normalization to SSH, without forcing `~/repos`.\n- [`commands/up.md`](commands/up.md): one-command project startup (`f up`) with optional lifecycle domain setup.\n- [`commands/down.md`](commands/down.md): one-command project shutdown (`f down`) with lifecycle teardown rules.\n- [`commands/reviews-todo.md`](commands/reviews-todo.md): fast-commit + deferred Codex deep-review backlog workflow.\n- [`fast-commit-deep-review-loop.md`](fast-commit-deep-review-loop.md): recommended speed-first workflow for `~/code/myflow` (GLM/Cerebras fast lane + batched Codex deep reviews).\n- [`how-to-use-flow-ai-to-manage-claude-code-sessions.md`](how-to-use-flow-ai-to-manage-claude-code-sessions.md): practical session workflow for Claude + Codex in one repo loop.\n- [`codex-first-control-plane-roadmap.md`](codex-first-control-plane-roadmap.md): concrete plan for making Flow the Codex-first control plane with warm app-server daemon, intent aliases, reference unrollers, and runtime skills.\n- [`codex-openai-session-resolver.md`](codex-openai-session-resolver.md): app-server-backed `L <query>` resolver for repo-scoped Codex session resume in `~/repos/openai/codex`.\n- [`codex-fork-tasks.md`](codex-fork-tasks.md): personal Codex fork automation tasks for `nikiv` sync, scoped worktree/session start, last-session reattach, and review-branch promotion.\n- [`session-history-mining.md`](session-history-mining.md): efficient cross-project session mining (`f sessions`) and prompt scaffolds for token-sensitive planning.\n- [`session-semantic-recovery-with-seq.md`](session-semantic-recovery-with-seq.md): recover lost Claude/Codex work after resets using Seq's zvec-backed semantic session search plus `f ai ... resume`.\n- [`env-security-roadmap.md`](env-security-roadmap.md): hardening plan for Flow env storage, local keychain-backed secrets, and future end-to-end encrypted sharing.\n- [`how-to-make-a-project-flow-project.md`](how-to-make-a-project-flow-project.md): detailed onboarding and migration playbook for turning any repo into a Flow-native project.\n- [`use-flow-to-write-software-better.md`](use-flow-to-write-software-better.md): full end-to-end operating model for building software with Flow + Claude/Codex.\n- [`usage-analytics-rollout.md`](usage-analytics-rollout.md): exact patch order for opt-in anonymous usage tracking.\n- [`flow-toml-spec.md`](flow-toml-spec.md): complete config schema including `[skills.codex]`, `[commit.testing]`, and `[commit.skill_gate]`.\n- [`local-domains-no-random-ports.md`](local-domains-no-random-ports.md): stable `*.localhost` local domains via a lightweight proxy, plus `flow.toml` task wiring.\n- [`local-domains-domainsd-cpp-spec.md`](local-domains-domainsd-cpp-spec.md): native C++ `domainsd` architecture, rollout, and reliability constraints for low-latency localhost routing.\n- [`myflow-localhost-runbook.md`](myflow-localhost-runbook.md): exact commands to run `~/code/myflow` on `myflow.localhost` and use in-app `/processes` and `/logs` views.\n- [`seq-agent-rpc-contract.md`](seq-agent-rpc-contract.md): hard interface contract for agent OS actions through `seq_client -> seqd` RPC v1.\n- [`everruns-seq-bridge-integration.md`](everruns-seq-bridge-integration.md): why/how `f ai everruns` now reuses Seq's shared Everruns bridge to avoid duplicate tool mapping logic.\n- [`everruns-maple-runbook.md`](everruns-maple-runbook.md): exact commands to enable Everruns -> Maple dual-ingest and verify spans in local + hosted Maple.\n- [`ascii-commit-visualization-pipeline.md`](ascii-commit-visualization-pipeline.md): end-to-end pipeline for commit analysis -> Flow API -> `box-of-rain` ASCII/SVG diagrams in myflow.\n- [`features.md`](features.md): practical command flows and examples.\n- [`moonbit-ai-tasks-implementation.md`](moonbit-ai-tasks-implementation.md): complete inventory of the task-centric MoonBit AI task runtime and Flow-local `.ai/tasks` pack.\n- [`ai-task-fast-path-guide.md`](ai-task-fast-path-guide.md): end-to-end setup and tuning guide for lowest-latency AI task execution (`ai-taskd` + `fai`).\n- [`moonbit-rust-boundary-refactor-plan.md`](moonbit-rust-boundary-refactor-plan.md): deep scan findings, benchmark gates, and zero-cost MoonBit <> Rust boundary roadmap.\n- [`bench/moonbit-rust-ffi-boundary.md`](bench/moonbit-rust-ffi-boundary.md): authoritative microbenchmark for MoonBit <-> Rust FFI overhead, plus tuning guidance.\n- [`rl-for-myflow-harbor.md`](rl-for-myflow-harbor.md): practical RL roadmap for turning myflow -> Harbor exports into a gated training/improvement loop.\n- [`rl-myflow-harbor-task-specs.md`](rl-myflow-harbor-task-specs.md): executable task contracts for validate/reward/canary/hardcase stages.\n- [`private-fork-flow.md`](private-fork-flow.md): generic AI runbook for private-fork setup and safe push routing via Flow `[git].remote`.\n- [`private-repo-fast.md`](private-repo-fast.md): fastest way to create a private GitHub repo from the current folder, including non-`~/repos` paths like `~/code/flow-extension` and separate `private` mirror remotes for existing public repos.\n- [`commands/jj.md`](commands/jj.md): Flow wrapper for `jj` workflows (`sync`, bookmarks, and workspace/lane management).\n- [`jj-workspaces-for-parallel-work.md`](jj-workspaces-for-parallel-work.md): practical parallel-branch workflow with isolated workspace lanes.\n- [`jj-review-workspaces.md`](jj-review-workspaces.md): stable JJ-native review workspaces for branch-specific inspection and edits without touching the current checkout.\n- [`jj-home-branch-workflow.md`](jj-home-branch-workflow.md): status-first workflow for a long-lived home branch with stacked review or codex branches in isolated JJ workspaces.\n- [`moving-repos.md`](moving-repos.md): how Flow manages repo locations, `f migrate` for moving projects with AI session continuity, and the `~/code` / `~/repos` / `~/run` layout.\n- [`run-repos.md`](run-repos.md): shortcuts and resolution rules for running tasks in `~/run` and `~/run/i` from anywhere.\n- [`ai-run-task-fast-path.md`](ai-run-task-fast-path.md): minimal prompt/response contract for AI to add public or internal run tasks quickly and return ready-to-run `f ...` commands.\n- [`dependency-vendoring.md`](dependency-vendoring.md): inhouse dependency workflow, offender ranking, and fast upstream sync loop for vendored crates.\n- [`vendor-code-intelligence.md`](vendor-code-intelligence.md): opensrc-style local code indexing/search for vendored crates + first-party code via Typesense.\n- [`vendor-nix-inspiration.md`](vendor-nix-inspiration.md): how Flow vendoring borrows Nix ideas (pinning, reproducibility, provenance, rollback) while staying Cargo-first.\n- [`vendor-optimization-loop.md`](vendor-optimization-loop.md): rough-edge audit + offender ranking + iteration benchmarks for dependency optimization.\n" }, { "path": "docs/install-script-latest-release-verification.md", "content": "# Verify `curl -fsSL https://myflow.sh/install.sh | sh` Installs the Latest Flow Release\n\nUse this runbook whenever you need to prove that the public installer is actually pulling the current latest stable Flow release.\n\nThe fastest repo-local check is now:\n\n```sh\n./scripts/verify-install-latest-release.sh\n```\n\nOr through Flow:\n\n```sh\nf verify-install-latest-release\n```\n\nThis is the check that matters for users:\n\n```sh\ncurl -fsSL https://myflow.sh/install.sh | sh\n```\n\n## What This Must Prove\n\nAfter a stable release, these values must all agree:\n\n- `Cargo.toml` package version\n- pushed release tag `vX.Y.Z`\n- GitHub `releases/latest` tag\n- version reported by a fresh temp-home install of `~/.flow/bin/f`\n\nIf any one of those differs, the public install story is broken.\n\n## One-Command Verification\n\nThe script performs all of these checks:\n\n1. validate expected tag vs `Cargo.toml` via `scripts/check_release_tag_version.py`\n2. poll GitHub `releases/latest` until it matches the expected tag\n3. run the real public installer in a fresh temp `HOME`\n4. verify the installed binary version\n5. download the direct release asset for the current platform and verify that too\n\nDefault usage:\n\n```sh\n./scripts/verify-install-latest-release.sh\n```\n\nUseful options:\n\n```sh\n./scripts/verify-install-latest-release.sh --latest-timeout 300\n./scripts/verify-install-latest-release.sh --tag v0.1.3\n./scripts/verify-install-latest-release.sh --skip-asset\n./scripts/verify-install-latest-release.sh --keep-temp\n```\n\n## When To Run This\n\nRun this after:\n\n- cutting a new stable release tag\n- changing `install.sh`\n- changing release packaging\n- changing versioning logic\n- fixing a release mismatch bug\n\n## Fast Pass Criteria\n\nThe installer is correct only if all of these are true:\n\n1. the release tag matches `Cargo.toml`\n2. GitHub marks that tag as latest stable\n3. a fresh temp-home install gets that same version\n4. a direct release asset download reports that same version\n\n## Manual Debug Procedure\n\nIf the one-command script fails, use the manual steps below to see exactly where the mismatch is.\n\n### Step 1: Confirm the Expected Version Locally\n\nRead the package version from the repo:\n\n```sh\npython3 - <<'PY'\nimport pathlib, re\ntext = pathlib.Path(\"Cargo.toml\").read_text(encoding=\"utf-8\")\nmatch = re.search(r'^version\\s*=\\s*\"([^\"]+)\"', text, re.MULTILINE)\nif not match:\n raise SystemExit(\"failed to read Cargo.toml version\")\nprint(match.group(1))\nPY\n```\n\nIf you already know the expected tag, validate it directly:\n\n```sh\npython3 scripts/check_release_tag_version.py v0.1.3\n```\n\nThat script should fail hard on mismatches.\n\n### Step 2: Confirm GitHub Latest Stable\n\nCheck the public API that the installer uses:\n\n```sh\ncurl -fsSL https://api.github.com/repos/nikivdev/flow/releases/latest \\\n | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"tag_name\"])'\n```\n\nThis should print the expected stable tag, for example:\n\n```text\nv0.1.3\n```\n\nOptional cross-checks:\n\n```sh\ngh release list --limit 5\ngh release view v0.1.3 --json tagName,publishedAt,isDraft,isPrerelease,url\n```\n\n### Step 3: Run the Real Public Installer in a Fresh Temp HOME\n\nThis is the main test. Use a fresh `HOME` and a minimal `PATH` so an existing install cannot leak in.\n\n```sh\ntmp_home=\"$(mktemp -d)\"\necho \"$tmp_home\"\n\nHOME=\"$tmp_home\" PATH=\"/usr/bin:/bin:/usr/sbin:/sbin\" sh -c \\\n 'curl -fsSL https://myflow.sh/install.sh | sh'\n\nHOME=\"$tmp_home\" \"$tmp_home/.flow/bin/f\" --version\n```\n\nExpected result:\n\n- install succeeds\n- `~/.flow/bin/f` exists under the temp home\n- `f --version` reports the latest stable version\n\nExample expected output:\n\n```text\nflow 0.1.3\n```\n\n### Step 4: Compare Installed Version to Latest Tag\n\nUse this one-shot comparison:\n\n```sh\nlatest_tag=\"$(curl -fsSL https://api.github.com/repos/nikivdev/flow/releases/latest \\\n | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"tag_name\"])')\"\n\ntmp_home=\"$(mktemp -d)\"\nHOME=\"$tmp_home\" PATH=\"/usr/bin:/bin:/usr/sbin:/sbin\" sh -c \\\n 'curl -fsSL https://myflow.sh/install.sh | sh >/dev/null'\n\ninstalled_version=\"$(HOME=\"$tmp_home\" \"$tmp_home/.flow/bin/f\" --version \\\n | python3 -c 'import sys,re; m=re.search(r\"flow ([0-9][^ ]*)\", sys.stdin.read()); print(m.group(1) if m else \"\")')\"\n\necho \"latest_tag=$latest_tag\"\necho \"installed_version=$installed_version\"\n\ntest \"v$installed_version\" = \"$latest_tag\"\n```\n\nIf that final `test` fails, the installer path is not trustworthy.\n\n### Step 5: Isolate Installer Bug vs Release Artifact Bug\n\nIf the fresh install reports the wrong version, download the release asset directly.\n\nChoose the target for your machine:\n\n- macOS Apple Silicon: `aarch64-apple-darwin`\n- macOS Intel: `x86_64-apple-darwin`\n- Linux x64: `x86_64-unknown-linux-gnu`\n- Linux arm64: `aarch64-unknown-linux-gnu`\n\nExample for macOS Apple Silicon:\n\n```sh\nlatest_tag=\"$(curl -fsSL https://api.github.com/repos/nikivdev/flow/releases/latest \\\n | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"tag_name\"])')\"\n\ntmp_dir=\"$(mktemp -d)\"\ncd \"$tmp_dir\"\n\ncurl -fsSLO \\\n \"https://github.com/nikivdev/flow/releases/download/${latest_tag}/flow-aarch64-apple-darwin.tar.gz\"\n\ntar -xzf flow-aarch64-apple-darwin.tar.gz\n./f --version\n```\n\nInterpretation:\n\n- direct asset wrong too: release artifact/versioning bug\n- direct asset correct but installer wrong: installer selection logic bug\n- API still shows old tag: release publication/propagation is not complete yet\n\n## Common Failure Modes\n\n### 1. Release tag does not match Cargo version\n\nSymptom:\n\n- `python3 scripts/check_release_tag_version.py vX.Y.Z` fails\n\nMeaning:\n\n- the release was tagged from the wrong crate version\n\nFix:\n\n- bump `Cargo.toml`\n- refresh generated artifacts if needed\n- cut a new release tag\n\n### 2. GitHub `releases/latest` still returns the old tag\n\nSymptom:\n\n- release workflow is green\n- release page shows the new version\n- `releases/latest` still returns the old tag for a short time\n\nMeaning:\n\n- GitHub publication or cache propagation delay\n\nFix:\n\n- wait and retry until `releases/latest` flips\n- do not declare success until the API itself returns the new tag\n\n### 3. Installer reports old version but latest tag is correct\n\nSymptom:\n\n- `releases/latest` returns the new tag\n- temp-home install still reports an older version\n\nMeaning:\n\n- likely wrong binary inside the published release asset\n\nFix:\n\n- test the direct asset\n- if direct asset is also wrong, cut a corrected release\n\n### 4. Temp-home test passes locally but users still get old `f`\n\nSymptom:\n\n- your test is clean\n- user machine still reports an older version by plain `f --version`\n\nMeaning:\n\n- user shell is resolving another binary earlier on `PATH`\n\nFix:\n\n- ask them to run:\n\n```sh\nwhich -a f\n~/.flow/bin/f --version\n```\n\n## Recommended Release Checklist\n\nAfter publishing a stable tag:\n\n1. run `python3 scripts/check_release_tag_version.py vX.Y.Z`\n2. wait for the Release workflow to complete\n3. verify `releases/latest` returns `vX.Y.Z`\n4. run `./scripts/verify-install-latest-release.sh`\n5. if there is any mismatch, test the direct asset before debugging the installer\n\nDo not mark the release done until step 4 is green.\n" }, { "path": "docs/jj-home-branch-workflow.md", "content": "# JJ Home-Branch Workflow\n\nThis workflow is for teams or individuals who keep one long-lived personal branch on top of trunk,\nthen stack short-lived task branches on top of that branch.\n\nFlow supports that model directly through:\n\n- `f status` for a workflow-aware status view\n- `jj.home_branch` in `flow.toml`\n- `f jj workspace review <branch>` for isolated branch-specific working copies\n\n## Mental model\n\nUse three layers:\n\n1. trunk: `main`\n2. home branch: your long-lived integration branch\n3. leaf branches: `review/*`, `codex/*`, or other task branches that sit on top of the home branch\n\nThe default checkout usually stays on the home branch. Branch-specific work happens in isolated\nJJ workspaces.\n\n## Config\n\n```toml\n[jj]\ndefault_branch = \"main\"\nhome_branch = \"alice\"\n```\n\n## Status as the preflight\n\nBefore switching branches, creating workspaces, committing, or publishing, run:\n\n```bash\nf status\n```\n\nThis should tell you:\n\n- current workspace and path\n- current branch and its role\n- configured home branch\n- whether you are on the home branch or a leaf branch\n- which `review/*` and `codex/*` branches currently sit on top of the home branch\n- whether the working copy is clean enough to mutate safely\n\nUse raw `f jj status` only when you need the underlying Jujutsu status output.\n\n## Default operating pattern\n\nKeep the main checkout on the home branch:\n\n```bash\ncd ~/code/org/project\nf status\n```\n\nCreate or reuse an isolated workspace for branch-specific work:\n\n```bash\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/project/review-alice-feature\nf status\n```\n\nInside the workspace, use `jj` or `f jj`.\n\n## Why this is safer\n\n- The main checkout stays stable.\n- Branch-specific edits do not mix with unrelated home-branch changes.\n- A second Codex or Claude session can work in the review workspace without disturbing the main\n checkout.\n- `f status` provides one consistent summary instead of forcing the user or agent to infer state\n from several lower-level commands.\n\n## Publish boundary\n\nThe important distinction is not just the branch name. It is also where the work lives:\n\n- Git branch checkout\n- JJ review workspace\n\nBe explicit about the publish path. Do not assume a colocated Git checkout and a JJ workspace are\ninterchangeable.\n\n## Recommended rule set\n\n- default checkout: home branch\n- task work: review workspace\n- preflight before mutation: `f status`\n- inspect raw JJ details only when needed: `f jj status`\n\nThat keeps the workflow legible to both humans and coding agents.\n" }, { "path": "docs/jj-review-workspaces.md", "content": "# JJ Review Workspaces\n\nWhen you need an isolated working copy for a review branch, use a **JJ review workspace** instead\nof switching your current checkout or creating an ad hoc temporary worktree.\n\nThis is the safest way to inspect, edit, and validate a review branch while leaving your current\nrepo state untouched.\n\n## Command\n\n```bash\ncd ~/code/org/project\nf status\nf jj workspace review review/alice-feature\n```\n\nThis creates or reuses a stable workspace at:\n\n```bash\n~/.jj/workspaces/project/review-alice-feature\n```\n\nThen work there:\n\n```bash\ncd ~/.jj/workspaces/project/review-alice-feature\nf status\n```\n\n## Why Use This\n\n- Your current checkout stays exactly as it is.\n- The workspace path is stable and reusable.\n- Another Codex or Claude session can work inside the review workspace safely.\n- You avoid mixing “temporary scratch path” decisions into your review flow.\n- `f status` makes the home-branch versus review-workspace role explicit before you mutate anything.\n\n## How It Resolves The Base\n\n`f jj workspace review <branch>` chooses the workspace base in this order:\n\n1. `--base <rev>` if you passed one\n2. the local Git branch commit for `<branch>`\n3. the remote Git branch commit for `<remote>/<branch>`\n4. trunk (`<default_branch>` or `<default_branch>@<remote>`)\n\nThat makes the command useful both before and after the review branch exists locally.\n\n## Reuse Behavior\n\nIf the review workspace already exists, Flow reuses it instead of creating another copy.\n\nThat means this is safe to run repeatedly:\n\n```bash\nf jj workspace review review/alice-feature\n```\n\nYou get one stable place for that branch, not a pile of temporary directories.\n\n## Important Caveat In Colocated Repos\n\nUse `jj` or `f jj` inside the review workspace.\n\nIn a colocated repo, plain `git` still points at the main Git checkout, not the JJ workspace's\nworking-copy commit. Because of that, `f jj workspace review` intentionally does **not** try to run\nbranch-switching logic for you.\n\nRecommended rule:\n\n- inside the review workspace: use `jj` / `f jj`\n- in the main checkout: use your normal Git or Flow branch-switch flow\n\n## Example Workflow\n\n```bash\n# Create or reuse the review workspace\nf jj workspace review review/alice-feature\n\n# Move into it\ncd ~/.jj/workspaces/project/review-alice-feature\n\n# Inspect state\njj st\njj log -r @\n\n# Make edits and commit as usual\njj describe -m \"Adjust runtime startup behavior\"\njj new\n```\n\nIf you want a tracked bookmark for publishing later:\n\n```bash\nf jj bookmark create review/alice-feature --rev @ --track --remote origin\n```\n\n## Cleanup\n\nWhen you no longer need the workspace:\n\n```bash\njj workspace list\njj workspace forget review-alice-feature\nrm -rf ~/.jj/workspaces/project/review-alice-feature\n```\n\n## When To Use This vs `lane`\n\nUse `f jj workspace lane <name>` when you want a new parallel line of work anchored from trunk.\n\nUse `f jj workspace review <branch>` when the workspace should correspond to a specific review\nbranch and keep a stable branch-derived path.\n" }, { "path": "docs/jj-workspaces-for-parallel-work.md", "content": "# JJ Workspaces: Work on Multiple Branches Simultaneously\n\nWhen you need to reference or work with code from another branch without disrupting your current work, use **jj workspaces**. This creates a second working copy of the same repo at a different path, pointed at a different revision.\n\n## The Problem\n\nYou're on `feature-a` actively coding. You need to send another Claude session a prompt like \"study the tracing code on `pr/main-fdb3446`\" — but you can't check out that branch without losing your current working state.\n\n## Solution: `jj workspace add`\n\n```bash\ncd ~/code/org/project\njj workspace add ../project-traces -r pr/main-fdb3446\n```\n\nFlow wrapper (recommended):\n\n```bash\ncd ~/code/org/project\nf jj workspace lane traces --base pr/main-fdb3446 --path ../project-traces\n```\n\nNow you have two working copies sharing the same repo:\n\n| Path | Branch | Use |\n|------|--------|-----|\n| `~/code/org/project` | `feature-a` | Your active work (untouched) |\n| `~/code/org/project-traces` | `pr/main-fdb3446` | Full checkout for reference |\n\nPoint any tool or Claude session at the second path — it has all files on disk, no risk to your branch.\n\n## Common Workflows\n\n### Reference code from another branch\n\n```bash\n# Create workspace\njj workspace add ../project-ref -r some-branch\n\n# Now another Claude session can freely explore:\n# \"study ~/code/org/project-ref — it has the tracing code\"\n\n# Clean up when done\njj workspace forget project-ref && rm -rf ../project-ref\n```\n\n### Cherry-pick files across branches\n\n```bash\n# No workspace needed — jj reads any revision directly:\njj file show src/lib/tracing.ts -r pr/main-fdb3446\njj diff --from main --to pr/main-fdb3446 --stat\n```\n\n### Work on two PRs at once\n\n```bash\nf jj workspace lane pr2 --base pr/feature-b --path ../project-pr2\n# Edit files in both directories independently\n# Both share the same jj repo — commits are visible everywhere\n```\n\n### Reuse one stable workspace for a review branch\n\n```bash\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/project/review-alice-feature\n```\n\nUse this when you want one predictable workspace path for a specific review branch instead of a\ngeneral-purpose lane.\n\n### Default isolated lanes from trunk\n\n```bash\nf jj workspace lane fix-otp\nf jj workspace lane release-testflight\n```\n\nBy default this fetches and anchors each lane on `<default_branch>@<remote>` (or `<default_branch>` if the remote bookmark is missing).\n\n## How It Works\n\n- Both workspaces share the same `.jj/` repo backend (no git clone, no duplication)\n- Each workspace has its own working copy commit (`@`)\n- Changes committed in one workspace are immediately visible in the other via `jj log`\n- The original workspace is completely unaffected\n\n## Cleanup\n\n```bash\n# List workspaces\njj workspace list\n\n# Remove a workspace (keeps the commits, removes the directory association)\njj workspace forget <name>\nrm -rf ../project-ref\n```\n\n## When to Use What\n\n| Need | Tool |\n|------|------|\n| Full directory for another tool/session to explore | `jj workspace add` |\n| Stable branch-specific review workspace | `f jj workspace review <branch>` |\n| Read a specific file from another branch | `jj file show <path> -r <rev>` |\n| See what changed on another branch | `jj diff --from main --to <branch>` |\n| Compare two branches | `jj log -r 'branchA..branchB'` |\n" }, { "path": "docs/local-domains-domainsd-cpp-spec.md", "content": "# Local Domains Native Daemon (C++) Spec\n\nThis document defines the native local-domains path for Flow.\n\nGoal:\n- keep stable `*.localhost` names,\n- remove docker/nginx runtime dependency,\n- provide low-overhead local routing suitable for agent-heavy workflows.\n\n## Scope\n\nThis is an incremental migration path.\n\nPhase 1 (implemented now):\n- opt-in engine: `f domains --engine native ...`\n- experimental C++ daemon (`domainsd-cpp`) built by Flow with `clang++`\n- host-based HTTP/1.1 routing from `~/.config/flow/local-domains/routes.json`\n- WebSocket upgrade passthrough\n- request-side chunked transfer-encoding decode\n- upstream keepalive connection pooling for safe HTTP/1.1 reuse\n- bounded active handler slots with overload shedding (`503`)\n- upstream connect/read/write timeouts (`504` for upstream connect timeout)\n- health endpoint: `/_flow/domains/health`\n- macOS launchd socket-activation installer for native privileged `:80` bind without Docker\n\nPhase 2:\n- better connection pooling and backpressure controls\n- optional HTTP/2/TLS frontend mode\n\nPhase 3:\n- optional HTTPS + HTTP/2\n- structured trace export for agent context\n\n## Non-goals (for current phase)\n\n- system DNS changes\n- packet filter / firewall manipulation\n- replacing `.localhost` conventions\n\n## Control plane\n\nFlow CLI remains the control plane:\n\n```bash\nf domains list\nf domains add app.localhost 127.0.0.1:3000\nf domains rm app.localhost\nf domains --engine native up\nf domains --engine native down\nf domains --engine native doctor\n```\n\nEngine selection:\n- CLI flag: `--engine docker|native`\n- env fallback: `FLOW_DOMAINS_ENGINE=native`\n- default: `docker`\n\n## State\n\nCurrent state remains:\n- routes: `~/.config/flow/local-domains/routes.json`\n\nNative runtime artifacts:\n- pid: `~/.config/flow/local-domains/domainsd.pid`\n- log: `~/.config/flow/local-domains/domainsd.log`\n- built daemon binary: `~/.config/flow/local-domains/domainsd-cpp`\n- macOS launchd plist (optional): `/Library/LaunchDaemons/dev.flow.domainsd.plist`\n\nNative tuning env vars (read by `f domains --engine native up` and passed to daemon):\n- `FLOW_DOMAINS_NATIVE_MAX_ACTIVE_CLIENTS` (default `128`)\n- `FLOW_DOMAINS_NATIVE_UPSTREAM_CONNECT_TIMEOUT_MS` (default `10000`)\n- `FLOW_DOMAINS_NATIVE_UPSTREAM_IO_TIMEOUT_MS` (default `15000`)\n- `FLOW_DOMAINS_NATIVE_CLIENT_IO_TIMEOUT_MS` (default `30000`)\n- `FLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_PER_KEY` (default `8`)\n- `FLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_TOTAL` (default `256`)\n- `FLOW_DOMAINS_NATIVE_POOL_IDLE_TIMEOUT_MS` (default `15000`)\n- `FLOW_DOMAINS_NATIVE_POOL_MAX_AGE_MS` (default `120000`)\n\n## Native daemon protocol (current)\n\nListen address:\n- `127.0.0.1:80`\n\nmacOS launchd mode:\n- daemon can be started with `--launchd-socket domainsd` (socket inherited from launchd)\n- launchd owns privileged bind; daemon runs as local user\n\nRouting:\n- Read `Host` header (strip `:port`)\n- Lookup `host -> target` from `routes.json`\n- Forward request to target (`host:port`)\n\nSpecial endpoint:\n- `GET /_flow/domains/health`\n- returns header `X-Flow-Domainsd: 1`\n\nErrors:\n- `404` when host route is not configured\n- `502` on upstream connection/forward failures\n- `503` when proxy is saturated and sheds overload\n- `504` on upstream connect timeout\n- `400` for malformed HTTP requests\n\n## Reliability guardrails\n\n- Keep Docker engine as default during hardening.\n- Native engine is explicit opt-in.\n- `f domains doctor` should always show effective owner on port 80.\n- Any startup failure must surface log path directly.\n\n## Performance targets\n\n- added local proxy latency p99 < 1ms for tiny responses\n- idle CPU near zero\n- route update visibility < 100ms (mtime-based reload)\n\n## Validation checklist\n\n```bash\nf domains add myflow.localhost 127.0.0.1:3000\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh # macOS when direct bind is denied\nf domains --engine native up\nf domains --engine native doctor\ncurl -H 'Host: myflow.localhost' http://127.0.0.1/\nsudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh # optional teardown\n```\n\n## Next implementation work\n\n1. Add per-upstream timeouts (connect, first-byte, total) with explicit 502/504 mapping.\n2. Add end-to-end trace summary output for agents (route misses, upstream failures, latency buckets).\n3. Add launchd install/uninstall tasks for persistent local startup.\n4. Add optional HTTPS + HTTP/2 frontend mode.\n" }, { "path": "docs/local-domains-no-random-ports.md", "content": "# Local Domains, No Random Ports\n\nThis pattern gives stable local URLs like `http://gen.localhost` and `http://linsa.localhost` instead of remembering random ports.\n\nUse shared ownership via `f domains` (see `docs/commands/domains.md`) so only one proxy binds port `80` across all repos.\n\nIt is fast and lightweight:\n- One shared local reverse proxy container (nginx).\n- No system-wide DNS daemon required.\n- No VPN or packet filter changes.\n\nExperimental native path:\n- `f domains --engine native up` runs a local C++ daemon instead of docker/nginx.\n- Keep this opt-in for now; docker remains the default engine.\n\n## Why `.localhost`\n\nUse `*.localhost` hostnames. They resolve to loopback by design, so traffic stays on your machine.\n\nThat means:\n- `gen.localhost` can map to `127.0.0.1:5001`.\n- `linsa.localhost` can map to `127.0.0.1:3481`.\n- `api.myflow.localhost` can map to `127.0.0.1:8780`.\n\n## Recommended Pattern: Shared `f domains`\n\nRegister routes once, then run your normal dev servers on fixed ports.\n\n```bash\nf domains add gen.localhost 127.0.0.1:5001\nf domains add linsa.localhost 127.0.0.1:3481\nf domains add myflow.localhost 127.0.0.1:3000\nf domains add api.myflow.localhost 127.0.0.1:8780\n\nf domains up\nf domains list\n```\n\n`f domains up` ensures the shared proxy is running. `f domains list` shows the active route table.\n\nNative engine (experimental):\n\n```bash\nf domains --engine native up\nf domains --engine native doctor\nf domains --engine native down\n```\n\nOn macOS, if native bind to `:80` is denied, install launchd socket mode once:\n\n```bash\ncd ~/code/flow\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\nYou can also set:\n\n```bash\nexport FLOW_DOMAINS_ENGINE=native\n```\n\n## Flow Task Pattern (`flow.toml`)\n\nUse these task shapes in each repo:\n\n```toml\n[[tasks]]\nname = \"domains-up\"\ncommand = \"\"\"\nset -euo pipefail\n\nf domains add <repo>.localhost 127.0.0.1:<port>\nf domains up\n\"\"\"\n\n[[tasks]]\nname = \"domains-down\"\ncommand = \"sh -lc 'f domains rm <repo>.localhost || true'\"\n\n[[tasks]]\nname = \"domains-status\"\ncommand = \"f domains doctor && f domains list\"\n```\n\nExample mappings used together safely:\n\n```bash\ngen.localhost -> 127.0.0.1:5001\nlinsa.localhost -> 127.0.0.1:3481\nmyflow.localhost -> 127.0.0.1:3000\napi.myflow.localhost -> 127.0.0.1:8780\n```\n\n## Reliability Notes\n\n- Keep app ports fixed (`5001`, `3481`, `3000`, `8780`) and route hostnames to them.\n- Do not run per-repo proxy stacks in parallel with `f domains`; use one shared proxy owner.\n- Check health with:\n\n```bash\nf domains doctor\n```\n\n## Troubleshooting\n\n- `ERR_CONNECTION_REFUSED` on `*.localhost`: run `f domains up`, then `f domains doctor`.\n- Wrong project opens on a hostname: route collision or stale mapping. Check `f domains list`, then `f domains rm <host>` and re-add.\n- Port `80` bind failure: another process owns port `80`. Find it with:\n\n```bash\nlsof -nP -iTCP:80 -sTCP:LISTEN\n```\n\n## Logs in myflow\n\nIf you use `myflow` as your local operations UI, open:\n\n- `http://myflow.localhost/processes` for process status and per-process log streams.\n- `http://myflow.localhost/logs` for focused live logs.\n\nRun `f lin` first so the Flow daemon is online for these pages.\n\nFor the full end-to-end setup (`f domains --engine native`, `f dev`, health checks, and troubleshooting), see:\n`docs/myflow-localhost-runbook.md`.\n\n## Legacy Pattern (Not Recommended)\n\nPer-repo docker-compose proxies also work, but they are easier to conflict on port `80` and cause hostname drift across repos. Prefer shared `f domains` unless you have a strict repo-isolated requirement.\n\n## Result\n\nYou keep internal service ports explicit in config, but humans use stable names:\n- `http://gen.localhost`\n- `http://linsa.localhost`\n- `http://myflow.localhost`\n" }, { "path": "docs/log-ingesting.md", "content": "# Log Ingestion\n\nFlow includes a log ingestion system for collecting and querying structured logs from your projects. Logs are stored in SQLite for later analysis.\n\n## Starting the Server\n\n```bash\nf server\n```\n\nThis starts the HTTP server on `127.0.0.1:9060` (default). Options:\n\n- `--host <IP>` - Bind address (default: 127.0.0.1)\n- `--port <PORT>` - Port number (default: 9060)\n\n## Endpoints\n\n### Health Check\n\n```\nGET /health\n```\n\nReturns `{\"status\": \"ok\"}` when the server is running.\n\n### Ingest Logs\n\n```\nPOST /logs/ingest\nContent-Type: application/json\n```\n\n**Single log:**\n\n```json\n{\n \"project\": \"my-app\",\n \"content\": \"TypeError: Cannot read property 'x' of undefined\",\n \"timestamp\": 1733150000000,\n \"type\": \"error\",\n \"service\": \"api\",\n \"stack\": \"at handler (api.ts:42)\\nat processRequest (server.ts:100)\",\n \"format\": \"text\"\n}\n```\n\n**Batch:**\n\n```json\n[\n {\n \"project\": \"my-app\",\n \"content\": \"Request received\",\n \"timestamp\": 1733150000000,\n \"type\": \"log\",\n \"service\": \"api\",\n \"format\": \"text\"\n },\n {\n \"project\": \"my-app\",\n \"content\": \"Database query\",\n \"timestamp\": 1733150001000,\n \"type\": \"log\",\n \"service\": \"db\",\n \"format\": \"text\"\n }\n]\n```\n\n**Response:**\n\n```json\n{ \"inserted\": 1, \"ids\": [42] }\n```\n\n### Query Logs\n\n```\nGET /logs/query\n```\n\n**Query parameters:**\n\n| Parameter | Description |\n| --------- | -------------------------------------- |\n| `project` | Filter by project name |\n| `service` | Filter by service |\n| `type` | Filter by log type (`log` or `error`) |\n| `since` | Timestamp (ms) - logs after this time |\n| `until` | Timestamp (ms) - logs before this time |\n| `limit` | Max results (default: 100) |\n| `offset` | Skip N results for pagination |\n\n**Examples:**\n\n```bash\n# All logs\ncurl \"http://127.0.0.1:9060/logs/query\"\n\n# Errors for a project\ncurl \"http://127.0.0.1:9060/logs/query?project=my-app&type=error\"\n\n# Logs from the last hour\ncurl \"http://127.0.0.1:9060/logs/query?since=$(($(date +%s) * 1000 - 3600000))\"\n```\n\n## Log Entry Schema\n\n| Field | Type | Required | Description |\n| ----------- | ------- | -------- | --------------------------------------- |\n| `project` | string | yes | Project identifier |\n| `content` | string | yes | Log message or error text |\n| `timestamp` | integer | yes | Unix timestamp in milliseconds |\n| `type` | string | yes | `\"log\"` or `\"error\"` |\n| `service` | string | yes | Service/task name that produced the log |\n| `stack` | string | no | Stack trace for errors |\n| `format` | string | no | `\"text\"` (default) or `\"json\"` |\n\n## Database\n\nLogs are stored in `~/.config/flow/flow.db` in the `logs` table. You can query directly:\n\n```bash\nsqlite3 ~/.config/flow/flow.db \"SELECT * FROM logs WHERE log_type='error' ORDER BY timestamp DESC LIMIT 10;\"\n```\n\n## Client Examples\n\n### TypeScript/JavaScript\n\n```typescript\nasync function sendLog(entry: {\n project: string;\n content: string;\n type: \"log\" | \"error\";\n service: string;\n stack?: string;\n}) {\n await fetch(\"http://127.0.0.1:9060/logs/ingest\", {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n ...entry,\n timestamp: Date.now(),\n format: \"text\",\n }),\n });\n}\n\n// Usage\nsendLog({\n project: \"my-app\",\n content: \"User login failed\",\n type: \"error\",\n service: \"auth\",\n});\n```\n\n### Python\n\n```python\nimport requests\nimport time\n\ndef send_log(project, content, log_type, service, stack=None):\n requests.post(\"http://127.0.0.1:9060/logs/ingest\", json={\n \"project\": project,\n \"content\": content,\n \"timestamp\": int(time.time() * 1000),\n \"type\": log_type,\n \"service\": service,\n \"stack\": stack,\n \"format\": \"text\"\n })\n\n# Usage\nsend_log(\"my-app\", \"Database connection failed\", \"error\", \"db\")\n```\n\n### curl\n\n```bash\ncurl -X POST http://127.0.0.1:9060/logs/ingest \\\n -H \"Content-Type: application/json\" \\\n -d '{\"project\":\"my-app\",\"content\":\"Test error\",\"timestamp\":'$(date +%s000)',\"type\":\"error\",\"service\":\"cli\",\"format\":\"text\"}'\n```\n\n## Testing\n\nRun the test task to verify the system is working:\n\n```bash\n# Terminal 1: Start the server\nf server\n\n# Terminal 2: Run tests\nf test-log-server\n```\n" }, { "path": "docs/moonbit-ai-tasks-implementation.md", "content": "# MoonBit AI Tasks: Implementation Inventory\n\nThis document captures the task-centric MoonBit implementation added in Flow, where `.ai/tasks/*.mbt` is the primary extension mechanism.\n\n## Scope\n\nThe implementation adds:\n\n- discovery and execution of AI MoonBit tasks under `.ai/tasks/`\n- CLI/docs updates to make `tasks` the primary interface\n- legacy `recipe` command demoted to compatibility mode\n- a concrete task pack for Flow self-development\n\n## Code Paths Added/Changed\n\nCore runtime and wiring:\n\n- `src/ai_tasks.rs`\n- `src/ai_taskd.rs`\n- `src/tasks.rs`\n- `src/bin/ai_taskd_client.rs`\n- `src/palette.rs`\n- `src/cli.rs`\n- `src/lib.rs`\n\nLegacy compatibility updates:\n\n- `src/recipe.rs`\n\nDocs updates:\n\n- `docs/commands/tasks.md`\n- `docs/commands/recipe.md`\n- `docs/commands/readme.md`\n- `docs/index.mdx`\n- `docs/moonbit-ai-tasks-implementation.md`\n\nWorkspace hygiene:\n\n- `.gitignore` (ignore Moon generated dirs under `.ai/tasks/**`)\n\n## Runtime Behavior\n\n### Discovery\n\nFlow scans `.ai/tasks/` recursively for `.mbt` files and exposes selectors as `ai:<path>`.\n\nKey behavior in `src/ai_tasks.rs`:\n\n- ignores generated Moon artifacts during discovery (`.mooncakes`, `_build`)\n- parses metadata from top comments:\n - `// title: ...`\n - `// description: ...`\n - `// tags: [a, b]`\n- resolves stable task IDs and selectors from path layout\n\n### Selection\n\nTask resolution accepts:\n\n- full selector: `ai:flow/dev-check`\n- scoped selector forms\n- name-based matching with ambiguity detection\n\n### Execution\n\nFlow executes AI tasks through a cache-first runtime.\n\nImportant execution details:\n\n- auto-resolves nearest Moon workspace root (`moon.mod.json` / `moon.mod`)\n- computes content hash (task source + Moon config + moon version)\n- builds native artifact once (`moon build --target native --release`)\n- reuses cached binary from `~/Library/Caches/flow/ai-tasks/<hash>/task-bin`\n- falls back to `moon run` for tasks without Moon workspace metadata\n- optional mode control via `FLOW_AI_TASK_MODE` (`dev`, `release`, `js`, etc.)\n- default frozen dependency behavior unless `FLOW_AI_TASK_NO_FROZEN` is set\n- runtime override via `FLOW_AI_TASK_RUNTIME=moon-run`\n\n### Daemon\n\nFlow now includes a lightweight Unix-socket daemon for repeated AI task runs:\n\n- socket: `~/.flow/run/ai-taskd.sock`\n- lifecycle: `f tasks daemon start|status|stop`\n- daemon execution: `f tasks run-ai --daemon <selector>`\n- low-overhead client execution: `./target/release/ai-taskd-client <selector>`\n\nRecent runtime optimizations:\n- daemon-side task discovery cache with TTL (`FLOW_AI_TASKD_DISCOVERY_TTL_MS`)\n- daemon-side hot artifact reuse cache with TTL (`FLOW_AI_TASKD_ARTIFACT_TTL_MS`)\n- fast exact selector resolution (skip full `.ai/tasks` scan for `ai:scope/task`)\n- cache key generation optimized to use file metadata fingerprints + cached Moon version\n- optional low-latency dispatch via `fai` with auto-preference from `f` for latency-tagged AI tasks in daemon mode\n\n## Task Pack Added\n\nFlow-local task pack under `.ai/tasks/flow/`:\n\n- `.ai/tasks/flow/dev-check/main.mbt`\n- `.ai/tasks/flow/pr-ready/main.mbt`\n- `.ai/tasks/flow/regression-smoke/main.mbt`\n- `.ai/tasks/flow/release-preflight/main.mbt`\n- `.ai/tasks/flow/bench-cli/main.mbt`\n- `.ai/tasks/flow/noop/main.mbt`\n\nEach task has its own Moon package/workspace files:\n\n- `.ai/tasks/flow/<task>/moon.mod.json`\n- `.ai/tasks/flow/<task>/moon.pkg.json`\n\n### Task Intents\n\n- `ai:flow/dev-check`: fast quality gate (`cargo check`, targeted tests, CLI help smoke)\n- `ai:flow/pr-ready`: pre-PR gate (dev-check + docs parity + gitignore hygiene)\n- `ai:flow/regression-smoke`: temporary project smoke for task discovery/execution\n- `ai:flow/release-preflight`: build release binary and run release-path smoke checks\n- `ai:flow/bench-cli`: quick latency benchmark for high-frequency Flow CLI entry points\n\n## How To Run\n\nFrom `~/code/flow`:\n\n```bash\nf tasks list\nf tasks build-ai ai:flow/dev-check\nf tasks run-ai ai:flow/dev-check\nf tasks run-ai --daemon ai:flow/dev-check\nf tasks daemon start\nf tasks daemon status\nf tasks daemon stop\nf ai:flow/dev-check\nf ai:flow/pr-ready\nf ai:flow/regression-smoke\nf ai:flow/release-preflight\nf ai:flow/bench-cli\n```\n\nOptional benchmark controls:\n\n```bash\nFLOW_BENCH_ITERATIONS=30 FLOW_BENCH_WARMUP=5 f ai:flow/bench-cli\n```\n\nRuntime-path benchmark harness:\n\n```bash\nf bench-ai-runtime --iterations 80 --warmup 10 --json-out /tmp/flow_ai_runtime_bench.json\n```\n\n## Automated myflow Commit→Session Check\n\nYou can automate the exact flow:\n\n1. Do real Claude/Codex work in a repo (for example `~/code/myflow`).\n2. Commit with sync (`f commit --sync ...`).\n3. Verify that commit is visible in myflow and has attached sessions.\n\nFlow task:\n\n```bash\nf myflow-commit-session-smoke --help\n```\n\nCommon run for `~/code/myflow`:\n\n```bash\nf myflow-commit-session-smoke --repo-path ~/code/myflow --require-sessions\n```\n\nWhat it checks:\n\n- `GET /api/commits?repo=<owner>/<repo>` contains the target commit\n- commit has `sessionWindow` metadata\n- if `--require-sessions` is set, commit has `sessions.length > 0`\n- first session id is fetchable via `GET /api/sessions/:id` (unless `--skip-session-fetch`)\n\nAuth:\n\n- uses `MYFLOW_TOKEN` if set\n- otherwise falls back to `~/.config/flow/auth.toml` token\n\n## Validation Commands\n\n```bash\ncargo check --all-targets\ncargo build --release --bin f\nf tasks list | rg '^ai:flow/'\nf ai:flow/regression-smoke\nf myflow-commit-session-smoke --repo-path ~/code/myflow --require-sessions\n```\n\n## Generated Artifact Hygiene\n\nTo prevent accidental commit noise from Moon caches/build output, Flow ignores:\n\n- `.ai/tasks/**/.mooncakes/`\n- `.ai/tasks/**/_build/`\n\n## Notes for Commits\n\nWhen committing this work, scope to the relevant code + docs only:\n\n```bash\nf commit --path src/ai_tasks.rs \\\n --path src/tasks.rs \\\n --path src/palette.rs \\\n --path src/cli.rs \\\n --path src/lib.rs \\\n --path src/recipe.rs \\\n --path docs/commands/tasks.md \\\n --path docs/commands/recipe.md \\\n --path docs/commands/readme.md \\\n --path docs/moonbit-ai-tasks-implementation.md \\\n \"add task-centric moonbit ai task runtime and flow task pack\"\n```\n" }, { "path": "docs/moonbit-rust-boundary-refactor-plan.md", "content": "# MoonBit Runtime Refactor Plan (Flow)\n\nThis plan is based on the current implementation in:\n\n- `src/ai_tasks.rs`\n- `src/ai_taskd.rs`\n- `src/tasks.rs`\n- `.ai/tasks/flow/*`\n\nGoal: keep Flow's Rust core stable while moving high-change task logic to MoonBit with near-zero boundary overhead and no performance regressions.\n\n## 1. Current Scan: Where Refactor Pressure Exists\n\n### 1.1 Task execution policy is still split across multiple layers\n\nCurrent paths:\n\n- `f ai:...` and task shortcut route through `tasks::run_with_discovery` in `src/tasks.rs`.\n- runtime policy (cached vs moon-run fallback) lives in `ai_tasks::run_task` in `src/ai_tasks.rs`.\n- daemon path (`f tasks run-ai --daemon`) is implemented separately in `src/ai_taskd.rs`.\n\nRefactor target:\n\n- Introduce one `AiTaskExecutor` policy entrypoint in Rust, used by all callsites.\n- Make shortcut path and explicit `tasks run-ai` path share identical behavior and telemetry.\n\n### 1.2 Startup/daemon policy is command-level, not config-level\n\nCurrent state:\n\n- daemon usage is chosen by CLI flags.\n\nRefactor target:\n\n- Add config-level defaults (e.g. `[ai_tasks] mode = \"cached\"`, `daemon = true`) and keep CLI as override.\n\n### 1.3 Task pack design is still shell-heavy\n\nCurrent state:\n\n- most `.ai/tasks/flow/*` tasks call shell commands directly.\n\nRefactor target:\n\n- move hot utility operations to typed host APIs over a stable ABI (git, file, json, process spawn, clock), reducing shell parsing/process overhead and improving deterministic latency.\n\n## 2. Benchmark Harness (Implemented)\n\nAdded:\n\n- `scripts/bench-ai-runtime.py`\n- `scripts/bench-moonbit-rust-ffi.py`\n- `flow.toml` task: `bench-ai-runtime`\n- `flow.toml` task: `bench-ffi-boundary`\n- minimal benchmark task: `.ai/tasks/flow/noop/*`\n- FFI microbench projects:\n - `bench/ffi_host_boundary` (Rust staticlib + Rust baseline bench)\n - `bench/moon_ffi_boundary` (MoonBit native bench calling Rust host exports)\n\nBenchmark scenarios:\n\n- `rust_help`\n- `moon_run_noop`\n- `cached_noop`\n- `daemon_cached_noop`\n- `cached_binary_direct`\n\nRun:\n\n```bash\ncd ~/code/flow\nf bench-ai-runtime --iterations 80 --warmup 10 --json-out /tmp/flow_ai_runtime_bench.json\n```\n\nThis is the baseline gate to ensure refactors do not regress p95 latency.\n\nRun boundary-only microbench:\n\n```bash\nf bench-ffi-boundary --iters 10000000 --json-out /tmp/flow_ffi_boundary.json\n```\n\n## 3. Zero-Cost Boundary Design (MoonBit <> Rust)\n\n### 3.1 Recommended boundary model\n\nUse a narrow C ABI with primitive handles, not JSON strings, for hot paths.\n\n- Rust hosts the scheduler, caches, daemon, security, lifecycle.\n- MoonBit tasks compile to native and call host exports via `extern \"C\"`.\n- Data boundary uses:\n - integers/enums for operation IDs and status\n - offsets/lengths into shared byte buffers for string/bytes payloads\n - opaque handles for host-managed resources\n\nWhy: this minimizes allocation/serialization churn and gives a predictable ABI.\n\n### 3.2 ABI contract for hot calls\n\nCandidate host functions:\n\n- `flow_host_now_ns() -> u64`\n- `flow_host_log(level: u32, ptr: *const u8, len: u32) -> i32`\n- `flow_host_spawn(cmd_ptr, cmd_len, argv_ptr, argv_len, out_handle) -> i32`\n- `flow_host_read_file(path_ptr, path_len, out_handle) -> i32`\n- `flow_host_git(op: u32, in_handle, out_handle) -> i32`\n- `flow_host_drop_handle(handle: u32)`\n\nFor MoonBit string interop helpers, the `justjavac/ffi` package is useful for C-string/wide-string conversions, but should remain at the edge of the ABI where text crossing is required.\n\n### 3.3 Boundary rules for latency\n\n- No JSON over FFI in hot loops.\n- No per-call dynamic symbol resolution.\n- Keep calls idempotent and batch-friendly.\n- Use borrow/owned annotations carefully on MoonBit side to avoid refcount overhead bugs.\n- Prefer fixed buffers + explicit lengths over repeated string allocations.\n\n## 4. Refactor Roadmap\n\n### Phase A (now)\n\n- Keep current cached runtime + daemon.\n- Add benchmark gates and require p95 non-regression before merge.\n\n### Phase B\n\n- Extract unified `AiTaskExecutor` in Rust.\n- Route all task entrypoints through one policy engine + one telemetry schema.\n\n### Phase C\n\n- Add `ai_task_host` C ABI layer in Rust.\n- Migrate one hot operation from shell to typed host call as a benchmarked pilot.\n\n### Phase D\n\n- Expand typed host API surface for common task operations.\n- Keep shell fallback for compatibility.\n\n## 5. Regression Gates\n\nUse these checks before approving runtime changes:\n\n1. `f bench-ai-runtime --iterations 80 --warmup 10 --json-out ...`\n2. Compare p95 for:\n - `cached_noop`\n - `daemon_cached_noop`\n3. Require:\n - no worse than +10% p95 vs baseline on same machine/load\n - no task failures\n\n## 6. What \"good\" looks like\n\n- Rust rebuilds become rare for workflow-level changes.\n- Most iteration happens in `.ai/tasks/*.mbt`.\n- Hot-path operations cross Rust/MoonBit boundary with primitive ABI payloads and stable p95 latency.\n" }, { "path": "docs/moving-repos.md", "content": "# Moving Repos with Flow\n\nHow Flow manages repository locations, migration, and AI session continuity.\n\n## Directory Layout\n\nFlow uses three managed roots:\n\n| Root | Purpose |\n|------|---------|\n| `~/code` | Active projects (`f code`) |\n| `~/repos` | Cloned third-party repos (`f repos`) |\n| `~/run` | Task-execution repos (`f r`, `f ri`, `f rp`) |\n\n## Cloning Into the Right Place\n\n### `f clone`\n\nClones with git-like destination behavior from your current working directory:\n\n```bash\nf clone owner/repo\nf clone https://github.com/owner/repo\nf clone owner/repo local-folder\n```\n\nGitHub inputs are normalized to SSH URLs, but destination behavior matches `git clone` (no forced `~/repos` root).\n\n### `f repos clone`\n\nClones GitHub repos into `~/repos/<owner>/<repo>`:\n\n```bash\nf repos clone owner/repo # -> ~/repos/owner/repo\nf repos clone https://github.com/owner/repo\n```\n\nShallow clone by default with background full-history fetch. Auto-sets upstream remote for forks. Initializes jj with `--colocate`.\n\n`~/repos` is immutable by default. Override with `FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1`.\n\nSee [commands/repos.md](commands/repos.md) for full options.\n\n### `f code`\n\nFuzzy-search git repos under `~/code` and open in editor:\n\n```bash\nf code # fzf picker over ~/code\nf code list # list all repos under ~/code\n```\n\n## Moving a Project\n\n### `f migrate` (primary command)\n\nMoves or copies a project folder and automatically:\n1. Moves/copies the directory (handles cross-device transparently)\n2. Relinks `~/bin` symlinks pointing into the old path (move only)\n3. Migrates Claude and Codex AI sessions to the new path\n\nThree usage forms:\n\n```bash\n# Move current dir into ~/code/<relative>\ncd ~/old/location/myproject\nf migrate code myproject # -> ~/code/myproject\nf migrate code lang/rust/mylib # -> ~/code/lang/rust/mylib\n\n# Move current dir to any path\nf migrate ~/code/stream\n\n# Move a specific source to a target (no cd needed)\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\nOptions:\n\n| Flag | Effect |\n|------|--------|\n| `--copy` / `-c` | Copy instead of move (keeps original) |\n| `--dry-run` | Preview without writing |\n| `--skip-claude` | Skip Claude session migration |\n| `--skip-codex` | Skip Codex session migration |\n\nPreview first:\n\n```bash\nf migrate --dry-run code stream\n```\n\n### What Happens to AI Sessions\n\nClaude and Codex store project sessions keyed by filesystem path:\n\n- **Claude**: `~/.claude/projects/<path-key>` directories are renamed\n- **Codex**: `~/.codex/projects/<path-key>` directories are renamed, plus `.jsonl` session files under `~/.codex/sessions/` are updated in-place (the `cwd` field in `session_meta` records)\n- **Seq zvec index**: if present at `~/repos/alibaba/zvec/data/agent_qa.jsonl`, matching docs are migrated so `metadata.project_path` (and project-keyed `metadata.source_path`) follows the new repo path for semantic session search.\n\nAfter migration a summary is printed:\n\n```\nSession migration summary:\n Claude project dirs moved: 1\n Codex legacy dirs moved: 1\n Codex jsonl files updated: 2\n Seq zvec docs updated: 124\n```\n\nWhen copying (`--copy`), sessions are duplicated with a derived ID so both locations have independent history. Seq zvec docs are duplicated too, with copied doc IDs and rewritten `metadata.project_path`.\n\n### `f code migrate` (alternative form)\n\nSame as `f migrate code` but accessed through the `code` subcommand:\n\n```bash\nf code migrate ~/old/path myproject # -> ~/code/myproject\n```\n\n### `f code move-sessions` (standalone session migration)\n\nMigrate only AI sessions without moving any files:\n\n```bash\nf code move-sessions --from /old/path --to /new/path\nf code move-sessions --from /old/path --to /new/path --dry-run\n```\n\nUseful when you moved a repo manually and need to fix sessions after the fact.\nThis also updates Seq zvec path metadata when the index exists.\n\nTo override the default zvec file or disable zvec migration:\n\n```bash\n# Use a custom zvec JSONL file\nexport FLOW_AGENT_QA_ZVEC_JSONL=/path/to/agent_qa.jsonl\n\n# Disable zvec migration for this command\nexport FLOW_AGENT_QA_ZVEC_JSONL=\"\"\n```\n\n## Run Repos (`~/run`)\n\nRun repos are a separate system for executing Flow tasks across multiple codebases without `cd`.\n\n```bash\nf r <task> # run in ~/run\nf ri <task> # run in ~/run/i\nf rp <project> <task> # run in ~/run/<project> (falls back to i/<project>)\nf rip <project> <task> # run in ~/run/i/<project>\n```\n\nManagement:\n\n```bash\nf run-load <name> <url> # clone/update a run repo\nf run-sync # sync all run repos\nf run-list # list all run repos\n```\n\nSee [run-repos.md](run-repos.md) for full details.\n\n## Common Workflows\n\n### Move a project into `~/code`\n\n```bash\ncd ~/downloads/cool-project\nf migrate code cool-project\n# -> ~/code/cool-project with sessions migrated\n```\n\n### Reorganize nested projects\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n# Directory moved, ~/bin symlinks updated, sessions migrated\n```\n\n### Clone a fork with upstream tracking\n\n```bash\nf repos clone myfork/repo\n# -> ~/repos/myfork/repo\n# upstream auto-detected via gh API, jj initialized\n```\n\n### Copy a project for experimentation\n\n```bash\nf migrate --copy ~/code/app ~/code/app-experiment\n# Original untouched, sessions duplicated with new IDs\n```\n\n### Fix sessions after a manual move\n\n```bash\nmv ~/code/old ~/code/new\nf code move-sessions --from ~/code/old --to ~/code/new\n```\n\n## See Also\n\n- [commands/clone.md](commands/clone.md) — `f clone` (git-like destination behavior)\n- [commands/repos.md](commands/repos.md) — `f repos clone` / `f repos create`\n- [commands/migrate.md](commands/migrate.md) — `f migrate` full reference\n- [run-repos.md](run-repos.md) — run repo shortcuts\n" }, { "path": "docs/myflow-localhost-runbook.md", "content": "# myflow.localhost Runbook (Native Domains)\n\nThis is the concrete setup for running `~/code/myflow` with stable local domains:\n\n- web UI: `http://myflow.localhost`\n- optional API hostname: `http://api.myflow.localhost`\n\nNo random ports to remember in daily browser use.\n\n## Prereqs\n\n- Flow CLI available as `f`\n- `clang++` installed (for native domains daemon build)\n- myflow repo at `~/code/myflow`\n\nIf your mac blocks native bind to port `80`, install launchd socket mode once:\n\n```bash\ncd ~/code/flow\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\n## One-time route setup\n\n```bash\nf domains add myflow.localhost 127.0.0.1:3000 --replace\nf domains add api.myflow.localhost 127.0.0.1:8780 --replace\n```\n\n## Start native domains engine\n\n```bash\nf domains --engine native up\nf domains --engine native doctor\nf domains list\n```\n\nOptional default (so you can run `f domains up` without `--engine native`):\n\n```bash\nexport FLOW_DOMAINS_ENGINE=native\n```\n\n## Start myflow dev\n\n```bash\ncd ~/code/myflow\nf dev\n```\n\nThen open:\n\n- `http://myflow.localhost`\n\nNotes:\n\n- `f dev` runs web on `127.0.0.1:3000` and API on `127.0.0.1:8780`.\n- myflow dev uses `/api` proxy to the local API port by default.\n- `api.myflow.localhost` is useful for direct API checks, but the web app does not require it in the default `f dev` path.\n\n## One-command mode (`f up` / `f down`)\n\nIn `~/code/myflow/flow.toml`, add:\n\n```toml\n[lifecycle]\nup_task = \"dev\"\n\n[lifecycle.domains]\nhost = \"myflow.localhost\"\ntarget = \"127.0.0.1:3000\"\nengine = \"native\"\nremove_on_down = false\nstop_proxy_on_down = false\n```\n\nThen use:\n\n```bash\ncd ~/code/myflow\nf up\nf down\n```\n\n`f down` will use task `down` if defined; otherwise it falls back to killing all running Flow-managed processes for the current project.\n\n## Logs inside myflow\n\nUse built-in myflow pages:\n\n- `http://myflow.localhost/processes`\n - process state\n - start/stop actions\n - live per-process logs\n- `http://myflow.localhost/logs`\n - focused log stream view\n\nThese pages query the local Flow daemon API (`http://127.0.0.1:9050`).\n\n## Native domains runtime files\n\nNative engine state is under:\n\n- `~/.config/flow/local-domains/routes.json`\n- `~/.config/flow/local-domains/domainsd.pid`\n- `~/.config/flow/local-domains/domainsd.log`\n- `~/.config/flow/local-domains/domainsd-cpp`\n\nQuick checks:\n\n```bash\ncurl -H 'Host: myflow.localhost' http://127.0.0.1/\ncurl http://127.0.0.1/_flow/domains/health\ntail -f ~/.config/flow/local-domains/domainsd.log\n```\n\n## Common failures\n\n1. `myflow.localhost` refuses connection\n\n```bash\nf domains --engine native doctor\nlsof -nP -iTCP:80 -sTCP:LISTEN\n```\n\nThen ensure `f dev` is running in `~/code/myflow`.\n\n2. Wrong app opens on `myflow.localhost`\n\n```bash\nf domains list\nf domains add myflow.localhost 127.0.0.1:3000 --replace\n```\n\n3. Browser console shows `Invalid base URL: /api`\n\n- update to latest `~/code/myflow` (this is handled in current auth client path resolution),\n- hard-refresh browser cache,\n- if running web manually (not via `f dev`), set an absolute API base, for example:\n\n```bash\nVITE_API_URL=http://api.myflow.localhost\n```\n\n## Stop\n\n```bash\nf domains --engine native down\n```\n\nFor launchd-managed native mode on macOS, use:\n\n```bash\ncd ~/code/flow\nsudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh\n```\n" }, { "path": "docs/new-branch.md", "content": "# New Branch (Flow + jj)\n\nUse this when you want a clean feature branch quickly with Flow (which syncs with jj under the hood).\n\n## Goal\n\nCreate a branch from latest `origin/main` (or preferred remote trunk), keep local state safe, and verify final state.\n\n## Recommended command flow\n\n```bash\n# 1) Start from repo root\ncd <repo>\n\n# 2) Sync trunk\nf sync\n\n# 3) Try Flow-native switch first\nf switch <branch-name>\n\n# 4) If Flow says \"Branch '<name>' not found locally or on remotes\", create from current HEAD\ngit switch -c <branch-name>\n\n# 5) Verify branch, upstream, and base commit\ngit rev-parse --abbrev-ref HEAD\ngit for-each-ref --format='%(refname:short) %(upstream:short)' refs/heads/<branch-name>\ngit status --short --branch\ngit log -1 --oneline\n\n# 6) Optional: publish branch and set tracking now\ngit push -u origin <branch-name>\n```\n\n## Reusable AI context template\n\nPaste this in requests when you want branch creation handled consistently:\n\n```md\nUse Flow-native branch creation in this repo:\n1. Run `f sync`.\n2. Try `f switch <branch-name>`.\n3. If Flow says branch is not found locally/remotely, run `git switch -c <branch-name>`.\n4. Verify branch name, upstream/tracking, and clean working tree (`git status --short --branch`).\n5. Report exact commands run, final branch, and HEAD commit.\n\nConstraints:\n- Keep unrelated local changes untouched.\n- Do not use destructive git commands.\n- If `f sync` is blocked by commit queue, list queue and clear stale entries safely before retrying.\n```\n\n## Notes\n\n- `f switch` preserves safety snapshots and stashes by default.\n- `f switch` may create `f-switch-save/<branch>-<timestamp>` even when it fails to find the target branch; this is expected safety behavior.\n- `f switch` now searches all configured Git remotes (not just `upstream`/`origin`) when resolving a missing local branch.\n- Today, `f switch` may fail for a brand-new local-only branch name; use the documented fallback.\n- If you intentionally need a different base, switch to that base first, then run `f switch <branch-name>`.\n- If your default trunk is `upstream/main`, use `--remote upstream`.\n- If you plan to open a PR soon, run `git push -u origin <branch-name>` right after creation so tracking is set.\n" }, { "path": "docs/new-pr.md", "content": "# New PR (Flow + jj)\n\nUse this when you want to create and iterate on a PR with Flow while keeping jj state clean.\n\n## Goal\n\nCreate a PR from a queued commit/bookmark, avoid accidental extra commits, and keep PR metadata easy to edit.\n\n## Recommended command flow\n\n```bash\n# 1) Start from repo root\ncd ~/code/org/linsa/linsa\n\n# 2) Sync trunk\nf sync\n\n# 3) Ensure jj is initialized (first time in repo)\nf jj init\n\n# 4) Create/track a feature bookmark (once per feature)\nf jj bookmark create <bookmark-name> --track\n\n# 5) Make changes, run checks, then queue commit (no push)\nf commit --queue -m \"<what changed>\"\n\n# 6) Create PR from queued commit (no new commit)\nf pr --no-commit --base main\n\n# 7) Edit PR title/body locally and auto-sync on save\nf pr open edit\n```\n\nImportant formatting rule:\n\n- Do not pass multi-line PR body text as a quoted CLI string with escaped `\\n`.\n- Use file-based markdown editing (`f pr open edit`) or `gh pr edit --body-file <file>`.\n\n## Update loop for follow-up commits\n\n```bash\n# After additional changes\nf commit --queue -m \"<follow-up>\"\nf pr --no-commit --base main\nf pr open edit\n```\n\n## Reusable AI context template\n\nPaste this in requests when you want PR creation handled consistently:\n\n```md\nUse Flow + jj PR workflow in this repo:\n1. Run `f sync`.\n2. Ensure jj is initialized (`f jj init`) and bookmark is tracked.\n3. Commit with `f commit --queue` (no direct push).\n4. Create/update PR with `f pr --no-commit --base main`.\n5. Open PR editor with `f pr open edit` and sync title/body.\n6. Report exact commands run and the final PR URL.\n\nConstraints:\n- Keep unrelated local changes untouched.\n- Do not use destructive git commands.\n- Do not create duplicate commits when creating PRs.\n```\n\n## Notes\n\n- `f pr` without `--no-commit` will stage/commit before creating the PR.\n- `f commit --queue` is the safest default for a review-first loop.\n- If your base branch is not `main`, always pass `--base <branch>`.\n- For bookmark-heavy workflows, run `f jj sync --bookmark <bookmark-name>` to fetch/rebase/push bookmark state.\n" }, { "path": "docs/outdated-readme.md", "content": "<!-- todo: remove/update this as its not up to date on whats in code repo -->\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/nikivdev/flow/main/scripts/install.sh | bash\n```\n\nThis downloads prebuilt binaries from GitHub releases. Falls back to building from source if no binary is available for your platform.\n\n**Environment variables:**\n- `FLOW_VERSION=v0.1.0` - Install specific version\n- `FLOW_BIN_DIR=/custom/path` - Custom install location (default: `~/.local/bin`)\n\nAfter install, add to your PATH if needed:\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n## Upgrade\n\n```bash\nf upgrade # Upgrade to latest version\nf upgrade --dry-run # Check what would be upgraded\nf upgrade v0.2.0 # Install specific version\n```\n\n## Short summary\n\nFor longer list of features available, see [docs/features.md](docs/features.md).\n\nCurrently [this thread](https://x.com/nikivdev/status/1997297174074499247) gives good overview of how you can use this tool to move fast with AI.\n\nI would suggest to open the repo and ask questions with claude code or codex how to make best use of the app. What it does well now is that you can define tasks in config.\n\nLike so:\n\n```\nversion = 1\nname = \"ts\"\n\n[deps]\nfast = \"github.com/nikivdev/fast\"\n\n[[tasks]]\nname = \"setup\"\ncommand = \"bun i\"\n\n[[tasks]]\nname = \"dev\"\ncommand = \"bun --watch run.ts\"\n\n[[tasks]]\nname = \"commit\"\ncommand = \"fast commitPush\"\ndescription = \"Commit with AI\"\ndependencies = [\"fast\"]\ndelegate_to_hub = true\n```\n\nAbove is from [ts repo](https://github.com/nikivdev/ts). Then you can run `f` to fuzzy search through tasks to run. Or do `f <task>` to run specific task.\n\nIf you setup [LM Studio](https://lmstudio.ai) & load MLX model like OpenAI 20B one, you can even make mistakes in `f <task>` and it would do a tool call match for you.\n\nAll flow tasks are traced for output/error after you ran them. `f last-cmd` would return the last commands output. In practice you can do this, open [warp](https://warp.dev) or [cursor](https://cursor.com) and then just ask agents things, you can literally say, `make me a flow.toml task to do..` then you run the task with `f <task>` or `f rerun` to rerun last ran task.\n\nAnd on errors, what I do at least is have [Keyboard Maestro](https://keyboardmaestro.com/main) macro to paste the output instantly into the agent. This way the feedback loop is insanely tight and you can iterate very fast.\n\nBelow readme is mostly generated with AI so feel free to ignore.\n\nI also use `flow` CLI to manage [hubs](#hub) but its experimental as the hub implementation I am running is closed code. The big idea is that `flow` just keeps the hub alive and that's it.\n\n## Building from Source\n\n```bash\n# Clone the repo\ngit clone https://github.com/nikivdev/flow.git\ncd flow\n\n# Build\ncargo build --release --bin f --bin lin\n\n# Install\ncp target/release/f ~/.local/bin/\ncp target/release/lin ~/.local/bin/\nln -sf ~/.local/bin/f ~/.local/bin/flow\n```\n\n## Creating Releases\n\nFor maintainers to create new releases:\n\n```bash\n# Build release binary\ncargo build --release --bin f --bin lin\n\n# Create tarball (adjust os/arch as needed)\nmkdir -p dist\ncd target/release\ntar -czvf ../../dist/flow_v0.2.0_darwin_arm64.tar.gz f lin\n\n# Create GitHub release with assets\nf release create v0.2.0 -a dist/flow_v0.2.0_darwin_arm64.tar.gz --generate-notes\n```\n\nOr use the `gh` CLI directly:\n```bash\ngh release create v0.2.0 --generate-notes dist/flow_v0.2.0_darwin_arm64.tar.gz\n```\n\n## Configuration\n\nOnce you have `f` (also available as `flow`) CLI, create `flow.toml` in your project:\n\n```toml\nversion = 1\nname = \"myproject\"\n\n[[tasks]]\nname = \"setup\"\ncommand = \"npm install\"\ndescription = \"Install dependencies\"\n\n[[tasks]]\nname = \"dev\"\ncommand = \"npm run dev\"\ndescription = \"Start development server\"\n\n[[tasks]]\nname = \"test\"\ncommand = \"npm test\"\n```\n\nRun `f` in your project to fuzzy search through tasks, or `f <task>` to run directly.\n\n## Commands\n\n**Tasks:**\n- `f` — Interactive fuzzy picker for tasks\n- `f <task>` — Run a specific task\n- `f tasks` — List all tasks from `flow.toml`\n- `f init` — Scaffold a starter `flow.toml`\n- `f rerun` — Re-run the last task\n\n**Git & Publishing:**\n- `f commit` / `f c` — AI-powered commit with code review\n- `f sync` — Pull, merge upstream, push\n- `f publish` — Create GitHub repository from current folder\n- `f release create` — Create GitHub release with assets\n\n**Self-management:**\n- `f upgrade` — Upgrade to latest version\n- `f doctor` — Check system dependencies\n\n**Other:**\n- `f search` / `f s` — Fuzzy search global tasks\n- `f hub start|stop` — Manage the lin hub daemon\n\n## Hub\n\nThere is component in flow that is a hub. It's a daemon that does things. Flow is not responsible for what the daemon does, all it does is it makes sure this daemon runs and in future perhaps auto heals or restarts as the idea is that the daemon should always be running.\n\nThere is an implementation of such hub built in private called `lin`. Will be possible to use soon, for now it's being tested in private as there are bugs. The goal of lin is to declaratively specify servers to run and trace all terminal I/O. In future more. Flow keeps a pointer to your production lin binary at `~/.config/flow/hub-runtime.json` (written by `lin register`); `f hub start` health-checks `http://127.0.0.1:9050/health` and launches that registered binary in daemon mode (passing `--config` if you supply one). If you want to experiment with a dev build, run it on another port so Flow can keep the production copy alive on the default port.\n\nThere are also plans for flow to handle communication between hubs. But flow will always try to abstract away the job of the actual hub to the hub itself as the hub can do many things. Right now it is assumed there is only 1 hub but in future there could be multiple hubs in theory.\n\nI like to think of flow as a program that is first top in class project manager with AI deeply embedded. But also as a small kubernetes like orchestrator of servers that run on the OS. Perhaps it will also handle the job of ingesting and streaming data from these hubs. i.e. in theory it can protect the user host from external potentially malicious hubs by making sure the hub has limited rights to do things.\n\n## Current state\n\nLightweight CLI that reads project-local `flow.toml` files, surfaces tasks, and delegates long-running background work to the `lin` hub. Flow itself no longer tries to manage servers, watchers, or tracing—that all belongs to `lin`. Flow’s job is to keep the hub running and give you a fast task entry point.\n\n### Tasks\n\n- Put a `flow.toml` next to your project.\n- Define tasks (see example at the top of this README).\n- Run `f` to fuzzy-pick a task (falls back to a numbered list if `fzf` is missing) or `f <task>` / `f run <task>` to execute directly.\n\n### Hub delegation\n\n- `lin` is the hub implementation; it reads `~/.config/lin/config.ts` (or `config.toml`) and owns servers/watchers/tracing.\n- Flow does not read `~/.config/flow/flow.toml` anymore; point `lin` at its config and keep it running (e.g., `lin -- daemon` or `lin hub start` if you use the helper).\n- Future Flow features will talk to the hub over HTTP instead of reimplementing those capabilities.\n" }, { "path": "docs/pr-edit-watcher.md", "content": "---\ntitle: PR Edit Watcher\n---\n\n# PR Edit Watcher\n\nFlow supports editing GitHub PR title/body from local Markdown files stored in `~/.flow/pr-edit/`.\n\nThere are two modes:\n\n1. One-shot editor + sync loop: `f pr open edit`\n2. Always-on background watcher (recommended): `f server`\n\n## Always-On Watcher (f server)\n\nWhen `f server` is running, it starts a lightweight watcher that:\n\n- Watches `~/.flow/pr-edit/` (non-recursive)\n- Debounces per-file changes (about 1.25s after the last write)\n- Parses title/body from the markdown\n- Updates the PR via GitHub REST (PATCH issue)\n- Writes status to `~/.flow/pr-edit/status.json`\n\nEndpoints:\n\n- `GET /pr-edit/status`\n- `POST /pr-edit/rescan`\n\nDefault server URL: `http://127.0.0.1:9060`\n\nExample:\n\n```sh\ncurl -s http://127.0.0.1:9060/pr-edit/status\n```\n\n## File Format\n\nEach file must map to a PR. The preferred mapping is YAML frontmatter:\n\n```md\n---\nrepo: owner/repo\npr: 123\n---\n\n# Title\n\nMy PR title\n\n# Description\n\nBody goes here.\n```\n\nIf the frontmatter is missing, Flow may fall back to `~/.flow/pr-edit/.index.json` (managed by\n`f pr open edit`).\n\n## Title/Body Parsing\n\n- Title: the first non-empty line under `# Title`\n- Body: everything under `# Description` (verbatim)\n\n## Using f pr open edit\n\n`f pr open edit`:\n\n- Finds the open PR for the current branch (fallback: queued commit PR)\n- Creates `~/.flow/pr-edit/<project>-<pr>.md` if missing\n- Ensures the file contains PR frontmatter\n- Opens the file in Zed Preview\n- Starts a foreground watcher that syncs on save (Ctrl-C to stop)\n\n## Status JSON\n\n`~/.flow/pr-edit/status.json` is written by the always-on watcher and can be used to build a UI.\n\nStates:\n\n- `unknown`: file exists but no PR mapping\n- `syncing`: change detected and being pushed\n- `clean`: last sync succeeded, content matches last pushed digest\n- `error`: last sync failed (see `last_error`)\n\n## Auth\n\nThe watcher uses `gh auth token` once and caches the token in memory. If syncing fails with auth\nerrors, run:\n\n```sh\ngh auth status\ngh auth login\n```\n\n## Debugging\n\nStart the server in foreground with debug prints for the PR watcher:\n\n```sh\nFLOW_PR_EDIT_DEBUG=1 f server foreground\n```\n\nIf the watcher failed to start, `GET /pr-edit/status` returns HTTP 503 with a `detail` field.\n\n" }, { "path": "docs/private-fork-flow.md", "content": "# Private Fork Flow Runbook\n\nUse this as the default AI-safe procedure when work must be pushed to a private fork, not public `origin`.\n\n## Goal\n\n- Keep upstream/public remotes for syncing.\n- Push writable changes to a private remote.\n- Make `f sync --push` and commit flows consistently target the private remote.\n\n## One-Time Setup Per Repo\n\n1. Add private remote.\n\n```bash\ncd <repo-dir>\ngit remote add <private-remote> git@github.com:<your-user>/<repo>-i.git\ngit fetch <private-remote>\n```\n\n2. Set Flow writable remote in `flow.toml`.\n\n```toml\n[git]\nremote = \"<private-remote>\"\n```\n\n3. Verify remote map.\n\n```bash\ngit remote -v\n```\n\nExpected pattern:\n- `origin` and/or `upstream` are read/sync sources.\n- `<private-remote>` is writable push target.\n\n## Standard Push Procedure\n\n```bash\ncd <repo-dir>\ngit status --short --branch\ngit diff --stat\ngit diff\nf commit --slow --review-model codex-high\nf sync --push\n```\n\nFlow behavior:\n- `f sync --push` uses `[git].remote` when configured.\n- Fallback order is `[git].remote`, then legacy `[jj].remote`, then `origin`.\n\n## AI Trigger Contract\n\nUse this exact phrase when you want review-first behavior:\n\n`analyze diff commit and push`\n\nExpected assistant behavior:\n\n1. Run `git status --short --branch`, `git diff --stat`, `git diff`.\n2. Produce a findings-first review (ordered by severity, with file references).\n3. If unresolved P1/P2 issues exist, stop before commit/push and fix or ask for override.\n4. Run `f commit --slow --review-model codex-high`.\n5. Run `f sync --push`.\n6. Report which remote received the push (`[git].remote` or fallback `origin`).\n\n## AI Guardrails (Must Follow)\n\n- Never push before reviewing `git status --short --branch` and `git diff --stat`.\n- Never include unrelated generated artifacts in the commit.\n- If the tree is noisy, create smaller focused commits before push.\n- If the remote target is unclear, stop and verify `flow.toml` `[git].remote` plus `git remote -v`.\n\n## Quick Validation\n\n```bash\ngit config --get branch.$(git rev-parse --abbrev-ref HEAD).remote || true\ngit remote get-url <private-remote>\n```\n\nThen run:\n\n```bash\nf sync --push\n```\n\n## Related Docs\n\n- `docs/commands/sync.md`\n- `docs/flow-toml-spec.md`\n- `docs/private-mirror-sync-workflow.md`\n- `docs/commands/upstream.md`\n" }, { "path": "docs/private-mirror-sync-workflow.md", "content": "# Private Mirror Sync Workflow (Upstream/Public + Private Fork)\n\nUse this when you work in a public fork clone locally but want to keep your full WIP history in a private mirror repo.\n\nExample mapping used here:\n\n- Local repo: `~/repos/pqrs-org/Karabiner-Elements-user-command-receiver`\n- Public remotes:\n - `origin` = `nikivdev/Karabiner-Elements-user-command-receiver`\n - `upstream` = `pqrs-org/Karabiner-Elements-user-command-receiver`\n- Private mirror remote:\n - `private` = `nikivdev/Karabiner-Elements-user-command-receiver-i`\n\n## Goal\n\n1. Move feature-branch work onto `main` locally.\n2. Sync with latest `origin/main`.\n3. Push local `main` to a private fork/mirror.\n\n## Recommended commands\n\n### 1) Save dirty working tree and move branch commits to `main`\n\n```bash\n# from repo root\ngit stash push -u -m \"move-to-main\"\ngit switch main\ngit merge --ff-only <feature-branch>\n```\n\nIf `--ff-only` fails, do a normal merge or cherry-pick intentionally.\n\n### 2) Sync with `origin/main`\n\nIf you want strict origin-only sync (no upstream automation):\n\n```bash\ngit fetch origin --prune\ngit rebase origin/main\n```\n\nThen reapply stash:\n\n```bash\ngit stash apply stash@{0}\n```\n\n### 3) Commit only intended files\n\nAvoid runtime artifacts (`out/logs/*`, todo scratch files, etc.).\n\n```bash\ngit add -A -- ':!out/logs/cli.log' ':!out/logs/trace.log' ':!.ai/todos/todos.json'\ngit commit -m \"<message>\"\n```\n\n### 4) Create private mirror repo and push\n\n```bash\n# one-time creation\ngh repo create nikivdev/<repo>-i --private --source=. --remote=private --disable-wiki\n\n# publish branch\ngit push -u private main\n```\n\n## Flow-specific notes (`f sync`)\n\n`f sync` can use jj integration and may rebase against upstream depending on repo setup.\nThat is useful in normal fork workflows, but if you need strict origin-only syncing for a private mirror flow, prefer explicit Git commands:\n\n```bash\ngit fetch origin --prune\ngit rebase origin/main\n```\n\nThen use Flow for commit/review as usual.\n\n## If `f sync` creates jj conflict artifacts\n\nSymptoms:\n\n- `jj` conflict commits\n- files like `.jjconflict-base-*` / `.jjconflict-side-*`\n\nRecovery pattern:\n\n1. stash uncommitted work (`git stash push -u`)\n2. create clean branch from `origin/main`\n3. cherry-pick your intended commits\n4. reapply stash\n5. continue from clean branch and move pointer back to `main`\n\n```bash\ngit stash push -u -m \"recovery\"\ngit fetch origin --prune\ngit switch -c main-clean origin/main\ngit cherry-pick <commit1> <commit2>\ngit stash apply <stash-with-real-work>\ngit branch -f main main-clean\ngit switch main\n```\n\n## Optional: keep `main` tracking private mirror\n\nIf this repo is now private-first for your local work:\n\n```bash\ngit push -u private main\n```\n\nand keep `origin`/`upstream` as fetch sources for rebases.\n" }, { "path": "docs/private-repo-fast.md", "content": "# Fast Private Repo Creation From An Existing Local Checkout\n\nUse this when you already have code locally and want a private GitHub repo quickly.\n\nThis guide covers two different cases:\n\n1. the current folder should become its own private GitHub repo\n2. the current folder already has `origin`/`upstream`, and you want an extra private share remote like `<repo>-i`\n\nThe important distinction:\n\n- `f publish` works from the current directory and is not tied to `~/repos`\n- `f repos clone` is the command that cares about `~/repos`\n\nSo yes, this works from places like:\n\n- `~/repos/viperrcrypto/Siftly`\n- `~/code/flow-extension`\n\n## Fastest path: current folder becomes a private repo\n\nUse this when:\n\n- the folder is your project\n- you want GitHub to become `origin`\n- you do not need to preserve some existing public `origin`/`upstream` setup\n\nFrom the repo root:\n\n```bash\nf publish -y --private\n```\n\nThis is the fastest default.\n\nWhat it does:\n\n- checks `gh` auth\n- initializes git if needed\n- creates an initial commit if the repo has none\n- creates the private GitHub repo\n- wires/pushes the current project\n\nExample from outside `~/repos`:\n\n```bash\ncd ~/code/flow-extension\nf publish -y --private\n```\n\nThat is the recommended path for repos like `~/code/flow-extension`.\n\n## Fast private share repo while keeping existing origin/upstream\n\nUse this when:\n\n- the repo already has a real public `origin` or `upstream`\n- you want a separate private mirror/share repo\n- you do not want to disturb existing remotes\n\nThis is the right pattern for repos like:\n\n```text\n~/repos/viperrcrypto/Siftly\n```\n\n### Recommended command sequence\n\n1. Make sure your intended work is committed.\n\n```bash\ngit status --short --branch\ngit add <intended files>\ngit commit -m \"<message>\"\n```\n\n2. Sync with `origin/main` if needed.\n\n```bash\ngit fetch origin main\ngit rev-parse HEAD origin/main\n```\n\nIf you need to move your work on top of `origin/main`, do that intentionally before publishing.\n\n3. Create the private repo and add it as a separate remote.\n\n```bash\ngh repo create nikivdev/<repo>-i --private --disable-wiki --source=. --remote=private\n```\n\n4. Push your current commit or branch to the new private repo.\n\n```bash\ngit push -u private HEAD:main\n```\n\nExample:\n\n```bash\ncd ~/repos/viperrcrypto/Siftly\ngh repo create nikivdev/Siftly-i --private --disable-wiki --source=. --remote=private\ngit push -u private HEAD:main\n```\n\nThis leaves:\n\n- `origin` alone\n- `upstream` alone\n- `private` as the new share/mirror remote\n\n## When to use `f publish` vs `gh repo create`\n\nUse `f publish` when:\n\n- you want the current folder to become the repo\n- you want the simplest path\n- the repo is new or self-owned\n\nUse `gh repo create ... --remote=private` when:\n\n- the checkout already tracks a public repo\n- you want a separate private mirror\n- you want to share WIP without changing `origin`\n\n## Safe default for a repo with an existing public origin\n\nIf a repo already has `origin` and you are not completely sure what to do, use this:\n\n```bash\ngit remote -v\ngit fetch origin main\ngh repo create nikivdev/<repo>-i --private --disable-wiki --source=. --remote=private\ngit push -u private HEAD:main\n```\n\nThat is the safest default for “share this work privately with another dev”.\n\n## Optional: make Flow push to the private remote by default\n\nIf you want future `f sync --push` calls to go to the private repo instead of `origin`, add this to the repo’s `flow.toml`:\n\n```toml\n[git]\nremote = \"private\"\n```\n\nOnly do this if the repo is now private-first for your workflow.\n\nIf you just want a one-off share snapshot, skip this.\n\n## Common examples\n\n### Example: private repo from `~/code/flow-extension`\n\n```bash\ncd ~/code/flow-extension\nf publish -y --private\n```\n\n### Example: private share mirror from `~/repos/viperrcrypto/Siftly`\n\n```bash\ncd ~/repos/viperrcrypto/Siftly\ngit fetch origin main\ngh repo create nikivdev/Siftly-i --private --disable-wiki --source=. --remote=private\ngit push -u private HEAD:main\n```\n\n## Troubleshooting\n\n### `gh` is not authenticated\n\nRun:\n\n```bash\ngh auth login\ngh auth status\n```\n\n### Repo already exists\n\nIf the private repo already exists, skip creation and just wire or verify the remote:\n\n```bash\ngit remote add private git@github.com:nikivdev/<repo>-i.git\ngit push -u private HEAD:main\n```\n\nIf `private` already exists:\n\n```bash\ngit remote -v\ngit push -u private HEAD:main\n```\n\n### I am outside `~/repos`\n\nThat is fine.\n\n`f publish` operates on the current folder, not on `~/repos`.\n\n### I do not want to push uncommitted changes\n\nGood. Commit first.\n\nFor existing repos with real history, do not rely on auto-magic here. Make the commit you want to share, then push that exact commit.\n\n## Related docs\n\n- [commands/publish.md](commands/publish.md)\n- [commands/repos.md](commands/repos.md)\n- [private-fork-flow.md](private-fork-flow.md)\n- [private-mirror-sync-workflow.md](private-mirror-sync-workflow.md)\n" }, { "path": "docs/proxyx-design.md", "content": "# proxyx: Zero-Cost Traced Reverse Proxy for Flow\n\nA lightweight reverse proxy with always-on observability, designed for macOS development.\n\n## Design Principles\n\n1. **Zero-cost tracing** - mmap ring buffer, no allocations per request\n2. **Flow-native** - integrates with `f` commands and flow.toml\n3. **AI-powered naming** - suggests proxy names from port/process info\n4. **macOS-optimized** - no Docker/K8s complexity\n5. **Dev-time intelligence** - traces inform AI agents writing code\n\n---\n\n## How Traces Help During Development (Rise Example)\n\nRise has multiple services that need coordination during development:\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│ Development Session │\n│ │\n│ Claude Code ◄──── reads traces ────► proxyx ring buffer │\n│ │ ▲ │\n│ │ writes code │ records all requests │\n│ ▼ │ │\n│ ┌─────────┐ ┌─────────┐ ┌───────────┴───────────┐ │\n│ │ web │───▶│ daemon │───▶│ zai/xai/cerebras/etc │ │\n│ │ :5173 │ │ :7654 │ └───────────────────────┘ │\n│ └─────────┘ └─────────┘ │\n│ │ │ │\n│ │ ▼ │\n│ │ ┌─────────┐ │\n│ └────────▶│ api │ │\n│ │ :8787 │ │\n│ └─────────┘ │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n### Use Case 1: \"Why is my AI call slow?\"\n\nWhen you're writing code and notice latency, instead of hunting through logs:\n\n```bash\nf proxy last --target daemon\n# Request 3f2a:\n# Path: /v1/chat/completions\n# Provider: zai → cerebras (fallback)\n# Latency: 4200ms (provider: 4150ms, overhead: 50ms)\n# Tokens: 1200 in, 340 out\n# Error: zai timeout after 3000ms, retried cerebras\n```\n\n**AI agent can read this** and suggest: \"zai is timing out - switch default provider to cerebras in your session\"\n\n### Use Case 2: \"What API calls does this component make?\"\n\nWhen editing a component, see exactly what requests it triggers:\n\n```bash\nf proxy trace --since \"10s ago\" --source web\n# TIME METHOD PATH STATUS LATENCY TARGET\n# 14:32:01 POST /v1/chat/completions 200 120ms daemon\n# 14:32:01 GET /api/user/profile 200 8ms api\n# 14:32:02 POST /api/mutations 200 45ms api\n```\n\n**AI agent can correlate**: \"Your UserProfile component makes 3 requests on mount - the chat completion is redundant here\"\n\n### Use Case 3: \"Debug failing mutation\"\n\nWhen Effect mutation fails, trace shows the full picture:\n\n```bash\nf proxy trace --errors --last 5\n# Request a3f1:\n# Path: /api/mutations\n# Status: 500\n# Upstream response: {\"_tag\":\"ParseError\",\"message\":\"Expected string at path.name\"}\n# Request body hash: 0x3f2a... (see f proxy body a3f1)\n```\n\n**AI agent sees**: typed error from Effect schema validation, can fix the code directly\n\n### Use Case 4: \"Correlation across services\"\n\nTrace ID propagates through all services:\n\n```bash\nf proxy trace --id abc123\n# Trace abc123 (total: 340ms):\n# 14:32:01.000 web → daemon POST /v1/chat/completions (started)\n# 14:32:01.050 daemon → zai POST /chat/completions (timeout 3000ms)\n# 14:32:04.050 daemon → cerebras POST /chat/completions (fallback)\n# 14:32:04.200 cerebras → daemon 200 OK (150ms)\n# 14:32:04.210 daemon → web 200 OK (streaming start)\n# 14:32:04.340 daemon → web streaming complete (340ms total)\n```\n\n### Use Case 5: \"What changed between working and broken?\"\n\nCompare request patterns before/after a code change:\n\n```bash\nf proxy diff --before \"5 min ago\" --after \"now\"\n# New requests:\n# + POST /api/mutations (didn't exist before)\n# Changed requests:\n# ~ GET /api/user/profile: added header X-Cache-Bust\n# Missing requests:\n# - GET /api/user/settings (no longer called)\n```\n\n---\n\n## Integration with Claude Code / AI Agents\n\nThe key insight: **traces are structured data AI agents can consume**.\n\n```rust\n// In Claude Code's context, expose trace summary\npub struct TraceContext {\n pub recent_errors: Vec<TraceRecord>, // Last 5 errors\n pub slow_requests: Vec<TraceRecord>, // p99 > 500ms\n pub request_patterns: HashMap<String, u32>, // Path -> count\n pub provider_health: HashMap<String, ProviderStats>,\n}\n\nimpl TraceContext {\n /// Called by AI agent to understand current state\n pub fn summarize(&self) -> String {\n format!(\n \"Recent errors: {}\\nSlow requests: {}\\nMost called: {}\",\n self.recent_errors.len(),\n self.slow_requests.len(),\n self.request_patterns.iter().max_by_key(|&(_, v)| v).map(|(k, _)| k).unwrap_or(\"none\")\n )\n }\n}\n```\n\n### Agent-Readable Trace File\n\nIn addition to binary ring buffer, write agent-friendly summary:\n\n```\n~/.config/flow/proxy/trace-summary.json\n{\n \"last_updated\": 1706000000,\n \"session\": {\n \"started\": 1705990000,\n \"requests\": 1234,\n \"errors\": 5,\n \"avg_latency_ms\": 45\n },\n \"recent_errors\": [\n {\n \"time\": \"14:32:01\",\n \"path\": \"/api/mutations\",\n \"status\": 500,\n \"error\": \"ParseError: Expected string at path.name\",\n \"suggestion\": \"Check schema validation in mutations endpoint\"\n }\n ],\n \"slow_requests\": [\n {\n \"time\": \"14:31:45\",\n \"path\": \"/v1/chat/completions\",\n \"latency_ms\": 4200,\n \"reason\": \"Provider fallback: zai → cerebras\"\n }\n ],\n \"provider_status\": {\n \"zai\": { \"healthy\": false, \"last_error\": \"timeout\", \"error_rate\": \"40%\" },\n \"cerebras\": { \"healthy\": true, \"avg_latency_ms\": 150 }\n }\n}\n```\n\nClaude Code can read this file and proactively suggest fixes:\n\n> \"I notice zai has a 40% error rate in the last 5 minutes. Should I switch your default provider to cerebras?\"\n\n---\n\n## Rise-Specific Configuration\n\n```toml\n# ~/code/rise/flow.toml\n\n[proxy]\ntrace_summary = true # Write agent-readable JSON summary\ntrace_interval = \"1s\" # Update summary every second\n\n[[proxies]]\nname = \"daemon\"\ntarget = \"localhost:7654\"\n# Capture request/response bodies for AI endpoints\ncapture_body = true\ncapture_body_max = \"64KB\"\n\n[[proxies]]\nname = \"api\"\ntarget = \"localhost:8787\"\n# Correlate with Effect trace events\neffect_trace_header = \"X-Trace-Id\"\n\n[[proxies]]\nname = \"web\"\ntarget = \"localhost:5173\"\n# Don't capture static assets\nexclude_paths = [\"/assets/*\", \"*.js\", \"*.css\"]\n```\n\n## Integration with Rise's Existing Tracing\n\nRise already has two tracing mechanisms:\n\n1. **Daemon logs** (`/logs` endpoint) - in-memory, lost on restart\n2. **Effect Trace service** - writes to JSONL file + HTTP endpoint\n\nproxyx unifies these by:\n\n1. **Intercepting all HTTP** - captures what daemon logs miss (non-AI requests)\n2. **Correlating trace IDs** - links Effect mutations to HTTP requests\n3. **Persisting in ring buffer** - survives restarts, zero-cost\n4. **Exposing to AI agents** - structured summary for Claude Code\n\n```\nBefore (fragmented):\n web → daemon (logged in daemon memory, lost on restart)\n web → api (logged in Effect Trace JSONL, separate file)\n No correlation between them\n\nAfter (unified):\n web → proxyx → daemon (ring buffer + summary JSON)\n └──────→ api (ring buffer + summary JSON)\n\n All requests correlated by trace ID, readable by AI agents\n```\n\n### Trace ID Propagation\n\nproxyx generates trace IDs and propagates them:\n\n```\nRequest from web:\n → proxyx adds X-Trace-Id: abc123 (if not present)\n → forwards to daemon with X-Trace-Id: abc123\n → daemon logs include trace_id: abc123\n → Effect Trace service receives X-Trace-Id header\n → All logs correlate to abc123\n```\n\nThis means `f proxy trace --id abc123` shows the complete journey.\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│ flow.toml │\n│ │\n│ [[proxies]] │\n│ name = \"api\" # AI can suggest this │\n│ listen = \":8080\" # or auto-assign │\n│ target = \"localhost:3000\" │\n│ host = \"api.local\" # optional host-based routing │\n│ │\n│ [[proxies]] │\n│ name = \"docs\" │\n│ target = \"localhost:4000\" │\n└─────────────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────────────┐\n│ proxyx daemon (spawned by flow supervisor) │\n│ │\n│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │\n│ │ Listener │───▶│ Router │───▶│ Backend Pool │ │\n│ │ (hyper) │ │ (path/host) │ │ (crossbeam queue) │ │\n│ └──────────────┘ └──────────────┘ └────────────────────────┘ │\n│ │ │ │\n│ │ ┌──────────────────────────────┘ │\n│ ▼ ▼ │\n│ ┌─────────────────────────────────────────────────────────────────┐│\n│ │ Trace Ring Buffer (mmap) ││\n│ │ ~/.config/flow/proxy/trace.<pid>.bin ││\n│ │ ││\n│ │ Header (64 bytes): ││\n│ │ magic: \"PROXYTRC\" ││\n│ │ version: 1 ││\n│ │ capacity: N ││\n│ │ write_index: AtomicU64 ││\n│ │ ││\n│ │ Records (128 bytes each): ││\n│ │ [ts_ns, req_id, method, status, latency_us, ││\n│ │ bytes_in, bytes_out, target_idx, path_hash, path_prefix] ││\n│ └─────────────────────────────────────────────────────────────────┘│\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n## Trace Record Structure\n\n```rust\nconst TRACE_MAGIC: &[u8; 8] = b\"PROXYTRC\";\nconst TRACE_VERSION: u32 = 1;\nconst TRACE_RECORD_SIZE: usize = 128;\nconst TRACE_PATH_BYTES: usize = 64;\n\n#[repr(C)]\nstruct TraceHeader {\n magic: [u8; 8],\n version: u32,\n record_size: u32,\n capacity: u64,\n write_index: AtomicU64,\n // Target table (name -> index mapping written at init)\n target_count: u32,\n _reserved: [u8; 28],\n}\n\n#[repr(C)]\nstruct TraceRecord {\n ts_ns: u64, // Monotonic timestamp\n req_id: u64, // Unique request ID (atomic counter)\n method: u8, // 1=GET, 2=POST, 3=PUT, 4=DELETE, etc.\n status: u16, // HTTP status code\n _pad: u8,\n latency_us: u32, // Response time in microseconds\n bytes_in: u32, // Request body size\n bytes_out: u32, // Response body size\n target_idx: u8, // Index into target table\n path_len: u8,\n _pad2: [u8; 2],\n path_hash: u64, // FNV-1a hash of full path\n path: [u8; 64], // Path prefix (truncated if longer)\n client_ip: [u8; 16], // IPv4 (4 bytes) or IPv6 (16 bytes)\n upstream_latency_us: u32,\n _reserved: [u8; 4],\n}\n```\n\n## Components\n\n### 1. Proxy Core (Pingora-inspired)\n\n```rust\n// Simplified from Pingora's ProxyHttp trait\npub trait ProxyHandler: Send + Sync {\n /// Called before forwarding request\n fn request_filter(&self, req: &mut Request, ctx: &mut ProxyCtx) -> Result<()> {\n Ok(())\n }\n\n /// Select upstream target\n fn upstream_peer(&self, req: &Request, ctx: &mut ProxyCtx) -> Result<&Backend>;\n\n /// Called after receiving response\n fn response_filter(&self, resp: &mut Response, ctx: &mut ProxyCtx) -> Result<()> {\n Ok(())\n }\n\n /// Called after request completes (success or failure)\n fn logging(&self, req: &Request, resp: Option<&Response>, ctx: &ProxyCtx) {\n // Default: write to trace ring buffer\n }\n}\n\npub struct ProxyCtx {\n pub req_id: u64,\n pub start_time: Instant,\n pub upstream_connect_time: Option<Duration>,\n pub target_idx: u8,\n}\n```\n\n### 2. Connection Pool (Pingora-inspired, simplified)\n\n```rust\nuse crossbeam::queue::ArrayQueue;\n\npub struct ConnectionPool {\n // Lock-free queue for hot connections (sized for dev workloads)\n hot: ArrayQueue<PooledConnection>,\n // Target address\n addr: SocketAddr,\n // Pool stats (atomic counters)\n reused: AtomicU64,\n created: AtomicU64,\n}\n\nimpl ConnectionPool {\n pub fn new(addr: SocketAddr, capacity: usize) -> Self {\n Self {\n hot: ArrayQueue::new(capacity),\n addr,\n reused: AtomicU64::new(0),\n created: AtomicU64::new(0),\n }\n }\n\n pub async fn get(&self) -> Result<Connection> {\n // Try hot queue first (lock-free)\n if let Some(conn) = self.hot.pop() {\n if conn.is_alive() {\n self.reused.fetch_add(1, Ordering::Relaxed);\n return Ok(conn.into_connection());\n }\n }\n // Create new connection\n self.created.fetch_add(1, Ordering::Relaxed);\n Connection::new(self.addr).await\n }\n\n pub fn put(&self, conn: Connection) {\n let pooled = PooledConnection::from(conn);\n // Best effort - if queue is full, connection is dropped\n let _ = self.hot.push(pooled);\n }\n}\n```\n\n### 3. Trace Ring Buffer\n\n```rust\nuse std::sync::atomic::{AtomicU64, Ordering};\nuse std::ptr::write_unaligned;\n\npub struct TraceBuffer {\n header: *mut TraceHeader,\n records: *mut u8,\n capacity: u64,\n req_counter: AtomicU64,\n}\n\nimpl TraceBuffer {\n /// Record a completed request (zero allocations)\n #[inline]\n pub fn record(&self, record: &TraceRecord) {\n let idx = unsafe {\n (*self.header).write_index.fetch_add(1, Ordering::Relaxed)\n };\n let slot = (idx % self.capacity) as usize;\n let dst = unsafe {\n self.records.add(slot * TRACE_RECORD_SIZE) as *mut TraceRecord\n };\n unsafe { write_unaligned(dst, *record) };\n }\n\n /// Get next request ID\n #[inline]\n pub fn next_req_id(&self) -> u64 {\n self.req_counter.fetch_add(1, Ordering::Relaxed)\n }\n}\n```\n\n### 4. Router\n\n```rust\npub struct Router {\n // Host -> target index\n host_routes: HashMap<String, usize>,\n // Path prefix -> target index\n path_routes: Vec<(String, usize)>,\n // Default target\n default_target: Option<usize>,\n // All backends\n backends: Vec<Backend>,\n}\n\npub struct Backend {\n pub name: String,\n pub addr: SocketAddr,\n pub pool: ConnectionPool,\n}\n\nimpl Router {\n pub fn route(&self, req: &Request) -> Option<&Backend> {\n // 1. Check host header\n if let Some(host) = req.headers().get(\"host\") {\n if let Some(&idx) = self.host_routes.get(host.to_str().ok()?) {\n return Some(&self.backends[idx]);\n }\n }\n\n // 2. Check path prefix\n let path = req.uri().path();\n for (prefix, idx) in &self.path_routes {\n if path.starts_with(prefix) {\n return Some(&self.backends[*idx]);\n }\n }\n\n // 3. Default\n self.default_target.map(|idx| &self.backends[idx])\n }\n}\n```\n\n## CLI Commands\n\n```bash\n# List active proxies\nf proxy\n# Output:\n# NAME LISTEN TARGET REQS ERRORS LATENCY(p99)\n# api :8080 localhost:3000 1.2k 0 12ms\n# docs :8081 localhost:4000 340 2 8ms\n\n# Add a proxy (AI suggests name)\nf proxy add localhost:3000\n# Detected: node process, cwd=~/code/myapi\n# Suggested name: \"myapi\" [Y/n/custom]:\n\n# Add with explicit name\nf proxy add localhost:3000 --name api\n\n# View recent requests\nf proxy trace\n# Output (tail of ring buffer):\n# TIME REQ_ID METHOD PATH STATUS LATENCY TARGET\n# 14:32:01 a3f2 GET /api/users 200 12ms api\n# 14:32:01 a3f3 POST /api/login 401 8ms api\n# 14:32:02 a3f4 GET /docs/intro 200 4ms docs\n\n# View last request details\nf proxy last\n# Request a3f4:\n# Method: GET\n# Path: /docs/intro\n# Status: 200\n# Latency: 4ms\n# Upstream: 3ms\n# Bytes: 0 in, 4.2KB out\n\n# Follow trace in real-time\nf proxy trace -f\n\n# Filter by target\nf proxy trace --target api\n\n# Stop proxy daemon\nf proxy stop\n```\n\n## Flow.toml Schema\n\n```toml\n[proxy]\n# Global proxy settings\nlisten = \":8080\" # Default listen address\ntrace_size = \"16MB\" # Ring buffer size\ntrace_dir = \"~/.config/flow/proxy\"\n\n[[proxies]]\nname = \"api\"\ntarget = \"localhost:3000\"\n# Optional: host-based routing\nhost = \"api.local\"\n# Optional: path prefix routing\npath = \"/api\"\n# Optional: health check\nhealth = \"/health\"\nhealth_interval = \"10s\"\n\n[[proxies]]\nname = \"docs\"\ntarget = \"localhost:4000\"\npath = \"/docs\"\n```\n\n## AI Naming Integration\n\nWhen `f proxy add <target>` is called without `--name`:\n\n```rust\npub struct PortInfo {\n pub port: u16,\n pub process: Option<String>, // e.g., \"node\", \"python\"\n pub cwd: Option<PathBuf>, // Process working directory\n pub cmdline: Option<String>, // Full command line\n pub listening_since: Option<Duration>,\n}\n\npub async fn suggest_proxy_name(info: &PortInfo) -> String {\n // 1. Try to infer from cwd (last path component)\n if let Some(cwd) = &info.cwd {\n if let Some(name) = cwd.file_name() {\n return sanitize_name(name.to_string_lossy());\n }\n }\n\n // 2. Try to infer from process + port\n if let Some(proc) = &info.process {\n return format!(\"{}-{}\", proc, info.port);\n }\n\n // 3. Fall back to port\n format!(\"svc-{}\", info.port)\n}\n\n// For smarter naming, call LLM with context\npub async fn ai_suggest_name(info: &PortInfo) -> Result<String> {\n let prompt = format!(\n \"Suggest a short, memorable name for a local dev proxy:\\n\\\n Port: {}\\n\\\n Process: {:?}\\n\\\n Working dir: {:?}\\n\\\n Reply with just the name (lowercase, no spaces).\",\n info.port, info.process, info.cwd\n );\n // Call local LLM or API\n llm_complete(&prompt).await\n}\n```\n\n## Implementation Plan\n\n### Phase 1: Core Proxy\n1. [ ] `ProxyConfig` struct in flow's config.rs\n2. [ ] Trace ring buffer module (`src/proxy/trace.rs`)\n3. [ ] Basic hyper-based proxy (`src/proxy/server.rs`)\n4. [ ] Router with host/path matching (`src/proxy/router.rs`)\n5. [ ] Connection pool (`src/proxy/pool.rs`)\n\n### Phase 2: Flow Integration\n1. [ ] `f proxy` subcommands in CLI\n2. [ ] Supervisor integration (daemon lifecycle)\n3. [ ] Hot reload on flow.toml changes\n\n### Phase 3: AI & Polish\n1. [ ] Port scanning for `f proxy add`\n2. [ ] AI name suggestion\n3. [ ] `f proxy trace` viewer\n4. [ ] Health checks\n\n## Dependencies\n\n```toml\n# Add to Cargo.toml\nhyper = { version = \"1\", features = [\"http1\", \"http2\", \"server\", \"client\"] }\nhyper-util = { version = \"0.1\", features = [\"tokio\"] }\ncrossbeam = { version = \"0.8\", features = [\"crossbeam-queue\"] }\n# Already have: tokio, libc, memmap2 (or use libc::mmap directly)\n```\n\n## File Structure\n\n```\nsrc/\n├── proxy/\n│ ├── mod.rs # Re-exports\n│ ├── config.rs # ProxyConfig parsing\n│ ├── server.rs # Hyper server + request handling\n│ ├── router.rs # Host/path routing\n│ ├── pool.rs # Connection pooling\n│ ├── trace.rs # mmap ring buffer\n│ ├── summary.rs # Agent-readable JSON summary\n│ └── ai.rs # Name suggestion\n├── cmd/\n│ └── proxy.rs # CLI commands\n└── ...\n```\n\n---\n\n## Claude Code Integration (The Key Feature)\n\nThe real value: **AI sees your app's behavior while helping you code**.\n\n### CLAUDE.md Hook\n\nAdd to your project's CLAUDE.md:\n\n```markdown\n## Development Context\n\nWhen helping with this project, check the proxy trace summary:\n- File: ~/.config/flow/proxy/trace-summary.json\n- Command: `f proxy last` for recent request details\n\nIf you see errors or slow requests, mention them proactively.\n```\n\n### Automatic Context Injection\n\nFlow can inject trace context into Claude Code sessions:\n\n```bash\n# In flow.toml\n[claude]\ncontext_files = [\n \"~/.config/flow/proxy/trace-summary.json\"\n]\n```\n\nNow Claude Code automatically sees:\n- Recent errors (can fix the code causing them)\n- Slow requests (can suggest optimizations)\n- Provider health (can suggest fallbacks)\n- Request patterns (can identify redundant calls)\n\n### Example Interaction\n\nYou: \"The user profile page is slow\"\n\nClaude (reading trace-summary.json):\n> Looking at the trace data, I see UserProfile makes 3 requests on mount:\n> 1. GET /api/user/profile (8ms) ✓\n> 2. POST /v1/chat/completions (4200ms) ← this is slow\n> 3. GET /api/user/settings (12ms) ✓\n>\n> The chat completion is being called on every mount. Looking at the code...\n> this is in useEffect without deps. Should I add caching or move it to user action?\n\n### Real-time Error Notification\n\nWhen a request fails, Flow can notify Claude Code:\n\n```rust\n// In proxyx, when error detected:\nif record.status >= 500 {\n // Write to a file Claude Code watches\n write_error_notification(&record);\n}\n```\n\nClaude Code sees the notification and can proactively say:\n> \"I just saw a 500 error on POST /api/mutations - the request body had an invalid schema. Want me to fix it?\"\n\n---\n\n## Development Workflow with Traces\n\n### Starting Development\n\n```bash\n# Terminal 1: Start proxyx (intercepts all traffic)\nf proxy start\n\n# Terminal 2: Start Rise services through proxy\nf dev # web, daemon, api all route through proxyx\n\n# Terminal 3: Claude Code\n# Claude reads trace-summary.json automatically\n```\n\n### While Coding\n\n1. **You edit code** → triggers requests\n2. **proxyx records** → updates trace-summary.json\n3. **Claude Code reads** → understands what happened\n4. **Claude suggests** → \"That request failed because...\"\n\n### Debugging Session\n\n```bash\n# See what's happening right now\nf proxy trace -f\n\n# See last error details\nf proxy last --errors\n\n# See specific request with body\nf proxy show abc123 --body\n\n# Compare before/after\nf proxy diff --before \"5min\" --after \"now\"\n```\n\n### Example: Fixing a Bug\n\n```\nYou: \"Login is broken\"\n\nClaude:\n> Checking trace-summary.json...\n> I see POST /api/auth/login returning 401 for the last 5 requests.\n> The error response is: {\"error\": \"Invalid token format\"}\n>\n> Looking at your recent code changes... you modified auth.ts 3 minutes ago.\n> The issue is on line 42 - you're passing the token without the \"Bearer \" prefix.\n>\n> Here's the fix: [shows diff]\n```\n\n---\n\n## Summary: Why This Matters\n\n| Without proxyx | With proxyx |\n|----------------|-------------|\n| \"Something is slow\" | \"zai provider timed out, cerebras fallback added 4s\" |\n| \"Login is broken\" | \"POST /api/auth returned 401, token format invalid\" |\n| \"Too many requests\" | \"UserProfile calls /v1/chat/completions on every mount\" |\n| Check daemon logs manually | Claude reads trace-summary.json automatically |\n| Logs lost on restart | Ring buffer persists, zero-cost |\n| No correlation | Trace ID links all services |\n\n**The core insight**: Development is about understanding what your code does at runtime. proxyx captures this automatically and makes it available to AI agents helping you write code.\n" }, { "path": "docs/read-stream-of-logs.md", "content": "# Reactive Log Stream Processing\n\nThis document describes how to build a TypeScript service that watches the flow logs database for new entries and takes action on errors (e.g., sending macOS notifications).\n\n## Architecture\n\n```\n┌─────────────┐ POST ┌──────────────┐ writes ┌─────────────┐\n│ Your Apps │ ────────────► │ f server │ ─────────────► │ flow.db │\n└─────────────┘ └──────────────┘ └─────────────┘\n │\n │ watches\n ▼\n ┌─────────────┐\n │ Log Watcher│\n │ (this doc) │\n └─────────────┘\n │\n │ on error\n ▼\n ┌─────────────┐\n │ Actions │\n │ - notify │\n │ - webhook │\n │ - AI fix │\n └─────────────┘\n```\n\n## Implementation\n\n### Option 1: Polling (Simple)\n\nPoll the database for new logs since the last check.\n\n```typescript\n// log-watcher.ts\nimport Database from \"bun:sqlite\";\nimport { exec } from \"child_process\";\nimport { homedir } from \"os\";\nimport { join } from \"path\";\n\nconst DB_PATH = join(homedir(), \".config/flow/flow.db\");\nconst POLL_INTERVAL_MS = 1000;\n\ninterface LogEntry {\n id: number;\n project: string;\n content: string;\n timestamp: number;\n log_type: string;\n service: string;\n stack: string | null;\n format: string;\n}\n\nfunction sendMacNotification(title: string, message: string) {\n const escaped = message.replace(/\"/g, '\\\\\"').substring(0, 200);\n exec(\n `osascript -e 'display notification \"${escaped}\" with title \"${title}\"'`\n );\n}\n\nasync function onError(entry: LogEntry) {\n console.log(`[ERROR] ${entry.project}/${entry.service}: ${entry.content}`);\n\n // Action 1: macOS notification\n sendMacNotification(\n `Error in ${entry.project}`,\n `${entry.service}: ${entry.content}`\n );\n\n // Action 2: Call AI to analyze/fix (placeholder)\n // await analyzeWithAI(entry);\n}\n\nfunction watchLogs() {\n const db = new Database(DB_PATH, { readonly: true });\n let lastId = 0;\n\n // Get the current max ID to start from\n const latest = db.query(\"SELECT MAX(id) as max_id FROM logs\").get() as {\n max_id: number | null;\n };\n lastId = latest?.max_id ?? 0;\n\n console.log(`Watching logs from id > ${lastId}...`);\n\n setInterval(() => {\n const newLogs = db\n .query(\n `\n SELECT id, project, content, timestamp, log_type, service, stack, format\n FROM logs\n WHERE id > ?\n ORDER BY id ASC\n `\n )\n .all(lastId) as LogEntry[];\n\n for (const log of newLogs) {\n lastId = log.id;\n\n if (log.log_type === \"error\") {\n onError(log);\n }\n }\n }, POLL_INTERVAL_MS);\n}\n\nwatchLogs();\n```\n\nRun with:\n\n```bash\nbun log-watcher.ts\n```\n\n### Option 2: File System Watch (More Reactive)\n\nWatch the SQLite file for changes using fs notifications.\n\n```typescript\n// log-watcher-fs.ts\nimport Database from \"bun:sqlite\";\nimport { watch } from \"fs\";\nimport { exec } from \"child_process\";\nimport { homedir } from \"os\";\nimport { join } from \"path\";\n\nconst DB_PATH = join(homedir(), \".config/flow/flow.db\");\n\ninterface LogEntry {\n id: number;\n project: string;\n content: string;\n timestamp: number;\n log_type: string;\n service: string;\n stack: string | null;\n format: string;\n}\n\nfunction sendMacNotification(title: string, message: string) {\n const escaped = message.replace(/\"/g, '\\\\\"').substring(0, 200);\n exec(\n `osascript -e 'display notification \"${escaped}\" with title \"${title}\"'`\n );\n}\n\nasync function onError(entry: LogEntry) {\n console.log(`[ERROR] ${entry.project}/${entry.service}: ${entry.content}`);\n sendMacNotification(\n `Error in ${entry.project}`,\n `${entry.service}: ${entry.content}`\n );\n}\n\nfunction createWatcher() {\n let lastId = 0;\n let debounceTimer: Timer | null = null;\n\n function checkNewLogs() {\n const db = new Database(DB_PATH, { readonly: true });\n\n try {\n if (lastId === 0) {\n const latest = db.query(\"SELECT MAX(id) as max_id FROM logs\").get() as {\n max_id: number | null;\n };\n lastId = latest?.max_id ?? 0;\n console.log(`Starting from id ${lastId}`);\n return;\n }\n\n const newLogs = db\n .query(\n `\n SELECT id, project, content, timestamp, log_type, service, stack, format\n FROM logs WHERE id > ? ORDER BY id ASC\n `\n )\n .all(lastId) as LogEntry[];\n\n for (const log of newLogs) {\n lastId = log.id;\n if (log.log_type === \"error\") {\n onError(log);\n }\n }\n } finally {\n db.close();\n }\n }\n\n // Initial check\n checkNewLogs();\n\n // Watch for file changes\n watch(DB_PATH, (eventType) => {\n if (eventType === \"change\") {\n // Debounce rapid changes\n if (debounceTimer) clearTimeout(debounceTimer);\n debounceTimer = setTimeout(checkNewLogs, 100);\n }\n });\n\n console.log(`Watching ${DB_PATH} for changes...`);\n}\n\ncreateWatcher();\n```\n\n### Option 3: HTTP Streaming Endpoint (Future)\n\nAdd a streaming endpoint to `f server` for real-time log delivery via SSE.\n\n```rust\n// In log_server.rs (future enhancement)\nasync fn logs_stream() -> impl IntoResponse {\n // Server-Sent Events stream\n // Clients connect and receive new logs in real-time\n}\n```\n\nClient would consume:\n\n```typescript\nconst events = new EventSource(\"http://127.0.0.1:9060/logs/stream\");\nevents.onmessage = (e) => {\n const log = JSON.parse(e.data);\n if (log.type === \"error\") {\n handleError(log);\n }\n};\n```\n\n## Actions on Error\n\n### macOS Notification\n\n```typescript\nimport { exec } from \"child_process\";\n\nfunction notify(title: string, message: string, sound = \"default\") {\n const escaped = message.replace(/\"/g, '\\\\\"').substring(0, 200);\n exec(\n `osascript -e 'display notification \"${escaped}\" with title \"${title}\" sound name \"${sound}\"'`\n );\n}\n```\n\n### Webhook\n\n```typescript\nasync function sendWebhook(url: string, entry: LogEntry) {\n await fetch(url, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n text: `Error in ${entry.project}/${entry.service}: ${entry.content}`,\n entry,\n }),\n });\n}\n```\n\n### AI Analysis\n\n```typescript\nasync function analyzeWithAI(entry: LogEntry) {\n const response = await fetch(\"https://api.anthropic.com/v1/messages\", {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n \"x-api-key\": process.env.ANTHROPIC_API_KEY!,\n \"anthropic-version\": \"2023-06-01\",\n },\n body: JSON.stringify({\n model: \"claude-sonnet-4-20250514\",\n max_tokens: 1024,\n messages: [\n {\n role: \"user\",\n content: `Analyze this error and suggest a fix:\n\nProject: ${entry.project}\nService: ${entry.service}\nError: ${entry.content}\n${entry.stack ? `Stack trace:\\n${entry.stack}` : \"\"}\n\nProvide a brief analysis and actionable fix.`,\n },\n ],\n }),\n });\n\n const data = await response.json();\n const analysis = data.content[0].text;\n\n // Send analysis as notification or log it\n console.log(\"AI Analysis:\", analysis);\n notify(\"AI Fix Suggestion\", analysis.substring(0, 200));\n}\n```\n\n## Full Example: Error Monitor Service\n\n```typescript\n// error-monitor.ts\nimport Database from \"bun:sqlite\";\nimport { watch } from \"fs\";\nimport { exec } from \"child_process\";\nimport { homedir } from \"os\";\nimport { join } from \"path\";\n\nconst DB_PATH = join(homedir(), \".config/flow/flow.db\");\n\ninterface LogEntry {\n id: number;\n project: string;\n content: string;\n timestamp: number;\n log_type: string;\n service: string;\n stack: string | null;\n format: string;\n}\n\ninterface Config {\n notify: boolean;\n webhook?: string;\n aiAnalysis: boolean;\n projectFilter?: string[];\n}\n\nconst config: Config = {\n notify: true,\n aiAnalysis: false, // Enable if you have ANTHROPIC_API_KEY set\n // projectFilter: ['my-app'], // Only watch specific projects\n};\n\nfunction notify(title: string, message: string) {\n if (!config.notify) return;\n const escaped = message.replace(/\"/g, '\\\\\"').substring(0, 200);\n exec(\n `osascript -e 'display notification \"${escaped}\" with title \"${title}\" sound name \"Basso\"'`\n );\n}\n\nasync function handleError(entry: LogEntry) {\n // Skip if project filter is set and doesn't match\n if (\n config.projectFilter &&\n !config.projectFilter.includes(entry.project)\n ) {\n return;\n }\n\n const timestamp = new Date(entry.timestamp).toLocaleTimeString();\n console.log(\n `\\n[${timestamp}] ERROR in ${entry.project}/${entry.service}`\n );\n console.log(` ${entry.content}`);\n if (entry.stack) {\n console.log(` Stack: ${entry.stack.split(\"\\n\")[0]}`);\n }\n\n // Send notification\n notify(`${entry.project} error`, `${entry.service}: ${entry.content}`);\n\n // Send to webhook if configured\n if (config.webhook) {\n fetch(config.webhook, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify(entry),\n }).catch(console.error);\n }\n}\n\nfunction startWatcher() {\n let lastId = 0;\n let debounceTimer: Timer | null = null;\n\n function checkNewLogs() {\n const db = new Database(DB_PATH, { readonly: true });\n\n try {\n if (lastId === 0) {\n const latest = db\n .query(\"SELECT MAX(id) as max_id FROM logs\")\n .get() as { max_id: number | null };\n lastId = latest?.max_id ?? 0;\n return;\n }\n\n const newLogs = db\n .query(\n `SELECT id, project, content, timestamp, log_type, service, stack, format\n FROM logs WHERE id > ? ORDER BY id ASC`\n )\n .all(lastId) as LogEntry[];\n\n for (const log of newLogs) {\n lastId = log.id;\n if (log.log_type === \"error\") {\n handleError(log);\n }\n }\n } finally {\n db.close();\n }\n }\n\n checkNewLogs();\n\n watch(DB_PATH, (eventType) => {\n if (eventType === \"change\") {\n if (debounceTimer) clearTimeout(debounceTimer);\n debounceTimer = setTimeout(checkNewLogs, 50);\n }\n });\n\n console.log(\"Error monitor started\");\n console.log(`Watching: ${DB_PATH}`);\n console.log(`Notifications: ${config.notify ? \"enabled\" : \"disabled\"}`);\n if (config.projectFilter) {\n console.log(`Projects: ${config.projectFilter.join(\", \")}`);\n }\n console.log(\"\");\n}\n\nstartWatcher();\n```\n\nRun as a background service:\n\n```bash\n# Run in foreground\nbun error-monitor.ts\n\n# Run in background\nnohup bun error-monitor.ts > /tmp/error-monitor.log 2>&1 &\n```\n\n## Testing\n\n1. Start the log server: `f server`\n2. Start the watcher: `bun error-monitor.ts`\n3. Send a test error:\n\n```bash\ncurl -X POST http://127.0.0.1:9060/logs/ingest \\\n -H \"Content-Type: application/json\" \\\n -d '{\"project\":\"test\",\"content\":\"Test error\",\"timestamp\":'$(date +%s000)',\"type\":\"error\",\"service\":\"test\",\"format\":\"text\"}'\n```\n\nYou should see the error logged and receive a macOS notification.\n" }, { "path": "docs/rise-sandbox-feature-test-runbook.md", "content": "# Rise Sandbox Feature Test Runbook (Flow)\n\nUse this when you want deterministic, isolated feature checks in a VM and fast feedback for infra tuning.\n\n## Goal\n\n- Verify a feature works in a clean sandbox.\n- Avoid host-machine state leaks.\n- Capture timings/logs so CI/CD and install paths can be optimized.\n\n## Prereqs\n\n- macOS host.\n- `rise` available.\n- `vibe` VM binary from `~/repos/lynaghk/vibe`.\n\n`rise sandbox` expects the VM-oriented `vibe`, not the unrelated CLI binary some PATHs contain.\n\nPreflight:\n\n```bash\ncd ~/repos/lynaghk/vibe\ncargo build --release\n```\n\n## Canonical Sandbox Command\n\nFrom `~/code/rise`:\n\n```bash\nrise sandbox \"set -euo pipefail; <your commands>; echo SANDBOX_OK\" \\\n --root ~/code/flow \\\n --expect SANDBOX_OK\n```\n\nWhy this shape:\n\n- `set -euo pipefail` fails hard on the first real issue.\n- `--expect` gives a strict pass/fail marker.\n- `--root ~/code/flow` mounts the Flow repo into `/root/project`.\n\n## Feature Test Template\n\nReplace with your feature command:\n\n```bash\nrise sandbox \"set -euo pipefail; cd /root/project; <feature command>; echo FEATURE_OK\" \\\n --root ~/code/flow \\\n --expect FEATURE_OK\n```\n\n## Installer/Release Verification (Flow)\n\nUse this to verify `curl -fsSL https://myflow.sh/install.sh | sh` pulls the latest release:\n\n```bash\nrise sandbox \"set -euo pipefail; curl -fsSL https://myflow.sh/install.sh | sh; ~/.flow/bin/f --version; echo INSTALL_OK\" \\\n --root ~/code/flow \\\n --expect INSTALL_OK\n```\n\nThen verify the latest release tag is what you expect:\n\n```bash\ngh release view --repo nikivdev/flow --json tagName,publishedAt\n```\n\n## Infra Optimization Loop\n\n1. Run the same sandbox test 3-5 times.\n2. Record:\n - VM boot + script duration from `rise sandbox` output.\n - Feature command duration inside script (`time <cmd>` if needed).\n - Artifact install/build timing (`f --version`, compile/install steps).\n3. Compare before/after infra changes:\n - CI runner mode (`github` vs `host` vs `blacksmith`).\n - Caching changes.\n - Installer path changes.\n\nSandbox logs are emitted under:\n\n```bash\n~/code/flow/out/logs/sandbox-<timestamp>.log\n```\n\n## Common Failures\n\n### `vibe: error: unrecognized arguments: --cpus --ram ...`\n\nCause: wrong `vibe` binary in PATH.\n\nFix: build/use `~/repos/lynaghk/vibe/target/release/vibe` (rise resolves this first when present).\n\n### Sandbox passes but installed version seems old\n\nCheck:\n\n1. Latest release tag:\n ```bash\n gh release view --repo nikivdev/flow --json tagName,publishedAt\n ```\n2. Latest release workflow status:\n ```bash\n gh run list -R nikivdev/flow --limit 5\n ```\n\nIf the latest release tag points to your target commit, installer should fetch that version.\n" }, { "path": "docs/rise.md", "content": "# Rise\n\nThis document explains how Rise integrates with Flow and why installing Rise gives you a high-leverage workflow layer across repos.\n\nRise itself is treated as closed/internal product code in many environments, but its operator model and command surface can still be documented and shared.\n\n## Start Here\n\nIntegration starts with one command:\n\n```bash\nf install rise\n```\n\nAfter install:\n\n```bash\nwhich rise\nrise --help\n```\n\nYou now have `rise` on your PATH and can use Rise workflows from any repo.\n\nFrom Flow's install behavior (`f install`):\n\n- backend resolution is automatic (`registry` -> `parm` -> `flox`)\n- `rise` is a built-in known install target\n- Rise can be part of bootstrap tool install flows\n\n## What You Get From `rise` In Practice\n\nRise is not just one command; it is a workflow layer that adds:\n\n1. Repo adoption overlays for external/team repositories.\n2. Task detection and `flow.toml` generation/merge.\n3. JJ-native branch/bookmark workflow for clean PRs.\n4. Multi-platform compile/dev loops (web, Expo/mobile, Electron, COI).\n5. Mobile/TestFlight build observability and debugging.\n6. Schema workflows with generated TypeScript/Effect bindings.\n7. Sandbox verification in VM environments.\n8. AI and trace workflows that integrate with Flow and surrounding tooling.\n\n## Core Model: Overlay, Not Pollution\n\nThe defining Rise behavior is `rise adopt`.\n\nFor external repos, Rise creates a JJ overlay bookmark (`rise`) above `main`:\n\n- `rise` layer contains your local workflow files (for example `flow.toml`, `.rise/`).\n- Team-facing `main` remains untouched.\n- PR branches are created from `main`, so Rise files do not leak into PRs.\n\nTypical flow:\n\n```bash\nrise adopt https://github.com/org/repo\ncd ~/code/org/repo\nrise sync\njj new main -m \"feat: clean PR change\"\n```\n\nThis is the main reason Rise is valuable in mixed team environments: private operator ergonomics without contaminating shared repo history.\n\n## Task Detection And Flow Integration\n\nDuring adoption, Rise detects project tasks from common sources (for example `package.json`, `Makefile`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `justfile`) and generates `flow.toml`.\n\nYou keep the generated baseline and extend it with your own project-specific tasks.\n\nUseful commands:\n\n```bash\nrise adopt .\nrise adopt --force .\nrise flow tasks .\nrise sync\nrise list\n```\n\nKey integration point: this makes Flow task execution (`f <task>`) available even in repos that did not originally ship with Flow conventions.\n\n## Development Loops\n\nRise provides higher-level wrappers while preserving underlying toolchains.\n\nCommon commands:\n\n```bash\nrise dev\nrise app\nrise run dev --runner turbo\nrise setup\nrise verify\n```\n\nFrom Rise docs/repo behavior:\n\n- `rise dev` starts local dev paths with platform-aware behavior.\n- `rise app` is a fast app shortcut path.\n- `rise run` can delegate to task runners (Turbo/Flow patterns).\n- `rise setup` is project setup entrypoint.\n- `rise verify` is local verification flow.\n\n## Mobile/TestFlight Workflows (High Value)\n\nRise has dedicated mobile commands with structured observability:\n\n```bash\nrise mobile validate\nrise mobile preflight\nrise mobile testflight\nrise mobile builds\nrise mobile logs\n```\n\nWhy this matters:\n\n- `validate` catches JS bundle issues quickly.\n- `preflight` checks config + bundle + prebuild inspect.\n- `testflight` captures structured build events.\n- `builds`/`logs` provide post-failure visibility and faster debugging loops.\n\nThis reduces the \"wait 10+ minutes to discover obvious build issues\" pattern in Expo/EAS flows.\n\n## Schema Workflows\n\nRise includes schema lifecycle commands:\n\n```bash\nrise schema init\nrise schema status\nrise schema diff\nrise schema generate\nrise schema push\nrise schema validate\n```\n\nThis supports a source-of-truth schema flow with generated app bindings (including TypeScript/Effect-oriented outputs in documented workflows).\n\n## Sandbox Workflows\n\nRise supports VM-backed sandbox execution and verification:\n\n```bash\nrise sandbox\nrise sandbox verify\nrise verify --sandbox\nrise sandbox kill\nrise sandbox clean\n```\n\nUse this when you need stronger isolation for verification or reproduction loops.\n\n## AI + Traces + Operational Debugging\n\nRise docs also describe:\n\n- AI trace collection (`rise logs`)\n- build failure context for AI-assisted remediation (`rise work --errors` paths)\n- integration patterns around generated prompts and operational context\n\nFor Flow users, this complements:\n\n- `f commit` review/message provider strategies that can call Rise-backed providers\n- task failure hooks that invoke `rise work`\n\n## Typical Onboarding Sequence\n\nFor a new machine:\n\n```bash\nf doctor\nf auth login\nf install rise\nrise --help\n```\n\nFor an external/team repo:\n\n```bash\ncd ~/code/org/repo\nrise adopt .\nrise sync\n```\n\nFor daily work:\n\n```bash\nrise verify\nrise mobile preflight # if mobile repo\njj new main -m \"feat: ...\"\n```\n\n## When To Use Rise\n\nUse Rise when you want:\n\n- an opinionated operator layer over heterogeneous repos\n- clean PRs with private local tooling overlays\n- stronger mobile/testflight diagnostics\n- schema/sandbox/dev orchestration from one CLI surface\n\nUse plain Flow-only setup when:\n\n- repo already has stable native workflows and minimal onboarding cost\n- you do not need overlay-based separation\n- your team explicitly avoids JJ overlay workflows\n\n## Relationship To Flow\n\nFlow and Rise are complementary:\n\n- Flow is the general control plane (`f tasks`, `f env`, `f commit`, deploy/sync/invariants).\n- Rise is the repo/workflow acceleration layer for adoption, platform compile loops, mobile observability, and overlay workflows.\n\nThe practical entrypoint is still:\n\n```bash\nf install rise\n```\n\nThen use `rise` where it adds leverage, while keeping Flow as your consistent command contract across projects.\n\n## References In Rise Docs\n\nIf you have access to the internal Rise repo docs, these are particularly relevant:\n\n- `docs/adopt-guide.md`\n- `docs/workflow-guide.md`\n- `docs/rise-branch-workflow.md`\n- `docs/build-observability.md`\n- `docs/schema-guide.md`\n- `docs/sandbox-vibe.md`\n- `docs/rise-mobile-compat.md`\n- `docs/expo-identifiers.md`\n" }, { "path": "docs/rl-for-myflow-harbor.md", "content": "# RL Plan For myflow -> Harbor System\n\nUse this plan to turn the current export/prep automation into a measurable RL improvement loop for agent behavior.\n\n## Scope\n\nCurrent system already has:\n\n- myflow export to Harbor snapshots (`assistant_sft.jsonl`, `train_events.jsonl`, `summary.json`)\n- deterministic Harbor split prep (`train/val/test/canary` + `manifest.json`)\n- infra timer wiring for recurring export/prepare jobs\n- Maple telemetry hooks for export visibility\n\nGoal: convert this into a closed loop where training updates are driven by observed failures/regressions and promoted only through hard gates.\n\n## What RL Should Improve\n\nPrimary outcomes:\n\n1. Better action selection in real workflows (fewer wrong tool/actions).\n2. Lower production regressions (canary deltas trend positive).\n3. Faster convergence per run (more useful data per training cycle).\n4. Higher reliability under ambiguous/long-horizon tasks.\n\n## Phase Plan\n\n## Phase 0: Stabilize Data Reliability (Now)\n\n1. Enforce snapshot integrity checks in Harbor ingest.\n2. Fail job if `assistant_sft.jsonl` is empty or split counts are invalid.\n3. Persist run metadata keyed by snapshot timestamp and git SHA of training config.\n\nDone definition:\n\n- every snapshot has a valid manifest + non-empty train split\n- every training run can be traced back to one exact snapshot + config\n\n## Phase 1: Reward Signal Contract (Next)\n\n1. Define reward schema from `train_events.jsonl` (success, retries, rollback, human override, time-to-fix).\n2. Map each signal to normalized reward components in Harbor.\n3. Store per-sample reward breakdown for auditability.\n\nDone definition:\n\n- reward function is versioned (`reward_schema_version`)\n- each trained sample has explainable reward components\n\n## Phase 2: Offline RL + Canary Gate (Next)\n\n1. Train candidate adapters on latest prepared snapshot.\n2. Evaluate on fixed holdout + canary split from same manifest.\n3. Add strict promotion gate: holdout pass + canary pass + no action-collapse.\n\nDone definition:\n\n- promotion is blocked automatically on gate failure\n- gate outputs are attached to snapshot and run IDs\n\n## Phase 3: Continuous Hard-Case Mining (Then)\n\n1. Mine failed canary/production cases into a hardcase set.\n2. Re-inject hardcases with higher sampling weight in next cycle.\n3. Track “failure class recurrence” across runs.\n\nDone definition:\n\n- recurring failure classes trend downward across 3+ cycles\n\n## Minimal Metrics To Track\n\n- `canary_reward_delta_mean`\n- `canary_reward_delta_ci95_low/high`\n- `action_error_rate`\n- `fallback_or_override_rate`\n- `time_to_resolution_p50/p95`\n- `hardcase_recurrence_rate`\n\n## Runbook (Operator Loop)\n\n```bash\n# 1) Export latest data from myflow to Harbor\ncd ~/code/myflow\nf harbor-export-data-maple\n\n# 2) Prepare deterministic splits\ncd ~/repos/laude-institute/harbor\npython3 scripts/prepare_myflow_dataset.py --snapshot latest\n\n# 3) Train/eval candidate in Harbor (task names TBD in harbor)\n# 4) Promote only if holdout + canary gates pass\n```\n\n## Immediate Next Steps\n\n1. Add Harbor task: `myflow-validate-snapshot` (manifest + split sanity checks).\n2. Add Harbor task: `myflow-eval-canary` (fixed JSON report schema for promotion gate).\n3. Add Harbor task: `myflow-mine-hardcases` (from failed canary/prod traces).\n4. Add one weekly dashboard cut from Maple + Harbor manifests for trend review.\n\n" }, { "path": "docs/rl-myflow-harbor-task-specs.md", "content": "# RL Task Specs: myflow -> Harbor\n\nConcrete task contracts for the Harbor RL loop. These map directly to scripts currently in `~/repos/laude-institute/harbor/scripts`.\n\n## Task 1: Validate Snapshot\n\n- Script: `scripts/myflow_validate_snapshot.py`\n- Purpose: fail fast on broken snapshot/split artifacts before reward labeling or gating.\n- Command:\n\n```bash\npython3 scripts/myflow_validate_snapshot.py \\\n --snapshot <snapshot|latest> \\\n --myflow-dir data/myflow \\\n --prepared-dir data/myflow_prepared \\\n --require-train-events \\\n --report-out data/myflow_prepared/<snapshot>/validation_report.json\n```\n\n- Inputs:\n - `data/myflow/<snapshot>/assistant_sft.jsonl`\n - `data/myflow/<snapshot>/train_events.jsonl` (required when `--require-train-events`)\n - `data/myflow_prepared/<snapshot>/manifest.json`\n- Outputs:\n - validation report JSON\n- Exit contract:\n - `0` = pass\n - non-zero = integrity failure\n\n## Task 2: Build Reward Labels\n\n- Script: `scripts/myflow_build_reward_labels.py`\n- Purpose: produce versioned per-event rewards for RL training and canary gating.\n- Command:\n\n```bash\npython3 scripts/myflow_build_reward_labels.py \\\n --snapshot <snapshot|latest> \\\n --myflow-dir data/myflow \\\n --out-dir data/myflow_rewards\n```\n\n- Inputs:\n - `data/myflow/<snapshot>/train_events.jsonl`\n- Outputs:\n - `data/myflow_rewards/<snapshot>/train_event_rewards.jsonl`\n - `data/myflow_rewards/<snapshot>/reward_summary.json`\n- Exit contract:\n - `0` = labels generated\n - non-zero = parse/IO/schema error\n\n## Task 3: Canary Promotion Gate\n\n- Script: `scripts/myflow_eval_canary.py`\n- Purpose: gate promotion based on reward quality and optional baseline deltas.\n- Command:\n\n```bash\npython3 scripts/myflow_eval_canary.py \\\n --candidate data/myflow_rewards/<snapshot>/train_event_rewards.jsonl \\\n --baseline data/myflow_rewards/<baseline_snapshot>/train_event_rewards.jsonl \\\n --report-out data/myflow_reports/<snapshot>/canary_gate.json \\\n --min-candidate-mean 0.55 \\\n --min-delta-mean 0.00 \\\n --min-delta-ci95-low -0.02\n```\n\n- Inputs:\n - candidate rewards JSONL\n - optional baseline rewards JSONL\n - optional `--rollouts` for action-dominance gate\n- Outputs:\n - canary gate report JSON\n- Exit contract:\n - `0` = promotion gate pass\n - `1` = gate fail (expected for regressions)\n - non-zero other = runtime error\n\n## Task 4: Mine Hardcases\n\n- Script: `scripts/myflow_mine_hardcases.py`\n- Purpose: mine regressions/low-reward canary samples and produce next-cycle seed set.\n- Command:\n\n```bash\npython3 scripts/myflow_mine_hardcases.py \\\n --snapshot <snapshot|latest> \\\n --prepared-dir data/myflow_prepared \\\n --candidate-rewards data/myflow_rewards/<snapshot>/train_event_rewards.jsonl \\\n --baseline-rewards data/myflow_rewards/<baseline_snapshot>/train_event_rewards.jsonl \\\n --out-dir data/myflow_hardcases \\\n --top-k 100\n```\n\n- Inputs:\n - prepared canary/train splits\n - candidate rewards\n - optional baseline rewards\n- Outputs:\n - `hardcases.jsonl`\n - `next_train_seed.jsonl`\n - `hardcase_summary.json`\n- Exit contract:\n - `0` = hardcases emitted\n - non-zero = missing inputs / parse errors\n\n## Recommended Harbor Flow Task Names\n\n1. `myflow-validate-snapshot`\n2. `myflow-build-reward-labels`\n3. `myflow-eval-canary`\n4. `myflow-mine-hardcases`\n\nUse these names in Harbor task orchestration so docs/runbooks stay stable.\n\n## Executed Verification (2026-02-18)\n\nExecuted end-to-end on a deterministic fixture snapshot:\n\n1. `prepare_myflow_dataset.py` (30 rows input)\n2. `myflow_validate_snapshot.py` -> `PASS`\n3. `myflow_build_reward_labels.py` -> labels generated\n4. `myflow_eval_canary.py` -> `Promotion gate: PASS`\n5. `myflow_mine_hardcases.py` -> hardcases + next seed generated\n\nArtifact root used during verification:\n\n- `/var/folders/.../tmp.5arfBojfhp/*` (temporary run directory)\n\n" }, { "path": "docs/rl-signal-capture-runbook.md", "content": "# RL Signal Capture Runbook (Flow + Seq)\n\nThis is the Phase 1 capture path for low-latency, high-signal RL data.\n\n## 1) Enable low-latency local seq capture\n\nFrom `~/code/seq`:\n\n```bash\nf rl-capture-on\nf agent-qa-capture-on\n```\n\nThis forces local spool mode (`SEQ_CH_MODE=file`) so user-path latency is not tied to remote network writes.\n\nOr from `~/code/flow` (single command):\n\n```bash\nf rl-capture-on-all\n```\n\n## 2) Enable flow RL signal logging\n\nFrom `~/code/flow`:\n\n```bash\nexport FLOW_RL_SIGNALS=true\nexport FLOW_RL_SIGNALS_PATH=out/logs/flow_rl_signals.jsonl\nexport FLOW_RL_SIGNALS_SEQ_MIRROR=true\nexport FLOW_RL_SIGNALS_SEQ_PATH=~/.config/flow/rl/seq_mem.jsonl\nexport FLOW_RL_SIGNAL_TEXT=snippet\nexport FLOW_RL_SIGNAL_MAX_CHARS=4000\n```\n\n`f ai everruns ...` now emits structured runtime/tool events into the JSONL file.\n`f ai:*` task execution via `ai-taskd` now also emits linked router events:\n\n- `flow.router.decision.v1`\n- `flow.router.override.v1` (when a suggested task differs from chosen task)\n- `flow.router.outcome.v1`\n\nThese are mirrored directly into `seq_mem.jsonl` when `FLOW_RL_SIGNALS_SEQ_MIRROR=true`.\n\nTo capture override events, set suggestion context on the command that triggers `f ai:*`:\n\n```bash\nexport FLOW_ROUTER_SUGGESTED_TASK=ai:flow/noop\nexport FLOW_ROUTER_OVERRIDE_REASON=manual_user_choice\nf ai:flow/dev-check\n```\n\n## 3) Inspect quality in real time\n\nFrom `~/code/flow`:\n\n```bash\nf rl-signals-tail\nf rl-signals-summary --last 2000\n```\n\nFrom `~/code/seq`:\n\n```bash\nf rl-signal-tail\nf rl-signal-summary\n```\n\n## 4) What should be present\n\n- `everruns.run_started`\n- `everruns.runtime_event` (includes stage + duration)\n- `everruns.tool_call_result` (includes seq op, success/failure, error class)\n- `everruns.qa_pair` (prompt/response supervision pair)\n- `everruns.run_completed` or `everruns.run_failed`\n- `agent.qa.pair` in `seq_mem.jsonl` (Claude/Codex Q/A pairs from background ingest)\n- `flow.router.decision.v1` in `seq_mem.jsonl`\n- `flow.router.override.v1` in `seq_mem.jsonl` (when suggestion context is provided)\n- `flow.router.outcome.v1` in `seq_mem.jsonl`\n\n## 5) Build Harbor snapshot from runtime traces\n\nFrom `~/code/flow`:\n\n```bash\nf rl-dataset-build\nf rl-dataset-validate\n```\n\nOutputs:\n\n- `~/repos/laude-institute/harbor/data/flow_runtime/<timestamp>/events.jsonl`\n- `~/repos/laude-institute/harbor/data/flow_runtime_prepared/<timestamp>/train.jsonl`\n- `~/repos/laude-institute/harbor/data/flow_runtime_prepared/<timestamp>/val.jsonl`\n- `~/repos/laude-institute/harbor/data/flow_runtime_prepared/<timestamp>/test.jsonl`\n- `~/repos/laude-institute/harbor/data/flow_runtime_prepared/<timestamp>/validation_report.json`\n\nLatest rolling copies are also written under `.../flow_runtime/latest` and `.../flow_runtime_prepared/latest`.\n\nIf capture is currently Q/A-only (`assistant_sft_example` rows), validation automatically relaxes event-diversity gates and still enforces row-count and basic quality checks.\n\n## 6) Feed into Harbor training loop\n\nKeep this file as raw trajectory telemetry; downstream pipelines should join with:\n\n- myflow commit/session exports\n- flow anon telemetry snapshots\n- reward labels / canary outcomes\n\nDo not train directly on raw logs without redaction + quality filtering.\n" }, { "path": "docs/run-repos.md", "content": "# Run Repos Shortcuts (`f r`, `f ri`, `f rp`, `f rip`)\n\nThis workflow lets you run Flow tasks in `~/run` and `~/run/i` from anywhere,\nwithout manual `cd`.\n\n## Standard Layout\n\n```text\n~/run/ # public run repo (has flow.toml)\n~/run/i/ # internal run repo (has flow.toml)\n~/run/i/linsa/ # nested internal project example\n```\n\n`f health` now ensures `~/run` and `~/run/i` directories exist.\n\nRoot behavior:\n- This is a hard path: run repos live under `~/run`.\n- `RUN_ROOT` can still override the root explicitly.\n\n## Primary Commands\n\n| Command | Meaning |\n|---|---|\n| `f r <task> [args...]` | Run task in `~/run` |\n| `f ri <task> [args...]` | Run task in `~/run/i` |\n| `f rp <project> <task> [args...]` | Run task in project under run tree |\n| `f rip <project> <task> [args...]` | Run task in `~/run/i/<project>` |\n\n## Resolution Rules\n\n`f rp <project> ...` resolves in this order:\n\n1. `~/run/<project>`\n2. `~/run/i/<project>` (fallback)\n\nIf both exist, Flow fails with an ambiguity error and asks for explicit path:\n\n- `f rp <project> ...` for public path\n- `f rp i/<project> ...` or `f rip <project> ...` for internal path\n\n## Nested Project Support\n\nNested `flow.toml` projects are supported. Example:\n\n```bash\nf rip linsa bootstrap\nf rp linsa opencode-codex-login\n```\n\nBoth target `~/run/i/linsa` (unless `~/run/linsa` also exists).\n\n## Why This Is Robust\n\n- Uses explicit `f run --config <dir>/flow.toml <task>` internally.\n- Avoids task-lookup ambiguity when nested `flow.toml` files exist.\n- Blocks unsafe paths (`/absolute`, `..` traversal) for run repo/project selectors.\n\n## Discovery and Maintenance\n\n```bash\nf run-list # list all flow.toml repos/projects under ~/run (recursive)\nf run-sync # sync all git repos under ~/run (recursive)\nf run-sync i # sync only ~/run/i\n```\n\n## Script Interface\n\nTask shortcuts are powered by:\n\n```bash\nscripts/run-repos.sh\n```\n\nDirect script commands:\n\n```bash\nbash ./scripts/run-repos.sh r <task> [args...]\nbash ./scripts/run-repos.sh ri <task> [args...]\nbash ./scripts/run-repos.sh rp <project> <task> [args...]\nbash ./scripts/run-repos.sh rip <project> <task> [args...]\n```\n\n`RUN_ROOT` can be overridden for testing:\n\n```bash\nRUN_ROOT=/tmp/my-run-layout f rp linsa whoami\n```\n" }, { "path": "docs/seq-agent-rpc-contract.md", "content": "# Seq Agent RPC Contract (Hard Interface)\n\nThis document defines the required interface between agent runtimes (Flow/AI server) and OS-level automation.\n\nStatus: **mandatory for new integrations**.\n\nIf an agent needs macOS UI/app/input actions, it must call `seqd` via the Rust `seq_client` library.\n\n## Why this is hard policy\n\n- Lowest control-plane overhead (persistent local Unix socket, no shell spawn per tool call).\n- Typed request/response contract with stable envelope fields.\n- Better observability (`request_id`, `run_id`, `tool_call_id`) across planner + OS executor.\n- Avoids drift from ad-hoc shell wrappers.\n\n## Required architecture\n\n1. Planner/agent loop runs in AI server.\n2. AI server uses `seq_client` (`~/code/seq/api/rust/seq_client`) for OS actions.\n3. `seq_client` sends JSON RPC v1 over Unix socket to `seqd`.\n4. `seqd` executes OS ops and returns typed response envelope.\n\nDo not insert shell wrappers in the hot path for OS actions.\n\n## Allowed and forbidden paths\n\nAllowed (required):\n- Rust: `seq_client::SeqClient` + `RpcRequest`.\n- Transport: Unix socket to `seqd` (`/tmp/seqd.sock` default).\n- Flow runtime bridge: `f seq-rpc ...` (internally uses native Rust socket RPC, no `seq rpc` subprocess).\n\nForbidden for production OS-tool execution:\n- `bash -lc \"seq ...\"` inside tool loop.\n- `curl`/`nc` direct JSON RPC from tool loop (okay for debugging only).\n- Parsing human text responses as protocol.\n\n## RPC envelope requirements\n\nEvery request should include:\n- `op`\n- `request_id`\n- `run_id`\n- `tool_call_id`\n\nThese IDs are required for trace joinability across:\n- agent run logs\n- tool-call logs\n- `seqd` metrics/traces\n\n## Operation mapping (agent tool -> seq op)\n\n- Open app: `open_app`\n- Toggle app: `open_app_toggle`\n- Run macro: `run_macro`\n- Click: `click`\n- Right click: `right_click`\n- Double click: `double_click`\n- Move mouse: `move`\n- Scroll: `scroll`\n- Drag: `drag`\n- Screenshot: `screenshot`\n- Runtime status: `ping`, `app_state`, `perf`\n\nSee canonical protocol details: `~/code/seq/docs/agent-rpc-v1.md`.\n\n## Reliability rules\n\n- Create one `SeqClient` per worker and reuse it.\n- Set explicit read/write timeout (`connect_with_timeout`).\n- Treat `ok=false` as tool failure (surface `error` field).\n- Retry policy:\n - Safe ops (`ping`, `app_state`, `perf`, maybe `screenshot`) may retry once.\n - Mutating UI ops (`click`, `drag`, `open_app`, `run_macro`) must not auto-retry blindly.\n- Max response size guard should remain enabled.\n\n## Latency policy\n\nHot path target is low latency at the control plane, not guaranteed zero end-to-end UI latency.\n\nExpectations:\n- RPC dispatch overhead should be microseconds to sub-millisecond locally.\n- UI/app activation latency depends on macOS/window server and target app state.\n\nBenchmark and regressions should measure:\n- request send/receive time at client\n- `dur_us` returned by `seqd`\n- operation-level tail latency (p95/p99)\n\n## Minimal integration example\n\n```rust\nuse seq_client::{RpcRequest, SeqClient};\nuse serde_json::json;\nuse std::time::Duration;\n\nfn call_open_app() -> Result<(), Box<dyn std::error::Error>> {\n let client = SeqClient::connect_with_timeout(\"/tmp/seqd.sock\", Duration::from_secs(5))?;\n let resp = client.call(\n RpcRequest::new(\"open_app\")\n .with_request_id(\"req-42\")\n .with_run_id(\"run-abc\")\n .with_tool_call_id(\"tool-7\")\n .with_args_json(json!({ \"name\": \"Safari\" })),\n )?;\n if !resp.ok {\n return Err(format!(\"seq open_app failed: {:?}\", resp.error).into());\n }\n Ok(())\n}\n```\n\n## Flow native command bridge (`f seq-rpc`)\n\nFor Flow-managed agent workloads, use `f seq-rpc` as the stable operator-facing interface.\nIt keeps protocol framing in Rust and avoids ad-hoc shell parsing of `seq` output.\n\nExamples:\n\n```bash\n# Health\nf seq-rpc ping --request-id req-1 --run-id run-1 --tool-call-id tool-1\n\n# Open app\nf seq-rpc open-app \"Safari\" --request-id req-2 --run-id run-1 --tool-call-id tool-2\n\n# Raw op + JSON args\nf seq-rpc rpc open_app --args-json '{\"name\":\"Google Chrome\"}' --pretty\n```\n\nDefault socket resolution order:\n\n1. `--socket <path>`\n2. `SEQ_SOCKET_PATH`\n3. `SEQD_SOCKET`\n4. `/tmp/seqd.sock`\n\n## Kimi smoke test (seq + agent workload)\n\n```bash\nAI_SERVER_URL=http://127.0.0.1:7331 \\\n~/code/org/gen/new/ai/scripts/ai-task.sh \\\n --provider nvidia \\\n --model moonshotai/kimi-k2.5 \\\n --project-path ~/code/flow \\\n --max-steps 6 \\\n --prompt \"Use bash tool once to run: f seq-rpc ping --request-id kimi-smoke --run-id run-smoke --tool-call-id tool-smoke; then summarize ok/op/dur_us.\"\n```\n\n## Migration checklist\n\n1. Replace shell-based OS tools with `seq_client`.\n2. For Flow command surfaces, prefer `f seq-rpc` (native Rust path) instead of `seq rpc`.\n3. Ensure all OS tool calls include `request_id`, `run_id`, `tool_call_id`.\n4. Remove ad-hoc JSON parsing of CLI stdout.\n5. Keep `seq rpc` / `nc` only for manual debugging and smoke tests.\n6. Gate new OS tool additions on this contract.\n" }, { "path": "docs/session-history-mining.md", "content": "# Session History Mining for Claude/Codex/Cursor\n\nUse this when you want an AI agent to study recent Claude/Codex/Cursor work before proposing a plan.\n\nThis is optimized for:\n- cross-project history review\n- low-noise context transfer\n- token efficiency (only new or condensed context)\n\n## What to Use\n\nUse Flow's cross-project session browser:\n\n```bash\nf sessions\n```\n\n`f sessions` scans Claude + Codex + Cursor sessions across projects, lets you pick one, and copies context to clipboard.\n\n## Core Commands\n\n```bash\n# List sessions across all projects without interactive selection\nf sessions --list\n\n# Only Claude sessions\nf sessions --provider claude --list\n\n# Only Codex sessions\nf sessions --provider codex --list\n\n# Only Cursor sessions\nf sessions --provider cursor --list\n\n# Copy selected session context (interactive picker via fzf)\nf sessions --provider all\n\n# Copy only the last N exchanges\nf sessions --provider all --count 8\n\n# Ignore checkpoints and copy full session\nf sessions --provider all --full\n\n# Produce a condensed handoff summary (requires Gemini key)\nf sessions --provider all --handoff\n```\n\n## Checkpoint Behavior (Important)\n\nDefault `f sessions` copies context since last consumption checkpoint for the current repo.\n\nThat means repeated runs do not keep re-copying old context.\n\nCheckpoint file:\n\n```text\n.ai/internal/consumed-checkpoints.json\n```\n\nUse `--full` when you explicitly want full history instead of incremental context.\n\n## Current-Repo Deep Pull (When Needed)\n\nIf you need more detail from a known session in the current repo:\n\n```bash\nf ai claude list\nf ai codex list\nf ai cursor list\n\n# Copy the last 6 exchanges from a selected Claude session for this repo\nf ai claude context - /absolute/path/to/repo 6\nf ai cursor context - /absolute/path/to/repo 6\n```\n\nUse this after `f sessions` when you want to zoom in on one thread.\n\n## Efficient Workflow (Recommended)\n\n1. In the target repo where you want the plan, run:\n `f sessions --provider all --list`\n2. Pull 2 to 4 high-signal contexts:\n `f sessions --provider claude --count 6`\n `f sessions --provider codex --count 6`\n `f sessions --provider cursor --count 6`\n3. For stale/long sessions, prefer condensed transfer:\n `f sessions --provider all --handoff`\n4. Paste each copied output into labeled blocks in your prompt.\n5. Ask for a plan with explicit constraints and ranked execution order.\n\n## Prompt Scaffold (Attach This)\n\nUse this format when asking an agent to mine history and propose execution:\n\n```text\nI have ~$500 of Claude tokens expiring in <N> day(s) and want to use them efficiently.\n\nGoal:\n- study goose and propose a concrete execution plan for token usage\n- use ideas from recent Claude/Codex/Cursor histories\n- rank ideas by expected impact and execution cost\n\nConstraints:\n- avoid low-signal exploration\n- maximize useful output per token\n- include exact next commands I should run\n\nSession context 1:\n<paste from f sessions --provider claude --count 6>\n\nSession context 2:\n<paste from f sessions --provider codex --count 6>\n\nSession context 3 (optional handoff):\n<paste from f sessions --provider all --handoff>\n\nSession context 4 (optional Cursor):\n<paste from f sessions --provider cursor --count 6>\n\nDeliver:\n1. top opportunities (ranked)\n2. 48-hour execution plan\n3. fallback plan if one assumption fails\n4. specific commands and owners\n```\n\n## Token-Efficiency Rules\n\n- Prefer `--count` over `--full` unless you are reconstructing full intent.\n- Prefer `--handoff` for large stale sessions before pasting into expensive models.\n- Cursor transcripts use file-modified time rather than per-message timestamps, so repeated copies may include the whole latest transcript after a new edit.\n- Merge duplicate context manually before sending to avoid repeated tokens.\n- Request ranked outputs with hard deliverables (plan, commands, owners, fallback).\n\n## Troubleshooting\n\n- `fzf not found`: install `fzf`, or use `--list` and then run interactive once `fzf` is available.\n- No new context copied: expected if checkpoint is current; rerun with `--full`.\n- `--handoff` not working: set `GEMINI_API_KEY` or `GOOGLE_API_KEY`.\n" }, { "path": "docs/session-semantic-recovery-with-seq.md", "content": "# Semantic Session Recovery with Seq (Claude/Codex)\n\nUse this when local Claude/Codex session state got wiped (for example after a machine reset), and you want to recover work by searching prior sessions semantically.\n\nThis workflow uses:\n- Flow session commands (`f ai ...`) for exact resume behavior\n- Seq's zvec-backed session index for semantic retrieval + fuzzy picker\n\n## What You Get\n\n- Fast semantic search over historical Claude/Codex Q/A pairs\n- Scope to the current repo path\n- Picker flow similar to Flow fuzzy task flows (`fzf`)\n- Direct resume command output:\n - `f ai claude resume <session-id>`\n - `f ai codex resume <session-id>`\n\n## Prerequisites\n\n1. `seq` repo exists at `~/code/seq`.\n2. Agent Q/A capture has data in `~/repos/alibaba/zvec/data/agent_qa.jsonl`.\n3. `fzf` installed for interactive picker.\n\n## One-Time Setup\n\nFrom `~/code/seq`:\n\n```bash\nf rl-capture-on\nf agent-qa-capture-on\n```\n\nIf you need historical backfill:\n\n```bash\nf agent-qa-capture-on-backfill\n```\n\nQuick status check:\n\n```bash\nf agent-qa-capture-status\n```\n\n## Primary Commands\n\nFrom `~/code/seq`:\n\n```bash\n# Semantic search + interactive picker + auto-resume\nf agent-session-search \"router regression around branch sync\"\n\n# Open picker with no query (recent-first)\nf agent-session-search\n\n# Non-interactive listing\nf agent-session-search-list \"skill sync force reload\"\n```\n\nProvider filter:\n\n```bash\nf agent-session-search --provider claude \"deploy rollback\"\nf agent-session-search --provider codex \"trace parser failure\"\n```\n\n## Use from Any Repo\n\nIf you are in another repo and want path-attached session search without changing directory:\n\n```bash\nf run --config ~/code/seq/flow.toml agent-session-search --path \"$(pwd)\" \"your query\"\n```\n\nList-only variant:\n\n```bash\nf run --config ~/code/seq/flow.toml agent-session-search-list --path \"$(pwd)\" \"your query\"\n```\n\n## Recovery Playbook After Reset\n\n1. Go to target repo:\n - `cd /path/to/repo`\n2. Run semantic search via Seq task:\n - `f run --config ~/code/seq/flow.toml agent-session-search --path \"$(pwd)\" \"<query>\"`\n3. Pick best session in `fzf`.\n4. Flow resumes exact session ID with strict provider behavior.\n5. If needed, inspect normal repo-local session list:\n - `f ai claude list`\n - `f ai codex list`\n\n## Troubleshooting\n\n- Repo path changed (rename/move):\n - Run `f code move-sessions --from /old/path --to /new/path`.\n - This migrates Claude/Codex session paths and Seq zvec `agent_qa.jsonl` metadata so folder-scoped semantic search still matches the new path.\n- No results:\n - Run `f agent-qa-capture-once --backfill --reset-state` in `~/code/seq`.\n- No picker:\n - Install `fzf`, or use `agent-session-search-list`.\n- Wrong scope:\n - Pass explicit `--path /absolute/repo/path`.\n" }, { "path": "docs/set-env-with-hive.md", "content": "# Set Env Vars with Hive\n\nThis doc shows how to use `hive` to store env vars in Flow’s **local personal** env store.\nThese values are global (not tied to a repo) and are later pulled during deploy.\n\n## Prereqs\n\n- `hive` installed (`f deploy` in `~/code/lang/mbt/hive`)\n- `env-help` installed (`f deploy-help` in `~/code/lang/mbt`)\n- Flow local env backend (default on this machine)\n\n## Recommended: editor-based paste (multi-line)\n\nThis opens your editor (Zed if installed, else nano), then saves and closes.\n\n```bash\nhive --paste env\n```\n\nPaste lines like:\n\n```bash\nSTREAM_SERVER_HETZNER_HOST=u533855.your-storagebox.de\nSTREAM_SERVER_HETZNER_USER=u533855\nSTREAM_SERVER_HETZNER_PATH=/backups/streams\nSTREAM_SERVER_HETZNER_PORT=23\n```\n\nSave and close the editor to apply.\n\n## One-liner (single line)\n\n```bash\nhive env STREAM_SERVER_HETZNER_HOST=u533855.your-storagebox.de STREAM_SERVER_HETZNER_USER=u533855 STREAM_SERVER_HETZNER_PATH=/backups/streams STREAM_SERVER_HETZNER_PORT=23\n```\n\n## Pipe (non-interactive)\n\n```bash\ncat <<'EOF' | hive --paste env\nSTREAM_SERVER_HETZNER_HOST=u533855.your-storagebox.de\nSTREAM_SERVER_HETZNER_USER=u533855\nSTREAM_SERVER_HETZNER_PATH=/backups/streams\nSTREAM_SERVER_HETZNER_PORT=23\nEOF\n```\n\n## Verify\n\n```bash\nf env list\n```\n\nThis lists envs in `personal` + `production` scope (values are masked).\n\n## Deploy using Flow env store\n\nFrom the repo using these envs (example: stream server):\n\n```bash\ncd ~/code/lang/cpp/stream\nf deploy host\n```\n\nFlow writes `/opt/stream/.env` on the host using the local env store.\n\n## Notes\n\n- Env vars are stored at:\n `~/.config/flow/env-local/personal/production.env`\n- Use `hive --paste env` whenever you need multi-line input.\n" }, { "path": "docs/task-failure-hooks.md", "content": "# Task Failure Hooks\n\nFlow can run a command automatically when a task fails. This is useful for\nopening a tailored prompt, collecting diagnostics, or launching a helper tool.\n\n## Overview\n\n- The hook runs after a task exits with a non-zero status.\n- The hook runs in the task's working directory.\n- The hook only runs when stdin is a TTY (no hook in non-interactive runs).\n- The hook is disabled when `FLOW_DISABLE_TASK_FAILURE_HOOK` is set.\n\n## Where The Hook Is Configured\n\nYou can set the hook in either place:\n\n1. Environment variable (highest priority):\n\n```bash\nexport FLOW_TASK_FAILURE_HOOK='rise work --errors --diff --patch --focus --focus-app lin --target codex \"fix $FLOW_TASK_NAME failure\"'\n```\n\n2. Global Flow config (generated file):\n\n- Edit `~/.config/lin/config.ts` and regenerate, or\n- Edit `~/.config/flow/config.ts` directly if you know it is safe to do so.\n\nExample entry in config:\n\n```ts\nexport default {\n flow: {\n taskFailureHook: \"rise work --errors --diff --patch --focus --focus-app lin --target codex \\\"fix $FLOW_TASK_NAME failure\\\"\"\n }\n}\n```\n\n## Command Execution Details\n\n- The hook is executed with `/bin/sh -c`.\n- The working directory is the task's `workdir` (the repo or task `cwd`).\n- The hook inherits stdin/stdout/stderr from the task runner.\n\n## Environment Variables Provided To The Hook\n\nFlow sets these environment variables when the hook runs:\n\n- `FLOW_TASK_NAME` (task name)\n- `FLOW_TASK_COMMAND` (command string)\n- `FLOW_TASK_WORKDIR` (absolute path)\n- `FLOW_TASK_STATUS` (exit code, or `-1` if unknown)\n- `FLOW_FAILURE_BUNDLE_PATH` (path to the last failure bundle)\n- `FLOW_TASK_OUTPUT_TAIL` (tail of task output, truncated)\n\n## Failure Bundle Location\n\nFlow writes a JSON failure bundle to one of these locations:\n\n- `FISHX_FAILURE_PATH` if set\n- `FLOW_FAILURE_BUNDLE_PATH` if set\n- `~/.cache/flow/last-task-failure.json` (default)\n\nThe resolved path is passed to hooks via `FLOW_FAILURE_BUNDLE_PATH`.\n\n## Disabling The Hook\n\nSet the following env var:\n\n```bash\nexport FLOW_DISABLE_TASK_FAILURE_HOOK=1\n```\n\n## Rise / Zed Behavior\n\nIf your hook calls `rise work`, Flow automatically appends `--no-open` and strips\n`--focus` / `--focus-app` unless you explicitly allow opening. This prevents Zed\nor other apps from launching on every failure.\n\nTo allow the open behavior:\n\n```bash\nexport FLOW_TASK_FAILURE_HOOK_ALLOW_OPEN=1\n```\n\n## Example Hook\n\n```bash\nexport FLOW_TASK_FAILURE_HOOK='rise work --errors --diff --patch --focus --focus-app lin --target codex \"fix $FLOW_TASK_NAME failure\"'\n```\n\nThis will write prompts to `.rise/prompts/` and focus the codex prompt without\nopening Zed by default.\n" }, { "path": "docs/usage-analytics-rollout.md", "content": "# Flow Anonymous Usage Tracking (Zero Cost) - Implementation Checklist\n\nThis is the execution plan to add opt-in anonymous usage tracking to Flow with near-zero runtime overhead.\n\n## Goals\n\n- Default off (or unknown until prompt), explicit user opt-in.\n- No sensitive data (no prompts, no command values, no paths, no repo names).\n- Command runtime must not block on network.\n- Ingest through `base` trace API and store in a separate ClickHouse instance.\n\n## Data Contract (anonymous only)\n\nEvent kind: `flow.command`\n\nAllowed fields:\n\n- `install_id` (random UUID, local)\n- `command_path` (e.g. `commit`, `skills.sync`, `setup.deploy`)\n- `success` (`true/false`)\n- `exit_code` (integer or null)\n- `duration_ms` (integer)\n- `flags_used` (flag names only; e.g. `[\"sync\",\"context\"]`)\n- `flow_version`\n- `os`, `arch`\n- `interactive` (`true/false`)\n- `ci` (`true/false`)\n- `project_fingerprint` (optional HMAC; never raw path/remote)\n- `at` timestamp\n\nForbidden fields:\n\n- prompts, command strings, args values, paths, repo URL/name, output.\n\n## Patch Order\n\n### Phase 1: Local capture + opt-in state (Flow only)\n\n1. Add `src/usage.rs`\n - `UsageConfigState` (enabled/disabled/unknown, install_id, secret, last_prompt_at).\n - local queue file: `~/.config/flow/usage-queue.jsonl`.\n - append-only write API: `record_command_event(...)`.\n - sanitize and normalize command path + flag names.\n2. Add config support in `src/config.rs`\n - `[analytics]` config:\n - `enabled` (`true/false` optional)\n - `endpoint` (default `http://127.0.0.1:7331/v1/trace`)\n - `sample_rate` (default `1.0`)\n3. Hook command lifecycle in `src/main.rs`\n - capture start timestamp before dispatch.\n - on return/error, emit one event through `usage::record_command_event`.\n - never fail command if analytics fails.\n4. Add command group in `src/cli.rs` and handler in new `src/analytics.rs`\n - `f analytics status`\n - `f analytics enable`\n - `f analytics disable`\n - `f analytics export`\n - `f analytics purge`\n5. Wire module exports in `src/lib.rs` and command dispatch in `src/main.rs`.\n\nValidation:\n\n```bash\ncd ~/code/flow\ncargo check\ncargo run --bin f -- analytics status\n```\n\n### Phase 2: Opt-in UX\n\n1. In `src/main.rs`, after first successful interactive command:\n - if state is `unknown` and non-CI, prompt once:\n - \"Enable anonymous usage tracking to improve Flow? [y/N/later]\"\n2. Persist response to `~/.config/flow/analytics.toml`.\n3. Add env overrides:\n - `FLOW_ANALYTICS_FORCE=1` (self-test)\n - `FLOW_ANALYTICS_DISABLE=1` (hard off)\n\nValidation:\n\n```bash\nFLOW_ANALYTICS_FORCE=1 cargo run --bin f -- tasks\ncargo run --bin f -- analytics status\n```\n\n### Phase 3: Async uploader (still in Flow)\n\n1. In `src/usage.rs` add `flush_queue_async()`\n - background thread\n - small batches (50-200)\n - short HTTP timeout (<=500ms)\n - retries with backoff\n2. Upload target defaults to base trace endpoint:\n - `http://127.0.0.1:7331/v1/trace`\n3. Add spool safety:\n - max queue bytes (e.g. 10MB), oldest-drop policy.\n\nValidation:\n\n```bash\nf analytics status\n# run a few commands\nf tasks\nf skills list\n# then flush\nf analytics export\n```\n\n### Phase 4: Base ingest + dedicated ClickHouse\n\nImplement using `base` doc `docs/flow-usage-tracking.md` (added in parallel).\n\n### Phase 5: Read path and dashboards\n\n1. Extend `seqch` in `~/code/org/linsa/base/crates/seqch-cli/src/main.rs`\n - new top-level area: `flow`\n - commands:\n - `seqch flow commands --hours 24`\n - `seqch flow flags --hours 24`\n - `seqch flow failures --hours 24`\n2. Add starter SQL dashboards:\n - command usage over time\n - adoption funnel (`unknown -> enabled`)\n - failures by command\n\n## Self-Test Rollout\n\n1. Enable only for yourself:\n - `FLOW_ANALYTICS_FORCE=1`\n2. Verify no sensitive fields in payload samples (`f analytics export`).\n3. Verify ingestion into separate CH instance.\n4. After 3-7 days, turn prompt on for all users (still opt-in).\n\n## Acceptance Criteria\n\n- P50 added runtime overhead per command < 1ms local.\n- Command success path unaffected by network or ingest failures.\n- No sensitive strings in stored events (spot-check samples).\n- Able to answer:\n - top-used commands\n - least-used commands\n - failure hotspots by command path.\n" }, { "path": "docs/use-flow-to-write-software-better.md", "content": "# Use Flow To Write Software Better\n\nThis is a practical, opinionated guide for using Flow as the control plane for software delivery, optimized for Claude Code and Codex.\n\nThe goal is simple: tighter feedback loops, fewer regressions, less context loss, and consistent quality gates.\n\n---\n\n## 1. Core idea: one operating loop\n\nDo not treat Flow as just a task runner. Use it as the enforced loop:\n\n1. Start with project context and reusable skills.\n2. Implement in Claude/Codex with task-native commands.\n3. Run the smallest meaningful tests first.\n4. Capture traces/logs when behavior is unclear.\n5. Commit through `f commit` with quality/testing/skill gates.\n6. Ship through Flow tasks, not ad hoc commands.\n\nIf you do this consistently, team behavior becomes predictable and AI sessions become reliable.\n\n---\n\n## 2. Machine baseline (once per machine)\n\nRun these first:\n\n```bash\nf doctor\nf auth login\nf latest\n```\n\nWhat this gives you:\n\n- verified shell and toolchain integration\n- authenticated Flow AI and storage access\n- latest Flow binary with current command behavior\n\nIf you use fish integration heavily:\n\n```bash\nf shell-init\n```\n\n---\n\n## 3. Project baseline (once per repo)\n\nFrom the repository root:\n\n```bash\nf info\nf tasks list\nf setup\n```\n\nIf project is not Flow-managed yet:\n\n```bash\nf init\n```\n\nThen immediately add these foundations to `flow.toml`:\n\n- `[skills]` and `[skills.codex]`\n- `[commit.testing]`\n- `[commit.quality]`\n- `[commit.skill_gate]`\n- core tasks (`test`, `test-related`, build, dev, deploy/ship)\n\n---\n\n## 4. Reference `flow.toml` pattern (AI-first, quality-enforced)\n\nUse this as a starting profile and adjust per repo:\n\n```toml\nversion = 1\n\n[project]\nname = \"your-project\"\n\n[skills]\nsync_tasks = true\ninstall = [\"quality-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n\n[[tasks]]\nname = \"test\"\ncommand = \"<your test command>\"\ndescription = \"Run project tests\"\n\n[[tasks]]\nname = \"test-related\"\ncommand = \"<script that runs likely related tests>\"\ndescription = \"Run smallest related tests for changed files\"\n\n[commit]\nreview_instructions_file = \".ai/commit-review-instructions.md\"\n\n[commit.testing]\nmode = \"block\" # off | warn | block\nrunner = \"bun\" # Bun-first local gate\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\" # optional gitignored AI scratch tests\nrun_ai_scratch_tests = true # run scratch tests when no related tracked tests\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 30\n\n[commit.quality]\nmode = \"block\"\nrequire_docs = true\nrequire_tests = true\nauto_generate_docs = true\ndoc_level = \"basic\"\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-feature-delivery\"]\n```\n\nWhy this matters:\n\n- `sync_tasks` + Codex skill generation makes tasks visible as skills.\n- blocked commit gates make quality non-optional.\n- related-test enforcement keeps the loop fast and relevant.\n\n---\n\n## 5. Daily development loop (the part that compounds)\n\n### 5.1 Start every session from repo root\n\n```bash\ncd <repo>\nf tasks list\n```\n\nThen choose one clear objective and one validation command before coding.\n\n### 5.2 Drive execution through tasks\n\nPrefer:\n\n```bash\nf dev\nf test-related\nf logs <task>\n```\n\nAvoid direct, inconsistent commands when equivalent Flow tasks exist.\n\n### 5.3 Use Claude/Codex with explicit constraints\n\nYour prompt should include:\n\n- objective\n- files or subsystem boundaries\n- required tests\n- expected output shape\n- “commit through `f commit` without skip flags”\n\nExample prompt frame:\n\n```text\nImplement X in Y files.\nRun f test-related-main first, then broader tests if needed.\nUpdate .ai/features for user-visible changes.\nCommit using f commit with no skip flags.\n```\n\n### 5.4 Keep loop tight before broad\n\nOrder of validation:\n\n1. related tests (`f test-related` / branch-based variant)\n2. subsystem suite\n3. full suite only if risk justifies\n\n### 5.5 Commit only through `f commit`\n\n```bash\nf commit\n```\n\nThis centralizes:\n\n- AI review\n- test/doc quality checks\n- feature documentation updates\n- sync/audit metadata\n\nDo not bypass with `--skip-quality` or `--skip-tests` unless explicitly intentional.\n\n---\n\n## 6. Features-as-knowledge (`.ai/features`)\n\nTreat `.ai/features/*.md` as the source of truth for what exists.\n\nEach user-visible feature should map to:\n\n- purpose/description\n- source files\n- test files\n- coverage status\n- last verified commit\n\nWhy this is high leverage:\n\n- new AI sessions start with real project capabilities\n- stale feature docs are detectable at commit time\n- dashboard/reporting can track drift and coverage\n\n---\n\n## 7. Skills as enforced behavior (not optional tips)\n\nUse local skills for repo-specific “how we build here”.\n\nRecommended minimum skill set:\n\n1. quality feature delivery (tests + docs + commit gates)\n2. environment/secret usage (`f env` only)\n3. release/ship protocol\n4. tracing/diagnostics protocol\n\nThen enforce with:\n\n```toml\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-feature-delivery\"]\n```\n\nThis is how you convert good intentions into default behavior.\n\n---\n\n## 8. Testing strategy for speed and confidence\n\n### 8.1 Two test lanes\n\n- lane A: very fast related tests for development iterations\n- lane B: broader suite for pre-ship confidence\n\n### 8.2 Make lane A deterministic\n\nUse a script (like `.ai/scripts/test-related.ts`) that:\n\n- maps changed source files to candidate tests\n- supports `--base origin/main --head HEAD`\n- can list commands without running (`--list`)\n- runs the smallest useful subset first\n\n### 8.3 Add preflight guards for expensive runners\n\nIf your runner fails due environment prerequisites (toolchain/vendor issues), add a preflight task:\n\n- `f <runner>-ready`\n- optional auto-repair task `f <runner>-fix`\n\nThis avoids burning minutes before obvious infra failures.\n\n---\n\n## 9. Logging and tracing loop\n\nWhen behavior is unclear, switch from “guess and patch” to “observe and patch”:\n\n1. run the target task via Flow\n2. inspect `f logs <task>`\n3. collect traces (`f trace` / project-specific trace tasks)\n4. summarize signal before changing code\n\nThe best pattern is “capture once, reason once, patch once.”\n\n---\n\n## 10. Environment and secrets discipline\n\nUse `f env` as the single path for secrets and runtime env management:\n\n```bash\nf env setup\nf env set KEY=value\nf env pull\nf env run <command>\n```\n\nAvoid ad hoc `.env` drift across machines.\n\n---\n\n## 11. Shipping loop (release confidence)\n\nFor deployment or mobile shipping flows, define one confidence task that runs before release:\n\n- health checks\n- trace ingestion checks\n- critical smoke test\n- related tests for release-impact files\n\nThen make ship task depend on that confidence task.\n\nExample:\n\n```text\nf mobile-confidence -> f mobile-ship\n```\n\nResult: broken pipelines fail before expensive release steps.\n\n---\n\n## 12. Existing project onboarding (high-value sequence)\n\nWhen adding Flow to an existing repo, use this order:\n\n1. add `flow.toml` with core tasks\n2. add env management (`[storage]` + `f env` flow)\n3. add related-test task/script\n4. add commit testing + quality + skill gates in warn mode\n5. validate for 2-3 days\n6. flip to block mode\n7. add `.ai/features` for top capabilities\n\nThis avoids destabilizing the team while still moving to enforcement.\n\n---\n\n## 13. Prompt templates that work better\n\n### Implementation prompt\n\n```text\nImplement <feature> in <scope>.\nUse Flow tasks only (no ad hoc commands when task exists).\nRun related tests first, then broaden if risk warrants.\nUpdate .ai/features for user-visible behavior changes.\nCommit with f commit (no skip flags).\n```\n\n### Debugging prompt\n\n```text\nDo not patch yet.\nCollect logs/traces via Flow tasks and summarize likely root causes.\nPropose smallest validating experiment.\nAfter confirmation, implement fix + related tests + feature doc update.\nCommit via f commit.\n```\n\n### Refactor prompt\n\n```text\nRefactor <module> without behavior changes.\nKeep public API stable.\nRun focused tests proving no regression.\nDocument any non-obvious migration risks.\nCommit via f commit.\n```\n\n---\n\n## 14. Anti-patterns to avoid\n\n1. Running direct commands repeatedly when Flow tasks exist.\n2. Treating tests as optional before `f commit`.\n3. Using skip flags routinely.\n4. Writing prompts without required validation commands.\n5. Keeping feature docs as manual, stale notes.\n6. Debugging by repeated blind edits instead of trace/log loop.\n\n---\n\n## 15. Operational checklists\n\n### Start-of-day checklist\n\n1. `f latest` (if Flow changed frequently)\n2. `f tasks list`\n3. `f ai` / `f codex` / `f claude` resume context\n4. confirm one objective + one validation command\n\n### Pre-commit checklist\n\n1. related tests pass\n2. feature docs updated (`.ai/features`)\n3. no quality gate bypass intended\n4. `f commit`\n\n### Pre-ship checklist\n\n1. confidence task passes\n2. relevant traces/logs clean\n3. release task run through Flow\n\n---\n\n## 16. Maturity model (how teams level up)\n\n### Level 1: Convenience\n\n- tasks run through `f`\n- basic env usage\n\n### Level 2: Consistency\n\n- related test task\n- shared review instructions\n- reusable skills\n\n### Level 3: Enforcement\n\n- blocked testing/quality gates\n- blocked skill gate\n- `.ai/features` as living capability map\n\n### Level 4: Observability-driven\n\n- preflight + confidence tasks\n- trace-first debugging\n- structured release checks\n\nAim to reach Level 3 quickly, then Level 4 where release speed and reliability both improve.\n\n---\n\n## 17. Practical defaults for Codex/Claude-heavy teams\n\nUse these defaults unless you have a reason not to:\n\n- `commit.testing.mode = \"block\"`\n- `commit.quality.mode = \"block\"`\n- `commit.skill_gate.mode = \"block\"`\n- `skills.sync_tasks = true`\n- `skills.codex.generate_openai_yaml = true`\n- `skills.codex.force_reload_after_sync = true`\n- branch-diff related tests (`--base origin/main --head HEAD`)\n\nThis gives the highest consistency with the least manual memory burden.\n\n---\n\n## 18. Bottom line\n\nFlow works best when it is the enforced operating system for development, not an optional helper.\n\nIf you route implementation, testing, docs, commit review, and shipping through Flow, you get:\n\n- faster iteration\n- lower regression rates\n- shared project memory for humans and AI\n- auditable delivery quality\n\nThat is the path to writing software better, repeatedly.\n" }, { "path": "docs/vendor-code-intelligence.md", "content": "# Vendor Code Intelligence (Typesense)\n\nThis document defines the crates-focused equivalent of `opensrc` for Flow vendoring.\n\n## Goal\n\nKeep Cargo as resolver/build authority while adding very fast local search across:\n\n- first-party code (`src`, `crates`, `scripts`, `docs`, `tests`),\n- vendored crates (`lib/vendor/*`),\n- source metadata (`lib/vendor-manifest/*.toml` + `vendor.lock.toml`).\n\nThis gives AI and humans a fast map of \"what code do we own right now?\" without remote lookups.\n\n## Why This Exists\n\nVendoring gives full control, but it increases local code volume.\nWithout a fast index, trim/rewrite/sync loops become slower.\n\nTypesense indexing solves that by keeping an always-queryable local code/search layer.\n\n## Commands\n\nStart local Typesense (shared launcher in `~/code/infra/base`):\n\n```bash\nf vendor-typesense-setup # one-time install in flox if needed\nf vendor-typesense-up\nf vendor-typesense-status\n```\n\nBuild index:\n\n```bash\nf vendor-code-index\n```\n\nSearch code chunks:\n\n```bash\nf vendor-code-search \"Router\"\nf vendor-code-search \"serde_json\" --scope vendor --crate reqwest\nf vendor-code-search \"spawn\" --scope firstparty --lang rs\n```\n\nSearch source inventory:\n\n```bash\nf vendor-code-search-sources \"ratatui\"\nf vendor-code-search-sources \"github.com\" --limit 50\n```\n\nInspect raw inventory:\n\n```bash\nf vendor-code-sources\n```\n\n## Data Model\n\nThe index script (`scripts/vendor/typesense_code_index.py`) writes:\n\n- `.vendor/typesense/sources.json`:\n - opensrc-style local source inventory for vendored + first-party scopes.\n- Typesense `<prefix>_sources` collection:\n - per source (crate/repo) metadata: name, version, materialized path, upstream, checksum.\n- Typesense `<prefix>_chunks` collection:\n - chunked code text + path + scope + crate + symbols + line ranges.\n\nDefault prefix is `flow_code`, so the default collections are:\n\n- `flow_code_sources`\n- `flow_code_chunks`\n\n## How It Stays Aligned With Upstream\n\n`vendor.lock.toml` is the canonical vendored crate set.\n`lib/vendor-manifest/*.toml` is the per-crate provenance and sync state.\n\nThe index script reads both, so every `inhouse/sync/hydrate` cycle can be followed by:\n\n```bash\nf vendor-code-index\n```\n\nThis keeps search aligned with the exact pinned state currently compiled by Cargo.\n\n## Operational Loop\n\n1. Sync or inhouse crates (`vendor-control.sh`, `scripts/vendor/sync-*`).\n2. Re-index (`f vendor-code-index`).\n3. Search for dead APIs/deps/macros and trim targets (`f vendor-code-search ...`).\n4. Validate (`cargo check`, vendoring verify gates).\n5. Commit source churn in `flow-vendor`, pin updates in `flow`.\n\n## Notes\n\n- The indexer is local-first and does not replace Cargo metadata.\n- Use `--dry-run` for large experiments before writing collections.\n- Use `--max-files` for quick smoke indexing in CI/debug runs.\n" }, { "path": "docs/vendor-nix-inspiration.md", "content": "# Nix Ideas In Cargo-First Vendoring\n\nThis vendoring model does not replace Cargo with Nix, but it borrows core Nix ideas\nto get reproducibility, control, and fast iteration.\n\n## What We Borrow\n\n### 1. Pinned, immutable inputs\n\n- `vendor.lock.toml` pins vendored source by exact commit.\n- `Cargo.lock` pins resolved crate versions.\n- CI/local hydrate from pinned state, not floating latest.\n\nNix analogy: flake/lock pinning exact inputs.\n\n### 2. Content/provenance tracking\n\n- `lib/vendor-manifest/<crate>.toml` records checksums and upstream metadata.\n- `verify --strict-provenance` enforces provenance completeness.\n\nNix analogy: content-addressed trust and auditable input provenance.\n\n### 3. Declarative materialization\n\n- `scripts/vendor/vendor-repo.sh hydrate` materializes `lib/vendor/*` from lock state.\n- Build uses explicit path patches in `Cargo.toml`.\n\nNix analogy: declarative store realization from a locked graph.\n\n### 4. Transactional updates and rollback safety\n\n- `vendor-control.sh inhouse` snapshots and rolls back on failure.\n- Vendor pin can be moved back to a known good commit.\n\nNix analogy: atomic generation switch + rollback.\n\n### 5. Source ownership as a separate store\n\n- source churn lives in `flow-vendor`,\n- product wiring and pins live in `flow`.\n\nNix analogy: separate immutable store objects from top-level project logic.\n\n### 6. Minimize closure size\n\n- remove unused features/deps/macros from vendored crates,\n- track duplicate versions and offender crates (`cargo tree -d`, `offenders.sh`).\n\nNix analogy: reducing closure size to speed builds and improve iteration.\n\n## Why This Matters For Our Goals\n\n- Faster compile/iteration: smaller dependency surface, less macro/dependency overhead.\n- Full control: direct edits in vendored crates when needed.\n- Reliable upstream sync: scripted update loop with lock pinning and provenance checks.\n- Reproducible builds: same vendored commit + same lockfile => same source graph.\n\n## Practical Loop\n\n```bash\n~/code/rise/scripts/vendor-control.sh sync --project ~/code/flow -- --important --dry-run\n~/code/rise/scripts/vendor-control.sh sync --project ~/code/flow -- --important\n~/code/rise/scripts/vendor-control.sh verify --project ~/code/flow --strict-provenance\nscripts/vendor/vendor-repo.sh hydrate\ncargo check -q\n```\n\nThis gives a Nix-like operational discipline while preserving Cargo ecosystem behavior.\n" }, { "path": "docs/vendor-optimization-loop.md", "content": "# Vendor Optimization Loop\n\nThis is the practical loop for aggressively optimizing dependencies in `flow`\nwhile keeping Cargo correctness and upstream sync reliability.\n\n## Goals\n\n- find and fix vendoring rough edges early,\n- rank high-impact dependency offenders,\n- track compile-iteration speed improvements over time.\n\n## Commands\n\n```bash\nf update-deps --dry-run\nf vendor-trims\nf vendor-rough-audit\nf vendor-offenders\nf vendor-bench-iter -- --mode incremental --samples 3\n```\n\nOne-command loop:\n\n```bash\nf vendor-optimize-loop\n```\n\nStrict mode (warnings fail):\n\n```bash\nf vendor-optimize-loop -- --strict\n```\n\n## What Each Tool Checks\n\n`vendor-rough-audit` (`scripts/vendor/rough_edges_audit.py`) checks:\n\n- lock/manifests/materialized crate path consistency,\n- Cargo patch wiring vs `vendor.lock.toml`,\n- vendored crate resolution in `Cargo.lock` (no registry source),\n- provenance fields in manifests (`history_head`, `upstream_repository`),\n- stale code index detection (`.vendor/typesense/sources.json` freshness),\n- extra drift artifacts (`lib/vendor/*` or patch entries not in lock).\n- warning-hygiene regressions in vendored crates that would reintroduce noisy\n release-build warnings.\n\n`vendor-offenders` (`scripts/vendor/offenders.sh`) shows:\n\n- direct dependencies ranked by transitive tree size,\n- duplicate version pressure (`cargo tree -d`),\n- proc-macro footprint.\n\n`vendor-bench-iter` (`scripts/vendor/bench_iteration.py`) provides:\n\n- repeated timing samples for a compile command (default `cargo check -q`),\n- rolling comparison against prior runs from `out/vendor/iteration_bench.jsonl`,\n- optional fail threshold for gating regressions.\n\n## Output Artifacts\n\n- `out/vendor/rough_edges_audit.txt`\n- `out/vendor/offenders_latest.txt`\n- `out/vendor/iteration_bench.jsonl`\n\nThese files make optimization work reviewable and repeatable across sessions.\n\n## Suggested Weekly Cadence\n\n1. `f vendor-optimize-loop -- --strict --samples 2`\n2. Pick top 1-2 offender crates.\n3. Apply trim/rewrite changes.\n4. Re-run loop.\n5. Confirm no new rough-edge findings.\n6. Confirm compile iteration trend improves or stays flat.\n7. Confirm upstream sync remains clean (`scripts/vendor/sync-all.sh --important --dry-run`).\n" }, { "path": "flow.py", "content": "#!/usr/bin/env python3\n\"\"\"\nFlow CLI - Demonstrate swarms in action\n\nUsage:\n flow single \"Your question here\"\n flow sequential \"Research topic\"\n flow concurrent \"Analysis task\"\n flow hierarchical \"Complex project\"\n flow rearrange \"Creative task\"\n flow chat \"Discussion topic\"\n flow auto \"Task description\"\n\"\"\"\n\nimport argparse\nimport sys\nfrom rich.console import Console\nfrom rich.panel import Panel\nfrom rich.markdown import Markdown\n\nconsole = Console()\n\n\ndef demo_single(task: str, model: str = \"gpt-4o-mini\"):\n \"\"\"Run a single agent on a task.\"\"\"\n from swarms import Agent\n\n console.print(Panel(f\"[bold cyan]Single Agent Demo[/bold cyan]\\nTask: {task}\"))\n\n agent = Agent(\n agent_name=\"Assistant\",\n model_name=model,\n max_loops=1,\n streaming=True,\n )\n\n console.print(\"\\n[yellow]Agent thinking...[/yellow]\\n\")\n response = agent.run(task)\n console.print(Panel(Markdown(response), title=\"[green]Response[/green]\"))\n\n\ndef demo_sequential(task: str, model: str = \"gpt-4o-mini\"):\n \"\"\"Run a sequential workflow: Researcher -> Analyst -> Writer.\"\"\"\n from swarms import Agent, SequentialWorkflow\n\n console.print(Panel(f\"[bold cyan]Sequential Workflow Demo[/bold cyan]\\n\"\n f\"Pipeline: Researcher -> Analyst -> Writer\\n\"\n f\"Task: {task}\"))\n\n researcher = Agent(\n agent_name=\"Researcher\",\n system_prompt=\"You are a thorough researcher. Investigate the topic and provide detailed findings with sources and data.\",\n model_name=model,\n max_loops=1,\n )\n\n analyst = Agent(\n agent_name=\"Analyst\",\n system_prompt=\"You are an analytical expert. Take the research provided and identify key patterns, insights, and implications.\",\n model_name=model,\n max_loops=1,\n )\n\n writer = Agent(\n agent_name=\"Writer\",\n system_prompt=\"You are a skilled writer. Take the analysis and create a clear, engaging summary with actionable conclusions.\",\n model_name=model,\n max_loops=1,\n )\n\n workflow = SequentialWorkflow(agents=[researcher, analyst, writer])\n\n console.print(\"\\n[yellow]Running pipeline...[/yellow]\\n\")\n result = workflow.run(task)\n console.print(Panel(Markdown(str(result)), title=\"[green]Final Output[/green]\"))\n\n\ndef demo_concurrent(task: str, model: str = \"gpt-4o-mini\"):\n \"\"\"Run agents concurrently with different perspectives.\"\"\"\n from swarms import Agent, ConcurrentWorkflow\n\n console.print(Panel(f\"[bold cyan]Concurrent Workflow Demo[/bold cyan]\\n\"\n f\"Running 3 agents in parallel with different perspectives\\n\"\n f\"Task: {task}\"))\n\n optimist = Agent(\n agent_name=\"Optimist\",\n system_prompt=\"You see opportunities and positive outcomes. Analyze from an optimistic perspective, highlighting benefits and potential.\",\n model_name=model,\n max_loops=1,\n )\n\n critic = Agent(\n agent_name=\"Critic\",\n system_prompt=\"You identify risks and challenges. Analyze from a critical perspective, highlighting potential problems and concerns.\",\n model_name=model,\n max_loops=1,\n )\n\n pragmatist = Agent(\n agent_name=\"Pragmatist\",\n system_prompt=\"You focus on practical implementation. Analyze from a pragmatic perspective, highlighting actionable steps and trade-offs.\",\n model_name=model,\n max_loops=1,\n )\n\n workflow = ConcurrentWorkflow(agents=[optimist, critic, pragmatist])\n\n console.print(\"\\n[yellow]Running agents in parallel...[/yellow]\\n\")\n results = workflow.run(task)\n\n for agent_name, output in results.items():\n console.print(Panel(Markdown(str(output)), title=f\"[green]{agent_name}[/green]\"))\n\n\ndef demo_hierarchical(task: str, model: str = \"gpt-4o-mini\"):\n \"\"\"Run a hierarchical swarm with a director and workers.\"\"\"\n from swarms import Agent, HierarchicalSwarm\n\n console.print(Panel(f\"[bold cyan]Hierarchical Swarm Demo[/bold cyan]\\n\"\n f\"Director assigns tasks to specialized workers\\n\"\n f\"Task: {task}\"))\n\n planner = Agent(\n agent_name=\"Planner\",\n system_prompt=\"You create detailed project plans and break down complex tasks into actionable steps.\",\n model_name=model,\n max_loops=1,\n )\n\n executor = Agent(\n agent_name=\"Executor\",\n system_prompt=\"You implement plans and execute tasks efficiently, providing concrete outputs.\",\n model_name=model,\n max_loops=1,\n )\n\n reviewer = Agent(\n agent_name=\"Reviewer\",\n system_prompt=\"You review work for quality, completeness, and suggest improvements.\",\n model_name=model,\n max_loops=1,\n )\n\n swarm = HierarchicalSwarm(\n name=\"Project-Team\",\n description=\"A team that plans, executes, and reviews work\",\n agents=[planner, executor, reviewer],\n max_loops=1,\n )\n\n console.print(\"\\n[yellow]Swarm working...[/yellow]\\n\")\n result = swarm.run(task)\n console.print(Panel(Markdown(str(result)), title=\"[green]Team Output[/green]\"))\n\n\ndef demo_rearrange(task: str, model: str = \"gpt-4o-mini\"):\n \"\"\"Run agent rearrange with custom flow patterns.\"\"\"\n from swarms import Agent, AgentRearrange\n\n console.print(Panel(f\"[bold cyan]Agent Rearrange Demo[/bold cyan]\\n\"\n f\"Flow: idea -> designer, developer -> integrator\\n\"\n f\"Task: {task}\"))\n\n idea = Agent(\n agent_name=\"idea\",\n system_prompt=\"You generate creative ideas and concepts. Brainstorm possibilities.\",\n model_name=model,\n max_loops=1,\n )\n\n designer = Agent(\n agent_name=\"designer\",\n system_prompt=\"You design user experiences and visual concepts based on ideas provided.\",\n model_name=model,\n max_loops=1,\n )\n\n developer = Agent(\n agent_name=\"developer\",\n system_prompt=\"You think about technical implementation and architecture based on ideas provided.\",\n model_name=model,\n max_loops=1,\n )\n\n integrator = Agent(\n agent_name=\"integrator\",\n system_prompt=\"You synthesize design and development perspectives into a cohesive plan.\",\n model_name=model,\n max_loops=1,\n )\n\n # idea sends to both designer and developer, both send to integrator\n flow = \"idea -> designer, developer -> integrator\"\n\n rearrange = AgentRearrange(\n agents=[idea, designer, developer, integrator],\n flow=flow,\n )\n\n console.print(\"\\n[yellow]Agents coordinating...[/yellow]\\n\")\n result = rearrange.run(task)\n console.print(Panel(Markdown(str(result)), title=\"[green]Integrated Output[/green]\"))\n\n\ndef demo_chat(topic: str, model: str = \"gpt-4o-mini\", rounds: int = 3):\n \"\"\"Run a group chat discussion.\"\"\"\n from swarms import Agent, GroupChat\n\n console.print(Panel(f\"[bold cyan]Group Chat Demo[/bold cyan]\\n\"\n f\"3 experts discussing for {rounds} rounds\\n\"\n f\"Topic: {topic}\"))\n\n scientist = Agent(\n agent_name=\"Scientist\",\n system_prompt=\"You are a scientist who values evidence and empirical data. Contribute scientific perspectives to discussions.\",\n model_name=model,\n max_loops=1,\n )\n\n philosopher = Agent(\n agent_name=\"Philosopher\",\n system_prompt=\"You are a philosopher who explores ethical and conceptual dimensions. Contribute philosophical perspectives.\",\n model_name=model,\n max_loops=1,\n )\n\n engineer = Agent(\n agent_name=\"Engineer\",\n system_prompt=\"You are an engineer focused on practical solutions. Contribute engineering perspectives.\",\n model_name=model,\n max_loops=1,\n )\n\n chat = GroupChat(\n name=\"Expert-Panel\",\n description=\"A panel of experts discussing complex topics\",\n agents=[scientist, philosopher, engineer],\n max_loops=rounds,\n )\n\n console.print(\"\\n[yellow]Discussion starting...[/yellow]\\n\")\n result = chat.run(f\"Let's discuss: {topic}\")\n console.print(Panel(Markdown(str(result)), title=\"[green]Discussion Summary[/green]\"))\n\n\ndef demo_auto(task: str, model: str = \"gpt-4o-mini\"):\n \"\"\"Auto-generate a swarm for a task.\"\"\"\n from swarms.structs.auto_swarm_builder import AutoSwarmBuilder\n import json\n\n console.print(Panel(f\"[bold cyan]Auto Swarm Builder Demo[/bold cyan]\\n\"\n f\"Automatically generates specialized agents\\n\"\n f\"Task: {task}\"))\n\n swarm = AutoSwarmBuilder(\n name=\"Auto-Generated-Swarm\",\n description=\"Automatically built swarm for the task\",\n verbose=True,\n max_loops=1,\n model_name=model,\n )\n\n console.print(\"\\n[yellow]Building and running swarm...[/yellow]\\n\")\n result = swarm.run(task=task)\n\n if isinstance(result, dict):\n console.print(Panel(json.dumps(result, indent=2), title=\"[green]Swarm Output[/green]\"))\n else:\n console.print(Panel(Markdown(str(result)), title=\"[green]Swarm Output[/green]\"))\n\n\ndef main():\n parser = argparse.ArgumentParser(\n description=\"Flow CLI - Demonstrate swarms in action\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n flow single \"What is quantum computing?\"\n flow sequential \"Research the future of renewable energy\"\n flow concurrent \"Analyze the pros and cons of remote work\"\n flow hierarchical \"Plan a mobile app launch strategy\"\n flow rearrange \"Design a new productivity tool\"\n flow chat \"The impact of AI on society\"\n flow auto \"Create a team to analyze cryptocurrency trends\"\n \"\"\"\n )\n\n parser.add_argument(\n \"--model\", \"-m\",\n default=\"gpt-4o-mini\",\n help=\"Model to use (default: gpt-4o-mini)\"\n )\n\n subparsers = parser.add_subparsers(dest=\"command\", help=\"Demo type\")\n\n # Single agent\n single_parser = subparsers.add_parser(\"single\", help=\"Single agent demo\")\n single_parser.add_argument(\"task\", help=\"Task for the agent\")\n\n # Sequential workflow\n seq_parser = subparsers.add_parser(\"sequential\", help=\"Sequential workflow (Researcher -> Analyst -> Writer)\")\n seq_parser.add_argument(\"task\", help=\"Topic to research and write about\")\n\n # Concurrent workflow\n conc_parser = subparsers.add_parser(\"concurrent\", help=\"Concurrent agents (Optimist, Critic, Pragmatist)\")\n conc_parser.add_argument(\"task\", help=\"Task to analyze from multiple perspectives\")\n\n # Hierarchical swarm\n hier_parser = subparsers.add_parser(\"hierarchical\", help=\"Hierarchical swarm (Director with workers)\")\n hier_parser.add_argument(\"task\", help=\"Complex project to coordinate\")\n\n # Agent rearrange\n rear_parser = subparsers.add_parser(\"rearrange\", help=\"Agent rearrange with custom flow\")\n rear_parser.add_argument(\"task\", help=\"Creative task for the flow\")\n\n # Group chat\n chat_parser = subparsers.add_parser(\"chat\", help=\"Group chat discussion\")\n chat_parser.add_argument(\"topic\", help=\"Topic to discuss\")\n chat_parser.add_argument(\"--rounds\", \"-r\", type=int, default=3, help=\"Discussion rounds (default: 3)\")\n\n # Auto swarm builder\n auto_parser = subparsers.add_parser(\"auto\", help=\"Auto-generate a swarm\")\n auto_parser.add_argument(\"task\", help=\"Task description for auto-generated swarm\")\n\n args = parser.parse_args()\n\n if not args.command:\n parser.print_help()\n sys.exit(0)\n\n console.print(f\"\\n[dim]Using model: {args.model}[/dim]\\n\")\n\n try:\n if args.command == \"single\":\n demo_single(args.task, args.model)\n elif args.command == \"sequential\":\n demo_sequential(args.task, args.model)\n elif args.command == \"concurrent\":\n demo_concurrent(args.task, args.model)\n elif args.command == \"hierarchical\":\n demo_hierarchical(args.task, args.model)\n elif args.command == \"rearrange\":\n demo_rearrange(args.task, args.model)\n elif args.command == \"chat\":\n demo_chat(args.topic, args.model, args.rounds)\n elif args.command == \"auto\":\n demo_auto(args.task, args.model)\n except KeyboardInterrupt:\n console.print(\"\\n[red]Interrupted[/red]\")\n sys.exit(1)\n except Exception as e:\n console.print(f\"\\n[red]Error: {e}[/red]\")\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "flow.toml", "content": "version = 1\nname = \"flow\"\n\n[agents]\nreview-agent = \"nikivdev:review-agent\"\n\n[flow]\nprimary_task = \"deploy\"\ndeploy_task = \"deploy\"\nrelease_task = \"release\"\n\n[options]\n# Enable gitedit.dev mirroring for commits\ngitedit_mirror = true\n# Enable gitedit.dev mirroring for commitWithCheck\ncommit_with_check_gitedit_mirror = true\n# Larger default review window for big diffs during `f commit`.\ncommit_with_check_timeout_secs = 300\ngitedit_url = \"https://gitedit.dev\"\ncommit_with_check_review_url = \"http://100.114.156.47:3000/review\"\n# Enable myflow.sh mirroring for commits\nmyflow_mirror = true\n\n[commit]\nqueue = true\nqueue_on_issues = true\n\n[jj]\ndefault_branch = \"main\"\nremote = \"origin\"\nauto_track = true\nreview_prefix = \"review\"\n\n[release]\n# Default release provider for `f release`.\ndefault = \"registry\"\n# Use calendar versioning for registry releases (YYYY.M.D).\nversioning = \"calver\"\n# Set these to your release host values.\ndomain = \"flow.yourdomain.com\"\nbase_url = \"https://flow.yourdomain.com\"\nroot = \"/var/www/flow\"\ncaddyfile = \"/etc/caddy/Caddyfile\"\nreadme = \"readme.md\"\n\n[release.registry]\nurl = \"https://myflow.sh\"\npackage = \"flow\"\nbins = [\"f\", \"lin\"]\ndefault_bin = \"f\"\ntoken_env = \"FLOW_REGISTRY_TOKEN\"\nlatest = true\n\n[flox]\n[flox.install]\ncargo.pkg-path = \"cargo\"\neza.pkg-path = \"eza\"\n\n[[tasks]]\nname = \"setup\"\ncommand = \"cargo check\"\ndescription = \"Compile the workspace to make sure the toolchain works\"\nactivate_on_cd_to_root = true\n\n[[tasks]]\nname = \"test\"\ncommand = \"cargo test\"\ndescription = \"Run the full test suite for a basic sanity check\"\n\n[[tasks]]\nname = \"which-cargo\"\ncommand = \"which cargo && cargo --version\"\ndescription = \"Confirm cargo is coming from the managed toolchain\"\ndependencies = [\"cargo\"]\n\n[[tasks]]\nname = \"test-deps\"\ncommand = \"tsx tests/deps.ts\"\ndescription = \"Run the e2e managed-deps test script\"\n\n[[tasks]]\nname = \"dev-hub\"\ncommand = \"cargo run -- hub start\"\ndescription = \"Ensure the hub daemon is running locally\"\n\n[[tasks]]\nname = \"generate-help-full-json\"\ncommand = \"python3 ./scripts/generate_help_full_json.py\"\ndescription = \"Regenerate the embedded --help-full JSON cache.\"\n\n[[tasks]]\nname = \"deps-check\"\ncommand = \"python3 ./scripts/deps_check.py $@\"\ndescription = \"Check vendored and workspace Cargo deps against the latest upstream releases.\"\n\n[[tasks]]\nname = \"deploy-cli-release\"\ncommand = \"FLOW_PROFILE=release ./scripts/deploy.sh\"\ndescription = \"Build the CLI/daemon with --release and copy the binary to ~/.local/bin/flow\"\n\n[[tasks]]\nname = \"deploy\"\ncommand = \"FLOW_PROFILE=release ./scripts/deploy.sh\"\ndescription = \"Build the CLI/daemon with --release and copy the binary to ~/.local/bin/flow\"\n\n[[tasks]]\nname = \"deploy-traces\"\ncommand = \"FLOW_PROFILE=release ./scripts/deploy.sh\"\ndescription = \"Deploy CLI with traces updates (f traces)\"\n\n[[tasks]]\nname = \"rl-signals-tail\"\ncommand = \"sh -lc \\\"mkdir -p out/logs && touch ${FLOW_RL_SIGNALS_PATH:-out/logs/flow_rl_signals.jsonl} && tail -f ${FLOW_RL_SIGNALS_PATH:-out/logs/flow_rl_signals.jsonl}\\\"\"\ndescription = \"Follow structured RL signal events emitted by flow runtime.\"\n\n[[tasks]]\nname = \"rl-signals-summary\"\ncommand = \"python3 ./scripts/rl_signal_summary.py ${FLOW_RL_SIGNALS_PATH:-out/logs/flow_rl_signals.jsonl} $@\"\ndescription = \"Summarize RL signal counts, errors, and latency percentiles.\"\n\n[[tasks]]\nname = \"rl-dataset-build\"\ncommand = \"python3 ./scripts/build_rl_runtime_dataset.py --harbor-dir ${HARBOR_DIR:-$HOME/repos/laude-institute/harbor} --flow-signals ${FLOW_RL_SIGNALS_PATH:-out/logs/flow_rl_signals.jsonl} --seq-mem ${SEQ_CH_MEM_PATH:-$HOME/.config/flow/rl/seq_mem.jsonl} --write-latest $@\"\ndescription = \"Build Harbor-ready RL dataset snapshot from flow+seq runtime signals.\"\n\n[[tasks]]\nname = \"rl-dataset-validate\"\ncommand = \"python3 -c \\\"import json, os, pathlib, sys; root = pathlib.Path(os.path.expanduser(os.environ.get('HARBOR_DIR', '~/repos/laude-institute/harbor'))); p = root / 'data' / 'flow_runtime_prepared' / 'latest' / 'validation_report.json'; (print(f'missing validation report: {p}') or sys.exit(1)) if not p.exists() else None; obj = json.loads(p.read_text(encoding='utf-8')); print(json.dumps(obj, indent=2)); sys.exit(0 if obj.get('ok') else 1)\\\"\"\ndescription = \"Print and enforce latest RL dataset validation report.\"\n\n[[tasks]]\nname = \"rl-capture-on-all\"\ncommand = \"sh -lc \\\"cd $HOME/code/seq && f rl-capture-on && f agent-qa-capture-on && f agent-qa-capture-status\\\"\"\ndescription = \"Enable seq low-latency capture + always-on Claude/Codex Q/A ingest.\"\n\n[[tasks]]\nname = \"rl-capture-status\"\ncommand = \"sh -lc \\\"cd $HOME/code/seq && f agent-qa-capture-status && f rl-signal-summary --last ${LAST:-5000}\\\"\"\ndescription = \"Show seq Q/A ingest status and current high-signal event density.\"\n\n[[tasks]]\nname = \"rl-capture-logs\"\ncommand = \"sh -lc \\\"cd $HOME/code/seq && f agent-qa-capture-logs\\\"\"\ndescription = \"Tail background Claude/Codex Q/A ingest daemon logs from seq.\"\n\n[[tasks]]\nname = \"deploy-with-hub-reload\"\ncommand = \"FLOW_PROFILE=release ./scripts/deploy.sh && f hub stop && FLOW_DOCS_FOCUS=1 f hub\"\ndescription = \"Deploy and restart hub daemons (lin + docs)\"\n\n[[tasks]]\nname = \"release-build\"\ncommand = \"bash ./scripts/package-release.sh\"\ndescription = \"Build signed release artifacts into dist/ (set FLOW_VERSION, CODESIGN_IDENTITY env vars as needed)\"\n\n[[tasks]]\nname = \"release\"\ncommand = \"./scripts/release.sh\"\ndescription = \"Build darwin/arm64 release, publish to host, update install snippet\"\n\n[[tasks]]\nname = \"release-host-setup\"\ncommand = \"infra release setup --path .\"\ndescription = \"Install Caddy and configure a release host (uses infra host set + [release])\"\n\n[[tasks]]\nname = \"release-publish\"\ncommand = \"bash -c 'tarball=$(ls -t dist/flow_*_darwin_arm64.tar.gz | head -n1) && infra release publish \\\"$tarball\\\" --path .'\"\ndescription = \"Upload the latest darwin/arm64 release tarball to the release host\"\n\n[[tasks]]\nname = \"verify-install-latest-release\"\ncommand = \"bash ./scripts/verify-install-latest-release.sh\"\ndescription = \"Verify that curl -fsSL https://myflow.sh/install.sh | sh installs the current latest stable release in a fresh temp HOME\"\n\n[[tasks]]\nname = \"ci-blacksmith-status\"\ncommand = \"python3 ./scripts/ci_blacksmith.py status\"\ndescription = \"Show CI runner mode for canary/release workflows (github, blacksmith, or host)\"\n\n[[tasks]]\nname = \"ci-blacksmith-enable\"\ncommand = \"python3 ./scripts/ci_blacksmith.py enable\"\ndescription = \"Switch Linux CI lanes to Blacksmith runners and enable Linux host SIMD job\"\n\n[[tasks]]\nname = \"ci-blacksmith-enable-apply\"\ncommand = \"python3 ./scripts/ci_blacksmith.py enable --commit --push\"\ndescription = \"Enable Blacksmith CI mode, commit workflow updates, and push\"\n\n[[tasks]]\nname = \"ci-blacksmith-disable\"\ncommand = \"python3 ./scripts/ci_blacksmith.py disable\"\ndescription = \"Switch CI back to GitHub-hosted Linux runners and disable Linux host SIMD job\"\n\n[[tasks]]\nname = \"ci-blacksmith-disable-apply\"\ncommand = \"python3 ./scripts/ci_blacksmith.py disable --commit --push\"\ndescription = \"Disable Blacksmith CI mode, commit workflow updates, and push\"\n\n[[tasks]]\nname = \"ci-host-enable\"\ncommand = \"python3 ./scripts/ci_blacksmith.py host\"\ndescription = \"Keep standard Linux CI lanes on GitHub runners, but enable Linux host SIMD build on ci-1focus self-hosted runner\"\n\n[[tasks]]\nname = \"ci-host-enable-apply\"\ncommand = \"python3 ./scripts/ci_blacksmith.py host --commit --push\"\ndescription = \"Enable host SIMD CI mode, commit workflow updates, and push\"\n\n[[tasks]]\nname = \"ci-host-runner-status\"\ncommand = \"python3 ./scripts/ci_host_runner.py status --repo nikivdev/flow\"\ndescription = \"Show ci-1focus runner service status on infra host and GitHub runner registration state\"\n\n[[tasks]]\nname = \"ci-host-runner-install\"\ncommand = \"python3 ./scripts/ci_host_runner.py install --repo nikivdev/flow\"\ndescription = \"Install/register self-hosted GitHub runner on configured infra Linux host (label: ci-1focus)\"\n\n[[tasks]]\nname = \"ci-host-runner-remove\"\ncommand = \"python3 ./scripts/ci_host_runner.py remove --repo nikivdev/flow\"\ndescription = \"Unregister ci-1focus self-hosted GitHub runner and remove runner service on infra host\"\n\n[[tasks]]\nname = \"ci-host-bootstrap\"\ncommand = \"python3 ./scripts/ci_host_runner.py install --repo nikivdev/flow && python3 ./scripts/ci_blacksmith.py host\"\ndescription = \"One-command setup: install ci-1focus runner on infra host and switch workflows to host SIMD mode\"\n\n[[tasks]]\nname = \"ci-host-bootstrap-apply\"\ncommand = \"python3 ./scripts/ci_host_runner.py install --repo nikivdev/flow && python3 ./scripts/ci_blacksmith.py host --commit --push\"\ndescription = \"Install ci-1focus runner, switch workflows to host SIMD mode, then commit and push workflow updates\"\n\n[[tasks]]\nname = \"ci-host-setup\"\ncommand = \"bash ./scripts/ci_host_setup.sh $@\"\ndescription = \"One command to set up ci.1focus.ai runner and switch workflows to host mode (optionally pass user@ip)\"\n\n[[tasks]]\nname = \"vendor-typesense-up\"\ncommand = \"bash -lc 'cd \\\"$HOME/code/infra/base\\\" && ./scripts/typesense.sh up'\"\ndescription = \"Start local Typesense via infra/base shared launcher\"\n\n[[tasks]]\nname = \"vendor-typesense-setup\"\ncommand = \"bash -lc 'cd \\\"$HOME/code/infra/base\\\" && ./scripts/typesense-flox-setup.sh'\"\ndescription = \"One-time setup for local Typesense via flox in infra/base\"\n\n[[tasks]]\nname = \"vendor-typesense-down\"\ncommand = \"bash -lc 'cd \\\"$HOME/code/infra/base\\\" && ./scripts/typesense.sh down'\"\ndescription = \"Stop local Typesense via infra/base shared launcher\"\n\n[[tasks]]\nname = \"vendor-typesense-status\"\ncommand = \"bash -lc 'cd \\\"$HOME/code/infra/base\\\" && ./scripts/typesense.sh status'\"\ndescription = \"Show local Typesense status via infra/base shared launcher\"\n\n[[tasks]]\nname = \"vendor-typesense-logs\"\ncommand = \"bash -lc 'cd \\\"$HOME/code/infra/base\\\" && ./scripts/typesense.sh logs'\"\ndescription = \"Tail local Typesense logs via infra/base shared launcher\"\n\n[[tasks]]\nname = \"vendor-code-sources\"\ncommand = \"python3 ./scripts/vendor/typesense_code_index.py --project . sources $@\"\ndescription = \"Print opensrc-style source inventory for first-party + vendored crates\"\n\n[[tasks]]\nname = \"vendor-code-index\"\ncommand = \"python3 ./scripts/vendor/typesense_code_index.py --project . index $@\"\ndescription = \"Index first-party and vendored code chunks into Typesense\"\n\n[[tasks]]\nname = \"vendor-code-search\"\ncommand = \"python3 ./scripts/vendor/typesense_code_index.py --project . search $@\"\ndescription = \"Search indexed code (chunks by default) with optional scope/crate/lang filters\"\n\n[[tasks]]\nname = \"vendor-code-search-sources\"\ncommand = \"python3 ./scripts/vendor/typesense_code_index.py --project . search --collection sources $@\"\ndescription = \"Search source inventory metadata (crate/version/path/upstream)\"\n\n[[tasks]]\nname = \"vendor-trims\"\ncommand = \"bash ./scripts/vendor/apply-trims.sh $@\"\ndescription = \"Apply deterministic trim + warning-hygiene patches to vendored crates\"\n\n[[tasks]]\nname = \"vendor-rough-audit\"\ncommand = \"python3 ./scripts/vendor/rough_edges_audit.py --project . $@\"\ndescription = \"Audit vendoring rough edges (lock/manifest/patch/provenance/index freshness)\"\n\n[[tasks]]\nname = \"vendor-rough-audit-strict\"\ncommand = \"python3 ./scripts/vendor/rough_edges_audit.py --project . --strict-warnings $@\"\ndescription = \"Strict vendoring audit: warnings fail (good for pre-merge hardening)\"\n\n[[tasks]]\nname = \"vendor-offenders\"\ncommand = \"bash ./scripts/vendor/offenders.sh\"\ndescription = \"Rank dependency offenders by tree size and show duplicate-version pressure\"\n\n[[tasks]]\nname = \"vendor-bench-iter\"\ncommand = \"python3 ./scripts/vendor/bench_iteration.py --project . $@\"\ndescription = \"Record compile-iteration benchmark samples to out/vendor/iteration_bench.jsonl\"\n\n[[tasks]]\nname = \"vendor-optimize-loop\"\ncommand = \"bash ./scripts/vendor/optimize_loop.sh $@\"\ndescription = \"Run audit + offender scan + iteration benchmark in one command\"\n\n[[tasks]]\nname = \"update-deps\"\ncommand = \"bash ./scripts/vendor/update-deps.sh $@\"\ndescription = \"One-command dependency refresh: sync vendored crates to latest, trim/harden, pin vendor lock, and validate\"\n\n[[tasks]]\nname = \"test-flow-task-tracing\"\ncommand = \"bun i-run.ts\"\n\n[[tasks]]\nname = \"test-flow-server-tracing\"\ncommand = \"bun i-server.ts\"\n\n[[tasks]]\nname = \"test-log-server\"\ncommand = \"bun tests/test_log_server.ts\"\ndescription = \"Test log ingestion and query endpoints (requires 'f server' running)\"\n\n[[tasks]]\nname = \"bench-ai-runtime\"\ncommand = \"python3 ./scripts/bench-ai-runtime.py $@\"\ndescription = \"Benchmark MoonBit AI task runtime paths (moon-run vs cached vs daemon)\"\n\n[[tasks]]\nname = \"bench-cli-startup\"\ncommand = \"python3 ./scripts/bench-cli-startup.py $@\"\ndescription = \"Benchmark Flow CLI startup and cheap read-only command latency\"\n\n[[tasks]]\nname = \"bench-cli-gate\"\ncommand = \"sh -lc 'CARGO_INCREMENTAL=0 cargo build --release --bin f && python3 ./scripts/bench-cli-startup.py --flow-bin ./target/release/f --json-out ./out/bench/cli-startup.json \\\"$@\\\" && python3 ./scripts/check_cli_startup_thresholds.py ./out/bench/cli-startup.json' -- $@\"\ndescription = \"Benchmark release CLI startup and fail if repository latency thresholds regress.\"\n\n[[tasks]]\nname = \"bench-ffi-boundary\"\ncommand = \"python3 ./scripts/bench-moonbit-rust-ffi.py $@\"\ndescription = \"Benchmark MoonBit <-> Rust FFI boundary ns/op overhead\"\n\n[[tasks]]\nname = \"myflow-commit-session-smoke\"\ncommand = \"bash ./scripts/myflow-commit-session-smoke.sh $@\"\ndescription = \"Verify commit sync to myflow and attached Claude/Codex sessions for a repo/commit.\"\nshortcuts = [\"mcss\"]\n\n[[tasks]]\nname = \"install-ai-fast-client\"\ncommand = \"mkdir -p \\\"$HOME/.local/bin\\\" && cargo build --release -p ai-taskd-client --bin ai-taskd-client && install -m 755 ./target/release/ai-taskd-client \\\"$HOME/.local/bin/fai\\\"\"\ndescription = \"Install low-latency ai-taskd client as ~/.local/bin/fai\"\n\n[[tasks]]\nname = \"ai-taskd-launchd-install\"\ncommand = \"python3 ./scripts/ai-taskd-launchd.py install\"\ndescription = \"Install always-on ai-taskd launch agent (launchd)\"\n\n[[tasks]]\nname = \"ai-taskd-launchd-uninstall\"\ncommand = \"python3 ./scripts/ai-taskd-launchd.py uninstall\"\ndescription = \"Remove ai-taskd launch agent (launchd)\"\n\n[[tasks]]\nname = \"ai-taskd-launchd-status\"\ncommand = \"python3 ./scripts/ai-taskd-launchd.py status\"\ndescription = \"Show ai-taskd launch agent status\"\n\n[[tasks]]\nname = \"ai-taskd-launchd-logs\"\ncommand = \"python3 ./scripts/ai-taskd-launchd.py logs $@\"\ndescription = \"Show ai-taskd launch agent logs\"\n\n[[tasks]]\nname = \"codex-skill-eval-launchd-install\"\ncommand = \"python3 ./scripts/codex-skill-eval-launchd.py install $@\"\ndescription = \"Install scheduled Codex skill-eval scorecard refresh (launchd)\"\n\n[[tasks]]\nname = \"codex-skill-eval-launchd-uninstall\"\ncommand = \"python3 ./scripts/codex-skill-eval-launchd.py uninstall\"\ndescription = \"Remove scheduled Codex skill-eval scorecard refresh (launchd)\"\n\n[[tasks]]\nname = \"codex-skill-eval-launchd-status\"\ncommand = \"python3 ./scripts/codex-skill-eval-launchd.py status\"\ndescription = \"Show scheduled Codex skill-eval launch agent status\"\n\n[[tasks]]\nname = \"codex-skill-eval-launchd-logs\"\ncommand = \"python3 ./scripts/codex-skill-eval-launchd.py logs $@\"\ndescription = \"Show scheduled Codex skill-eval launch agent logs\"\n\n[[tasks]]\nname = \"codex-telemetry-status\"\ncommand = \"f codex telemetry status $@\"\ndescription = \"Show optional redacted Codex telemetry export state\"\n\n[[tasks]]\nname = \"codex-telemetry-flush\"\ncommand = \"f codex telemetry flush $@\"\ndescription = \"Flush unseen redacted Codex telemetry to configured Maple endpoints once\"\n\n[[tasks]]\nname = \"test-args\"\ncommand = \"echo \\\"arg1=$1 arg2=$2 all=$@\\\"\"\ndescription = \"Test that task args are passed correctly\"\n\n[[tasks]]\nname = \"clone-test-repo\"\ncommand = \"git clone https://github.com/nikivdev/flow-testing testing/flow-testing\"\ndescription = \"Clone the flow-testing repo into testing/\"\n\n[[tasks]]\nname = \"agents\"\ncommand = \"bash ./scripts/agents-switch.sh $@\"\ndescription = \"Switch agents.md profile in a repo\"\ninteractive = true\n\n[[tasks]]\nname = \"run-root\"\ncommand = \"bash ./scripts/run-repos.sh root\"\ndescription = \"Print run repo root path (default: ~/run)\"\n\n[[tasks]]\nname = \"run-ensure\"\ncommand = \"bash ./scripts/run-repos.sh ensure\"\ndescription = \"Ensure local run repo root exists\"\n\n[[tasks]]\nname = \"run-list\"\ncommand = \"bash ./scripts/run-repos.sh list\"\ndescription = \"List run repos under ~/run (flow.toml + git metadata)\"\n\n[[tasks]]\nname = \"run-load\"\ncommand = \"bash ./scripts/run-repos.sh load $@\"\ndescription = \"Clone or update a run repo. Usage: f run-load <name> <repo-ssh-url> [branch]\"\n\n[[tasks]]\nname = \"run-sync\"\ncommand = \"bash ./scripts/run-repos.sh sync $@\"\ndescription = \"Sync run repo(s). Usage: f run-sync [name]\"\n\n[[tasks]]\nname = \"run-task\"\ncommand = \"bash ./scripts/run-repos.sh task $@\"\ndescription = \"Run a Flow task inside a run repo. Usage: f run-task <name> <task> [args...]\"\n\n[[tasks]]\nname = \"run-exec\"\ncommand = \"bash ./scripts/run-repos.sh exec $@\"\ndescription = \"Ensure run repo exists (clone/sync) and run a task. Usage: f run-exec <name> <repo-ssh-url> [--branch <branch>] <task> [args...]\"\n\n[[tasks]]\nname = \"run-ri\"\ncommand = \"bash ./scripts/run-repos.sh ri $@\"\ndescription = \"Run a task in the internal run repo (~/run/i). Usage: f ri <task> [args...]\"\nshortcuts = [\"ri\"]\n\n[[tasks]]\nname = \"run-r\"\ncommand = \"bash ./scripts/run-repos.sh r $@\"\ndescription = \"Run a task in the public run repo (~/run). Usage: f r <task> [args...]\"\nshortcuts = [\"r\"]\n\n[[tasks]]\nname = \"run-rp\"\ncommand = \"bash ./scripts/run-repos.sh rp $@\"\ndescription = \"Run a task in a run project. Usage: f rp <project> <task> [args...] (resolves ~/run/<project> or ~/run/i/<project>)\"\nshortcuts = [\"rp\"]\n\n[[tasks]]\nname = \"run-rip\"\ncommand = \"bash ./scripts/run-repos.sh rip $@\"\ndescription = \"Run a task in an internal run project. Usage: f rip <project> <task> [args...] (maps to ~/run/i/<project>)\"\nshortcuts = [\"rip\"]\n\n[storage]\nprovider = \"myflow.sh\"\nenv_var = \"FLOW_SECRETS_TOKEN\" # optional; defaults to this value\n\n[[storage.envs]]\nname = \"local\"\ndescription = \"Local development defaults\"\nvariables = [\n { key = \"DATABASE_URL\", default = \"\" },\n { key = \"OPENAI_API_KEY\", default = \"\" },\n { key = \"ANTHROPIC_API_KEY\", default = \"\" },\n { key = \"FLOW_RL_SIGNALS\", default = \"true\" },\n { key = \"FLOW_RL_SIGNALS_PATH\", default = \"out/logs/flow_rl_signals.jsonl\" },\n { key = \"FLOW_RL_SIGNALS_SEQ_MIRROR\", default = \"true\" },\n { key = \"FLOW_RL_SIGNALS_SEQ_PATH\", default = \"~/.config/flow/rl/seq_mem.jsonl\" },\n { key = \"FLOW_ROUTER_SUGGESTED_TASK\", default = \"\" },\n { key = \"FLOW_ROUTER_OVERRIDE_REASON\", default = \"\" },\n { key = \"FLOW_RL_SIGNAL_TEXT\", default = \"snippet\" },\n { key = \"FLOW_RL_SIGNAL_MAX_CHARS\", default = \"4000\" },\n { key = \"FLOW_CODEX_MAPLE_LOCAL_ENDPOINT\", default = \"\" },\n { key = \"FLOW_CODEX_MAPLE_LOCAL_INGEST_KEY\", default = \"\" },\n { key = \"FLOW_CODEX_MAPLE_HOSTED_ENDPOINT\", default = \"\" },\n { key = \"FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY\", default = \"\" },\n { key = \"FLOW_CODEX_MAPLE_HOSTED_PUBLIC_INGEST_KEY\", default = \"\" },\n { key = \"FLOW_CODEX_MAPLE_TRACES_ENDPOINTS\", default = \"\" },\n { key = \"FLOW_CODEX_MAPLE_INGEST_KEYS\", default = \"\" },\n { key = \"FLOW_CODEX_MAPLE_SERVICE_NAME\", default = \"flow-codex\" },\n { key = \"FLOW_CODEX_MAPLE_SERVICE_VERSION\", default = \"\" },\n { key = \"FLOW_CODEX_MAPLE_SCOPE_NAME\", default = \"flow.codex\" },\n { key = \"FLOW_CODEX_MAPLE_ENV\", default = \"local\" },\n { key = \"FLOW_CODEX_MAPLE_QUEUE_CAPACITY\", default = \"1024\" },\n { key = \"FLOW_CODEX_MAPLE_MAX_BATCH_SIZE\", default = \"64\" },\n { key = \"FLOW_CODEX_MAPLE_FLUSH_INTERVAL_MS\", default = \"100\" },\n { key = \"FLOW_CODEX_MAPLE_CONNECT_TIMEOUT_MS\", default = \"400\" },\n { key = \"FLOW_CODEX_MAPLE_REQUEST_TIMEOUT_MS\", default = \"800\" },\n { key = \"MAPLE_API_TOKEN\", default = \"\" },\n { key = \"MAPLE_MCP_URL\", default = \"https://api.maple.dev/mcp\" },\n { key = \"SEQ_CH_MEM_PATH\", default = \"~/.config/flow/rl/seq_mem.jsonl\" },\n { key = \"HARBOR_DIR\", default = \"~/repos/laude-institute/harbor\" },\n]\n\n# ============================================================================\n# Swarm Demo Tasks - Run with: uv run flow <command> \"<task>\"\n# ============================================================================\n\n[[tasks]]\nname = \"swarm-single\"\ncommand = \"uv run flow.py single \\\"$@\\\"\"\ndescription = \"Single agent demo\"\n\n[[tasks]]\nname = \"swarm-seq\"\ncommand = \"uv run flow.py sequential \\\"$@\\\"\"\ndescription = \"Sequential workflow (Researcher -> Analyst -> Writer)\"\n\n[[tasks]]\nname = \"swarm-parallel\"\ncommand = \"uv run flow.py concurrent \\\"$@\\\"\"\ndescription = \"Concurrent agents (Optimist, Critic, Pragmatist)\"\n\n[[tasks]]\nname = \"swarm-hier\"\ncommand = \"uv run flow.py hierarchical \\\"$@\\\"\"\ndescription = \"Hierarchical swarm (Director with workers)\"\n\n[[tasks]]\nname = \"swarm-rearrange\"\ncommand = \"uv run flow.py rearrange \\\"$@\\\"\"\ndescription = \"Agent rearrange with custom flow\"\n\n[[tasks]]\nname = \"swarm-chat\"\ncommand = \"uv run flow.py chat \\\"$@\\\"\"\ndescription = \"Group chat discussion\"\n\n[[tasks]]\nname = \"swarm-auto\"\ncommand = \"uv run flow.py auto \\\"$@\\\"\"\ndescription = \"Auto-generate a swarm for a task\"\n\n[[tasks]]\nname = \"pond-build\"\ncommand = \"bash -c 'cd ~/repos/ghostty-org/ghostty && zig build && zig build -Doptimize=ReleaseFast'\"\ndescription = \"Build Pond (Ghostty fork) in debug and production modes\"\n\n[[tasks]]\nname = \"pond-debug\"\ncommand = \"bash -c 'cd ~/repos/ghostty-org/ghostty && zig build -Doptimize=Debug'\"\ndescription = \"Build Pond (Ghostty fork) in debug mode\"\n\n[[tasks]]\nname = \"zed-build-debug-release\"\ncommand = \"bash -c 'cd ~/repos/zed-industries/zed && ./script/bundle-mac -d && ./script/bundle-mac'\"\ndescription = \"Build Zed macOS bundle in debug mode (fast) and then in release mode\"\n\n[[tasks]]\nname = \"linsa-assistant-serve\"\ncommand = \"bash -c 'cd ~/code/org/linsa/linsa/api/cpp && sh ./run.sh serve'\"\ndescription = \"Build + run the Linsa C++ assistant proxy server\"\n\n[[tasks]]\nname = \"linsa-assistant-stream\"\ncommand = \"bash -c 'curl -N -X POST http://127.0.0.1:8788/api/assistant/chat/stream -H \\\"Content-Type: application/json\\\" -d \\\"{\\\\\\\"message\\\\\\\":\\\\\\\"hello\\\\\\\"}\\\"'\"\ndescription = \"Stream assistant response via SSE from the local proxy\"\n\n[[tasks]]\nname = \"x-deploy\"\ncommand = \"bash -lc 'bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh install && bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh run build'\"\ndescription = \"Install and build the zvec X likes/bookmarks CLI workspace with the local Bun debug build\"\n\n[[tasks]]\nname = \"x-doctor\"\ncommand = \"bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh ~/repos/alibaba/zvec/tools/x/src/cli.ts doctor $@\"\ndescription = \"Inspect zvec X archive settings, discovered query ids, and auth prerequisites\"\n\n[[tasks]]\nname = \"x-import-file\"\ncommand = \"bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh ~/repos/alibaba/zvec/tools/x/src/cli.ts import-file $@\"\ndescription = \"Ingest a bookmarks.json or likes.json export into the zvec X archive\"\n\n[[tasks]]\nname = \"x-capture-js\"\ncommand = \"bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh ~/repos/alibaba/zvec/tools/x/src/cli.ts capture-js\"\ndescription = \"Print a browser console script that captures bookmarks or likes into JSON\"\n\n[[tasks]]\nname = \"x-sync\"\ncommand = \"bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh ~/repos/alibaba/zvec/tools/x/src/cli.ts sync --source all $@\"\ndescription = \"Incrementally sync X bookmarks and likes into ~/repos/alibaba/zvec/var/x\"\n\n[[tasks]]\nname = \"x-backfill\"\ncommand = \"bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh ~/repos/alibaba/zvec/tools/x/src/cli.ts backfill --source all $@\"\ndescription = \"Fetch as much of the bookmarks and likes timelines as X will return into the zvec archive\"\n\n[[tasks]]\nname = \"x-sync-loop\"\ncommand = \"bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh ~/repos/alibaba/zvec/tools/x/src/cli.ts watch --source all $@\"\ndescription = \"Poll X continuously and keep the zvec archive and search index current\"\n\n[[tasks]]\nname = \"x-search\"\ncommand = \"bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh ~/repos/alibaba/zvec/tools/x/src/cli.ts search $@\"\ndescription = \"Search the local zvec X archive across bookmarks and likes\"\n\n[[tasks]]\nname = \"x-list\"\ncommand = \"bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh ~/repos/alibaba/zvec/tools/x/src/cli.ts list $@\"\ndescription = \"List recent items from the local zvec X archive\"\n\n[[tasks]]\nname = \"x-stats\"\ncommand = \"bash ~/repos/alibaba/zvec/tools/x/run-local-bun.sh ~/repos/alibaba/zvec/tools/x/src/cli.ts stats $@\"\ndescription = \"Show counts and latest-seen timestamps for the local zvec X archive\"\n\n[[tasks]]\nname = \"siftly-x\"\ncommand = \"bash ~/repos/viperrcrypto/Siftly/scripts/run-local-bun.sh run siftly -- x $@\"\ndescription = \"Run the Siftly CLI wrapper for the zvec X workspace with the local Bun debug build\"\n\n[[tasks]]\nname = \"siftly-x-deploy\"\ncommand = \"bash ~/repos/viperrcrypto/Siftly/scripts/run-local-bun.sh run siftly -- x deploy $@\"\ndescription = \"Install and build the zvec X workspace for use through the Siftly CLI with the local Bun debug build\"\n\n[[tasks]]\nname = \"codex-fork-status\"\ncommand = \"python3 ./scripts/codex_fork.py status \\\"$@\\\"\"\ndescription = \"Show the Codex fork home checkout, worktree, and last-session state\"\n\n[[tasks]]\nname = \"codex-fork-sync\"\ncommand = \"python3 ./scripts/codex_fork.py sync \\\"$@\\\"\"\ndescription = \"Fast-forward nikiv in ~/repos/nikivdev/codex to upstream/main and optionally push private\"\n\n[[tasks]]\nname = \"codex-fork-task\"\ncommand = \"python3 ./scripts/codex_fork.py task \\\"$@\\\"\"\ndescription = \"Create or reuse a scoped Codex fork worktree and open the matching Codex session\"\ninteractive = true\n\n[[tasks]]\nname = \"codex-fork-last\"\ncommand = \"python3 ./scripts/codex_fork.py last \\\"$@\\\"\"\ndescription = \"Resume the last Codex fork session from the last used worktree\"\ninteractive = true\n\n[[tasks]]\nname = \"codex-fork-promote\"\ncommand = \"python3 ./scripts/codex_fork.py promote \\\"$@\\\"\"\ndescription = \"Create or update a review/nikiv-* branch from a codex/* worktree branch\"\n\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n" }, { "path": "install.sh", "content": "#!/bin/sh\nset -eu\n\n# Flow CLI installer\n# Usage: curl -fsSL https://myflow.sh/install.sh | sh\n\n# Security posture:\n# - We require SHA-256 verification by default.\n# - Set FLOW_INSTALL_INSECURE=1 (or true/yes) to bypass verification.\n\n#region logging\nif [ \"${FLOW_DEBUG-}\" = \"true\" ] || [ \"${FLOW_DEBUG-}\" = \"1\" ]; then\n debug() { echo \"$@\" >&2; }\nelse\n debug() { :; }\nfi\n\nif [ \"${FLOW_QUIET-}\" = \"1\" ] || [ \"${FLOW_QUIET-}\" = \"true\" ]; then\n info() { :; }\nelse\n info() { echo \"$@\" >&2; }\nfi\n\nerror() {\n echo \"error: $@\" >&2\n exit 1\n}\n\nis_truthy() {\n case \"${1:-}\" in\n 1|true|TRUE|yes|YES|y|Y) return 0 ;;\n *) return 1 ;;\n esac\n}\n\nFLOW_SHIM_DIR_SELECTED=\"\"\n\ncan_execute_flow_binary() {\n bin_path=\"$1\"\n if [ ! -f \"$bin_path\" ]; then\n return 1\n fi\n if [ ! -x \"$bin_path\" ]; then\n chmod +x \"$bin_path\" 2>/dev/null || true\n fi\n \"$bin_path\" --version >/dev/null 2>&1\n}\n#endregion\n\n#region platform detection\nget_os() {\n os=\"$(uname -s)\"\n if [ \"$os\" = Darwin ]; then\n echo \"macos\"\n elif [ \"$os\" = Linux ]; then\n echo \"linux\"\n else\n error \"unsupported OS: $os\"\n fi\n}\n\nget_arch() {\n arch=\"$(uname -m)\"\n if [ \"$arch\" = x86_64 ]; then\n echo \"x64\"\n elif [ \"$arch\" = aarch64 ] || [ \"$arch\" = arm64 ]; then\n echo \"arm64\"\n else\n error \"unsupported architecture: $arch\"\n fi\n}\n\nget_target() {\n os=\"$1\"\n arch=\"$2\"\n case \"$os-$arch\" in\n macos-x64) echo \"x86_64-apple-darwin\" ;;\n macos-arm64) echo \"aarch64-apple-darwin\" ;;\n linux-x64) echo \"x86_64-unknown-linux-gnu\" ;;\n linux-arm64) echo \"aarch64-unknown-linux-gnu\" ;;\n *) error \"unsupported platform: $os-$arch\" ;;\n esac\n}\n\nshasum_bin() {\n if command -v shasum >/dev/null 2>&1; then\n echo \"shasum -a 256\"\n elif command -v sha256sum >/dev/null 2>&1; then\n echo \"sha256sum\"\n else\n echo \"\"\n fi\n}\n\nvalidate_repo() {\n repo=\"$1\"\n if [ -z \"${repo:-}\" ]; then\n error \"FLOW_UPGRADE_REPO is empty\"\n fi\n\n owner=\"${repo%/*}\"\n name=\"${repo#*/}\"\n if [ \"$owner\" = \"$repo\" ] || [ \"$name\" = \"$repo\" ]; then\n error \"invalid repo '${repo}' (expected owner/repo)\"\n fi\n case \"$owner\" in */*) error \"invalid repo '${repo}' (expected owner/repo)\" ;; esac\n case \"$name\" in */*) error \"invalid repo '${repo}' (expected owner/repo)\" ;; esac\n\n case \"$owner\" in *[!A-Za-z0-9._-]*)\n error \"invalid repo owner '${owner}' (allowed: A-Z a-z 0-9 . _ -)\"\n ;;\n esac\n case \"$name\" in *[!A-Za-z0-9._-]*)\n error \"invalid repo name '${name}' (allowed: A-Z a-z 0-9 . _ -)\"\n ;;\n esac\n}\n\nvalidate_token() {\n token=\"$1\"\n if [ -z \"${token:-}\" ]; then\n error \"GitHub token is empty\"\n fi\n case \"$token\" in\n *[!A-Za-z0-9._-]*)\n error \"invalid GitHub token characters (refusing to use it)\"\n ;;\n esac\n}\n\nvalidate_version() {\n version=\"$1\"\n case \"$version\" in\n v*) tag=\"${version#v}\" ;;\n *) tag=\"$version\" ;;\n esac\n case \"$tag\" in\n \"\"|*[!0-9A-Za-z._-]*)\n error \"invalid release version '${version}'\"\n ;;\n esac\n}\n#endregion\n\nshould_install_source() {\n case \"${FLOW_INSTALL_SOURCE:-1}\" in\n 0|false|FALSE|no|NO|n|N) return 1 ;;\n *) return 0 ;;\n esac\n}\n\nshould_install_path_shim() {\n case \"${FLOW_INSTALL_PATH_SHIM:-1}\" in\n 0|false|FALSE|no|NO|n|N) return 1 ;;\n *) return 0 ;;\n esac\n}\n\nensure_flow_source_checkout() {\n if ! should_install_source; then\n info \"flow: skipping source checkout (FLOW_INSTALL_SOURCE=0)\"\n return 0\n fi\n\n if ! command -v git >/dev/null 2>&1; then\n error \"git is required to install flow source to ~/code/flow (or set FLOW_INSTALL_SOURCE=0)\"\n fi\n\n source_dir=\"${FLOW_SOURCE_DIR:-$HOME/code/flow}\"\n source_repo=\"${FLOW_SOURCE_REPO_URL:-https://github.com/nikivdev/flow.git}\"\n source_branch=\"${FLOW_SOURCE_BRANCH:-main}\"\n\n mkdir -p \"$(dirname \"$source_dir\")\"\n\n if [ -d \"$source_dir/.git\" ]; then\n info \"flow: source checkout found at $source_dir\"\n\n if ! git -C \"$source_dir\" diff --quiet >/dev/null 2>&1 || ! git -C \"$source_dir\" diff --cached --quiet >/dev/null 2>&1; then\n info \"flow: warning: source checkout has local changes; skipping auto-sync\"\n return 0\n fi\n\n if git -C \"$source_dir\" fetch --all --prune >/dev/null 2>&1; then\n if git -C \"$source_dir\" show-ref --verify --quiet \"refs/remotes/origin/$source_branch\"; then\n if ! git -C \"$source_dir\" checkout \"$source_branch\" >/dev/null 2>&1; then\n info \"flow: warning: failed to checkout '$source_branch'; leaving current branch\"\n fi\n if ! git -C \"$source_dir\" pull --ff-only origin \"$source_branch\" >/dev/null 2>&1; then\n info \"flow: warning: failed to fast-forward source checkout; sync manually\"\n fi\n fi\n else\n info \"flow: warning: failed to fetch source checkout\"\n fi\n\n return 0\n fi\n\n if [ -e \"$source_dir\" ]; then\n error \"flow source path exists but is not a git checkout: $source_dir\"\n fi\n\n info \"flow: cloning source checkout to $source_dir\"\n if ! git clone --branch \"$source_branch\" \"$source_repo\" \"$source_dir\" >/dev/null 2>&1; then\n error \"failed to clone flow source from $source_repo\"\n fi\n}\n\nfind_shim_dir() {\n if [ -n \"${FLOW_SHIM_DIR:-}\" ]; then\n if [ ! -d \"$FLOW_SHIM_DIR\" ]; then\n mkdir -p \"$FLOW_SHIM_DIR\" 2>/dev/null || true\n fi\n if [ -d \"$FLOW_SHIM_DIR\" ] && [ -w \"$FLOW_SHIM_DIR\" ]; then\n echo \"$FLOW_SHIM_DIR\"\n return 0\n fi\n fi\n\n old_ifs=\"${IFS:- }\"\n IFS=':'\n for dir in ${PATH:-}; do\n [ -n \"$dir\" ] || continue\n [ \"$dir\" = \".\" ] && continue\n [ -d \"$dir\" ] || continue\n [ -w \"$dir\" ] || continue\n echo \"$dir\"\n IFS=\"$old_ifs\"\n return 0\n done\n IFS=\"$old_ifs\"\n\n fallback=\"$HOME/.local/bin\"\n if [ ! -d \"$fallback\" ]; then\n mkdir -p \"$fallback\" 2>/dev/null || true\n fi\n if [ -d \"$fallback\" ] && [ -w \"$fallback\" ]; then\n echo \"$fallback\"\n return 0\n fi\n\n return 1\n}\n\ninstall_path_shim() {\n if ! should_install_path_shim; then\n return 0\n fi\n\n install_path=\"${FLOW_INSTALL_PATH:-$HOME/.flow/bin/f}\"\n install_dir=\"$(dirname \"$install_path\")\"\n shim_dir=\"$(find_shim_dir 2>/dev/null || true)\"\n\n if [ -z \"${shim_dir:-}\" ]; then\n info \"flow: warning: no writable PATH directory found for immediate command shim\"\n return 0\n fi\n\n FLOW_SHIM_DIR_SELECTED=\"$shim_dir\"\n\n for name in f flow; do\n target=\"$shim_dir/$name\"\n # Never overwrite the installed binary with a symlink to itself.\n if [ \"$target\" = \"$install_path\" ]; then\n continue\n fi\n if [ -e \"$target\" ] && [ ! -L \"$target\" ]; then\n # Do not replace existing non-symlink binaries/scripts.\n continue\n fi\n ln -sf \"$install_path\" \"$target\" 2>/dev/null || true\n done\n\n if [ \"$shim_dir\" != \"$install_dir\" ]; then\n info \"flow: command shim installed in $shim_dir\"\n fi\n}\n\nensure_line_in_file() {\n file=\"$1\"\n needle=\"$2\"\n line=\"$3\"\n\n parent=\"$(dirname \"$file\")\"\n [ -d \"$parent\" ] || mkdir -p \"$parent\" 2>/dev/null || true\n [ -f \"$file\" ] || touch \"$file\" 2>/dev/null || true\n\n if ! grep -F -q \"$needle\" \"$file\" 2>/dev/null; then\n printf '%s\\n' \"$line\" >> \"$file\"\n fi\n}\n\nensure_sh_path_entry() {\n file=\"$1\"\n dir=\"$2\"\n ensure_line_in_file \"$file\" \"$dir\" \"export PATH=\\\"$dir:\\$PATH\\\"\"\n}\n\n#region download helpers\ndownload_file() {\n url=\"$1\"\n file=\"$2\"\n if command -v curl >/dev/null 2>&1; then\n debug \">\" curl -fsSL -o \"$file\" \"$url\"\n if [ \"${FLOW_DEBUG-}\" = \"true\" ] || [ \"${FLOW_DEBUG-}\" = \"1\" ]; then\n curl -fsSL --proto '=https' --tlsv1.2 -o \"$file\" \"$url\"\n else\n curl -fsSL --proto '=https' --tlsv1.2 -o \"$file\" \"$url\" 2>/dev/null\n fi\n elif command -v wget >/dev/null 2>&1; then\n debug \">\" wget -qO \"$file\" \"$url\"\n wget -qO \"$file\" \"$url\"\n else\n error \"curl or wget is required\"\n fi\n}\n\nfetch_url() {\n url=\"$1\"\n if command -v curl >/dev/null 2>&1; then\n case \"$url\" in\n https://api.github.com/*)\n token=\"${GITHUB_TOKEN:-${GH_TOKEN:-${FLOW_GITHUB_TOKEN:-}}}\"\n if [ -n \"${token:-}\" ]; then\n validate_token \"$token\"\n curl -fsSL --proto '=https' --tlsv1.2 -H \"Authorization: Bearer ${token}\" \"$url\"\n else\n curl -fsSL --proto '=https' --tlsv1.2 \"$url\"\n fi\n ;;\n *)\n curl -fsSL --proto '=https' --tlsv1.2 \"$url\"\n ;;\n esac\n elif command -v wget >/dev/null 2>&1; then\n wget -qO- \"$url\"\n else\n error \"curl or wget is required\"\n fi\n}\n\nget_latest_version() {\n repo=\"${FLOW_UPGRADE_REPO:-}\"\n if [ -z \"${repo:-}\" ] && [ -n \"${FLOW_GITHUB_OWNER:-}\" ] && [ -n \"${FLOW_GITHUB_REPO:-}\" ]; then\n repo=\"${FLOW_GITHUB_OWNER}/${FLOW_GITHUB_REPO}\"\n fi\n repo=\"${repo:-nikivdev/flow}\"\n validate_repo \"$repo\"\n\n url=\"https://api.github.com/repos/${repo}/releases/latest\"\n version=\"$(fetch_url \"$url\" | grep '\"tag_name\":' | sed -E 's/.*\"([^\"]+)\".*/\\1/')\"\n validate_version \"$version\"\n echo \"$version\"\n}\n\nget_checksum() {\n version=\"$1\"\n target=\"$2\"\n repo=\"${FLOW_UPGRADE_REPO:-}\"\n if [ -z \"${repo:-}\" ] && [ -n \"${FLOW_GITHUB_OWNER:-}\" ] && [ -n \"${FLOW_GITHUB_REPO:-}\" ]; then\n repo=\"${FLOW_GITHUB_OWNER}/${FLOW_GITHUB_REPO}\"\n fi\n repo=\"${repo:-nikivdev/flow}\"\n validate_repo \"$repo\"\n\n url=\"https://github.com/${repo}/releases/download/${version}/checksums.txt\"\n checksums=\"$(fetch_url \"$url\" 2>/dev/null)\" || return 1\n echo \"$checksums\" | grep \"flow-${target}.tar.gz\" | awk '{print $1}'\n}\n\nget_checksum_for_file() {\n version=\"$1\"\n file=\"$2\"\n repo=\"${FLOW_UPGRADE_REPO:-}\"\n if [ -z \"${repo:-}\" ] && [ -n \"${FLOW_GITHUB_OWNER:-}\" ] && [ -n \"${FLOW_GITHUB_REPO:-}\" ]; then\n repo=\"${FLOW_GITHUB_OWNER}/${FLOW_GITHUB_REPO}\"\n fi\n repo=\"${repo:-nikivdev/flow}\"\n validate_repo \"$repo\"\n\n url=\"https://github.com/${repo}/releases/download/${version}/checksums.txt\"\n checksums=\"$(fetch_url \"$url\" 2>/dev/null)\" || return 1\n # checksums.txt format: \"<sha256> <filename>\"\n echo \"$checksums\" | awk -v f=\"$file\" '$2==f {print $1}'\n}\n#endregion\n\ninstall_flow() {\n version=\"${FLOW_VERSION:-latest}\"\n os=\"${FLOW_OS:-$(get_os)}\"\n arch=\"${FLOW_ARCH:-$(get_arch)}\"\n target=\"$(get_target \"$os\" \"$arch\")\"\n install_path=\"${FLOW_INSTALL_PATH:-$HOME/.flow/bin/f}\"\n install_dir=\"$(dirname \"$install_path\")\"\n\n info \"flow: installing flow CLI...\"\n info \"flow: platform: $os-$arch ($target)\"\n\n # Get latest version if needed\n if [ \"$version\" = \"latest\" ]; then\n info \"flow: fetching latest version...\"\n version=\"$(get_latest_version)\"\n if [ -z \"$version\" ]; then\n error \"failed to fetch latest version\"\n fi\n fi\n validate_version \"$version\"\n info \"flow: version: $version\"\n\n # URLs - try CDN first, fallback to GitHub\n cdn_url=\"https://cdn.myflow.sh/${version}/flow-${target}.tar.gz\"\n repo=\"${FLOW_UPGRADE_REPO:-}\"\n if [ -z \"${repo:-}\" ] && [ -n \"${FLOW_GITHUB_OWNER:-}\" ] && [ -n \"${FLOW_GITHUB_REPO:-}\" ]; then\n repo=\"${FLOW_GITHUB_OWNER}/${FLOW_GITHUB_REPO}\"\n fi\n repo=\"${repo:-nikivdev/flow}\"\n validate_repo \"$repo\"\n github_url=\"https://github.com/${repo}/releases/download/${version}/flow-${target}.tar.gz\"\n\n download_dir=\"$(mktemp -d)\"\n tarball=\"$download_dir/flow.tar.gz\"\n download_source=\"unknown\"\n\n asset_file=\"flow-${target}.tar.gz\"\n legacy_os=\"$os\"\n if [ \"$legacy_os\" = \"macos\" ]; then\n legacy_os=\"darwin\"\n fi\n legacy_arch=\"amd64\"\n if [ \"$arch\" = \"arm64\" ]; then\n legacy_arch=\"arm64\"\n fi\n legacy_file=\"flow_${version}_${legacy_os}_${legacy_arch}.tar.gz\"\n legacy_url=\"https://github.com/${repo}/releases/download/${version}/${legacy_file}\"\n\n # Try CDN first (faster)\n info \"flow: downloading...\"\n if command -v curl >/dev/null 2>&1 && curl -fsSL -o \"$tarball\" \"$cdn_url\" 2>/dev/null; then\n debug \"flow: downloaded from CDN\"\n download_source=\"cdn\"\n else\n debug \"flow: trying GitHub...\"\n if download_file \"$github_url\" \"$tarball\"; then\n asset_file=\"flow-${target}.tar.gz\"\n download_source=\"github\"\n elif download_file \"$legacy_url\" \"$tarball\"; then\n asset_file=\"$legacy_file\"\n download_source=\"legacy\"\n else\n error \"download failed\"\n fi\n fi\n\n # Verify checksum if available\n shasum=\"$(shasum_bin)\"\n if [ -n \"$shasum\" ]; then\n expected=\"$(get_checksum_for_file \"$version\" \"$asset_file\" 2>/dev/null)\" || true\n if [ -z \"${expected:-}\" ]; then\n # Back-compat: allow checksums.txt to contain either naming scheme.\n if [ \"$asset_file\" = \"$legacy_file\" ]; then\n expected=\"$(get_checksum_for_file \"$version\" \"flow-${target}.tar.gz\" 2>/dev/null)\" || true\n elif [ \"$asset_file\" = \"flow-${target}.tar.gz\" ]; then\n expected=\"$(get_checksum_for_file \"$version\" \"$legacy_file\" 2>/dev/null)\" || true\n fi\n fi\n if [ -z \"${expected:-}\" ]; then\n if is_truthy \"${FLOW_INSTALL_INSECURE-}\"; then\n info \"flow: warning: checksum not verified (FLOW_INSTALL_INSECURE=1)\"\n elif [ \"${download_source:-}\" = \"cdn\" ]; then\n rm -rf \"$download_dir\" \"$extract_dir\" 2>/dev/null || true\n error \"checksum verification failed for CDN download (checksums.txt missing or entry not found). Refusing to install.\\nSet FLOW_INSTALL_INSECURE=1 to bypass (not recommended).\"\n else\n info \"flow: warning: checksum not verified (checksums.txt missing or entry not found; legacy release?)\"\n expected=\"\"\n fi\n fi\n if [ -n \"${expected:-}\" ]; then\n debug \"flow: verifying checksum...\"\n actual=\"$($shasum \"$tarball\" | awk '{print $1}')\"\n if [ \"$expected\" != \"$actual\" ]; then\n rm -rf \"$download_dir\"\n error \"checksum mismatch\"\n fi\n info \"flow: checksum verified\"\n fi\n else\n if is_truthy \"${FLOW_INSTALL_INSECURE-}\"; then\n info \"flow: warning: sha256 tool not found, skipping checksum verification (FLOW_INSTALL_INSECURE=1)\"\n else\n error \"sha256 tool not found (need shasum or sha256sum). Refusing to install.\\nSet FLOW_INSTALL_INSECURE=1 to bypass (not recommended).\"\n fi\n fi\n\n # Extract and install\n mkdir -p \"$install_dir\"\n extract_dir=\"$(mktemp -d)\"\n tar -xzf \"$tarball\" -C \"$extract_dir\"\n\n # Find binary\n if [ -f \"$extract_dir/f\" ]; then\n mv \"$extract_dir/f\" \"$install_path\"\n else\n binary=\"$(find \"$extract_dir\" -type f \\( -name \"f\" -o -name \"flow\" \\) 2>/dev/null | head -1)\"\n if [ -z \"$binary\" ]; then\n binary=\"$(find \"$extract_dir\" -type f -perm +111 2>/dev/null | head -1)\"\n fi\n if [ -z \"$binary\" ]; then\n rm -rf \"$download_dir\" \"$extract_dir\"\n error \"binary not found in archive\"\n fi\n mv \"$binary\" \"$install_path\"\n fi\n chmod +x \"$install_path\"\n\n # Provide both `f` and `flow` as entrypoints.\n base=\"$(basename \"$install_path\")\"\n if [ \"$base\" = \"f\" ]; then\n if [ -e \"$install_dir/flow\" ] && [ -d \"$install_dir/flow\" ]; then\n info \"flow: warning: cannot create symlink $install_dir/flow (path is a directory)\"\n else\n ln -sf \"f\" \"$install_dir/flow\" 2>/dev/null || true\n fi\n elif [ \"$base\" = \"flow\" ]; then\n if [ -e \"$install_dir/f\" ] && [ -d \"$install_dir/f\" ]; then\n info \"flow: warning: cannot create symlink $install_dir/f (path is a directory)\"\n else\n ln -sf \"flow\" \"$install_dir/f\" 2>/dev/null || true\n fi\n fi\n\n # Cleanup\n rm -rf \"$download_dir\" \"$extract_dir\"\n\n if ! can_execute_flow_binary \"$install_path\"; then\n if [ \"$os\" = \"macos\" ] && ! is_truthy \"${FLOW_INSTALL_RETRY_ALT_ARCH:-0}\"; then\n alt_arch=\"x64\"\n if [ \"$arch\" = \"x64\" ]; then\n alt_arch=\"arm64\"\n fi\n info \"flow: installed binary failed execution; retrying with macos-$alt_arch build\"\n FLOW_ARCH=\"$alt_arch\" FLOW_INSTALL_RETRY_ALT_ARCH=1 install_flow\n return 0\n fi\n\n info \"flow: diagnostic: unable to execute $install_path\"\n info \"flow: diagnostic: $(ls -l \"$install_path\" 2>/dev/null || echo missing)\"\n if command -v file >/dev/null 2>&1; then\n info \"flow: diagnostic: $(file \"$install_path\" 2>/dev/null || true)\"\n fi\n error \"installed flow binary is not executable on this host\"\n fi\n\n info \"flow: installed to $install_path\"\n}\n\nconfigure_shell() {\n install_dir=\"$(dirname \"${FLOW_INSTALL_PATH:-$HOME/.flow/bin/f}\")\"\n shim_dir=\"${FLOW_SHIM_DIR_SELECTED:-}\"\n fallback_shim=\"$HOME/.local/bin\"\n registry_url=\"${FLOW_REGISTRY_URL:-https://myflow.sh}\"\n\n # Fish\n if [ -f \"$HOME/.config/fish/config.fish\" ]; then\n ensure_line_in_file \"$HOME/.config/fish/config.fish\" \"$install_dir\" \"fish_add_path $install_dir\"\n if [ -n \"$shim_dir\" ] && [ \"$shim_dir\" != \"$install_dir\" ]; then\n ensure_line_in_file \"$HOME/.config/fish/config.fish\" \"$shim_dir\" \"fish_add_path $shim_dir\"\n fi\n ensure_line_in_file \"$HOME/.config/fish/config.fish\" \"$fallback_shim\" \"fish_add_path $fallback_shim\"\n ensure_line_in_file \"$HOME/.config/fish/config.fish\" \"FLOW_REGISTRY_URL\" \"set -gx FLOW_REGISTRY_URL \\\"$registry_url\\\"\"\n info \"flow: updated ~/.config/fish/config.fish\"\n fi\n\n # Zsh\n for zsh_rc in \"$HOME/.zshrc\" \"$HOME/.zprofile\"; do\n ensure_sh_path_entry \"$zsh_rc\" \"$install_dir\"\n if [ -n \"$shim_dir\" ] && [ \"$shim_dir\" != \"$install_dir\" ]; then\n ensure_sh_path_entry \"$zsh_rc\" \"$shim_dir\"\n fi\n ensure_sh_path_entry \"$zsh_rc\" \"$fallback_shim\"\n ensure_line_in_file \"$zsh_rc\" \"FLOW_REGISTRY_URL\" \"export FLOW_REGISTRY_URL=\\\"$registry_url\\\"\"\n done\n info \"flow: updated ~/.zshrc and ~/.zprofile\"\n\n # Bash\n bash_updated=0\n for rc in \"$HOME/.bashrc\" \"$HOME/.bash_profile\"; do\n if [ -f \"$rc\" ]; then\n ensure_sh_path_entry \"$rc\" \"$install_dir\"\n if [ -n \"$shim_dir\" ] && [ \"$shim_dir\" != \"$install_dir\" ]; then\n ensure_sh_path_entry \"$rc\" \"$shim_dir\"\n fi\n ensure_sh_path_entry \"$rc\" \"$fallback_shim\"\n ensure_line_in_file \"$rc\" \"FLOW_REGISTRY_URL\" \"export FLOW_REGISTRY_URL=\\\"$registry_url\\\"\"\n bash_updated=1\n fi\n done\n if [ \"$bash_updated\" = \"0\" ]; then\n rc=\"$HOME/.bashrc\"\n ensure_sh_path_entry \"$rc\" \"$install_dir\"\n if [ -n \"$shim_dir\" ] && [ \"$shim_dir\" != \"$install_dir\" ]; then\n ensure_sh_path_entry \"$rc\" \"$shim_dir\"\n fi\n ensure_sh_path_entry \"$rc\" \"$fallback_shim\"\n ensure_line_in_file \"$rc\" \"FLOW_REGISTRY_URL\" \"export FLOW_REGISTRY_URL=\\\"$registry_url\\\"\"\n fi\n}\n\nafter_install() {\n source_dir=\"${FLOW_SOURCE_DIR:-$HOME/code/flow}\"\n install_path=\"${FLOW_INSTALL_PATH:-$HOME/.flow/bin/f}\"\n if [ ! -x \"$install_path\" ]; then\n chmod +x \"$install_path\" 2>/dev/null || true\n fi\n\n if ! can_execute_flow_binary \"$install_path\"; then\n if command -v xattr >/dev/null 2>&1; then\n xattr -d com.apple.quarantine \"$install_path\" >/dev/null 2>&1 || true\n fi\n chmod +x \"$install_path\" 2>/dev/null || true\n fi\n\n if ! can_execute_flow_binary \"$install_path\"; then\n info \"flow: diagnostic: unable to execute fallback binary: $install_path\"\n info \"flow: diagnostic: $(ls -l \"$install_path\" 2>/dev/null || echo missing)\"\n if command -v file >/dev/null 2>&1; then\n info \"flow: diagnostic: $(file \"$install_path\" 2>/dev/null || true)\"\n fi\n error \"installed flow binary is not runnable; rerun with FLOW_DEBUG=1 and share diagnostics\"\n fi\n\n info \"\"\n info \"flow: installed successfully!\"\n if command -v f >/dev/null 2>&1; then\n info \"flow: command ready: $(command -v f)\"\n elif [ -n \"${FLOW_SHIM_DIR_SELECTED:-}\" ] && [ -x \"${FLOW_SHIM_DIR_SELECTED}/f\" ]; then\n info \"flow: command shim ready: ${FLOW_SHIM_DIR_SELECTED}/f\"\n info \"flow: open a new shell to refresh PATH (zsh: exec zsh -l)\"\n else\n info \"flow: OPEN NEW SHELL to use 'f' by name\"\n info \"flow: immediate fallback: $install_path --help\"\n fi\n if should_install_source; then\n info \"flow: source checkout: $source_dir\"\n fi\n info \"flow: then run 'f --help' to get started\"\n info \"flow: docs: https://myflow.sh\"\n}\n\nshould_setup_run() {\n case \"${FLOW_SETUP_RUN:-1}\" in\n 0|false|FALSE|no|NO|n|N) return 1 ;;\n *) return 0 ;;\n esac\n}\n\nis_interactive() {\n [ -t 0 ] && [ -t 1 ]\n}\n\nprompt_value() {\n label=\"$1\"\n default=\"$2\"\n env_override=\"$3\"\n if [ -n \"$env_override\" ]; then\n echo \"$env_override\"\n return 0\n fi\n if ! is_interactive; then\n echo \"$default\"\n return 0\n fi\n printf '%s [%s]: ' \"$label\" \"$default\" >&2\n read -r answer </dev/tty || answer=\"\"\n answer=\"${answer:-$default}\"\n echo \"$answer\"\n}\n\nprompt_yn() {\n question=\"$1\"\n default=\"${2:-y}\"\n if ! is_interactive; then\n case \"$default\" in y|Y) return 0 ;; *) return 1 ;; esac\n fi\n if [ \"$default\" = \"y\" ]; then\n hint=\"Y/n\"\n else\n hint=\"y/N\"\n fi\n printf '%s (%s): ' \"$question\" \"$hint\" >&2\n read -r answer </dev/tty || answer=\"\"\n answer=\"${answer:-$default}\"\n case \"$answer\" in\n y|Y|yes|YES) return 0 ;;\n *) return 1 ;;\n esac\n}\n\nclone_if_missing() {\n target_dir=\"$1\"\n repo_url=\"$2\"\n label=\"$3\"\n\n if [ -d \"$target_dir/.git\" ]; then\n info \"flow: $label already exists at $target_dir\"\n return 0\n fi\n\n if [ -e \"$target_dir\" ] && [ ! -d \"$target_dir\" ]; then\n info \"flow: warning: $target_dir exists but is not a directory; skipping $label\"\n return 1\n fi\n\n if [ -z \"$repo_url\" ] || [ \"$repo_url\" = \"-\" ] || [ \"$repo_url\" = \"skip\" ]; then\n info \"flow: skipping $label (no repo URL)\"\n return 0\n fi\n\n mkdir -p \"$(dirname \"$target_dir\")\"\n info \"flow: cloning $label -> $target_dir\"\n if git clone \"$repo_url\" \"$target_dir\" >/dev/null 2>&1; then\n info \"flow: $label ready\"\n else\n info \"flow: warning: failed to clone $label from $repo_url\"\n return 1\n fi\n}\n\nsetup_run_repos() {\n if ! should_setup_run; then\n info \"flow: skipping ~/run setup (FLOW_SETUP_RUN=0)\"\n return 0\n fi\n\n if ! command -v git >/dev/null 2>&1; then\n info \"flow: warning: git not found; skipping ~/run setup\"\n return 0\n fi\n\n run_root=\"${RUN_ROOT:-$HOME/run}\"\n\n # If both already exist, skip entirely\n if [ -d \"$run_root/.git\" ] && [ -d \"$run_root/i/.git\" ]; then\n info \"flow: ~/run and ~/run/i already set up\"\n return 0\n fi\n\n info \"\"\n if ! prompt_yn \"Set up ~/run repos (task collections)?\"; then\n info \"flow: skipping ~/run setup\"\n info \"flow: you can set this up later with: f run-load\"\n return 0\n fi\n\n # ~/run (public)\n if [ ! -d \"$run_root/.git\" ]; then\n run_url=\"$(prompt_value \"~/run repo URL (SSH or HTTPS)\" \"git@github.com:nikivdev/run.git\" \"${FLOW_RUN_REPO:-}\")\"\n clone_if_missing \"$run_root\" \"$run_url\" \"~/run\"\n fi\n\n # ~/run/i (internal/private)\n if [ ! -d \"$run_root/i/.git\" ]; then\n run_i_url=\"$(prompt_value \"~/run/i repo URL (SSH or HTTPS, or 'skip')\" \"git@github.com:nikivdev/run-i.git\" \"${FLOW_RUN_I_REPO:-}\")\"\n clone_if_missing \"$run_root/i\" \"$run_i_url\" \"~/run/i\"\n fi\n\n info \"flow: ~/run repos ready\"\n info \"flow: run tasks with: f r <task> (public) or f ri <task> (internal)\"\n}\n\ninstall_flow\ninstall_path_shim\nensure_flow_source_checkout\nconfigure_shell\nsetup_run_repos\nafter_install\n" }, { "path": "lib/vendor-manifest/axum.toml", "content": "crate = \"axum\"\nversion = \"0.8.8\"\nsource = \"crates.io\"\nsynced_at_utc = \"2026-02-22T18:24:59Z\"\nhistory_repo = \"lib/vendor-history/axum.git\"\nhistory_head = \"fffdbe0b3d192ef263fda82d186a45c18aac3466\"\nmaterialized_path = \"lib/vendor/axum\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh axum 0.8.8\"\n" }, { "path": "lib/vendor-manifest/clap.toml", "content": "crate = \"clap\"\nversion = \"4.6.0\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"b193af5b67834b676abd72466a96c1024e6a6ad978a1f484bd90b85c94041351\"\ncrate_archive_sha256 = \"b193af5b67834b676abd72466a96c1024e6a6ad978a1f484bd90b85c94041351\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/clap-rs/clap\"\nupstream_homepage = \"\"\nsynced_at_utc = \"2026-03-18T18:43:50Z\"\nhistory_repo = \"lib/vendor-history/clap.git\"\nhistory_head = \"2b9744adfa21ccac060f42fce80cfeebfbcebbe5\"\nmaterialized_path = \"lib/vendor/clap\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh clap 4.6.0\"\n" }, { "path": "lib/vendor-manifest/crossterm.toml", "content": "crate = \"crossterm\"\nversion = \"0.29.0\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"d8b9f2e4c67f833b660cdb0a3523065869fb35570177239812ed4c905aeff87b\"\ncrate_archive_sha256 = \"d8b9f2e4c67f833b660cdb0a3523065869fb35570177239812ed4c905aeff87b\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/crossterm-rs/crossterm\"\nupstream_homepage = \"\"\nsynced_at_utc = \"2026-03-09T16:48:35Z\"\nhistory_repo = \"lib/vendor-history/crossterm.git\"\nhistory_head = \"da02bb3cfe73f6f2da5cdd42ec7575c69f9eb75f\"\nmaterialized_path = \"lib/vendor/crossterm\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh crossterm 0.29.0\"\n" }, { "path": "lib/vendor-manifest/crypto_secretbox.toml", "content": "crate = \"crypto_secretbox\"\nversion = \"0.1.1\"\nsource = \"crates.io\"\nsynced_at_utc = \"2026-02-22T18:28:40Z\"\nhistory_repo = \"lib/vendor-history/crypto_secretbox.git\"\nhistory_head = \"0a1c004e1f9c97e92b405455a6a31305cda49902\"\nmaterialized_path = \"lib/vendor/crypto_secretbox\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh crypto_secretbox 0.1.1\"\n" }, { "path": "lib/vendor-manifest/ctrlc.toml", "content": "crate = \"ctrlc\"\nversion = \"3.5.2\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"e0b1fab2ae45819af2d0731d60f2afe17227ebb1a1538a236da84c93e9a60162\"\ncrate_archive_sha256 = \"e0b1fab2ae45819af2d0731d60f2afe17227ebb1a1538a236da84c93e9a60162\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/Detegr/rust-ctrlc.git\"\nupstream_homepage = \"https://github.com/Detegr/rust-ctrlc\"\nsynced_at_utc = \"2026-03-09T16:48:36Z\"\nhistory_repo = \"lib/vendor-history/ctrlc.git\"\nhistory_head = \"d1e8661047f0425f7a10d44fe3cf04391a9e59b0\"\nmaterialized_path = \"lib/vendor/ctrlc\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh ctrlc 3.5.2\"\n" }, { "path": "lib/vendor-manifest/futures.toml", "content": "crate = \"futures\"\nversion = \"0.3.32\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"eadce39539ca5cb3985590102671f2567e659fca9666581ad3411d59207951f3\"\ncrate_archive_sha256 = \"8b147ee9d1f6d097cef9ce628cd2ee62288d963e16fb287bd9286455b241382d\"\nchecksum_match = \"no\"\nupstream_repository = \"https://github.com/rust-lang/futures-rs\"\nupstream_homepage = \"https://rust-lang.github.io/futures-rs\"\nsynced_at_utc = \"2026-03-09T16:48:37Z\"\nhistory_repo = \"lib/vendor-history/futures.git\"\nhistory_head = \"250364bfd7ce80eee9074e4baf9d3f134f84e11a\"\nmaterialized_path = \"lib/vendor/futures\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh futures 0.3.32\"\n" }, { "path": "lib/vendor-manifest/hmac.toml", "content": "crate = \"hmac\"\nversion = \"0.12.1\"\nsource = \"crates.io\"\nsynced_at_utc = \"2026-02-22T19:00:48Z\"\nhistory_repo = \"lib/vendor-history/hmac.git\"\nhistory_head = \"392173235d4c2340c040a971e9945d2fd057576b\"\nmaterialized_path = \"lib/vendor/hmac\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh hmac 0.12.1\"\n" }, { "path": "lib/vendor-manifest/ignore.toml", "content": "crate = \"ignore\"\nversion = \"0.4.25\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"d3d782a365a015e0f5c04902246139249abf769125006fbe7649e2ee88169b4a\"\ncrate_archive_sha256 = \"d3d782a365a015e0f5c04902246139249abf769125006fbe7649e2ee88169b4a\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/BurntSushi/ripgrep/tree/master/crates/ignore\"\nupstream_homepage = \"https://github.com/BurntSushi/ripgrep/tree/master/crates/ignore\"\nsynced_at_utc = \"2026-02-23T09:23:22Z\"\nhistory_repo = \"lib/vendor-history/ignore.git\"\nhistory_head = \"932118a48f5d111ef261e1e108bbf356269d618f\"\nmaterialized_path = \"lib/vendor/ignore\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh ignore 0.4.25\"\n" }, { "path": "lib/vendor-manifest/notify-debouncer-mini.toml", "content": "crate = \"notify-debouncer-mini\"\nversion = \"0.7.0\"\nsource = \"crates.io\"\nsynced_at_utc = \"2026-02-22T19:37:32Z\"\nhistory_repo = \"lib/vendor-history/notify-debouncer-mini.git\"\nhistory_head = \"9ef9af7ca1216d1c855d9b34bf8e7faebc73c5ba\"\nmaterialized_path = \"lib/vendor/notify-debouncer-mini\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh notify-debouncer-mini 0.7.0\"\n" }, { "path": "lib/vendor-manifest/notify.toml", "content": "crate = \"notify\"\nversion = \"8.2.0\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"4d3d07927151ff8575b7087f245456e549fea62edf0ec4e565a5ee50c8402bc3\"\ncrate_archive_sha256 = \"4d3d07927151ff8575b7087f245456e549fea62edf0ec4e565a5ee50c8402bc3\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/notify-rs/notify.git\"\nupstream_homepage = \"https://github.com/notify-rs/notify\"\nsynced_at_utc = \"2026-02-23T09:31:51Z\"\nhistory_repo = \"lib/vendor-history/notify.git\"\nhistory_head = \"752b8136c01b100bfc8b8e425f12ef319e97d5d1\"\nmaterialized_path = \"lib/vendor/notify\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh notify 8.2.0\"\n" }, { "path": "lib/vendor-manifest/portable-pty.toml", "content": "crate = \"portable-pty\"\nversion = \"0.9.0\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"b4a596a2b3d2752d94f51fac2d4a96737b8705dddd311a32b9af47211f08671e\"\ncrate_archive_sha256 = \"b4a596a2b3d2752d94f51fac2d4a96737b8705dddd311a32b9af47211f08671e\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/wezterm/wezterm\"\nupstream_homepage = \"\"\nsynced_at_utc = \"2026-03-09T16:48:39Z\"\nhistory_repo = \"lib/vendor-history/portable-pty.git\"\nhistory_head = \"06a5eafe103dc7040e47ad88ae43f3cf52bbfc92\"\nmaterialized_path = \"lib/vendor/portable-pty\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh portable-pty 0.9.0\"\n" }, { "path": "lib/vendor-manifest/ratatui.toml", "content": "crate = \"ratatui\"\nversion = \"0.30.0\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"d1ce67fb8ba4446454d1c8dbaeda0557ff5e94d39d5e5ed7f10a65eb4c8266bc\"\ncrate_archive_sha256 = \"d1ce67fb8ba4446454d1c8dbaeda0557ff5e94d39d5e5ed7f10a65eb4c8266bc\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/ratatui/ratatui\"\nupstream_homepage = \"https://ratatui.rs\"\nsynced_at_utc = \"2026-03-09T16:48:40Z\"\nhistory_repo = \"lib/vendor-history/ratatui.git\"\nhistory_head = \"cb656d8aa7b019f66ac65383bfe2d304c9373ec5\"\nmaterialized_path = \"lib/vendor/ratatui\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh ratatui 0.30.0\"\n" }, { "path": "lib/vendor-manifest/regex.toml", "content": "crate = \"regex\"\nversion = \"1.12.3\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276\"\ncrate_archive_sha256 = \"e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/rust-lang/regex\"\nupstream_homepage = \"https://github.com/rust-lang/regex\"\nsynced_at_utc = \"2026-03-09T16:49:10Z\"\nhistory_repo = \"lib/vendor-history/regex.git\"\nhistory_head = \"140d77161444f8975123b2c394d360022d17a949\"\nmaterialized_path = \"lib/vendor/regex\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh regex 1.12.3\"\n" }, { "path": "lib/vendor-manifest/reqwest.toml", "content": "crate = \"reqwest\"\nversion = \"0.13.2\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"ab3f43e3283ab1488b624b44b0e988d0acea0b3214e694730a055cb6b2efa801\"\ncrate_archive_sha256 = \"ab3f43e3283ab1488b624b44b0e988d0acea0b3214e694730a055cb6b2efa801\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/seanmonstar/reqwest\"\nupstream_homepage = \"\"\nsynced_at_utc = \"2026-03-09T16:49:10Z\"\nhistory_repo = \"lib/vendor-history/reqwest.git\"\nhistory_head = \"b0189fa9fb0cba412eb64d96992558da9cd6372f\"\nmaterialized_path = \"lib/vendor/reqwest\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh reqwest 0.13.2\"\n" }, { "path": "lib/vendor-manifest/rmp-serde.toml", "content": "crate = \"rmp-serde\"\nversion = \"1.3.1\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"72f81bee8c8ef9b577d1681a70ebbc962c232461e397b22c208c43c04b67a155\"\ncrate_archive_sha256 = \"72f81bee8c8ef9b577d1681a70ebbc962c232461e397b22c208c43c04b67a155\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/3Hren/msgpack-rust\"\nupstream_homepage = \"\"\nsynced_at_utc = \"2026-02-23T09:28:28Z\"\nhistory_repo = \"lib/vendor-history/rmp-serde.git\"\nhistory_head = \"0a515b86613c05ab18f14483d8e47fca9a43101d\"\nmaterialized_path = \"lib/vendor/rmp-serde\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh rmp-serde 1.3.1\"\n" }, { "path": "lib/vendor-manifest/rusqlite.toml", "content": "crate = \"rusqlite\"\nversion = \"0.39.0\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"a0d2b0146dd9661bf67bb107c0bb2a55064d556eeb3fc314151b957f313bcd4e\"\ncrate_archive_sha256 = \"a0d2b0146dd9661bf67bb107c0bb2a55064d556eeb3fc314151b957f313bcd4e\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/rusqlite/rusqlite\"\nupstream_homepage = \"\"\nsynced_at_utc = \"2026-03-18T18:43:53Z\"\nhistory_repo = \"lib/vendor-history/rusqlite.git\"\nhistory_head = \"ec74f8123a7ab7973c969dd538a681e5838461a4\"\nmaterialized_path = \"lib/vendor/rusqlite\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh rusqlite 0.39.0\"\n" }, { "path": "lib/vendor-manifest/serde.toml", "content": "crate = \"serde\"\nversion = \"1.0.228\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e\"\ncrate_archive_sha256 = \"9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/serde-rs/serde\"\nupstream_homepage = \"https://serde.rs\"\nsynced_at_utc = \"2026-02-23T09:32:11Z\"\nhistory_repo = \"lib/vendor-history/serde.git\"\nhistory_head = \"eb6297112aad0f87ddbb8223d95617fd6c8c815b\"\nmaterialized_path = \"lib/vendor/serde\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh serde 1.0.228\"\n" }, { "path": "lib/vendor-manifest/sha1.toml", "content": "crate = \"sha1\"\nversion = \"0.10.6\"\nsource = \"crates.io\"\nsynced_at_utc = \"2026-02-22T18:57:02Z\"\nhistory_repo = \"lib/vendor-history/sha1.git\"\nhistory_head = \"1a7bcebde8f534fb40a8b08e3a38f3c0244e23d9\"\nmaterialized_path = \"lib/vendor/sha1\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh sha1 0.10.6\"\n" }, { "path": "lib/vendor-manifest/sha2.toml", "content": "crate = \"sha2\"\nversion = \"0.10.9\"\nsource = \"crates.io\"\nsynced_at_utc = \"2026-02-22T18:57:49Z\"\nhistory_repo = \"lib/vendor-history/sha2.git\"\nhistory_head = \"1aa3f56560840c076acfbb3cb7183f2c2b789814\"\nmaterialized_path = \"lib/vendor/sha2\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh sha2 0.10.9\"\n" }, { "path": "lib/vendor-manifest/tokio-stream.toml", "content": "crate = \"tokio-stream\"\nversion = \"0.1.18\"\nsource = \"crates.io\"\nsynced_at_utc = \"2026-02-22T18:36:31Z\"\nhistory_repo = \"lib/vendor-history/tokio-stream.git\"\nhistory_head = \"94ba626bae40a85be086bcef2b10f297f6e4d3b4\"\nmaterialized_path = \"lib/vendor/tokio-stream\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh tokio-stream 0.1.18\"\n" }, { "path": "lib/vendor-manifest/tokio.toml", "content": "crate = \"tokio\"\nversion = \"1.50.0\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"27ad5e34374e03cfffefc301becb44e9dc3c17584f414349ebe29ed26661822d\"\ncrate_archive_sha256 = \"27ad5e34374e03cfffefc301becb44e9dc3c17584f414349ebe29ed26661822d\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/tokio-rs/tokio\"\nupstream_homepage = \"https://tokio.rs\"\nsynced_at_utc = \"2026-03-09T16:49:10Z\"\nhistory_repo = \"lib/vendor-history/tokio.git\"\nhistory_head = \"65a5636827a1b6dcc7f808d8cc71be60342db1b6\"\nmaterialized_path = \"lib/vendor/tokio\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh tokio 1.50.0\"\n" }, { "path": "lib/vendor-manifest/toml.toml", "content": "crate = \"toml\"\nversion = \"1.0.7+spec-1.1.0\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"dd28d57d8a6f6e458bc0b8784f8fdcc4b99a437936056fa122cb234f18656a96\"\ncrate_archive_sha256 = \"dd28d57d8a6f6e458bc0b8784f8fdcc4b99a437936056fa122cb234f18656a96\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/toml-rs/toml\"\nupstream_homepage = \"\"\nsynced_at_utc = \"2026-03-18T18:43:56Z\"\nhistory_repo = \"lib/vendor-history/toml.git\"\nhistory_head = \"9bc4b3f4804194d8a42535001fb7c9ddfde6f2b0\"\nmaterialized_path = \"lib/vendor/toml\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh toml 1.0.7+spec-1.1.0\"\n" }, { "path": "lib/vendor-manifest/tower-http.toml", "content": "crate = \"tower-http\"\nversion = \"0.6.8\"\nsource = \"crates.io\"\nsynced_at_utc = \"2026-02-22T18:25:01Z\"\nhistory_repo = \"lib/vendor-history/tower-http.git\"\nhistory_head = \"954fa60bf1e962dc30919a13414833d7efac8e98\"\nmaterialized_path = \"lib/vendor/tower-http\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh tower-http 0.6.8\"\n" }, { "path": "lib/vendor-manifest/tracing-subscriber.toml", "content": "crate = \"tracing-subscriber\"\nversion = \"0.3.23\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319\"\ncrate_archive_sha256 = \"cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/tokio-rs/tracing\"\nupstream_homepage = \"https://tokio.rs\"\nsynced_at_utc = \"2026-03-18T18:43:57Z\"\nhistory_repo = \"lib/vendor-history/tracing-subscriber.git\"\nhistory_head = \"86291ff1c974187a82c5d33b310940c01f1ed3a8\"\nmaterialized_path = \"lib/vendor/tracing-subscriber\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh tracing-subscriber 0.3.23\"\n" }, { "path": "lib/vendor-manifest/url.toml", "content": "crate = \"url\"\nversion = \"2.5.8\"\nsource = \"crates.io\"\nsynced_at_utc = \"2026-02-22T18:25:03Z\"\nhistory_repo = \"lib/vendor-history/url.git\"\nhistory_head = \"42e98d5f89b624f6d1bb7d3e57f887c74461aed2\"\nmaterialized_path = \"lib/vendor/url\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh url 2.5.8\"\n" }, { "path": "lib/vendor-manifest/x25519-dalek.toml", "content": "crate = \"x25519-dalek\"\nversion = \"2.0.1\"\nsource = \"crates.io\"\nregistry_index = \"https://github.com/rust-lang/crates.io-index\"\ncargo_registry_checksum = \"c7e468321c81fb07fa7f4c636c3972b9100f0346e5b6a9f2bd0603a52f7ed277\"\ncrate_archive_sha256 = \"c7e468321c81fb07fa7f4c636c3972b9100f0346e5b6a9f2bd0603a52f7ed277\"\nchecksum_match = \"yes\"\nupstream_repository = \"https://github.com/dalek-cryptography/curve25519-dalek/tree/main/x25519-dalek\"\nupstream_homepage = \"https://github.com/dalek-cryptography/curve25519-dalek\"\nsynced_at_utc = \"2026-02-23T09:23:30Z\"\nhistory_repo = \"lib/vendor-history/x25519-dalek.git\"\nhistory_head = \"b3c01403757dcebd4c603f0f9c28dc924be49d75\"\nmaterialized_path = \"lib/vendor/x25519-dalek\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh x25519-dalek 2.0.1\"\n" }, { "path": "license", "content": "MIT License\n\nCopyright (c) nikiv.dev\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "pyproject.toml", "content": "[project]\nname = \"flow\"\nversion = \"0.1.0\"\ndescription = \"CLI to demonstrate swarms in action\"\nrequires-python = \">=3.10\"\ndependencies = [\n \"swarms>=8.9.0\",\n \"rich>=13.0.0\",\n]\n\n[project.scripts]\nflow = \"flow:main\"\n\n[tool.uv]\npackage = true\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n" }, { "path": "readme.md", "content": "# [flow](https://myflow.sh)\n\n> Everything you need to move your project faster\n\n## Install\n\nInstall the latest release (macOS/Linux):\n\n```sh\ncurl -fsSL https://myflow.sh/install.sh | sh\n```\n\nThen run:\n\n```sh\n~/.flow/bin/f --version\n~/.flow/bin/f doctor\n```\n\nIf `f` is not found by name immediately, open a new shell (`exec zsh -l` on zsh).\n\nThe installer verifies SHA-256 checksums when available. If you are installing a legacy release\nthat doesn't ship `checksums.txt`, it will warn and continue (GitHub download only). To bypass\nverification explicitly (not recommended), set `FLOW_INSTALL_INSECURE=1`.\n\n## Upgrade\n\nUpgrade to the latest release:\n\n```sh\nf upgrade\n```\n\nUpgrade to the latest canary build:\n\n```sh\nf upgrade --canary\n```\n\nSwitch back to stable:\n\n```sh\nf upgrade --stable\n```\n\nIf you fork Flow (or publish releases under a different repo), set:\n\n- `FLOW_UPGRADE_REPO=owner/repo`\n- `FLOW_GITHUB_TOKEN` (or `GITHUB_TOKEN` / `GH_TOKEN`) to avoid GitHub API rate limits\n\nIf you are upgrading to a very old tag that doesn't ship `checksums.txt`, you can force bypassing\nchecksum verification with `FLOW_UPGRADE_INSECURE=1` (not recommended).\n\n## Build From Source\n\nClone Flow, hydrate the pinned vendor snapshot, and install an optimized local build:\n\n```sh\ngit clone https://github.com/nikivdev/flow.git\ncd flow\n./scripts/vendor/vendor-repo.sh hydrate\nFLOW_PROFILE=release ./scripts/deploy.sh\n~/bin/f --version\n```\n\n- `./scripts/vendor/vendor-repo.sh hydrate` reuses `.vendor/flow-vendor` if it already exists.\n- If `.vendor/flow-vendor` is missing, it clones the pinned vendor repo from [`vendor.lock.toml`](vendor.lock.toml) and materializes `lib/vendor/*` from that exact commit.\n- The pinned vendor repo is public: `https://github.com/nikivdev/flow-vendor`\n- `FLOW_PROFILE=release ./scripts/deploy.sh` builds the optimized release binary and installs `f` / `flow` / `lin` into `~/bin` (and symlinks into `~/.local/bin` if that directory exists).\n\nIf you want to populate the vendor checkout yourself first, that works too:\n\n```sh\ngit clone https://github.com/nikivdev/flow-vendor.git .vendor/flow-vendor\n./scripts/vendor/vendor-repo.sh hydrate\n```\n\n## Dev Fast\n\nTypical local loop:\n\n```sh\nf setup\nf test\nf deploy\n```\n\n- `f setup` checks the workspace and toolchain.\n- `f test` runs the test suite.\n- `f deploy` builds and installs the local CLI into your path.\n\nIf you want to inspect tasks first:\n\n```sh\nf tasks list\n```\n\n## Features\n\nTo see the current CLI surface:\n\n```sh\nf --help\n```\n\nFor deeper docs, read [`docs/`](docs).\n\n## Supported Platforms\n\nRelease artifacts are built for:\n\n- macOS: `arm64`, `x86_64`\n- Linux (glibc): `arm64`, `x86_64`\n\n## Contributing\n\nUse Flow and AI. For the full command surface, run `f --help`. For project docs and workflows, read [`docs/`](docs).\n\n[![Discord](https://go.nikiv.dev/badge-discord)](https://go.nikiv.dev/discord) [![X](https://go.nikiv.dev/badge-x)](https://x.com/nikivdev) [![nikiv.dev](https://go.nikiv.dev/badge-nikiv)](https://nikiv.dev)\n" }, { "path": "scripts/agents-switch.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\ncmd=\"${1:-}\"\nprofile=\"${2:-}\"\nrepo=\"${3:-$(pwd)}\"\n\nif [[ -z \"$cmd\" ]]; then\n echo \"Usage:\"\n echo \" f agents <profile> [repo]\"\n echo \" f agents rules [profile] [repo]\"\n exit 1\nfi\n\nif [[ \"$cmd\" == \"rules\" ]]; then\n if [[ -n \"$profile\" && -d \"$profile\" && -z \"${3:-}\" ]]; then\n repo=\"$profile\"\n profile=\"\"\n elif [[ -n \"${3:-}\" ]]; then\n repo=\"${3}\"\n fi\n\n if [[ ! -d \"$repo\" ]]; then\n echo \"Repo not found: $repo\"\n exit 1\n fi\n if [[ ! -d \"$repo/agents\" ]]; then\n echo \"No agents/ directory in $repo\"\n exit 1\n fi\n mapfile -t profiles < <(ls \"$repo\"/agents/agents.*.md \"$repo\"/agents/AGENTS.*.md 2>/dev/null | sed -E 's#.*/(AGENTS|agents)\\\\.##; s#\\\\.md$##' | sort -u)\n if [[ ${#profiles[@]} -eq 0 ]]; then\n echo \"No profiles found in $repo/agents\"\n exit 1\n fi\n\n if [[ -n \"$profile\" ]]; then\n if [[ ! -f \"$repo/agents/agents.${profile}.md\" && ! -f \"$repo/agents/AGENTS.${profile}.md\" ]]; then\n echo \"Missing profile: $repo/agents/agents.${profile}.md\"\n exit 1\n fi\n else\n if command -v fzf >/dev/null 2>&1; then\n profile=\"$(printf '%s\\n' \"${profiles[@]}\" | fzf --prompt=\"agents> \" --height=40% --border)\"\n else\n echo \"fzf not found; using numbered selection.\"\n select choice in \"${profiles[@]}\"; do\n profile=\"$choice\"\n break\n done\n fi\n if [[ -z \"$profile\" ]]; then\n echo \"No profile selected.\"\n exit 1\n fi\n fi\nelif [[ -z \"$profile\" ]]; then\n if [[ -d \"$repo/agents\" && -f \"$repo/agents/.default\" ]]; then\n profile=\"$(cat \"$repo/agents/.default\" | tr -d '[:space:]')\"\n else\n echo \"Usage:\"\n echo \" f agents <profile> [repo]\"\n echo \" f agents rules [profile] [repo]\"\n exit 1\n fi\nfi\n\nif [[ ! -d \"$repo\" ]]; then\n echo \"Repo not found: $repo\"\n exit 1\nfi\n\ncandidate=\"$repo/agents/agents.${profile}.md\"\nif [[ ! -f \"$candidate\" ]]; then\n candidate=\"$repo/agents/AGENTS.${profile}.md\"\n if [[ ! -f \"$candidate\" ]]; then\n echo \"Missing profile: $candidate\"\n exit 1\n fi\nfi\n\ncp \"$candidate\" \"$repo/agents.md\"\n\necho \"$profile\" > \"$repo/agents/.default\"\necho \"Activated agents.md -> $candidate\"\necho \"Default profile set to: $profile\"\n" }, { "path": "scripts/ai-taskd-launchd.py", "content": "#!/usr/bin/env python3\nimport argparse\nimport os\nimport plistlib\nimport shutil\nimport subprocess\nimport sys\nfrom pathlib import Path\n\n\nLABEL = \"dev.nikiv.flow-ai-taskd\"\n\n\ndef run(cmd: list[str]) -> subprocess.CompletedProcess:\n return subprocess.run(cmd, text=True, capture_output=True, check=False)\n\n\ndef resolve_f_bin(repo_root: Path) -> str:\n env_override = os.environ.get(\"FLOW_AI_TASKD_F_BIN\", \"\").strip()\n if env_override:\n return env_override\n which_f = shutil.which(\"f\")\n if which_f:\n return which_f\n for candidate in [\n repo_root / \"target\" / \"release\" / \"f\",\n repo_root / \"target\" / \"debug\" / \"f\",\n ]:\n if candidate.exists():\n return str(candidate)\n raise SystemExit(\"Could not resolve f binary. Build flow first or set FLOW_AI_TASKD_F_BIN.\")\n\n\ndef plist_path() -> Path:\n return Path.home() / \"Library\" / \"LaunchAgents\" / f\"{LABEL}.plist\"\n\n\ndef domain_target() -> str:\n return f\"gui/{os.getuid()}/{LABEL}\"\n\n\ndef install(repo_root: Path) -> int:\n f_bin = resolve_f_bin(repo_root)\n p = plist_path()\n p.parent.mkdir(parents=True, exist_ok=True)\n log_dir = Path.home() / \".flow\" / \"logs\"\n log_dir.mkdir(parents=True, exist_ok=True)\n\n payload = {\n \"Label\": LABEL,\n \"ProgramArguments\": [f_bin, \"tasks\", \"daemon\", \"serve\"],\n \"RunAtLoad\": True,\n \"KeepAlive\": True,\n \"StandardOutPath\": str(log_dir / \"ai-taskd.launchd.stdout.log\"),\n \"StandardErrorPath\": str(log_dir / \"ai-taskd.launchd.stderr.log\"),\n \"EnvironmentVariables\": {\n \"PATH\": \"/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin\",\n \"FLOW_AI_TASKD_TIMINGS_LOG\": os.environ.get(\"FLOW_AI_TASKD_TIMINGS_LOG\", \"0\"),\n },\n }\n with p.open(\"wb\") as f:\n plistlib.dump(payload, f)\n\n run([\"launchctl\", \"bootout\", f\"gui/{os.getuid()}\", str(p)])\n b = run([\"launchctl\", \"bootstrap\", f\"gui/{os.getuid()}\", str(p)])\n if b.returncode != 0:\n print(b.stderr.strip(), file=sys.stderr)\n return b.returncode\n run([\"launchctl\", \"kickstart\", \"-k\", domain_target()])\n print(f\"loaded: {domain_target()}\")\n print(f\"plist: {p}\")\n print(f\"f_bin: {f_bin}\")\n return 0\n\n\ndef uninstall() -> int:\n p = plist_path()\n run([\"launchctl\", \"bootout\", f\"gui/{os.getuid()}\", str(p)])\n if p.exists():\n p.unlink()\n print(f\"unloaded: {domain_target()}\")\n print(f\"removed: {p}\")\n return 0\n\n\ndef status() -> int:\n out = run([\"launchctl\", \"print\", domain_target()])\n if out.returncode != 0:\n print(f\"{domain_target()}: not loaded\")\n if out.stderr.strip():\n print(out.stderr.strip())\n return 0\n print(out.stdout, end=\"\")\n return 0\n\n\ndef logs(lines: int) -> int:\n log_dir = Path.home() / \".flow\" / \"logs\"\n stdout = log_dir / \"ai-taskd.launchd.stdout.log\"\n stderr = log_dir / \"ai-taskd.launchd.stderr.log\"\n for path in [stdout, stderr]:\n print(f\"==> {path}\")\n if not path.exists():\n print(\"(missing)\")\n continue\n text = path.read_text(encoding=\"utf-8\", errors=\"replace\").splitlines()\n for line in text[-lines:]:\n print(line)\n return 0\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(description=\"Manage launchd service for ai-taskd.\")\n sub = parser.add_subparsers(dest=\"cmd\", required=True)\n sub.add_parser(\"install\")\n sub.add_parser(\"uninstall\")\n sub.add_parser(\"status\")\n p_logs = sub.add_parser(\"logs\")\n p_logs.add_argument(\"--lines\", type=int, default=120)\n args = parser.parse_args()\n\n repo_root = Path(__file__).resolve().parents[1]\n if args.cmd == \"install\":\n return install(repo_root)\n if args.cmd == \"uninstall\":\n return uninstall()\n if args.cmd == \"status\":\n return status()\n if args.cmd == \"logs\":\n return logs(args.lines)\n return 1\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/bench-ai-runtime.py", "content": "#!/usr/bin/env python3\nimport argparse\nimport json\nimport math\nimport os\nimport re\nimport statistics\nimport subprocess\nimport sys\nimport time\nfrom pathlib import Path\nfrom typing import Dict, List, Tuple\n\n\ndef run_cmd(cmd: List[str], cwd: Path, env: Dict[str, str] | None = None, capture: bool = True) -> subprocess.CompletedProcess:\n merged_env = os.environ.copy()\n if env:\n merged_env.update(env)\n return subprocess.run(\n cmd,\n cwd=str(cwd),\n env=merged_env,\n text=True,\n capture_output=capture,\n check=False,\n )\n\n\ndef pct(values_us: List[float], p: float) -> float:\n if not values_us:\n return math.nan\n vals = sorted(values_us)\n idx = int(math.ceil((p / 100.0) * len(vals))) - 1\n idx = max(0, min(idx, len(vals) - 1))\n return vals[idx]\n\n\ndef summarize(values_us: List[float]) -> Dict[str, float]:\n return {\n \"n\": float(len(values_us)),\n \"min_us\": min(values_us),\n \"p50_us\": pct(values_us, 50),\n \"p95_us\": pct(values_us, 95),\n \"p99_us\": pct(values_us, 99),\n \"mean_us\": statistics.fmean(values_us),\n \"max_us\": max(values_us),\n }\n\n\ndef benchmark_command(\n *,\n label: str,\n cmd: List[str],\n cwd: Path,\n env: Dict[str, str] | None,\n warmup: int,\n iterations: int,\n) -> Tuple[str, Dict[str, float]]:\n for _ in range(warmup):\n proc = run_cmd(cmd, cwd=cwd, env=env)\n if proc.returncode != 0:\n raise RuntimeError(f\"warmup failed for {label}: {' '.join(cmd)}\\n{proc.stderr}\")\n\n durations_us: List[float] = []\n for _ in range(iterations):\n start = time.perf_counter_ns()\n proc = run_cmd(cmd, cwd=cwd, env=env)\n end = time.perf_counter_ns()\n if proc.returncode != 0:\n raise RuntimeError(f\"run failed for {label}: {' '.join(cmd)}\\n{proc.stderr}\")\n durations_us.append((end - start) / 1000.0)\n\n return label, summarize(durations_us)\n\n\ndef find_flow_bin(repo: Path, flow_bin: str | None) -> str:\n if flow_bin:\n return flow_bin\n # Prefer release binary first to reduce stale-protocol mismatch when debug was not rebuilt.\n for candidate in [repo / \"target\" / \"release\" / \"f\", repo / \"target\" / \"debug\" / \"f\"]:\n if candidate.exists() and os.access(candidate, os.X_OK):\n return str(candidate)\n return \"f\"\n\n\ndef find_ai_taskd_client_bin(repo: Path) -> str | None:\n for candidate in [\n repo / \"target\" / \"release\" / \"ai-taskd-client\",\n repo / \"target\" / \"debug\" / \"ai-taskd-client\",\n ]:\n if candidate.exists() and os.access(candidate, os.X_OK):\n return str(candidate)\n return None\n\n\ndef ensure_cached_binary(repo: Path, flow_bin: str) -> str:\n proc = run_cmd([flow_bin, \"tasks\", \"build-ai\", \"ai:flow/noop\"], cwd=repo)\n if proc.returncode != 0:\n raise RuntimeError(f\"failed to build noop task cache\\n{proc.stderr}\")\n\n match = re.search(r\"binary:\\s*(.+)\", proc.stdout)\n if not match:\n raise RuntimeError(f\"failed to parse cached binary path from output:\\n{proc.stdout}\")\n\n binary_path = match.group(1).strip()\n if not os.path.exists(binary_path):\n raise RuntimeError(f\"cached binary path does not exist: {binary_path}\")\n return binary_path\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(description=\"Benchmark Flow AI task runtime paths.\")\n parser.add_argument(\"--iterations\", type=int, default=50)\n parser.add_argument(\"--warmup\", type=int, default=5)\n parser.add_argument(\"--flow-bin\", default=None)\n parser.add_argument(\"--json-out\", default=\"\")\n args = parser.parse_args()\n\n if args.iterations <= 0:\n raise SystemExit(\"--iterations must be > 0\")\n\n repo = Path(__file__).resolve().parents[1]\n flow_bin = find_flow_bin(repo, args.flow_bin)\n ai_taskd_client_bin = find_ai_taskd_client_bin(repo)\n\n print(f\"repo: {repo}\")\n print(f\"flow_bin: {flow_bin}\")\n if ai_taskd_client_bin:\n print(f\"ai_taskd_client_bin: {ai_taskd_client_bin}\")\n print(f\"iterations={args.iterations} warmup={args.warmup}\")\n\n # ensure daemon is up for daemon path benchmark (restart to avoid stale protocol mismatch)\n _ = run_cmd([flow_bin, \"tasks\", \"daemon\", \"stop\"], cwd=repo)\n _ = run_cmd([flow_bin, \"tasks\", \"daemon\", \"start\"], cwd=repo)\n\n cached_binary = ensure_cached_binary(repo, flow_bin)\n\n scenarios = [\n (\n \"rust_help\",\n [flow_bin, \"--help\"],\n None,\n ),\n (\n \"moon_run_noop\",\n [flow_bin, \"ai:flow/noop\"],\n {\"FLOW_AI_TASK_RUNTIME\": \"moon-run\"},\n ),\n (\n \"cached_noop\",\n [flow_bin, \"ai:flow/noop\"],\n {\"FLOW_AI_TASK_RUNTIME\": \"cached\"},\n ),\n (\n \"daemon_cached_noop\",\n [flow_bin, \"tasks\", \"run-ai\", \"--daemon\", \"ai:flow/noop\"],\n None,\n ),\n (\n \"cached_binary_direct\",\n [cached_binary],\n {\"FLOW_AI_TASK_PROJECT_ROOT\": str(repo)},\n ),\n ]\n if ai_taskd_client_bin:\n scenarios.append(\n (\n \"daemon_client_noop\",\n [ai_taskd_client_bin, \"ai:flow/noop\"],\n None,\n )\n )\n\n results: Dict[str, Dict[str, float]] = {}\n for label, cmd, env in scenarios:\n label, stats = benchmark_command(\n label=label,\n cmd=cmd,\n cwd=repo,\n env=env,\n warmup=args.warmup,\n iterations=args.iterations,\n )\n results[label] = stats\n print(\n f\"{label:<22} n={int(stats['n'])} p50={stats['p50_us']:.1f}us \"\n f\"p95={stats['p95_us']:.1f}us p99={stats['p99_us']:.1f}us mean={stats['mean_us']:.1f}us\"\n )\n\n cached_vs_moon = results[\"moon_run_noop\"][\"p95_us\"] / results[\"cached_noop\"][\"p95_us\"]\n daemon_vs_cached = results[\"daemon_cached_noop\"][\"p95_us\"] / results[\"cached_noop\"][\"p95_us\"]\n\n print(f\"p95 ratio moon_run/cached: {cached_vs_moon:.2f}x\")\n print(f\"p95 ratio daemon/cached: {daemon_vs_cached:.2f}x\")\n daemon_client_vs_f = None\n if \"daemon_client_noop\" in results:\n daemon_client_vs_f = (\n results[\"daemon_cached_noop\"][\"p95_us\"] / results[\"daemon_client_noop\"][\"p95_us\"]\n )\n print(f\"p95 ratio f-daemon/client-daemon: {daemon_client_vs_f:.2f}x\")\n\n payload = {\n \"repo\": str(repo),\n \"flow_bin\": flow_bin,\n \"iterations\": args.iterations,\n \"warmup\": args.warmup,\n \"results\": results,\n \"ratios\": {\n \"moon_run_p95_div_cached_p95\": cached_vs_moon,\n \"daemon_p95_div_cached_p95\": daemon_vs_cached,\n \"f_daemon_p95_div_client_daemon_p95\": daemon_client_vs_f,\n },\n }\n\n if args.json_out:\n out = Path(args.json_out)\n out.write_text(json.dumps(payload, indent=2) + \"\\n\", encoding=\"utf-8\")\n print(f\"wrote: {out}\")\n\n _ = run_cmd([flow_bin, \"tasks\", \"daemon\", \"stop\"], cwd=repo)\n return 0\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/bench-cli-startup.py", "content": "#!/usr/bin/env python3\nimport argparse\nimport json\nimport math\nimport os\nimport statistics\nimport subprocess\nimport time\nfrom pathlib import Path\nfrom typing import Dict, List, Tuple\n\n\ndef pct(values_ms: List[float], p: float) -> float:\n if not values_ms:\n return math.nan\n vals = sorted(values_ms)\n idx = int(math.ceil((p / 100.0) * len(vals))) - 1\n idx = max(0, min(idx, len(vals) - 1))\n return vals[idx]\n\n\ndef summarize(values_ms: List[float]) -> Dict[str, float]:\n return {\n \"n\": float(len(values_ms)),\n \"min_ms\": min(values_ms),\n \"p50_ms\": pct(values_ms, 50),\n \"p95_ms\": pct(values_ms, 95),\n \"p99_ms\": pct(values_ms, 99),\n \"mean_ms\": statistics.fmean(values_ms),\n \"max_ms\": max(values_ms),\n }\n\n\ndef run_cmd(\n cmd: List[str],\n *,\n cwd: Path,\n env: Dict[str, str],\n) -> subprocess.CompletedProcess[str]:\n merged_env = os.environ.copy()\n merged_env.update(env)\n return subprocess.run(\n cmd,\n cwd=str(cwd),\n env=merged_env,\n text=True,\n capture_output=True,\n check=False,\n )\n\n\ndef benchmark_command(\n *,\n label: str,\n cmd: List[str],\n cwd: Path,\n env: Dict[str, str],\n warmup: int,\n iterations: int,\n) -> Tuple[str, Dict[str, float]]:\n for _ in range(warmup):\n proc = run_cmd(cmd, cwd=cwd, env=env)\n if proc.returncode != 0:\n raise RuntimeError(\n f\"warmup failed for {label}: {' '.join(cmd)}\\n\"\n f\"stdout:\\n{proc.stdout}\\n\"\n f\"stderr:\\n{proc.stderr}\"\n )\n\n durations_ms: List[float] = []\n for _ in range(iterations):\n start = time.perf_counter_ns()\n proc = run_cmd(cmd, cwd=cwd, env=env)\n end = time.perf_counter_ns()\n if proc.returncode != 0:\n raise RuntimeError(\n f\"run failed for {label}: {' '.join(cmd)}\\n\"\n f\"stdout:\\n{proc.stdout}\\n\"\n f\"stderr:\\n{proc.stderr}\"\n )\n durations_ms.append((end - start) / 1_000_000.0)\n\n return label, summarize(durations_ms)\n\n\ndef find_flow_bin(repo: Path, flow_bin: str | None) -> str:\n if flow_bin:\n return flow_bin\n for candidate in [repo / \"target\" / \"release\" / \"f\", repo / \"target\" / \"debug\" / \"f\"]:\n if candidate.exists() and os.access(candidate, os.X_OK):\n return str(candidate)\n return \"f\"\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(\n description=\"Benchmark Flow CLI startup and low-latency read-only commands.\"\n )\n parser.add_argument(\"--iterations\", type=int, default=20)\n parser.add_argument(\"--warmup\", type=int, default=3)\n parser.add_argument(\"--flow-bin\", default=None)\n parser.add_argument(\"--project-root\", default=\".\")\n parser.add_argument(\"--json-out\", default=\"\")\n args = parser.parse_args()\n\n if args.iterations <= 0:\n raise SystemExit(\"--iterations must be > 0\")\n if args.warmup < 0:\n raise SystemExit(\"--warmup must be >= 0\")\n\n repo = Path(__file__).resolve().parents[1]\n project_root = Path(args.project_root).expanduser()\n if not project_root.is_absolute():\n project_root = (repo / project_root).resolve()\n flow_bin = find_flow_bin(repo, args.flow_bin)\n\n base_env = {\n \"CI\": \"1\",\n \"FLOW_ANALYTICS_DISABLE\": \"1\",\n }\n\n scenarios = [\n (\"help\", [flow_bin, \"--help\"], repo),\n (\"help_full\", [flow_bin, \"--help-full\"], repo),\n (\"info\", [flow_bin, \"info\"], project_root),\n (\"projects\", [flow_bin, \"projects\"], project_root),\n (\"analytics_status\", [flow_bin, \"analytics\", \"status\"], project_root),\n (\"tasks_list\", [flow_bin, \"tasks\", \"list\"], project_root),\n (\"tasks_dupes\", [flow_bin, \"tasks\", \"dupes\"], project_root),\n (\"deploy_show_host\", [flow_bin, \"deploy\", \"show-host\"], project_root),\n ]\n\n print(f\"repo: {repo}\", flush=True)\n print(f\"project_root: {project_root}\", flush=True)\n print(f\"flow_bin: {flow_bin}\", flush=True)\n print(f\"iterations={args.iterations} warmup={args.warmup}\", flush=True)\n\n results: Dict[str, Dict[str, float]] = {}\n for label, cmd, cwd in scenarios:\n label, stats = benchmark_command(\n label=label,\n cmd=cmd,\n cwd=cwd,\n env=base_env,\n warmup=args.warmup,\n iterations=args.iterations,\n )\n results[label] = stats\n print(\n f\"{label:<18} n={int(stats['n'])} p50={stats['p50_ms']:.2f}ms \"\n f\"p95={stats['p95_ms']:.2f}ms p99={stats['p99_ms']:.2f}ms \"\n f\"mean={stats['mean_ms']:.2f}ms\",\n flush=True,\n )\n\n payload = {\n \"repo\": str(repo),\n \"project_root\": str(project_root),\n \"flow_bin\": flow_bin,\n \"iterations\": args.iterations,\n \"warmup\": args.warmup,\n \"results\": results,\n }\n\n if args.json_out:\n out = Path(args.json_out).expanduser()\n if not out.is_absolute():\n out = (repo / out).resolve()\n out.parent.mkdir(parents=True, exist_ok=True)\n out.write_text(json.dumps(payload, indent=2) + \"\\n\", encoding=\"utf-8\")\n print(f\"wrote: {out}\", flush=True)\n\n return 0\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/bench-moonbit-rust-ffi.py", "content": "#!/usr/bin/env python3\nimport argparse\nimport json\nimport os\nimport re\nimport subprocess\nfrom pathlib import Path\nfrom typing import Dict\n\n\ndef run(cmd, cwd: Path, env: Dict[str, str] | None = None) -> subprocess.CompletedProcess:\n merged = os.environ.copy()\n if env:\n merged.update(env)\n return subprocess.run(cmd, cwd=str(cwd), text=True, capture_output=True, env=merged, check=False)\n\n\ndef parse_metrics(text: str) -> Dict[str, Dict[str, float]]:\n metrics: Dict[str, Dict[str, float]] = {}\n pattern = re.compile(r\"^(\\S+)\\s+ns_total=(\\d+)\\s+ns_per_op=([0-9.]+)\\s+checksum=(\\d+)$\")\n for line in text.splitlines():\n m = pattern.match(line.strip())\n if not m:\n continue\n label = m.group(1)\n total = int(m.group(2))\n per_op = float(m.group(3))\n checksum = int(m.group(4))\n metrics[label] = {\n \"ns_total\": float(total),\n \"ns_per_op_reported\": per_op,\n \"checksum\": float(checksum),\n }\n return metrics\n\n\ndef write_moon_pkg(moon_dir: Path, rust_lib_dir: Path, cc_flags: str) -> None:\n template = (moon_dir / \"moon.pkg.template.json\").read_text(encoding=\"utf-8\")\n flags = f\"-L{rust_lib_dir} -lflow_ffi_host_boundary\"\n body = template.replace(\"__CC_FLAGS__\", cc_flags).replace(\"__CC_LINK_FLAGS__\", flags)\n (moon_dir / \"moon.pkg.json\").write_text(body, encoding=\"utf-8\")\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(description=\"Benchmark MoonBit <-> Rust FFI boundary overhead.\")\n parser.add_argument(\"--iters\", type=int, default=10_000_000)\n parser.add_argument(\n \"--native-opt\",\n action=\"store_true\",\n help=\"Enable machine-local tuning (Rust target-cpu=native and Moon cc-flags -O3 -march=native).\",\n )\n parser.add_argument(\"--json-out\", default=\"\")\n args = parser.parse_args()\n\n if args.iters <= 0:\n raise SystemExit(\"--iters must be > 0\")\n\n root = Path(__file__).resolve().parents[1]\n rust_manifest = root / \"bench\" / \"ffi_host_boundary\" / \"Cargo.toml\"\n rust_dir = rust_manifest.parent\n moon_dir = root / \"bench\" / \"moon_ffi_boundary\"\n rust_lib_dir = rust_dir / \"target\" / \"release\"\n\n env = {\"FLOW_FFI_ITERS\": str(args.iters)}\n moon_cc_flags = \"-O3\"\n if args.native_opt:\n env[\"RUSTFLAGS\"] = \"-C target-cpu=native\"\n moon_cc_flags = \"-O3 -march=native -mtune=native\"\n\n print(f\"root: {root}\")\n print(f\"iters: {args.iters}\")\n\n build = run([\n \"cargo\",\n \"build\",\n \"--manifest-path\",\n str(rust_manifest),\n \"--release\",\n ], cwd=root)\n if build.returncode != 0:\n print(build.stdout)\n print(build.stderr)\n raise SystemExit(\"failed to build rust ffi host crate\")\n\n write_moon_pkg(moon_dir, rust_lib_dir, moon_cc_flags)\n\n rust_proc = run([\n \"cargo\",\n \"run\",\n \"--manifest-path\",\n str(rust_manifest),\n \"--release\",\n \"--bin\",\n \"rust_boundary_bench\",\n \"--\",\n \"--iters\",\n str(args.iters),\n ], cwd=root, env=env)\n if rust_proc.returncode != 0:\n print(rust_proc.stdout)\n print(rust_proc.stderr)\n raise SystemExit(\"rust benchmark failed\")\n\n moon_proc = run([\n \"moon\",\n \"-C\",\n str(moon_dir),\n \"run\",\n \"main.mbt\",\n \"--target\",\n \"native\",\n \"--release\",\n ], cwd=root, env=env)\n if moon_proc.returncode != 0:\n print(moon_proc.stdout)\n print(moon_proc.stderr)\n raise SystemExit(\"moon benchmark failed\")\n\n rust_metrics = parse_metrics(rust_proc.stdout)\n moon_metrics = parse_metrics(moon_proc.stdout)\n\n required = [\n \"rust_inline_add\",\n \"rust_fn_add\",\n \"rust_extern_add\",\n \"rust_extern_noop\",\n \"moon_ffi_add\",\n \"moon_ffi_noop\",\n ]\n missing = [key for key in required if key not in rust_metrics and key not in moon_metrics]\n if missing:\n raise SystemExit(f\"missing metrics in output: {missing}\")\n\n def ns_per_op(metrics: Dict[str, Dict[str, float]], key: str) -> float:\n return metrics[key][\"ns_total\"] / float(args.iters)\n\n print(\"--- Rust ---\")\n for key in [\"rust_inline_add\", \"rust_fn_add\", \"rust_extern_add\", \"rust_extern_noop\"]:\n if key in rust_metrics:\n m = rust_metrics[key]\n print(\n f\"{key:<18} ns/op={ns_per_op(rust_metrics, key):.4f} \"\n f\"total_ns={int(m['ns_total'])} checksum={int(m['checksum'])}\"\n )\n\n print(\"--- MoonBit ---\")\n for key in [\"moon_add\", \"moon_ffi_add\", \"moon_ffi_noop\"]:\n if key in moon_metrics:\n m = moon_metrics[key]\n print(\n f\"{key:<18} ns/op={ns_per_op(moon_metrics, key):.4f} \"\n f\"total_ns={int(m['ns_total'])} checksum={int(m['checksum'])}\"\n )\n\n ratios = {\n \"moon_ffi_add_div_rust_extern_add\": ns_per_op(moon_metrics, \"moon_ffi_add\")\n / ns_per_op(rust_metrics, \"rust_extern_add\"),\n \"moon_ffi_noop_div_rust_extern_noop\": ns_per_op(moon_metrics, \"moon_ffi_noop\")\n / ns_per_op(rust_metrics, \"rust_extern_noop\"),\n }\n\n print(\"--- Ratios ---\")\n for k, v in ratios.items():\n print(f\"{k}: {v:.3f}x\")\n\n payload = {\n \"iters\": args.iters,\n \"native_opt\": args.native_opt,\n \"rust\": rust_metrics,\n \"moon\": moon_metrics,\n \"ns_per_op\": {\n \"rust_inline_add\": ns_per_op(rust_metrics, \"rust_inline_add\"),\n \"rust_fn_add\": ns_per_op(rust_metrics, \"rust_fn_add\"),\n \"rust_extern_add\": ns_per_op(rust_metrics, \"rust_extern_add\"),\n \"rust_extern_noop\": ns_per_op(rust_metrics, \"rust_extern_noop\"),\n \"moon_ffi_add\": ns_per_op(moon_metrics, \"moon_ffi_add\"),\n \"moon_ffi_noop\": ns_per_op(moon_metrics, \"moon_ffi_noop\"),\n },\n \"ratios\": ratios,\n }\n if \"moon_add\" in moon_metrics:\n payload[\"ns_per_op\"][\"moon_add\"] = ns_per_op(moon_metrics, \"moon_add\")\n\n if args.json_out:\n out = Path(args.json_out)\n out.write_text(json.dumps(payload, indent=2) + \"\\n\", encoding=\"utf-8\")\n print(f\"wrote: {out}\")\n\n return 0\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/build_rl_runtime_dataset.py", "content": "#!/usr/bin/env python3\n\"\"\"Build Harbor-ready RL dataset snapshots from Flow + Seq runtime traces.\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport hashlib\nimport json\nimport re\nfrom collections import Counter, defaultdict\nfrom dataclasses import dataclass\nfrom datetime import datetime, timezone\nfrom pathlib import Path\nfrom typing import Any\n\n\nSEQ_HIGH_SIGNAL_PATTERNS = [\n r\"^seqd\\.request$\",\n r\"^seqd\\.run(\\.|$)\",\n r\"^cli\\.run(\\.|$)\",\n r\"^cli\\.agent$\",\n r\"^cli\\.open_app_toggle(\\.|$)\",\n r\"^seq\\.sequence\\.\",\n r\"^menu\\.select\\.\",\n r\"^open_url(\\.|$)\",\n r\"^app\\.activate$\",\n r\"^actions\\.\",\n r\"^AX_(STATUS|PROMPT)$\",\n]\nSEQ_HIGH_SIGNAL_RE = re.compile(\"|\".join(f\"(?:{p})\" for p in SEQ_HIGH_SIGNAL_PATTERNS))\nLONG_TOKEN_RE = re.compile(r\"\\b[A-Za-z0-9_\\-]{32,}\\b\")\n\n\n@dataclass\nclass DatasetRow:\n id: str\n source: str\n event_name: str\n at_ms: int\n success: bool\n duration_ms: int\n error_class: str\n record: dict[str, Any]\n\n\ndef _read_jsonl(path: Path, *, last: int = 0) -> list[dict[str, Any]]:\n if not path.exists():\n return []\n lines = path.read_text(encoding=\"utf-8\", errors=\"replace\").splitlines()\n if last > 0:\n lines = lines[-last:]\n out: list[dict[str, Any]] = []\n for line in lines:\n line = line.strip()\n if not line:\n continue\n try:\n payload = json.loads(line)\n except json.JSONDecodeError:\n continue\n if isinstance(payload, dict):\n out.append(payload)\n return out\n\n\ndef _now_stamp() -> str:\n return datetime.now(timezone.utc).strftime(\"%Y%m%d-%H%M%S\")\n\n\ndef _hash_id(parts: list[str]) -> str:\n joined = \"||\".join(parts)\n return hashlib.sha256(joined.encode(\"utf-8\")).hexdigest()\n\n\ndef _bucket(row_id: str, seed: int) -> int:\n digest = hashlib.sha256(f\"{seed}:{row_id}\".encode(\"utf-8\")).hexdigest()\n return int(digest[:8], 16) % 100\n\n\ndef _as_int(value: Any, default: int = 0) -> int:\n if isinstance(value, bool):\n return default\n if isinstance(value, int):\n return value\n if isinstance(value, float) and value.is_integer():\n return int(value)\n return default\n\n\ndef _sanitize_text(value: Any) -> str:\n if not isinstance(value, str):\n return \"\"\n text = value.strip()\n text = LONG_TOKEN_RE.sub(\"[REDACTED]\", text)\n return text\n\n\ndef _extract_captured_text(value: Any) -> str:\n if isinstance(value, dict):\n text = value.get(\"text\")\n if isinstance(text, str):\n return _sanitize_text(text)\n return \"\"\n return _sanitize_text(value)\n\n\ndef _reward_components(success: bool, duration_ms: int) -> tuple[float, float, float]:\n success_score = 1.0 if success else 0.0\n # Keep this bounded and simple for initial training signal.\n efficiency = max(0.0, 1.0 - (min(duration_ms, 20_000) / 20_000.0))\n composite = (0.8 * success_score) + (0.2 * efficiency)\n return round(success_score, 6), round(efficiency, 6), round(composite, 6)\n\n\ndef _normalize_flow(rows: list[dict[str, Any]]) -> list[DatasetRow]:\n out: list[DatasetRow] = []\n for idx, row in enumerate(rows, start=1):\n event_type = str(row.get(\"event_type\") or \"\")\n if not event_type.startswith(\"everruns.\"):\n continue\n\n stage = str(row.get(\"stage\") or \"\")\n event_name = f\"everruns.stage.{stage}\" if event_type == \"everruns.runtime_event\" and stage else event_type\n\n session_id = str(row.get(\"session_id\") or \"\")\n event_id = str(row.get(\"event_id\") or f\"flow-event-{idx}\")\n ts_ms = max(0, _as_int(row.get(\"ts_unix_ms\"), 0))\n duration_ms = max(0, _as_int(row.get(\"duration_ms\"), 0))\n success = bool(row.get(\"ok\", True))\n error_class = _sanitize_text(row.get(\"error_class\"))\n\n if event_type == \"everruns.qa_pair\":\n prompt = _extract_captured_text(row.get(\"prompt_text\"))\n response = _extract_captured_text(row.get(\"response_text\"))\n if not prompt or not response:\n continue\n success_score, efficiency_score, composite = _reward_components(success, duration_ms)\n stable_id = _hash_id(\n [\n \"flow_qa\",\n session_id,\n event_id,\n str(ts_ms),\n prompt[:256],\n response[:256],\n ]\n )\n record = {\n \"record_type\": \"assistant_sft_example\",\n \"id\": stable_id,\n \"source\": \"flow_rl_signals\",\n \"event_name\": event_name,\n \"at_ms\": ts_ms,\n \"success\": success,\n \"duration_ms\": duration_ms,\n \"error_class\": error_class,\n \"session_id\": session_id,\n \"prompt\": prompt,\n \"response\": response,\n \"reward_components\": {\n \"success\": success_score,\n \"efficiency\": efficiency_score,\n },\n \"reward_composite\": composite,\n \"metadata\": {\n \"runtime\": str(row.get(\"runtime\") or \"\"),\n \"input_message_id\": _sanitize_text(row.get(\"input_message_id\")),\n \"event_id\": event_id,\n },\n }\n out.append(\n DatasetRow(\n id=stable_id,\n source=\"flow_rl_signals\",\n event_name=event_name,\n at_ms=ts_ms,\n success=success,\n duration_ms=duration_ms,\n error_class=error_class,\n record=record,\n )\n )\n continue\n\n stable_id = _hash_id([\"flow\", session_id, event_id, event_name, str(ts_ms)])\n success_score, efficiency_score, composite = _reward_components(success, duration_ms)\n\n record = {\n \"record_type\": \"runtime_training_event\",\n \"id\": stable_id,\n \"source\": \"flow_rl_signals\",\n \"event_name\": event_name,\n \"at_ms\": ts_ms,\n \"success\": success,\n \"duration_ms\": duration_ms,\n \"error_class\": error_class,\n \"session_id\": session_id,\n \"reward_components\": {\n \"success\": success_score,\n \"efficiency\": efficiency_score,\n },\n \"reward_composite\": composite,\n \"metadata\": {\n \"runtime\": str(row.get(\"runtime\") or \"\"),\n \"tool_call_id\": _sanitize_text(row.get(\"tool_call_id\")),\n \"tool_name\": _sanitize_text(row.get(\"tool_name\")),\n \"seq_op\": _sanitize_text(row.get(\"seq_op\")),\n \"attrs\": row.get(\"attrs\", {}),\n },\n }\n out.append(\n DatasetRow(\n id=stable_id,\n source=\"flow_rl_signals\",\n event_name=event_name,\n at_ms=ts_ms,\n success=success,\n duration_ms=duration_ms,\n error_class=error_class,\n record=record,\n )\n )\n return out\n\n\ndef _normalize_seq(rows: list[dict[str, Any]]) -> list[DatasetRow]:\n out: list[DatasetRow] = []\n for idx, row in enumerate(rows, start=1):\n name = str(row.get(\"name\") or row.get(\"event\") or row.get(\"kind\") or \"\")\n if not name:\n continue\n\n if name == \"agent.qa.pair\":\n subject_raw = row.get(\"subject\")\n subject_obj: dict[str, Any] = {}\n if isinstance(subject_raw, str):\n try:\n parsed = json.loads(subject_raw)\n if isinstance(parsed, dict):\n subject_obj = parsed\n except json.JSONDecodeError:\n subject_obj = {}\n elif isinstance(subject_raw, dict):\n subject_obj = subject_raw\n\n prompt = _sanitize_text(subject_obj.get(\"question\"))\n response = _sanitize_text(subject_obj.get(\"answer\"))\n if not prompt or not response:\n continue\n\n event_id = str(row.get(\"event_id\") or f\"seq-event-{idx}\")\n session_id = str(row.get(\"session_id\") or subject_obj.get(\"session_id\") or \"\")\n ts_ms = max(0, _as_int(row.get(\"ts_ms\"), 0))\n dur_us = max(0, _as_int(row.get(\"dur_us\"), 0))\n duration_ms = dur_us // 1000\n success = bool(row.get(\"ok\", True))\n error_class = \"\"\n stable_id = _hash_id(\n [\n \"seq_qa\",\n session_id,\n event_id,\n str(ts_ms),\n prompt[:256],\n response[:256],\n ]\n )\n success_score, efficiency_score, composite = _reward_components(success, duration_ms)\n record = {\n \"record_type\": \"assistant_sft_example\",\n \"id\": stable_id,\n \"source\": \"seq_mem\",\n \"event_name\": name,\n \"at_ms\": ts_ms,\n \"success\": success,\n \"duration_ms\": duration_ms,\n \"error_class\": error_class,\n \"session_id\": session_id,\n \"prompt\": prompt,\n \"response\": response,\n \"reward_components\": {\n \"success\": success_score,\n \"efficiency\": efficiency_score,\n },\n \"reward_composite\": composite,\n \"metadata\": {\n \"agent\": _sanitize_text(subject_obj.get(\"agent\")),\n \"project_path\": _sanitize_text(subject_obj.get(\"project_path\")),\n \"source_path\": _sanitize_text(subject_obj.get(\"source_path\")),\n \"line_offset\": _as_int(subject_obj.get(\"offset\"), 0),\n },\n }\n out.append(\n DatasetRow(\n id=stable_id,\n source=\"seq_mem\",\n event_name=name,\n at_ms=ts_ms,\n success=success,\n duration_ms=duration_ms,\n error_class=error_class,\n record=record,\n )\n )\n continue\n\n if not SEQ_HIGH_SIGNAL_RE.search(name):\n continue\n\n event_id = str(row.get(\"event_id\") or f\"seq-event-{idx}\")\n session_id = str(row.get(\"session_id\") or \"\")\n ts_ms = max(0, _as_int(row.get(\"ts_ms\"), 0))\n dur_us = max(0, _as_int(row.get(\"dur_us\"), 0))\n duration_ms = dur_us // 1000\n success = bool(row.get(\"ok\", True))\n error_class = \"\"\n\n stable_id = _hash_id([\"seq\", session_id, event_id, name, str(ts_ms)])\n success_score, efficiency_score, composite = _reward_components(success, duration_ms)\n subject = _sanitize_text(row.get(\"subject\"))\n\n record = {\n \"record_type\": \"runtime_training_event\",\n \"id\": stable_id,\n \"source\": \"seq_mem\",\n \"event_name\": name,\n \"at_ms\": ts_ms,\n \"success\": success,\n \"duration_ms\": duration_ms,\n \"error_class\": error_class,\n \"session_id\": session_id,\n \"reward_components\": {\n \"success\": success_score,\n \"efficiency\": efficiency_score,\n },\n \"reward_composite\": composite,\n \"metadata\": {\n \"event_id\": event_id,\n \"subject\": subject,\n \"content_hash\": _sanitize_text(row.get(\"content_hash\")),\n },\n }\n out.append(\n DatasetRow(\n id=stable_id,\n source=\"seq_mem\",\n event_name=name,\n at_ms=ts_ms,\n success=success,\n duration_ms=duration_ms,\n error_class=error_class,\n record=record,\n )\n )\n return out\n\n\ndef _cap_by_event(rows: list[DatasetRow], *, max_per_event: int, seed: int) -> tuple[list[DatasetRow], dict[str, int]]:\n if max_per_event <= 0:\n return rows, {}\n grouped: dict[str, list[DatasetRow]] = defaultdict(list)\n for row in rows:\n grouped[row.event_name].append(row)\n\n kept: list[DatasetRow] = []\n dropped: dict[str, int] = {}\n for event_name, event_rows in grouped.items():\n ranked = sorted(\n event_rows,\n key=lambda r: hashlib.sha256(f\"{seed}:{r.id}\".encode(\"utf-8\")).hexdigest(),\n )\n kept_rows = ranked[:max_per_event]\n kept.extend(kept_rows)\n if len(ranked) > max_per_event:\n dropped[event_name] = len(ranked) - max_per_event\n kept.sort(key=lambda r: (r.at_ms, r.id))\n return kept, dropped\n\n\ndef _write_jsonl(path: Path, rows: list[dict[str, Any]]) -> None:\n path.parent.mkdir(parents=True, exist_ok=True)\n with path.open(\"w\", encoding=\"utf-8\") as fh:\n for row in rows:\n fh.write(json.dumps(row, ensure_ascii=True))\n fh.write(\"\\n\")\n\n\ndef _build_report(\n rows: list[DatasetRow],\n train: list[DatasetRow],\n val: list[DatasetRow],\n test: list[DatasetRow],\n *,\n min_rows: int,\n min_unique_events: int,\n max_dominance: float,\n) -> tuple[dict[str, Any], bool]:\n errors: list[str] = []\n warnings: list[str] = []\n\n total_rows = len(rows)\n if total_rows < max(1, min_rows):\n errors.append(f\"rows below threshold: {total_rows} < {min_rows}\")\n if not train:\n errors.append(\"train split is empty\")\n\n event_counts = Counter(r.event_name for r in rows)\n record_type_counts = Counter(str(r.record.get(\"record_type\") or \"\") for r in rows)\n sft_only = total_rows > 0 and set(record_type_counts.keys()) <= {\"assistant_sft_example\"}\n unique_events = len(event_counts)\n min_unique_gate = 1 if sft_only else max(1, min_unique_events)\n if unique_events < min_unique_gate:\n errors.append(f\"unique event names below threshold: {unique_events} < {min_unique_gate}\")\n\n dominant_name = \"\"\n dominant_ratio = 0.0\n if event_counts and total_rows > 0:\n dominant_name, dominant_count = event_counts.most_common(1)[0]\n dominant_ratio = dominant_count / total_rows\n dominance_gate = 1.0 if sft_only else max_dominance\n if dominant_ratio > dominance_gate:\n errors.append(\n f\"event dominance too high: {dominant_name}={dominant_ratio:.3f} > {dominance_gate:.3f}\"\n )\n\n success_count = sum(1 for r in rows if r.success)\n success_rate = (success_count / total_rows) if total_rows else 0.0\n if total_rows > 0 and (success_rate < 0.05 or success_rate > 0.98):\n warnings.append(f\"success rate skewed: {success_rate:.3f}\")\n\n report = {\n \"schema_version\": \"flow_runtime_validation_v1\",\n \"generated_at\": datetime.now(timezone.utc).isoformat(),\n \"ok\": len(errors) == 0,\n \"counts\": {\n \"rows\": total_rows,\n \"train_rows\": len(train),\n \"val_rows\": len(val),\n \"test_rows\": len(test),\n \"unique_events\": unique_events,\n \"success_rate\": round(success_rate, 6),\n \"record_types\": dict(record_type_counts),\n \"sft_only\": sft_only,\n },\n \"dominance\": {\n \"event_name\": dominant_name,\n \"ratio\": round(dominant_ratio, 6),\n },\n \"errors\": errors,\n \"warnings\": warnings,\n }\n return report, len(errors) == 0\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(description=\"Build RL runtime dataset from flow + seq logs\")\n parser.add_argument(\"--harbor-dir\", default=str(Path(\"~/repos/laude-institute/harbor\").expanduser()))\n parser.add_argument(\"--flow-signals\", default=\"out/logs/flow_rl_signals.jsonl\")\n parser.add_argument(\"--seq-mem\", default=str(Path(\"~/.config/flow/rl/seq_mem.jsonl\").expanduser()))\n parser.add_argument(\"--snapshot\", default=\"\", help=\"snapshot name; default timestamp\")\n parser.add_argument(\"--flow-last\", type=int, default=20_000)\n parser.add_argument(\"--seq-last\", type=int, default=50_000)\n parser.add_argument(\"--seed\", type=int, default=42)\n parser.add_argument(\"--val-percent\", type=int, default=10)\n parser.add_argument(\"--test-percent\", type=int, default=10)\n parser.add_argument(\"--max-per-event\", type=int, default=120)\n parser.add_argument(\"--min-rows\", type=int, default=50)\n parser.add_argument(\"--min-unique-events\", type=int, default=3)\n parser.add_argument(\"--max-dominance\", type=float, default=0.90)\n parser.add_argument(\"--write-latest\", action=\"store_true\")\n parser.add_argument(\"--allow-quality-fail\", action=\"store_true\")\n args = parser.parse_args()\n\n harbor_dir = Path(args.harbor_dir).expanduser().resolve()\n snapshot = args.snapshot.strip() or _now_stamp()\n\n flow_rows_raw = _read_jsonl(Path(args.flow_signals).expanduser().resolve(), last=max(0, args.flow_last))\n seq_rows_raw = _read_jsonl(Path(args.seq_mem).expanduser().resolve(), last=max(0, args.seq_last))\n\n flow_rows = _normalize_flow(flow_rows_raw)\n seq_rows = _normalize_seq(seq_rows_raw)\n merged = flow_rows + seq_rows\n\n unique: dict[str, DatasetRow] = {}\n for row in merged:\n unique[row.id] = row\n deduped = list(unique.values())\n deduped.sort(key=lambda r: (r.at_ms, r.id))\n deduped, dropped_by_event = _cap_by_event(\n deduped,\n max_per_event=max(0, args.max_per_event),\n seed=args.seed,\n )\n\n val_pct = max(0, min(args.val_percent, 100))\n test_pct = max(0, min(args.test_percent, 100 - val_pct))\n train_rows: list[DatasetRow] = []\n val_rows: list[DatasetRow] = []\n test_rows: list[DatasetRow] = []\n\n for row in deduped:\n b = _bucket(row.id, args.seed)\n if b < test_pct:\n test_rows.append(row)\n elif b < test_pct + val_pct:\n val_rows.append(row)\n else:\n train_rows.append(row)\n\n raw_dir = harbor_dir / \"data\" / \"flow_runtime\" / snapshot\n prepared_dir = harbor_dir / \"data\" / \"flow_runtime_prepared\" / snapshot\n _write_jsonl(raw_dir / \"events.jsonl\", [r.record for r in deduped])\n _write_jsonl(prepared_dir / \"train.jsonl\", [r.record for r in train_rows])\n _write_jsonl(prepared_dir / \"val.jsonl\", [r.record for r in val_rows])\n _write_jsonl(prepared_dir / \"test.jsonl\", [r.record for r in test_rows])\n\n event_counts = Counter(r.event_name for r in deduped)\n _write_jsonl(\n prepared_dir / \"event_counts.jsonl\",\n [{\"event_name\": name, \"count\": count} for name, count in event_counts.most_common()],\n )\n\n manifest = {\n \"schema_version\": \"flow_runtime_dataset_v1\",\n \"generated_at\": datetime.now(timezone.utc).isoformat(),\n \"snapshot\": snapshot,\n \"seed\": args.seed,\n \"split\": {\"val_percent\": val_pct, \"test_percent\": test_pct},\n \"cap\": {\"max_per_event\": max(0, args.max_per_event), \"dropped_by_event\": dropped_by_event},\n \"counts\": {\n \"flow_rows_raw\": len(flow_rows_raw),\n \"seq_rows_raw\": len(seq_rows_raw),\n \"flow_rows_mapped\": len(flow_rows),\n \"seq_rows_mapped\": len(seq_rows),\n \"deduped_rows\": len(deduped),\n \"train_rows\": len(train_rows),\n \"val_rows\": len(val_rows),\n \"test_rows\": len(test_rows),\n },\n \"paths\": {\n \"raw_events\": str(raw_dir / \"events.jsonl\"),\n \"train\": str(prepared_dir / \"train.jsonl\"),\n \"val\": str(prepared_dir / \"val.jsonl\"),\n \"test\": str(prepared_dir / \"test.jsonl\"),\n \"event_counts\": str(prepared_dir / \"event_counts.jsonl\"),\n },\n }\n (raw_dir / \"summary.json\").write_text(json.dumps(manifest, indent=2) + \"\\n\", encoding=\"utf-8\")\n (prepared_dir / \"manifest.json\").write_text(json.dumps(manifest, indent=2) + \"\\n\", encoding=\"utf-8\")\n\n report, ok = _build_report(\n deduped,\n train_rows,\n val_rows,\n test_rows,\n min_rows=max(1, args.min_rows),\n min_unique_events=max(1, args.min_unique_events),\n max_dominance=max(0.0, min(args.max_dominance, 1.0)),\n )\n (prepared_dir / \"validation_report.json\").write_text(json.dumps(report, indent=2) + \"\\n\", encoding=\"utf-8\")\n\n if args.write_latest:\n latest_raw = harbor_dir / \"data\" / \"flow_runtime\" / \"latest\"\n latest_prepared = harbor_dir / \"data\" / \"flow_runtime_prepared\" / \"latest\"\n _write_jsonl(latest_raw / \"events.jsonl\", [r.record for r in deduped])\n _write_jsonl(latest_prepared / \"train.jsonl\", [r.record for r in train_rows])\n _write_jsonl(latest_prepared / \"val.jsonl\", [r.record for r in val_rows])\n _write_jsonl(latest_prepared / \"test.jsonl\", [r.record for r in test_rows])\n _write_jsonl(\n latest_prepared / \"event_counts.jsonl\",\n [{\"event_name\": name, \"count\": count} for name, count in event_counts.most_common()],\n )\n (latest_raw / \"summary.json\").write_text(json.dumps(manifest, indent=2) + \"\\n\", encoding=\"utf-8\")\n (latest_prepared / \"manifest.json\").write_text(json.dumps(manifest, indent=2) + \"\\n\", encoding=\"utf-8\")\n (latest_prepared / \"validation_report.json\").write_text(\n json.dumps(report, indent=2) + \"\\n\",\n encoding=\"utf-8\",\n )\n\n print(f\"Built flow runtime dataset snapshot: {snapshot}\")\n print(f\" flow rows mapped: {len(flow_rows)}\")\n print(f\" seq rows mapped: {len(seq_rows)}\")\n print(f\" deduped rows: {len(deduped)}\")\n print(f\" train/val/test: {len(train_rows)}/{len(val_rows)}/{len(test_rows)}\")\n print(f\" quality ok: {ok}\")\n print(f\" raw: {raw_dir}\")\n print(f\" prepared: {prepared_dir}\")\n\n if not ok and not args.allow_quality_fail:\n return 1\n return 0\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/cdn-nginx.conf", "content": "# Nginx config for cdn.myflow.sh\n# Copy to /etc/nginx/sites-available/cdn.myflow.sh\n# Then: ln -s /etc/nginx/sites-available/cdn.myflow.sh /etc/nginx/sites-enabled/\n# And: nginx -t && systemctl reload nginx\n\nserver {\n listen 80;\n server_name cdn.myflow.sh;\n return 301 https://$server_name$request_uri;\n}\n\nserver {\n listen 443 ssl http2;\n server_name cdn.myflow.sh;\n\n # SSL certs (use certbot)\n ssl_certificate /etc/letsencrypt/live/cdn.myflow.sh/fullchain.pem;\n ssl_certificate_key /etc/letsencrypt/live/cdn.myflow.sh/privkey.pem;\n\n root /var/www/cdn.myflow.sh;\n autoindex on;\n\n # Cache static files\n location / {\n add_header Cache-Control \"public, max-age=31536000\";\n add_header Access-Control-Allow-Origin \"*\";\n }\n\n # Gzip\n gzip on;\n gzip_types application/octet-stream application/x-tar;\n}\n" }, { "path": "scripts/check_cli_startup_thresholds.py", "content": "#!/usr/bin/env python3\nfrom __future__ import annotations\n\nimport argparse\nimport json\nfrom pathlib import Path\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(\n description=\"Fail when CLI startup benchmark results exceed repository thresholds.\"\n )\n parser.add_argument(\"benchmark_json\", help=\"Path to JSON output from scripts/bench-cli-startup.py\")\n parser.add_argument(\n \"--thresholds\",\n default=str(Path(__file__).with_name(\"cli_startup_thresholds.json\")),\n help=\"Path to threshold JSON file\",\n )\n args = parser.parse_args()\n\n benchmark_path = Path(args.benchmark_json).expanduser()\n thresholds_path = Path(args.thresholds).expanduser()\n\n payload = json.loads(benchmark_path.read_text(encoding=\"utf-8\"))\n thresholds = json.loads(thresholds_path.read_text(encoding=\"utf-8\"))\n\n violations: list[str] = []\n results = payload.get(\"results\", {})\n\n for scenario, expected in thresholds.items():\n actual = results.get(scenario)\n if actual is None:\n violations.append(f\"{scenario}: missing from benchmark output\")\n continue\n for metric, limit in expected.items():\n value = actual.get(metric)\n if value is None:\n violations.append(f\"{scenario}: missing metric {metric}\")\n continue\n if value > limit:\n violations.append(\n f\"{scenario}: {metric}={value:.2f}ms exceeds {limit:.2f}ms\"\n )\n\n if violations:\n print(\"CLI startup threshold violations:\")\n for violation in violations:\n print(f\" - {violation}\")\n return 1\n\n print(\"CLI startup thresholds passed.\")\n return 0\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/check_release_tag_version.py", "content": "#!/usr/bin/env python3\nfrom __future__ import annotations\n\nimport pathlib\nimport re\nimport sys\n\n\ndef read_package_version(cargo_toml: pathlib.Path) -> str:\n text = cargo_toml.read_text(encoding=\"utf-8\")\n in_package = False\n for raw_line in text.splitlines():\n line = raw_line.strip()\n if line.startswith(\"[\"):\n in_package = line == \"[package]\"\n continue\n if not in_package:\n continue\n match = re.match(r'version\\s*=\\s*\"([^\"]+)\"', line)\n if match:\n return match.group(1)\n raise RuntimeError(f\"failed to find [package].version in {cargo_toml}\")\n\n\ndef main(argv: list[str]) -> int:\n if len(argv) != 2:\n print(\"usage: check_release_tag_version.py <tag>\", file=sys.stderr)\n return 2\n\n tag = argv[1]\n if not tag.startswith(\"v\"):\n print(f\"error: expected release tag like vX.Y.Z, got {tag}\", file=sys.stderr)\n return 1\n\n root = pathlib.Path(__file__).resolve().parent.parent\n version = read_package_version(root / \"Cargo.toml\")\n expected_tag = f\"v{version}\"\n if tag != expected_tag:\n print(\n f\"error: release tag {tag} does not match Cargo.toml version {version} \"\n f\"(expected {expected_tag})\",\n file=sys.stderr,\n )\n return 1\n\n print(f\"verified: release tag {tag} matches Cargo.toml version {version}\")\n return 0\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main(sys.argv))\n" }, { "path": "scripts/ci/check-readme-case.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\n# Enforce lowercase readme filenames in tracked files.\nbad=\"$(git ls-files | rg '(^|/)README\\.md$' || true)\"\n\nif [[ -n \"$bad\" ]]; then\n echo \"error: uppercase README.md paths are not allowed; use lowercase readme.md\"\n echo \"$bad\" | sed 's/^/ - /'\n exit 1\nfi\n\necho \"ok: no uppercase README.md paths found\"\n" }, { "path": "scripts/ci_blacksmith.py", "content": "#!/usr/bin/env python3\n\"\"\"\nToggle CI workflows between runner profiles.\n\nProfiles:\n - github: Default GitHub-hosted Linux jobs, SIMD lane disabled.\n - blacksmith: Blacksmith Linux jobs, SIMD lane enabled on Blacksmith.\n - host: GitHub Linux jobs, SIMD lane enabled on ci.1focus.ai self-hosted runner.\n\nUsage:\n python3 scripts/ci_blacksmith.py status\n python3 scripts/ci_blacksmith.py enable\n python3 scripts/ci_blacksmith.py enable --commit --push\n python3 scripts/ci_blacksmith.py host\n python3 scripts/ci_blacksmith.py disable\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport re\nimport subprocess\nimport sys\nfrom pathlib import Path\n\nROOT = Path(__file__).resolve().parents[1]\nWORKFLOWS = [\n ROOT / \".github\" / \"workflows\" / \"canary.yml\",\n ROOT / \".github\" / \"workflows\" / \"release.yml\",\n]\n\nGITHUB_X64 = \"ubuntu-latest\"\nGITHUB_ARM = \"ubuntu-latest\"\nBLACKSMITH_X64 = \"blacksmith-2vcpu-ubuntu-2404\"\nBLACKSMITH_ARM = \"blacksmith-2vcpu-ubuntu-2404-arm\"\nBLACKSMITH_SIMD = \"blacksmith-4vcpu-ubuntu-2404\"\nHOST_SIMD = \"[self-hosted, linux, x64, ci-1focus]\"\n\nWORKFLOW_REL_PATHS = [\n \".github/workflows/canary.yml\",\n \".github/workflows/release.yml\",\n]\n\n\ndef rewrite_workflow(path: Path, mode: str) -> bool:\n content = path.read_text(encoding=\"utf-8\")\n original = content\n\n if mode == \"blacksmith\":\n linux_x64 = BLACKSMITH_X64\n linux_arm = BLACKSMITH_ARM\n simd_runs_on = BLACKSMITH_SIMD\n simd_if_line = \"\"\n elif mode == \"host\":\n linux_x64 = GITHUB_X64\n linux_arm = GITHUB_ARM\n simd_runs_on = HOST_SIMD\n simd_if_line = \"\"\n else:\n linux_x64 = GITHUB_X64\n linux_arm = GITHUB_ARM\n simd_runs_on = \"ubuntu-latest\"\n simd_if_line = \" if: ${{ false }}\\n\"\n\n content = re.sub(\n r\"(- target: x86_64-unknown-linux-gnu\\s*\\n\\s*os:\\s*)([^\\n]+)\",\n rf\"\\1{linux_x64}\",\n content,\n count=1,\n )\n content = re.sub(\n r\"(- target: aarch64-unknown-linux-gnu\\s*\\n\\s*os:\\s*)([^\\n]+)\",\n rf\"\\1{linux_arm}\",\n content,\n count=1,\n )\n\n simd_block = re.compile(\n r\"(^ build-linux-host-simd:\\n)(?P<body>(?:^ .*\\n)*)\",\n re.MULTILINE,\n )\n block_match = simd_block.search(content)\n if block_match:\n body_lines = block_match.group(\"body\").splitlines(keepends=True)\n rewritten_body: list[str] = []\n has_runs_on = False\n for line in body_lines:\n if re.match(r\"^ if:\", line):\n continue\n if re.match(r\"^ runs-on:\", line):\n rewritten_body.append(f\" runs-on: {simd_runs_on}\\n\")\n has_runs_on = True\n continue\n rewritten_body.append(line)\n\n if not has_runs_on:\n rewritten_body.insert(0, f\" runs-on: {simd_runs_on}\\n\")\n if simd_if_line:\n rewritten_body.insert(0, simd_if_line)\n\n replacement = block_match.group(1) + \"\".join(rewritten_body)\n content = (\n content[: block_match.start()]\n + replacement\n + content[block_match.end() :]\n )\n\n changed = content != original\n if changed:\n path.write_text(content, encoding=\"utf-8\")\n return changed\n\n\ndef detect_profile(path: Path) -> str:\n content = path.read_text(encoding=\"utf-8\")\n if BLACKSMITH_X64 in content and BLACKSMITH_ARM in content:\n return \"blacksmith\"\n if HOST_SIMD in content and \"if: ${{ false }}\" not in content:\n return \"host\"\n if GITHUB_X64 in content and \"blacksmith-\" not in content:\n return \"github\"\n if GITHUB_X64 in content and GITHUB_ARM in content:\n return \"github\"\n return \"mixed\"\n\n\ndef status() -> int:\n all_ok = True\n for wf in WORKFLOWS:\n profile = detect_profile(wf)\n print(f\"{wf.relative_to(ROOT)}: {profile}\")\n if profile == \"mixed\":\n all_ok = False\n if not all_ok:\n print(\"Detected mixed workflow state; run enable or disable to normalize.\")\n return 1\n return 0\n\n\ndef run_cmd(args: list[str]) -> None:\n subprocess.run(args, cwd=ROOT, check=True)\n\n\ndef has_staged_workflow_changes() -> bool:\n result = subprocess.run(\n [\"git\", \"diff\", \"--cached\", \"--quiet\", \"--\", *WORKFLOW_REL_PATHS],\n cwd=ROOT,\n check=False,\n )\n return result.returncode != 0\n\n\ndef maybe_commit_and_push(mode: str, commit: bool, push: bool) -> int:\n if push and not commit:\n print(\"--push requires --commit\", file=sys.stderr)\n return 2\n\n if not commit:\n return 0\n\n run_cmd([\"git\", \"add\", *WORKFLOW_REL_PATHS])\n if not has_staged_workflow_changes():\n print(\"No workflow changes to commit.\")\n return 0\n\n run_cmd([\"git\", \"commit\", \"-m\", f\"ci: switch workflows to {mode} runners\"])\n print(\"Committed workflow changes.\")\n\n if push:\n run_cmd([\"git\", \"push\", \"origin\", \"HEAD\"])\n print(\"Pushed commit.\")\n\n return 0\n\n\ndef set_mode(mode: str, commit: bool, push: bool) -> int:\n if push and not commit:\n print(\"--push requires --commit\", file=sys.stderr)\n return 2\n\n changed_any = False\n for wf in WORKFLOWS:\n changed = rewrite_workflow(wf, mode=mode)\n changed_any = changed_any or changed\n state = \"updated\" if changed else \"unchanged\"\n print(f\"{wf.relative_to(ROOT)}: {state}\")\n\n if changed_any:\n print(f\"CI runner mode set to: {mode}\")\n else:\n print(f\"CI runner mode already set to: {mode}\")\n return maybe_commit_and_push(mode=mode, commit=commit, push=push)\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(description=\"Manage CI runner profile.\")\n parser.add_argument(\n \"command\",\n choices=[\"status\", \"enable\", \"disable\", \"host\"],\n help=\"status | enable (Blacksmith) | host (self-hosted SIMD lane) | disable (GitHub-hosted)\",\n )\n parser.add_argument(\n \"--commit\",\n action=\"store_true\",\n help=\"Commit workflow changes after rewriting files\",\n )\n parser.add_argument(\n \"--push\",\n action=\"store_true\",\n help=\"Push the commit (requires --commit)\",\n )\n args = parser.parse_args()\n\n if args.command == \"status\":\n return status()\n if args.command == \"enable\":\n return set_mode(mode=\"blacksmith\", commit=args.commit, push=args.push)\n if args.command == \"host\":\n return set_mode(mode=\"host\", commit=args.commit, push=args.push)\n if args.command == \"disable\":\n return set_mode(mode=\"github\", commit=args.commit, push=args.push)\n return 2\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/ci_host_runner.py", "content": "#!/usr/bin/env python3\n\"\"\"\nProvision and manage a self-hosted GitHub Actions runner on the configured infra Linux host.\n\nThis script intentionally uses:\n - `infra host show` for host resolution (no ad-hoc env vars)\n - `gh api` for runner registration/remove tokens\n\nUsage:\n python3 scripts/ci_host_runner.py status\n python3 scripts/ci_host_runner.py install --repo nikivdev/flow\n python3 scripts/ci_host_runner.py remove --repo nikivdev/flow\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport re\nimport shlex\nimport subprocess\nimport sys\nimport time\nfrom dataclasses import dataclass\n\nDEFAULT_REPO = \"nikivdev/flow\"\nDEFAULT_LABELS = \"ci-1focus,linux,x64\"\nDEFAULT_RUNNER_DIR = \"/opt/actions-runner\"\n\n\n@dataclass\nclass HostTriplet:\n user: str\n host: str\n port: str\n\n\ndef run_capture(args: list[str], cwd: str | None = None) -> str:\n result = subprocess.run(\n args,\n cwd=cwd,\n check=True,\n text=True,\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n )\n return result.stdout.strip()\n\n\ndef run_stream(args: list[str], *, input_text: str | None = None) -> None:\n subprocess.run(args, check=True, text=True, input=input_text)\n\n\ndef load_host_triplet() -> HostTriplet:\n shown = run_capture([\"infra\", \"host\", \"show\"])\n match = re.search(r\"Linux\\s+host:\\s*([^@\\s]+)@([^:\\s]+):(\\d+)\", shown)\n if not match:\n raise SystemExit(\n \"Unable to parse infra host config. Run: infra host set <user@ip>\"\n )\n return HostTriplet(user=match.group(1), host=match.group(2), port=match.group(3))\n\n\ndef gh_api(path: str, *, method: str = \"GET\", jq: str | None = None) -> str:\n cmd = [\"gh\", \"api\"]\n if method != \"GET\":\n cmd += [\"-X\", method]\n cmd += [path]\n if jq:\n cmd += [\"--jq\", jq]\n return run_capture(cmd)\n\n\ndef gh_api_json(path: str, *, method: str = \"GET\") -> dict:\n out = gh_api(path, method=method)\n return json.loads(out) if out else {}\n\n\ndef ssh_script(host: HostTriplet, script: str) -> None:\n ssh_target = f\"{host.user}@{host.host}\"\n cmd = [\n \"ssh\",\n \"-p\",\n host.port,\n \"-o\",\n \"BatchMode=yes\",\n \"-o\",\n \"StrictHostKeyChecking=accept-new\",\n ssh_target,\n \"bash\",\n \"-s\",\n ]\n run_stream(cmd, input_text=script)\n\n\ndef ssh_capture(host: HostTriplet, script: str) -> str:\n ssh_target = f\"{host.user}@{host.host}\"\n cmd = [\n \"ssh\",\n \"-p\",\n host.port,\n \"-o\",\n \"BatchMode=yes\",\n \"-o\",\n \"StrictHostKeyChecking=accept-new\",\n ssh_target,\n \"bash\",\n \"-s\",\n ]\n result = subprocess.run(\n cmd,\n check=True,\n text=True,\n input=script,\n stdout=subprocess.PIPE,\n stderr=subprocess.PIPE,\n )\n return result.stdout.strip()\n\n\ndef shell_assign(name: str, value: str) -> str:\n return f\"{name}={shlex.quote(value)}\"\n\n\ndef default_runner_name(host: HostTriplet) -> str:\n safe_host = re.sub(r\"[^a-zA-Z0-9-]\", \"-\", host.host)\n return f\"ci-1focus-{safe_host}\"\n\n\ndef github_runner_state(repo: str, runner_name: str) -> tuple[str, bool | None]:\n payload = gh_api_json(f\"repos/{repo}/actions/runners\")\n for runner in payload.get(\"runners\", []):\n if runner.get(\"name\") == runner_name:\n return str(runner.get(\"status\", \"unknown\")), bool(runner.get(\"busy\", False))\n return \"missing\", None\n\n\ndef host_service_state(host: HostTriplet) -> str:\n script = r'''\nset -euo pipefail\nstate=\"$(systemctl is-active 'actions.runner.*' 2>/dev/null || true)\"\nif echo \"$state\" | grep -q '^active$'; then\n echo \"active\"\nelif echo \"$state\" | grep -Eq '^(inactive|failed|activating|deactivating)$'; then\n echo \"${state%%$'\\n'*}\"\nelif systemctl list-unit-files 'actions.runner.*' 2>/dev/null | grep -q 'actions.runner.'; then\n echo \"inactive\"\nelse\n echo \"missing\"\nfi\n'''\n return ssh_capture(host, script).strip()\n\n\ndef cmd_status(args: argparse.Namespace) -> int:\n host = load_host_triplet()\n print(f\"Host: {host.user}@{host.host}:{host.port}\")\n\n remote_status = r'''\nset -euo pipefail\nstatus_out=\"$(systemctl --no-pager --full status 'actions.runner.*' 2>/dev/null || true)\"\nif [[ -n \"${status_out}\" ]]; then\n printf '%s\\n' \"${status_out}\" | sed -n '1,60p'\nelse\n echo \"No GitHub Actions runner service is installed on this host.\"\nfi\n'''\n ssh_script(host, remote_status)\n\n repo = args.repo\n print(f\"\\nGitHub runners for {repo} (label: ci-1focus):\")\n out = gh_api(\n f\"repos/{repo}/actions/runners\",\n jq='[.runners[] | select(any(.labels[]; .name == \"ci-1focus\")) | \"\\\\(.name)\\\\t\\\\(.status)\\\\tbusy=\\\\(.busy)\"] | .[]?',\n )\n if out:\n print(out)\n else:\n print(\"No runners with label ci-1focus found.\")\n return 0\n\n\ndef cmd_health(args: argparse.Namespace) -> int:\n host = load_host_triplet()\n runner_name = args.runner_name or default_runner_name(host)\n service = host_service_state(host)\n gh_status, busy = github_runner_state(args.repo, runner_name)\n busy_str = \"n/a\" if busy is None else (\"true\" if busy else \"false\")\n print(\n f\"runner={runner_name} host_service={service} github_status={gh_status} busy={busy_str}\"\n )\n return 0 if service == \"active\" and gh_status == \"online\" else 1\n\n\ndef cmd_wait_online(args: argparse.Namespace) -> int:\n host = load_host_triplet()\n runner_name = args.runner_name or default_runner_name(host)\n deadline = time.time() + max(1, args.timeout_secs)\n interval = max(1, args.interval_secs)\n\n while time.time() <= deadline:\n service = host_service_state(host)\n gh_status, busy = github_runner_state(args.repo, runner_name)\n busy_str = \"n/a\" if busy is None else (\"true\" if busy else \"false\")\n print(\n f\"waiting: runner={runner_name} host_service={service} github_status={gh_status} busy={busy_str}\"\n )\n if service == \"active\" and gh_status == \"online\":\n return 0\n time.sleep(interval)\n\n print(\n f\"Timed out waiting for runner to become online: {runner_name}\",\n file=sys.stderr,\n )\n return 1\n\n\ndef cmd_install(args: argparse.Namespace) -> int:\n host = load_host_triplet()\n repo = args.repo\n labels = args.labels\n runner_name = args.runner_name or default_runner_name(host)\n\n version = args.version\n if not version:\n latest = gh_api(\"repos/actions/runner/releases/latest\", jq=\".tag_name\")\n version = latest.lstrip(\"v\")\n\n registration_token = gh_api(\n f\"repos/{repo}/actions/runners/registration-token\",\n method=\"POST\",\n jq=\".token\",\n )\n remove_token = gh_api(\n f\"repos/{repo}/actions/runners/remove-token\",\n method=\"POST\",\n jq=\".token\",\n )\n\n setup_script = f'''\nset -euo pipefail\n{shell_assign(\"RUNNER_DIR\", DEFAULT_RUNNER_DIR)}\n{shell_assign(\"REPO\", repo)}\n{shell_assign(\"VERSION\", version)}\n{shell_assign(\"RUNNER_NAME\", runner_name)}\n{shell_assign(\"LABELS\", labels)}\n{shell_assign(\"REGISTRATION_TOKEN\", registration_token)}\n{shell_assign(\"REMOVE_TOKEN\", remove_token)}\n\nif [ \"$(id -u)\" -eq 0 ]; then\n SUDO=\"\"\n RUNNER_USER_CMD=\"runuser -u gha-runner --\"\nelse\n if ! command -v sudo >/dev/null 2>&1; then\n echo \"sudo is required for non-root execution on the host\" >&2\n exit 1\n fi\n SUDO=\"sudo\"\n RUNNER_USER_CMD=\"sudo -u gha-runner\"\nfi\n\nif command -v apt-get >/dev/null 2>&1; then\n $SUDO apt-get update -y\n $SUDO apt-get install -y curl ca-certificates tar\nfi\n\nif ! id -u gha-runner >/dev/null 2>&1; then\n $SUDO useradd --create-home --home-dir /home/gha-runner --shell /bin/bash gha-runner\nfi\n\n$SUDO mkdir -p \"$RUNNER_DIR\"\n$SUDO chown -R gha-runner:gha-runner \"$RUNNER_DIR\"\ncd \"$RUNNER_DIR\"\n\nCURRENT_VERSION=\"\"\nif [ -f .runner_version ]; then\n CURRENT_VERSION=\"$(cat .runner_version || true)\"\nfi\n\nif [ ! -x ./config.sh ] || [ \"$CURRENT_VERSION\" != \"$VERSION\" ]; then\n rm -rf \"$RUNNER_DIR\"/*\n curl -fsSL -o actions-runner.tar.gz \"https://github.com/actions/runner/releases/download/v${{VERSION}}/actions-runner-linux-x64-${{VERSION}}.tar.gz\"\n tar xzf actions-runner.tar.gz\n rm -f actions-runner.tar.gz\n echo \"$VERSION\" > .runner_version\n $SUDO chown -R gha-runner:gha-runner \"$RUNNER_DIR\"\nfi\n\n# Ensure re-install is idempotent: service must be removed before reconfiguration.\nif [ -x ./svc.sh ]; then\n ./svc.sh stop || true\n ./svc.sh uninstall || true\nfi\n\nif [ -f .runner ]; then\n $RUNNER_USER_CMD env RUNNER_DIR=\"$RUNNER_DIR\" REMOVE_TOKEN=\"$REMOVE_TOKEN\" \\\n bash -lc 'cd \"$RUNNER_DIR\" && ./config.sh remove --token \"$REMOVE_TOKEN\" || true'\nfi\n\n$RUNNER_USER_CMD env RUNNER_DIR=\"$RUNNER_DIR\" REPO=\"$REPO\" REGISTRATION_TOKEN=\"$REGISTRATION_TOKEN\" RUNNER_NAME=\"$RUNNER_NAME\" LABELS=\"$LABELS\" \\\n bash -lc 'cd \"$RUNNER_DIR\" && ./config.sh --url \"https://github.com/$REPO\" --token \"$REGISTRATION_TOKEN\" --name \"$RUNNER_NAME\" --labels \"$LABELS\" --work _work --unattended --replace'\n\ncd \"$RUNNER_DIR\"\nif [ -x ./svc.sh ]; then\n ./svc.sh install gha-runner || true\n ./svc.sh start\nfi\n\nsystemctl --no-pager --full status 'actions.runner.*' | sed -n '1,60p' || true\n'''\n\n print(f\"Installing runner on {host.user}@{host.host}:{host.port}\")\n print(f\"Repo: {repo}\")\n print(f\"Runner name: {runner_name}\")\n print(f\"Labels: {labels}\")\n print(f\"Runner version: {version}\")\n ssh_script(host, setup_script)\n return 0\n\n\ndef cmd_remove(args: argparse.Namespace) -> int:\n host = load_host_triplet()\n repo = args.repo\n remove_token = gh_api(\n f\"repos/{repo}/actions/runners/remove-token\",\n method=\"POST\",\n jq=\".token\",\n )\n purge = \"1\" if args.purge else \"0\"\n\n remove_script = f'''\nset -euo pipefail\n{shell_assign(\"RUNNER_DIR\", DEFAULT_RUNNER_DIR)}\n{shell_assign(\"REMOVE_TOKEN\", remove_token)}\n{shell_assign(\"PURGE\", purge)}\n\nif [ \"$(id -u)\" -eq 0 ]; then\n SUDO=\"\"\n RUNNER_USER_CMD=\"runuser -u gha-runner --\"\nelse\n if ! command -v sudo >/dev/null 2>&1; then\n echo \"sudo is required for non-root execution on the host\" >&2\n exit 1\n fi\n SUDO=\"sudo\"\n RUNNER_USER_CMD=\"sudo -u gha-runner\"\nfi\n\nif [ ! -d \"$RUNNER_DIR\" ]; then\n echo \"Runner directory not found: $RUNNER_DIR\"\n exit 0\nfi\n\ncd \"$RUNNER_DIR\"\nif [ -x ./svc.sh ]; then\n ./svc.sh stop || true\nfi\n\nif [ -f .runner ] && [ -x ./config.sh ]; then\n $RUNNER_USER_CMD env RUNNER_DIR=\"$RUNNER_DIR\" REMOVE_TOKEN=\"$REMOVE_TOKEN\" \\\n bash -lc 'cd \"$RUNNER_DIR\" && ./config.sh remove --token \"$REMOVE_TOKEN\" || true'\nfi\n\nif [ -x ./svc.sh ]; then\n ./svc.sh uninstall || true\nfi\n\nif [ \"$PURGE\" = \"1\" ]; then\n cd /\n $SUDO rm -rf \"$RUNNER_DIR\"\n $SUDO userdel -r gha-runner || true\n echo \"Runner files and gha-runner user removed.\"\nelse\n echo \"Runner unregistered and service removed (files kept).\"\nfi\n'''\n\n print(f\"Removing runner from {host.user}@{host.host}:{host.port}\")\n ssh_script(host, remove_script)\n return 0\n\n\ndef build_parser() -> argparse.ArgumentParser:\n parser = argparse.ArgumentParser(description=\"Manage ci.1focus.ai host GitHub runner\")\n sub = parser.add_subparsers(dest=\"command\", required=True)\n\n status = sub.add_parser(\"status\", help=\"Show remote service status + GitHub runner status\")\n status.add_argument(\"--repo\", default=DEFAULT_REPO, help=\"GitHub repo in owner/name format\")\n status.set_defaults(handler=cmd_status)\n\n install = sub.add_parser(\"install\", help=\"Install/register runner on configured infra Linux host\")\n install.add_argument(\"--repo\", default=DEFAULT_REPO, help=\"GitHub repo in owner/name format\")\n install.add_argument(\"--runner-name\", default=\"\", help=\"Runner name override\")\n install.add_argument(\"--labels\", default=DEFAULT_LABELS, help=\"Comma-separated runner labels\")\n install.add_argument(\"--version\", default=\"\", help=\"actions/runner version (default: latest)\")\n install.set_defaults(handler=cmd_install)\n\n remove = sub.add_parser(\"remove\", help=\"Unregister runner and remove service\")\n remove.add_argument(\"--repo\", default=DEFAULT_REPO, help=\"GitHub repo in owner/name format\")\n remove.add_argument(\"--purge\", action=\"store_true\", help=\"Also delete runner files and gha-runner user\")\n remove.set_defaults(handler=cmd_remove)\n\n health = sub.add_parser(\"health\", help=\"Machine-friendly runner health check\")\n health.add_argument(\"--repo\", default=DEFAULT_REPO, help=\"GitHub repo in owner/name format\")\n health.add_argument(\"--runner-name\", default=\"\", help=\"Runner name override\")\n health.set_defaults(handler=cmd_health)\n\n wait_online = sub.add_parser(\"wait-online\", help=\"Wait until runner is active and GitHub reports online\")\n wait_online.add_argument(\"--repo\", default=DEFAULT_REPO, help=\"GitHub repo in owner/name format\")\n wait_online.add_argument(\"--runner-name\", default=\"\", help=\"Runner name override\")\n wait_online.add_argument(\"--timeout-secs\", type=int, default=120, help=\"Maximum wait time\")\n wait_online.add_argument(\"--interval-secs\", type=int, default=5, help=\"Polling interval\")\n wait_online.set_defaults(handler=cmd_wait_online)\n\n return parser\n\n\ndef main() -> int:\n parser = build_parser()\n args = parser.parse_args()\n try:\n return int(args.handler(args))\n except subprocess.CalledProcessError as exc:\n if exc.stderr:\n print(exc.stderr.strip(), file=sys.stderr)\n return exc.returncode or 1\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/ci_host_setup.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nREPO=\"${FLOW_CI_REPO:-nikivdev/flow}\"\nHOST_TARGET=\"${1:-}\"\nFORCE_REINSTALL=\"${FLOW_CI_FORCE_REINSTALL:-0}\"\nWAIT_SECS=\"${FLOW_CI_WAIT_SECS:-120}\"\n\nif [[ \"${HOST_TARGET}\" == \"-h\" || \"${HOST_TARGET}\" == \"--help\" ]]; then\n cat <<'EOF'\nUsage: f ci-host-setup [user@ip]\n\nOne-command setup for Flow CI host mode:\n 1) Optionally set infra host (if user@ip is provided)\n 2) Install/register ci-1focus self-hosted GitHub runner\n 3) Switch workflows to host runner mode (commit + push)\n 4) Print final runner status\n\nEnv toggles:\n FLOW_CI_FORCE_REINSTALL=1 Force reinstall even if runner is healthy\n FLOW_CI_WAIT_SECS=180 Wait timeout for GitHub online status (default 120)\nEOF\n exit 0\nfi\n\nif ! command -v gh >/dev/null 2>&1; then\n echo \"gh CLI is required (install GitHub CLI first).\" >&2\n exit 1\nfi\n\nif ! command -v infra >/dev/null 2>&1; then\n echo \"infra CLI is required (install infra first).\" >&2\n exit 1\nfi\n\nif ! command -v python3 >/dev/null 2>&1; then\n echo \"python3 is required.\" >&2\n exit 1\nfi\n\nif [[ -n \"${HOST_TARGET}\" ]]; then\n echo \"Configuring infra host: ${HOST_TARGET}\"\n infra host set \"${HOST_TARGET}\"\nelse\n if ! infra host show >/dev/null 2>&1; then\n echo \"No infra host configured. Run: f ci-host-setup <user@ip>\" >&2\n exit 1\n fi\nfi\n\necho \"Checking GitHub auth...\"\ngh auth status >/dev/null\n\nif python3 ./scripts/ci_host_runner.py health --repo \"${REPO}\" >/dev/null 2>&1 && [[ \"${FORCE_REINSTALL}\" != \"1\" ]]; then\n echo \"Runner already healthy; skipping reinstall. Set FLOW_CI_FORCE_REINSTALL=1 to force.\"\nelse\n echo \"Installing/registering ci-1focus runner...\"\n attempts=0\n max_attempts=2\n until python3 ./scripts/ci_host_runner.py install --repo \"${REPO}\"; do\n attempts=$((attempts + 1))\n if [[ $attempts -ge $max_attempts ]]; then\n echo \"Runner installation failed after ${max_attempts} attempts.\" >&2\n exit 1\n fi\n echo \"Retrying runner installation (${attempts}/${max_attempts})...\"\n sleep 3\n done\nfi\n\necho \"Waiting for runner to report online...\"\npython3 ./scripts/ci_host_runner.py wait-online --repo \"${REPO}\" --timeout-secs \"${WAIT_SECS}\" --interval-secs 5\n\necho \"Switching workflows to host mode (commit + push)...\"\npython3 ./scripts/ci_blacksmith.py host --commit --push\n\necho \"Final runner health:\"\npython3 ./scripts/ci_host_runner.py health --repo \"${REPO}\"\n\necho \"Final runner status:\"\npython3 ./scripts/ci_host_runner.py status --repo \"${REPO}\" || true\n" }, { "path": "scripts/cli_startup_thresholds.json", "content": "{\n \"help\": {\n \"p50_ms\": 60.0,\n \"p95_ms\": 100.0\n },\n \"help_full\": {\n \"p50_ms\": 80.0,\n \"p95_ms\": 140.0\n },\n \"info\": {\n \"p50_ms\": 80.0,\n \"p95_ms\": 150.0\n },\n \"projects\": {\n \"p50_ms\": 80.0,\n \"p95_ms\": 150.0\n },\n \"analytics_status\": {\n \"p50_ms\": 100.0,\n \"p95_ms\": 180.0\n },\n \"tasks_list\": {\n \"p50_ms\": 120.0,\n \"p95_ms\": 220.0\n },\n \"tasks_dupes\": {\n \"p50_ms\": 120.0,\n \"p95_ms\": 220.0\n },\n \"deploy_show_host\": {\n \"p50_ms\": 80.0,\n \"p95_ms\": 150.0\n }\n}\n" }, { "path": "scripts/codex-flow-wrapper", "content": "#!/usr/bin/env python3\n\nfrom __future__ import annotations\n\nimport json\nimport os\nimport signal\nimport subprocess\nimport sys\nfrom pathlib import Path\n\n\nRUNTIME_PREFIX = \"flow-runtime-\"\n\n\ndef real_codex_bin() -> str:\n value = os.environ.get(\"FLOW_CODEX_REAL_BIN\", \"\").strip()\n return value or \"codex\"\n\n\ndef agents_skill_root() -> Path:\n return Path.home() / \".agents\" / \"skills\"\n\n\ndef load_runtime_state() -> dict | None:\n raw_path = os.environ.get(\"FLOW_CODEX_RUNTIME_STATE\", \"\").strip()\n if not raw_path:\n return None\n path = Path(raw_path).expanduser()\n if not path.is_file():\n return None\n return json.loads(path.read_text(encoding=\"utf-8\"))\n\n\ndef remove_path(path: Path) -> None:\n try:\n if path.is_symlink() or path.is_file():\n path.unlink()\n elif path.is_dir():\n for child in path.iterdir():\n remove_path(child)\n path.rmdir()\n except FileNotFoundError:\n pass\n\n\ndef materialize_runtime_skills(state: dict) -> list[Path]:\n token = str(state.get(\"token\", \"\")).strip()\n skills = state.get(\"skills\", [])\n if not token or not isinstance(skills, list) or not skills:\n return []\n\n root = agents_skill_root()\n root.mkdir(parents=True, exist_ok=True)\n created: list[Path] = []\n for skill in skills:\n if not isinstance(skill, dict):\n continue\n name = str(skill.get(\"name\", \"\")).strip()\n source = str(skill.get(\"path\", \"\")).strip()\n if not name or not source:\n continue\n source_path = Path(source).expanduser()\n if not source_path.is_dir():\n continue\n target = root / name\n if target.exists() or target.is_symlink():\n remove_path(target)\n os.symlink(source_path, target, target_is_directory=True)\n created.append(target)\n return created\n\n\ndef cleanup_runtime_symlinks(paths: list[Path]) -> None:\n for path in paths:\n remove_path(path)\n\n\ndef main() -> int:\n state = load_runtime_state()\n created = materialize_runtime_skills(state) if state else []\n\n env = dict(os.environ)\n runtime_state_path = env.get(\"FLOW_CODEX_RUNTIME_STATE\", \"\").strip()\n if runtime_state_path:\n env[\"FLOW_CODEX_RUNTIME_STATE_PATH\"] = runtime_state_path\n env.pop(\"FLOW_CODEX_RUNTIME_STATE\", None)\n proc = None\n\n def forward_signal(signum: int, _frame) -> None:\n nonlocal proc\n if proc is not None:\n proc.send_signal(signum)\n\n for signum in (signal.SIGINT, signal.SIGTERM):\n signal.signal(signum, forward_signal)\n\n try:\n proc = subprocess.Popen([real_codex_bin(), *sys.argv[1:]], env=env)\n return proc.wait()\n finally:\n cleanup_runtime_symlinks(created)\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/codex-jazz-wrapper", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\n# Shared Codex wrapper for Flow-managed repos.\n# Keep stdio untouched so `app-server` JSON-RPC works exactly like raw codex.\n#\n# Optional env:\n# - CODEX_REAL_BIN: absolute path to the real codex binary.\n# - CODEX_JAZZ_HOOK: executable hook invoked asynchronously as:\n# <hook> <real-codex-bin> <original-args...>\n# Hook output is suppressed and never affects review flow.\n\nSELF_PATH=\"$(cd \"$(dirname \"$0\")\" && pwd)/$(basename \"$0\")\"\n\nresolve_real_codex() {\n if [ -n \"${CODEX_REAL_BIN:-}\" ]; then\n printf '%s\\n' \"$CODEX_REAL_BIN\"\n return 0\n fi\n\n while IFS= read -r candidate; do\n [ -z \"$candidate\" ] && continue\n if [ \"$candidate\" != \"$SELF_PATH\" ]; then\n printf '%s\\n' \"$candidate\"\n return 0\n fi\n done < <(which -a codex 2>/dev/null || true)\n\n return 1\n}\n\nif ! REAL_CODEX_BIN=\"$(resolve_real_codex)\"; then\n echo \"codex-jazz-wrapper: could not resolve real codex binary; set CODEX_REAL_BIN\" >&2\n exit 127\nfi\n\nif [ -n \"${CODEX_JAZZ_HOOK:-}\" ] && [ -x \"${CODEX_JAZZ_HOOK}\" ]; then\n \"${CODEX_JAZZ_HOOK}\" \"${REAL_CODEX_BIN}\" \"$@\" >/dev/null 2>&1 || true &\nfi\n\nexec \"${REAL_CODEX_BIN}\" \"$@\"\n" }, { "path": "scripts/codex-skill-eval-launchd.py", "content": "#!/usr/bin/env python3\nimport argparse\nimport os\nimport plistlib\nimport shutil\nimport subprocess\nimport sys\nfrom pathlib import Path\n\n\nLABEL = \"dev.nikiv.flow-codex-skill-eval\"\n\n\ndef run(cmd: list[str]) -> subprocess.CompletedProcess:\n return subprocess.run(cmd, text=True, capture_output=True, check=False)\n\n\ndef resolve_f_bin(repo_root: Path) -> str:\n env_override = os.environ.get(\"FLOW_CODEX_SKILL_EVAL_F_BIN\", \"\").strip()\n if env_override:\n return env_override\n which_f = shutil.which(\"f\")\n if which_f:\n return which_f\n for candidate in [\n repo_root / \"target\" / \"release\" / \"f\",\n repo_root / \"target\" / \"debug\" / \"f\",\n ]:\n if candidate.exists():\n return str(candidate)\n raise SystemExit(\"Could not resolve f binary. Build flow first or set FLOW_CODEX_SKILL_EVAL_F_BIN.\")\n\n\ndef plist_path() -> Path:\n return Path.home() / \"Library\" / \"LaunchAgents\" / f\"{LABEL}.plist\"\n\n\ndef domain_target() -> str:\n return f\"gui/{os.getuid()}/{LABEL}\"\n\n\ndef log_dir() -> Path:\n path = Path.home() / \".flow\" / \"logs\"\n path.mkdir(parents=True, exist_ok=True)\n return path\n\n\ndef install(\n repo_root: Path,\n minutes: int,\n limit: int,\n max_targets: int,\n within_hours: int,\n dry_run: bool,\n) -> int:\n if minutes < 5:\n raise SystemExit(\"--minutes must be at least 5\")\n if limit < 1 or max_targets < 1 or within_hours < 1:\n raise SystemExit(\"--limit, --max-targets, and --within-hours must be positive\")\n\n f_bin = resolve_f_bin(repo_root)\n p = plist_path()\n p.parent.mkdir(parents=True, exist_ok=True)\n logs = log_dir()\n\n payload = {\n \"Label\": LABEL,\n \"ProgramArguments\": [\n f_bin,\n \"codex\",\n \"skill-eval\",\n \"cron\",\n \"--limit\",\n str(limit),\n \"--max-targets\",\n str(max_targets),\n \"--within-hours\",\n str(within_hours),\n ],\n \"RunAtLoad\": True,\n \"StartInterval\": minutes * 60,\n \"ProcessType\": \"Background\",\n \"StandardOutPath\": str(logs / \"codex-skill-eval.launchd.stdout.log\"),\n \"StandardErrorPath\": str(logs / \"codex-skill-eval.launchd.stderr.log\"),\n \"EnvironmentVariables\": {\n \"PATH\": \"/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin\",\n },\n }\n if dry_run:\n print(f\"plist: {p}\")\n print(f\"f_bin: {f_bin}\")\n print(f\"every: {minutes} minutes\")\n print(f\"limit: {limit}\")\n print(f\"max_targets: {max_targets}\")\n print(f\"within_hours: {within_hours}\")\n print(plistlib.dumps(payload).decode(\"utf-8\"), end=\"\")\n return 0\n with p.open(\"wb\") as f:\n plistlib.dump(payload, f)\n\n run([\"launchctl\", \"bootout\", f\"gui/{os.getuid()}\", str(p)])\n b = run([\"launchctl\", \"bootstrap\", f\"gui/{os.getuid()}\", str(p)])\n if b.returncode != 0:\n print(b.stderr.strip(), file=sys.stderr)\n return b.returncode\n run([\"launchctl\", \"kickstart\", \"-k\", domain_target()])\n print(f\"loaded: {domain_target()}\")\n print(f\"plist: {p}\")\n print(f\"f_bin: {f_bin}\")\n print(f\"every: {minutes} minutes\")\n print(f\"limit: {limit}\")\n print(f\"max_targets: {max_targets}\")\n print(f\"within_hours: {within_hours}\")\n return 0\n\n\ndef uninstall() -> int:\n p = plist_path()\n run([\"launchctl\", \"bootout\", f\"gui/{os.getuid()}\", str(p)])\n if p.exists():\n p.unlink()\n print(f\"unloaded: {domain_target()}\")\n print(f\"removed: {p}\")\n return 0\n\n\ndef status() -> int:\n out = run([\"launchctl\", \"print\", domain_target()])\n if out.returncode != 0:\n print(f\"{domain_target()}: not loaded\")\n if out.stderr.strip():\n print(out.stderr.strip())\n return 0\n print(out.stdout, end=\"\")\n return 0\n\n\ndef logs(lines: int) -> int:\n stdout = log_dir() / \"codex-skill-eval.launchd.stdout.log\"\n stderr = log_dir() / \"codex-skill-eval.launchd.stderr.log\"\n for path in [stdout, stderr]:\n print(f\"==> {path}\")\n if not path.exists():\n print(\"(missing)\")\n continue\n text = path.read_text(encoding=\"utf-8\", errors=\"replace\").splitlines()\n for line in text[-lines:]:\n print(line)\n return 0\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(\n description=\"Manage launchd schedule for Flow Codex skill-eval cron.\"\n )\n sub = parser.add_subparsers(dest=\"cmd\", required=True)\n\n p_install = sub.add_parser(\"install\")\n p_install.add_argument(\"--minutes\", type=int, default=30)\n p_install.add_argument(\"--limit\", type=int, default=400)\n p_install.add_argument(\"--max-targets\", type=int, default=12)\n p_install.add_argument(\"--within-hours\", type=int, default=168)\n p_install.add_argument(\"--dry-run\", action=\"store_true\")\n\n sub.add_parser(\"uninstall\")\n sub.add_parser(\"status\")\n\n p_logs = sub.add_parser(\"logs\")\n p_logs.add_argument(\"--lines\", type=int, default=120)\n\n args = parser.parse_args()\n repo_root = Path(__file__).resolve().parents[1]\n if args.cmd == \"install\":\n return install(\n repo_root,\n args.minutes,\n args.limit,\n args.max_targets,\n args.within_hours,\n args.dry_run,\n )\n if args.cmd == \"uninstall\":\n return uninstall()\n if args.cmd == \"status\":\n return status()\n if args.cmd == \"logs\":\n return logs(args.lines)\n return 1\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/codex_fork.py", "content": "#!/usr/bin/env python3\n\nfrom __future__ import annotations\n\nimport argparse\nimport os\nimport re\nimport shlex\nimport subprocess\nimport sys\nfrom pathlib import Path\n\n\ndef env_path(name: str, default: Path) -> Path:\n value = os.environ.get(name)\n if not value:\n return default\n return Path(value).expanduser()\n\n\nHOME = Path.home()\nUPSTREAM_CHECKOUT = env_path(\n \"FLOW_CODEX_UPSTREAM_CHECKOUT\",\n HOME / \"repos\" / \"openai\" / \"codex\",\n)\nFORK_HOME = env_path(\n \"FLOW_CODEX_FORK_HOME\",\n HOME / \"repos\" / \"nikivdev\" / \"codex\",\n)\nWORKTREE_ROOT = env_path(\n \"FLOW_CODEX_WORKTREE_ROOT\",\n HOME / \".worktrees\" / \"codex\",\n)\nWORKFLOW_DOC = env_path(\n \"FLOW_CODEX_WORKFLOW_DOC\",\n HOME / \"docs\" / \"codex\" / \"codex-fork-home-branch-workflow.md\",\n)\nSTATE_DIR = env_path(\n \"FLOW_CODEX_FORK_STATE_DIR\",\n HOME / \".flow\" / \"codex-fork\",\n)\nLAST_WORKTREE_FILE = STATE_DIR / \"last-worktree.txt\"\nDEFAULT_BASE_BRANCH = os.environ.get(\"FLOW_CODEX_FORK_BASE_BRANCH\", \"nikiv\")\nDEFAULT_BRANCH_PREFIX = os.environ.get(\"FLOW_CODEX_FORK_BRANCH_PREFIX\", \"codex\")\nDEFAULT_REVIEW_PREFIX = os.environ.get(\"FLOW_CODEX_FORK_REVIEW_PREFIX\", \"review/nikiv\")\nDEFAULT_PRIVATE_REMOTE = os.environ.get(\"FLOW_CODEX_FORK_PRIVATE_REMOTE\", \"private\")\nDEFAULT_UPSTREAM_REMOTE = os.environ.get(\"FLOW_CODEX_FORK_UPSTREAM_REMOTE\", \"upstream\")\nDEFAULT_UPSTREAM_BRANCH = os.environ.get(\"FLOW_CODEX_FORK_UPSTREAM_BRANCH\", \"main\")\n\n\ndef fail(message: str, code: int = 1) -> int:\n print(f\"Error: {message}\", file=sys.stderr)\n return code\n\n\ndef run(\n cmd: list[str],\n *,\n cwd: Path | None = None,\n capture: bool = False,\n check: bool = True,\n) -> subprocess.CompletedProcess[str]:\n result = subprocess.run(\n cmd,\n cwd=str(cwd) if cwd is not None else None,\n text=True,\n capture_output=capture,\n check=False,\n )\n if check and result.returncode != 0:\n if capture and result.stderr:\n print(result.stderr.rstrip(), file=sys.stderr)\n raise SystemExit(result.returncode)\n return result\n\n\ndef capture(cmd: list[str], *, cwd: Path | None = None, check: bool = True) -> str:\n result = run(cmd, cwd=cwd, capture=True, check=check)\n return result.stdout.strip()\n\n\ndef ensure_repo(path: Path, label: str) -> None:\n if not path.exists():\n raise SystemExit(fail(f\"{label} does not exist: {path}\"))\n probe = run(\n [\"git\", \"rev-parse\", \"--is-inside-work-tree\"],\n cwd=path,\n capture=True,\n check=False,\n )\n if probe.returncode != 0 or probe.stdout.strip() != \"true\":\n raise SystemExit(fail(f\"{label} is not a git checkout: {path}\"))\n\n\ndef ensure_state_dir() -> None:\n STATE_DIR.mkdir(parents=True, exist_ok=True)\n\n\ndef read_last_worktree() -> Path | None:\n if not LAST_WORKTREE_FILE.exists():\n return None\n value = LAST_WORKTREE_FILE.read_text().strip()\n if not value:\n return None\n return Path(value).expanduser()\n\n\ndef write_last_worktree(path: Path) -> None:\n ensure_state_dir()\n LAST_WORKTREE_FILE.write_text(f\"{path}\\n\")\n\n\ndef slugify(text: str) -> str:\n slug = re.sub(r\"[^a-z0-9]+\", \"-\", text.lower()).strip(\"-\")\n slug = re.sub(r\"-{2,}\", \"-\", slug)\n if not slug:\n raise SystemExit(fail(f\"could not derive a branch slug from query: {text!r}\"))\n return slug\n\n\ndef branch_to_worktree_name(branch: str) -> str:\n return branch.replace(\"/\", \"-\")\n\n\ndef git_ref_exists(repo: Path, ref: str) -> bool:\n result = run(\n [\"git\", \"show-ref\", \"--verify\", \"--quiet\", ref],\n cwd=repo,\n check=False,\n )\n return result.returncode == 0\n\n\ndef git_branch_exists(repo: Path, branch: str) -> bool:\n return git_ref_exists(repo, f\"refs/heads/{branch}\")\n\n\ndef git_current_branch(repo: Path) -> str:\n branch = capture([\"git\", \"branch\", \"--show-current\"], cwd=repo)\n if not branch:\n raise SystemExit(fail(f\"could not resolve current branch in {repo}\"))\n return branch\n\n\ndef git_rev(repo: Path, ref: str) -> str | None:\n result = run([\"git\", \"rev-parse\", \"--verify\", ref], cwd=repo, capture=True, check=False)\n if result.returncode != 0:\n return None\n return result.stdout.strip()\n\n\ndef worktree_entries(repo: Path) -> list[dict[str, str]]:\n output = capture([\"git\", \"worktree\", \"list\", \"--porcelain\"], cwd=repo)\n entries: list[dict[str, str]] = []\n current: dict[str, str] = {}\n for line in output.splitlines():\n if not line:\n if current:\n entries.append(current)\n current = {}\n continue\n key, _, value = line.partition(\" \")\n if key == \"worktree\":\n current[\"path\"] = value\n elif key == \"branch\":\n current[\"branch\"] = value.removeprefix(\"refs/heads/\")\n elif key == \"HEAD\":\n current[\"head\"] = value\n elif key == \"detached\":\n current[\"detached\"] = \"true\"\n if current:\n entries.append(current)\n return entries\n\n\ndef worktree_for_branch(repo: Path, branch: str) -> Path | None:\n for entry in worktree_entries(repo):\n if entry.get(\"branch\") == branch:\n return Path(entry[\"path\"])\n return None\n\n\ndef branch_from_target(target: str) -> str:\n if target.startswith(\"codex/\") or target.startswith(\"review/\"):\n return target\n return f\"{DEFAULT_BRANCH_PREFIX}/{slugify(target)}\"\n\n\ndef default_worktree_path(branch: str) -> Path:\n return WORKTREE_ROOT / branch_to_worktree_name(branch)\n\n\ndef ensure_task_worktree(branch: str, path: Path, base: str) -> tuple[Path, bool]:\n existing = worktree_for_branch(FORK_HOME, branch)\n if existing is not None:\n return existing, True\n\n if path.exists() and not (path / \".git\").exists():\n if any(path.iterdir()):\n raise SystemExit(\n fail(f\"requested worktree path already exists and is not empty: {path}\")\n )\n\n path.parent.mkdir(parents=True, exist_ok=True)\n if git_branch_exists(FORK_HOME, branch):\n run([\"git\", \"worktree\", \"add\", str(path), branch], cwd=FORK_HOME)\n else:\n run([\"git\", \"worktree\", \"add\", \"-b\", branch, str(path), base], cwd=FORK_HOME)\n return path, False\n\n\ndef build_prompt(query: str, branch: str, worktree: Path, base: str) -> str:\n return \"\\n\".join(\n [\n f\"Read {WORKFLOW_DOC} and make plan first.\",\n \"\",\n f\"Task: {query}\",\n f\"Branch: {branch}\",\n f\"Worktree: {worktree}\",\n f\"Base branch: {base}\",\n f\"Fork home checkout: {FORK_HOME}\",\n f\"Upstream reference checkout: {UPSTREAM_CHECKOUT}\",\n \"Keep the work scoped to this branch/worktree and do not touch unrelated fork worktrees.\",\n ]\n )\n\n\ndef launch_codex_new(worktree: Path, prompt: str) -> int:\n cmd = [\n \"codex\",\n \"--cd\",\n str(worktree),\n \"--yolo\",\n \"--sandbox\",\n \"danger-full-access\",\n prompt,\n ]\n return subprocess.run(cmd, check=False).returncode\n\n\ndef launch_codex_resume_last(worktree: Path, prompt: str | None = None) -> int:\n cmd = [\n \"codex\",\n \"--cd\",\n str(worktree),\n \"resume\",\n \"--last\",\n \"--dangerously-bypass-approvals-and-sandbox\",\n ]\n if prompt:\n cmd.append(prompt)\n return subprocess.run(cmd, check=False).returncode\n\n\ndef print_next_commands(worktree: Path, branch: str, prompt: str) -> None:\n print(f\"branch: {branch}\")\n print(f\"worktree: {worktree}\")\n print()\n print(\"next:\")\n print(f\" cd {shlex.quote(str(worktree))}\")\n print(\n \" \"\n + shlex.join(\n [\n \"codex\",\n \"--cd\",\n str(worktree),\n \"--yolo\",\n \"--sandbox\",\n \"danger-full-access\",\n prompt,\n ]\n )\n )\n\n\ndef cmd_status(_args: argparse.Namespace) -> int:\n ensure_repo(FORK_HOME, \"codex fork home checkout\")\n print(\"# Codex fork workflow\")\n print(f\"upstream checkout: {UPSTREAM_CHECKOUT}\")\n print(f\"fork home: {FORK_HOME}\")\n print(f\"worktree root: {WORKTREE_ROOT}\")\n print(f\"workflow doc: {WORKFLOW_DOC}\")\n print()\n\n nikiv_sha = git_rev(FORK_HOME, DEFAULT_BASE_BRANCH)\n upstream_sha = git_rev(FORK_HOME, f\"{DEFAULT_UPSTREAM_REMOTE}/{DEFAULT_UPSTREAM_BRANCH}\")\n private_sha = git_rev(FORK_HOME, f\"{DEFAULT_PRIVATE_REMOTE}/{DEFAULT_BASE_BRANCH}\")\n\n print(\"# Branch heads\")\n print(f\"{DEFAULT_BASE_BRANCH}: {nikiv_sha or 'missing'}\")\n print(f\"{DEFAULT_UPSTREAM_REMOTE}/{DEFAULT_UPSTREAM_BRANCH}: {upstream_sha or 'missing'}\")\n print(f\"{DEFAULT_PRIVATE_REMOTE}/{DEFAULT_BASE_BRANCH}: {private_sha or 'missing'}\")\n print()\n\n print(\"# Remotes\")\n print(capture([\"git\", \"remote\", \"-v\"], cwd=FORK_HOME))\n print()\n\n print(\"# Worktrees\")\n for entry in worktree_entries(FORK_HOME):\n branch = entry.get(\"branch\", \"(detached)\")\n print(f\"{branch:32} {entry['path']}\")\n print()\n\n last = read_last_worktree()\n print(\"# Last worktree\")\n if last is None:\n print(\"none recorded\")\n return 0\n\n print(last)\n if last.exists():\n print()\n print(\"# Last worktree status\")\n status = capture([\"git\", \"status\", \"-sb\"], cwd=last, check=False)\n if status:\n print(status)\n return 0\n\n\ndef cmd_sync(args: argparse.Namespace) -> int:\n ensure_repo(FORK_HOME, \"codex fork home checkout\")\n status = capture([\"git\", \"status\", \"--porcelain\"], cwd=FORK_HOME)\n if status:\n return fail(\n f\"{FORK_HOME} is dirty; clean or stash it before syncing {DEFAULT_BASE_BRANCH}\"\n )\n\n run(\n [\"git\", \"fetch\", DEFAULT_UPSTREAM_REMOTE, DEFAULT_UPSTREAM_BRANCH],\n cwd=FORK_HOME,\n )\n if git_ref_exists(FORK_HOME, f\"refs/remotes/{DEFAULT_PRIVATE_REMOTE}/{DEFAULT_BASE_BRANCH}\"):\n run([\"git\", \"fetch\", DEFAULT_PRIVATE_REMOTE, DEFAULT_BASE_BRANCH], cwd=FORK_HOME)\n\n run([\"git\", \"switch\", DEFAULT_BASE_BRANCH], cwd=FORK_HOME)\n run(\n [\"git\", \"merge\", \"--ff-only\", f\"{DEFAULT_UPSTREAM_REMOTE}/{DEFAULT_UPSTREAM_BRANCH}\"],\n cwd=FORK_HOME,\n )\n if args.push:\n run([\"git\", \"push\", DEFAULT_PRIVATE_REMOTE, DEFAULT_BASE_BRANCH], cwd=FORK_HOME)\n\n print(f\"{DEFAULT_BASE_BRANCH} now matches {DEFAULT_UPSTREAM_REMOTE}/{DEFAULT_UPSTREAM_BRANCH}\")\n if args.push:\n print(f\"pushed {DEFAULT_BASE_BRANCH} to {DEFAULT_PRIVATE_REMOTE}\")\n return 0\n\n\ndef cmd_task(args: argparse.Namespace) -> int:\n ensure_repo(FORK_HOME, \"codex fork home checkout\")\n branch = args.branch or branch_from_target(args.query)\n worktree = Path(args.path).expanduser() if args.path else default_worktree_path(branch)\n worktree, reused = ensure_task_worktree(branch, worktree, args.base)\n write_last_worktree(worktree)\n\n prompt = build_prompt(args.query, branch, worktree, args.base)\n print(f\"branch: {branch}\")\n print(f\"worktree: {worktree}\")\n print(f\"mode: {'resume-or-new' if not args.new else 'new'}\")\n print()\n\n if args.no_launch:\n print_next_commands(worktree, branch, prompt)\n return 0\n\n if reused and not args.new:\n resume_code = launch_codex_resume_last(worktree)\n if resume_code == 0:\n return 0\n print(\"No prior Codex session found for that worktree; starting a new one.\", file=sys.stderr)\n\n return launch_codex_new(worktree, prompt)\n\n\ndef resolve_target_worktree(target: str | None) -> Path:\n if target:\n candidate = Path(target).expanduser()\n if candidate.exists():\n return candidate\n branch = branch_from_target(target)\n existing = worktree_for_branch(FORK_HOME, branch)\n if existing is not None:\n return existing\n raise SystemExit(fail(f\"could not resolve worktree for target: {target}\"))\n\n last = read_last_worktree()\n if last is None:\n raise SystemExit(\n fail(\"no last Codex fork worktree recorded yet; start one with `f codex-fork-task`\")\n )\n return last\n\n\ndef cmd_last(args: argparse.Namespace) -> int:\n ensure_repo(FORK_HOME, \"codex fork home checkout\")\n worktree = resolve_target_worktree(args.target)\n if not worktree.exists():\n return fail(f\"recorded worktree does not exist: {worktree}\")\n write_last_worktree(worktree)\n return launch_codex_resume_last(worktree)\n\n\ndef review_branch_for(source_branch: str) -> str:\n if source_branch.startswith(\"review/\"):\n return source_branch\n if source_branch.startswith(\"codex/\"):\n suffix = source_branch.removeprefix(\"codex/\").replace(\"/\", \"-\")\n return f\"{DEFAULT_REVIEW_PREFIX}-{suffix}\"\n return f\"{DEFAULT_REVIEW_PREFIX}-{source_branch.replace('/', '-')}\"\n\n\ndef cmd_promote(args: argparse.Namespace) -> int:\n ensure_repo(FORK_HOME, \"codex fork home checkout\")\n target = resolve_target_worktree(args.target)\n ensure_repo(target, \"codex fork worktree\")\n source_branch = git_current_branch(target)\n review_branch = args.review_branch or review_branch_for(source_branch)\n\n source_commit = capture([\"git\", \"rev-parse\", \"HEAD\"], cwd=target)\n run([\"git\", \"branch\", \"-f\", review_branch, source_commit], cwd=FORK_HOME)\n print(f\"source branch: {source_branch}\")\n print(f\"review branch: {review_branch}\")\n print(f\"commit: {source_commit}\")\n if args.push:\n run([\"git\", \"push\", \"-u\", DEFAULT_PRIVATE_REMOTE, review_branch], cwd=FORK_HOME)\n print(f\"pushed to {DEFAULT_PRIVATE_REMOTE}/{review_branch}\")\n return 0\n\n\ndef build_parser() -> argparse.ArgumentParser:\n parser = argparse.ArgumentParser(\n description=\"Automate the personal Codex fork home-branch/worktree workflow.\"\n )\n subparsers = parser.add_subparsers(dest=\"command\", required=True)\n\n status = subparsers.add_parser(\"status\", help=\"Show fork checkout/worktree state.\")\n status.set_defaults(func=cmd_status)\n\n sync = subparsers.add_parser(\n \"sync\",\n help=\"Fast-forward nikiv in the personal fork checkout to upstream/main.\",\n )\n sync.add_argument(\n \"--push\",\n action=\"store_true\",\n help=\"Also push nikiv to the private remote after the fast-forward.\",\n )\n sync.set_defaults(func=cmd_sync)\n\n task = subparsers.add_parser(\n \"task\",\n help=\"Create or reuse a scoped worktree for a Codex fork task and launch Codex there.\",\n )\n task.add_argument(\"query\", help=\"Natural-language task; used for branch slug + initial prompt.\")\n task.add_argument(\n \"--branch\",\n help=\"Explicit branch name to use instead of deriving codex/<slug> from the query.\",\n )\n task.add_argument(\n \"--base\",\n default=DEFAULT_BASE_BRANCH,\n help=f\"Base branch/ref for new worktrees (default: {DEFAULT_BASE_BRANCH}).\",\n )\n task.add_argument(\n \"--path\",\n help=\"Explicit worktree path to use instead of ~/.worktrees/codex/<branch>.\",\n )\n task.add_argument(\n \"--new\",\n action=\"store_true\",\n help=\"Always start a fresh Codex session instead of trying resume --last first.\",\n )\n task.add_argument(\n \"--no-launch\",\n action=\"store_true\",\n help=\"Only create/reuse the worktree and print the next command instead of launching Codex.\",\n )\n task.set_defaults(func=cmd_task)\n\n last = subparsers.add_parser(\n \"last\",\n help=\"Resume the last Codex session in the last used fork worktree.\",\n )\n last.add_argument(\n \"target\",\n nargs=\"?\",\n help=\"Optional branch name or worktree path. Defaults to the last used fork worktree.\",\n )\n last.set_defaults(func=cmd_last)\n\n promote = subparsers.add_parser(\n \"promote\",\n help=\"Create or update a review/nikiv-* branch from a codex/* worktree branch.\",\n )\n promote.add_argument(\n \"target\",\n nargs=\"?\",\n help=\"Optional branch name or worktree path. Defaults to the last used fork worktree.\",\n )\n promote.add_argument(\n \"--review-branch\",\n help=\"Explicit review branch name instead of deriving review/nikiv-<slug>.\",\n )\n promote.add_argument(\n \"--push\",\n action=\"store_true\",\n help=\"Also push the promoted review branch to the private remote.\",\n )\n promote.set_defaults(func=cmd_promote)\n\n return parser\n\n\ndef main() -> int:\n parser = build_parser()\n args = parser.parse_args()\n return args.func(args)\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/deploy.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nROOT_DIR=\"$(cd -- \"$(dirname -- \"${BASH_SOURCE[0]}\")/..\" && pwd)\"\ncd \"${ROOT_DIR}\"\n\nPROFILE=\"${FLOW_PROFILE:-debug}\"\nTARGET_DIR=\"debug\"\nBUILD_ARGS=()\n[[ \"${PROFILE}\" == \"release\" ]] && TARGET_DIR=\"release\" && BUILD_ARGS+=(\"--release\")\n\nappend_rustflag() {\n local flag=\"$1\"\n if [[ -n \"${RUSTFLAGS:-}\" ]]; then\n RUSTFLAGS+=\" ${flag}\"\n else\n RUSTFLAGS=\"${flag}\"\n fi\n}\n\nif [[ \"${PROFILE}\" == \"release\" ]]; then\n export CARGO_INCREMENTAL=0\n\n if [[ \"$(uname -s)\" == \"Darwin\" ]]; then\n append_rustflag \"-C target-cpu=${FLOW_DEPLOY_TARGET_CPU:-native}\"\n append_rustflag \"-C link-arg=-Wl,-dead_strip\"\n append_rustflag \"-C link-arg=-Wl,-dead_strip_dylibs\"\n fi\n\n if [[ -n \"${FLOW_DEPLOY_RUSTFLAGS:-}\" ]]; then\n append_rustflag \"${FLOW_DEPLOY_RUSTFLAGS}\"\n fi\n\n export RUSTFLAGS\nfi\n\n# Build\ncargo build \"${BUILD_ARGS[@]}\" --quiet\n\nSOURCE_F=\"${ROOT_DIR}/target/${TARGET_DIR}/f\"\nSOURCE_LIN=\"${ROOT_DIR}/target/${TARGET_DIR}/lin\"\n\nPRIMARY_DIR=\"${HOME}/bin\"\nALT_DIR=\"${HOME}/.local/bin\"\nPRIMARY_F=\"$(command -v f 2>/dev/null || true)\"\nPRIMARY_INSTALLED=false\n\nad_hoc_sign_if_available() {\n local bin_path=\"$1\"\n [[ -f \"$bin_path\" ]] || return 0\n if command -v codesign >/dev/null 2>&1; then\n # Avoid macOS \"load code signature error\" on copied local binaries.\n codesign --force --sign - --timestamp=none \"$bin_path\" >/dev/null 2>&1 || true\n fi\n}\n\nif [[ -n \"${PRIMARY_F}\" ]]; then\n PRIMARY_DIR=\"$(dirname -- \"${PRIMARY_F}\")\"\nfi\n\ninstall_to_dir() {\n local dir=\"$1\"\n [[ -d \"${dir}\" ]] || return 0\n [[ -w \"${dir}\" ]] || return 0\n\n # Copy binaries (more reliable than symlinks)\n if [[ -e \"${dir}/f\" && \"${SOURCE_F}\" -ef \"${dir}/f\" ]]; then\n :\n else\n cp -f \"${SOURCE_F}\" \"${dir}/f\" 2>/dev/null || return 1\n fi\n ad_hoc_sign_if_available \"${dir}/f\"\n if [[ -e \"${dir}/flow\" && \"${SOURCE_F}\" -ef \"${dir}/flow\" ]]; then\n :\n else\n cp -f \"${SOURCE_F}\" \"${dir}/flow\" 2>/dev/null || true\n fi\n ad_hoc_sign_if_available \"${dir}/flow\"\n if [[ -e \"${dir}/lin\" && \"${SOURCE_LIN}\" -ef \"${dir}/lin\" ]]; then\n :\n else\n cp -f \"${SOURCE_LIN}\" \"${dir}/lin\" 2>/dev/null || true\n fi\n ad_hoc_sign_if_available \"${dir}/lin\"\n return 0\n}\n\nmkdir -p \"${PRIMARY_DIR}\"\nif install_to_dir \"${PRIMARY_DIR}\"; then\n PRIMARY_INSTALLED=true\nfi\n\n# If ~/.local/bin exists, link to the primary install for consistency.\nif [[ -d \"${ALT_DIR}\" ]]; then\n ln -sf \"${PRIMARY_DIR}/f\" \"${ALT_DIR}/f\"\n ln -sf \"${PRIMARY_DIR}/f\" \"${ALT_DIR}/flow\"\n ln -sf \"${PRIMARY_DIR}/lin\" \"${ALT_DIR}/lin\"\nfi\n\n# Verify\nif command -v f &>/dev/null; then\n echo \"flow ${PROFILE} build installed\"\nelse\n echo \"Installed to ~/bin - add to PATH: export PATH=\\\"\\$HOME/bin:\\$PATH\\\"\"\nfi\n" }, { "path": "scripts/deps_check.py", "content": "#!/usr/bin/env python3\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport subprocess\nimport sys\nimport time\nimport urllib.error\nimport urllib.request\nfrom pathlib import Path\nfrom typing import Any\n\n\ndef run_json(cmd: list[str], *, cwd: Path) -> Any:\n result = subprocess.run(\n cmd,\n cwd=cwd,\n text=True,\n capture_output=True,\n check=False,\n )\n if result.returncode != 0:\n raise RuntimeError(\n f\"command failed: {' '.join(cmd)}\\nstdout:\\n{result.stdout}\\nstderr:\\n{result.stderr}\"\n )\n return json.loads(result.stdout)\n\n\ndef fetch_latest(crate: str, cache: dict[str, str]) -> str:\n if crate in cache:\n return cache[crate]\n url = f\"https://crates.io/api/v1/crates/{crate}\"\n request = urllib.request.Request(\n url,\n headers={\n \"Accept\": \"application/json\",\n \"User-Agent\": \"flow-deps-check/1.0\",\n },\n )\n last_error: Exception | None = None\n for attempt in range(3):\n try:\n with urllib.request.urlopen(request, timeout=30) as response:\n payload = json.load(response)\n break\n except (TimeoutError, urllib.error.URLError) as error:\n last_error = error\n if attempt == 2:\n raise RuntimeError(f\"failed to fetch latest version for {crate}: {error}\") from error\n time.sleep(1.0 + attempt)\n else:\n raise RuntimeError(f\"failed to fetch latest version for {crate}: {last_error}\")\n latest = payload[\"crate\"].get(\"max_stable_version\") or payload[\"crate\"][\"newest_version\"]\n cache[crate] = latest\n return latest\n\n\ndef load_vendor_rows(repo_root: Path) -> list[dict[str, Any]]:\n rows = run_json([\"scripts/vendor/check-upstream.sh\", \"--json\"], cwd=repo_root)\n rows.sort(key=lambda row: row[\"crate\"])\n return rows\n\n\ndef load_direct_rows(repo_root: Path) -> list[dict[str, Any]]:\n metadata = run_json([\"cargo\", \"metadata\", \"--format-version\", \"1\", \"--locked\"], cwd=repo_root)\n packages_by_id = {pkg[\"id\"]: pkg for pkg in metadata[\"packages\"]}\n nodes_by_id = {node[\"id\"]: node for node in metadata[\"resolve\"][\"nodes\"]}\n workspace_member_ids = set(metadata.get(\"workspace_members\", []))\n latest_cache: dict[str, str] = {}\n rows: list[dict[str, Any]] = []\n seen_rows: set[tuple[str, str, tuple[str, ...], str]] = set()\n\n for member_id in sorted(workspace_member_ids):\n workspace_pkg = packages_by_id[member_id]\n workspace_name = workspace_pkg[\"name\"]\n workspace_node = nodes_by_id[member_id]\n\n for dep in workspace_node.get(\"deps\", []):\n pkg_id = dep[\"pkg\"]\n pkg = packages_by_id[pkg_id]\n if pkg.get(\"source\") is None:\n continue\n\n kinds = tuple(\n sorted(\n {\n dep_kind.get(\"kind\") or \"normal\"\n for dep_kind in dep.get(\"dep_kinds\", [])\n }\n )\n ) or (\"normal\",)\n row_key = (workspace_name, pkg[\"name\"], kinds, pkg[\"version\"])\n if row_key in seen_rows:\n continue\n seen_rows.add(row_key)\n\n current = pkg[\"version\"]\n latest = fetch_latest(pkg[\"name\"], latest_cache)\n rows.append(\n {\n \"workspace\": workspace_name,\n \"crate\": pkg[\"name\"],\n \"current\": current,\n \"latest\": latest,\n \"kinds\": list(kinds),\n \"status\": \"up-to-date\" if current == latest else \"update-available\",\n }\n )\n\n rows.sort(key=lambda row: (row[\"workspace\"], row[\"crate\"]))\n return rows\n\n\ndef print_rows(title: str, rows: list[dict[str, Any]], *, include_kinds: bool) -> None:\n print(title)\n if not rows:\n print(\" none\")\n return\n for row in rows:\n suffix = \"\"\n if include_kinds:\n suffix = f\" [{row['workspace']}] ({','.join(row['kinds'])})\"\n print(\n f\" {row['crate']}{suffix}: current={row['current']} latest={row['latest']} status={row['status']}\"\n )\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(\n description=\"Check Flow vendored and direct Cargo dependencies against the latest upstream releases.\"\n )\n parser.add_argument(\"--json\", action=\"store_true\", help=\"Emit machine-readable JSON\")\n args = parser.parse_args()\n\n repo_root = Path(__file__).resolve().parent.parent\n vendor_rows = load_vendor_rows(repo_root)\n direct_rows = load_direct_rows(repo_root)\n\n stale_vendor = [row for row in vendor_rows if row[\"status\"] != \"up-to-date\"]\n stale_direct = [row for row in direct_rows if row[\"status\"] != \"up-to-date\"]\n\n payload = {\n \"vendor\": vendor_rows,\n \"direct\": direct_rows,\n \"ok\": not stale_vendor and not stale_direct,\n }\n\n if args.json:\n print(json.dumps(payload, indent=2))\n else:\n print_rows(\"Vendored deps\", vendor_rows, include_kinds=False)\n print_rows(\"Direct Cargo deps\", direct_rows, include_kinds=True)\n print()\n if payload[\"ok\"]:\n print(\"deps-check: ok\")\n else:\n print(\n f\"deps-check: failed ({len(stale_vendor)} vendored stale, {len(stale_direct)} direct stale)\"\n )\n\n return 0 if payload[\"ok\"] else 1\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/generate_help_full_json.py", "content": "#!/usr/bin/env python3\nfrom __future__ import annotations\n\nimport os\nimport pathlib\nimport subprocess\nimport sys\n\n\ndef main() -> int:\n root = pathlib.Path(__file__).resolve().parent.parent\n output = root / \"src\" / \"help_full.json\"\n env = os.environ.copy()\n env[\"FLOW_REGENERATE_HELP_FULL\"] = \"1\"\n cmd = [\"cargo\", \"run\", \"--quiet\", \"--bin\", \"f\", \"--\", \"--help-full\"]\n result = subprocess.run(cmd, cwd=root, env=env, capture_output=True, text=True)\n if result.returncode != 0:\n sys.stderr.write(result.stderr)\n return result.returncode\n output.write_text(result.stdout, encoding=\"utf-8\")\n print(output)\n return 0\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n" }, { "path": "scripts/install-linux-hub.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\n# Installs the flow hub daemon on a Linux machine that can reach the supplied\n# binary/config URLs. Intended to be run via:\n# curl -fsSL https://raw.githubusercontent.com/nikiv/flow/main/scripts/install-linux-hub.sh | \\\n# sudo FLOW_BINARY_URL=https://example.com/f-linux FLOW_CONFIG_URL=https://example.com/config.toml bash\n\nif [[ \"${EUID}\" -ne 0 ]]; then\n echo \"This installer must run as root (use sudo).\" >&2\n exit 1\nfi\n\nFLOW_BINARY_URL=\"${FLOW_BINARY_URL:-}\"\nFLOW_CONFIG_URL=\"${FLOW_CONFIG_URL:-}\"\nFLOW_ROOT=\"${FLOW_ROOT:-/opt/flow}\"\nFLOW_USER=\"${FLOW_USER:-flow}\"\nFLOW_PORT=\"${FLOW_PORT:-9050}\"\nFLOW_SERVICE_NAME=\"${FLOW_SERVICE_NAME:-flowd}\"\n\nif [[ -z \"${FLOW_BINARY_URL}\" ]]; then\n echo \"FLOW_BINARY_URL must be set to a downloadable flow binary.\" >&2\n exit 1\nfi\n\nif [[ -z \"${FLOW_CONFIG_URL}\" ]]; then\n echo \"FLOW_CONFIG_URL must be set to a downloadable flow.toml.\" >&2\n exit 1\nfi\n\ncommand -v curl >/dev/null 2>&1 || {\n echo \"curl is required to download assets. Install it and retry.\" >&2\n exit 1\n}\n\nif [[ ! -d /run/systemd/system ]]; then\n echo \"systemd is required to install the hub as a service.\" >&2\n exit 1\nfi\n\nif ! id -u \"${FLOW_USER}\" >/dev/null 2>&1; then\n echo \"Creating system user ${FLOW_USER}\"\n useradd --system --create-home --shell /usr/sbin/nologin \"${FLOW_USER}\"\nfi\n\nBIN_DIR=\"${FLOW_ROOT}/bin\"\nCONFIG_DIR=\"${FLOW_ROOT}/config\"\nmkdir -p \"${BIN_DIR}\" \"${CONFIG_DIR}\"\nchown -R \"${FLOW_USER}:${FLOW_USER}\" \"${FLOW_ROOT}\"\n\nBIN_PATH=\"${BIN_DIR}/f\"\nCONFIG_PATH=\"${CONFIG_DIR}/flow.toml\"\n\necho \"Downloading flow binary from ${FLOW_BINARY_URL}\"\ncurl -fsSL \"${FLOW_BINARY_URL}\" -o \"${BIN_PATH}\"\nchmod +x \"${BIN_PATH}\"\nchown \"${FLOW_USER}:${FLOW_USER}\" \"${BIN_PATH}\"\n\necho \"Downloading flow config from ${FLOW_CONFIG_URL}\"\ncurl -fsSL \"${FLOW_CONFIG_URL}\" -o \"${CONFIG_PATH}\"\nchown \"${FLOW_USER}:${FLOW_USER}\" \"${CONFIG_PATH}\"\n\nUNIT_FILE=\"/etc/systemd/system/${FLOW_SERVICE_NAME}.service\"\ncat <<EOF >\"${UNIT_FILE}\"\n[Unit]\nDescription=Flow hub daemon\nAfter=network.target\n\n[Service]\nType=simple\nEnvironment=FLOW_CONFIG=${CONFIG_PATH}\nExecStart=${BIN_PATH} daemon --host 0.0.0.0 --port ${FLOW_PORT}\nRestart=always\nRestartSec=5\nUser=${FLOW_USER}\nWorkingDirectory=${FLOW_ROOT}\n\n[Install]\nWantedBy=multi-user.target\nEOF\n\necho \"Enabling ${FLOW_SERVICE_NAME} systemd unit\"\nsystemctl daemon-reload\nsystemctl enable --now \"${FLOW_SERVICE_NAME}\"\n\necho \"Flow hub installed.\"\necho \"Check status with: sudo systemctl status ${FLOW_SERVICE_NAME}\"\necho \"Verify health: curl http://<tailscale-ip>:${FLOW_PORT}/health\"\n" }, { "path": "scripts/install-macos-dev.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\n# macOS-only dev installer for Flow + local Jazz2.\n# Clones Flow + Jazz2, builds, and\n# symlinks binaries into ~/.local/bin.\n\nfail() {\n echo \"flow macos dev install: $*\" >&2\n exit 1\n}\n\ninfo() {\n echo \"flow macos dev install: $*\"\n}\n\nif [[ \"$(uname -s)\" != \"Darwin\" ]]; then\n fail \"this script is macOS-only\"\nfi\n\nBASE_DIR=\"${FLOW_DEV_ROOT:-$HOME/code/org/1f}\"\nFLOW_REPO_URL=\"${FLOW_REPO_URL:-https://github.com/nikivdev/flow}\"\nJAZZ_REPO_URL=\"${FLOW_JAZZ_URL:-https://github.com/garden-co/jazz2}\"\nFLOW_DIR=\"${FLOW_DEV_FLOW_DIR:-$BASE_DIR/flow}\"\nJAZZ_DIR=\"${FLOW_DEV_JAZZ_DIR:-$BASE_DIR/jazz2}\"\nBIN_DIR=\"${FLOW_BIN_DIR:-$HOME/.local/bin}\"\nUSE_SSH=\"${FLOW_GIT_SSH:-}\"\nGITHUB_TOKEN=\"${FLOW_GITHUB_TOKEN:-${GITHUB_TOKEN:-}}\"\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nJAZZ_OPTIONAL=\"${FLOW_JAZZ_OPTIONAL:-1}\"\nJAZZ_AVAILABLE=1\nDIST_DIR=\"${FLOW_DIST_DIR:-${SCRIPT_DIR}/../dist}\"\nFORCE_HTTPS=0\n\nensure_brew() {\n if command -v brew >/dev/null 2>&1; then\n return 0\n fi\n info \"installing Homebrew...\"\n /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n if [[ -f \"/opt/homebrew/bin/brew\" ]]; then\n eval \"$(/opt/homebrew/bin/brew shellenv)\"\n elif [[ -f \"/usr/local/bin/brew\" ]]; then\n eval \"$(/usr/local/bin/brew shellenv)\"\n fi\n}\n\nensure_fnm_and_node() {\n if ! command -v fnm >/dev/null 2>&1; then\n info \"installing fnm...\"\n brew install fnm\n fi\n\n # Ensure fnm is active in this shell\n eval \"$(fnm env)\"\n\n if ! command -v node >/dev/null 2>&1; then\n info \"installing Node.js (LTS) via fnm...\"\n install_out=\"$(fnm install --lts 2>&1)\" || fail \"fnm install --lts failed\"\n echo \"$install_out\"\n installed_version=\"$(printf \"%s\\n\" \"$install_out\" | grep -Eo 'v[0-9]+\\.[0-9]+\\.[0-9]+' | tail -n1 || true)\"\n if [[ -n \"${installed_version}\" ]]; then\n fnm default \"${installed_version}\" || true\n fi\n fi\n}\n\nensure_fzf() {\n if command -v fzf >/dev/null 2>&1; then\n return 0\n fi\n info \"installing fzf...\"\n brew install fzf\n}\n\nensure_rust() {\n if command -v cargo >/dev/null 2>&1; then\n return 0\n fi\n info \"installing Rust...\"\n curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y\n # shellcheck disable=SC1090\n source \"$HOME/.cargo/env\"\n}\n\ncheck_github_ssh() {\n if [[ \"${FLOW_FORCE_HTTPS:-}\" = \"1\" ]]; then\n FORCE_HTTPS=1\n return 0\n fi\n if [[ \"${FLOW_SSH_MODE:-}\" = \"https\" ]]; then\n FORCE_HTTPS=1\n return 0\n fi\n if ! command -v ssh >/dev/null 2>&1; then\n return 0\n fi\n\n local out\n out=\"$(ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new -T git@github.com 2>&1 || true)\"\n if echo \"${out}\" | grep -qi \"successfully authenticated\"; then\n info \"GitHub SSH auth OK.\"\n return 0\n fi\n if echo \"${out}\" | grep -qi \"Permission denied\"; then\n FORCE_HTTPS=1\n info \"GitHub SSH auth failed; configuring Flow to prefer HTTPS.\"\n fi\n}\n\nclone_or_update() {\n mkdir -p \"${BASE_DIR}\"\n\n local resolved_jazz_url\n local resolved_flow_url\n\n resolved_jazz_url=\"$(resolve_repo_url \"${JAZZ_REPO_URL}\")\"\n resolved_flow_url=\"$(resolve_repo_url \"${FLOW_REPO_URL}\")\"\n\n if [[ -d \"${JAZZ_DIR}/.git\" ]]; then\n info \"updating Jazz2...\"\n (cd \"${JAZZ_DIR}\" && GIT_TERMINAL_PROMPT=0 git pull --rebase) || true\n else\n info \"cloning Jazz2 to ${JAZZ_DIR}...\"\n if ! GIT_TERMINAL_PROMPT=0 git clone \"${resolved_jazz_url}\" \"${JAZZ_DIR}\"; then\n if [[ \"${JAZZ_OPTIONAL}\" != \"0\" ]]; then\n info \"Jazz2 clone failed; continuing without local Jazz2 (release fallback).\"\n info \"To build with local Jazz2, set FLOW_GIT_SSH=1 or FLOW_GITHUB_TOKEN=... and rerun.\"\n if [[ -x \"${SCRIPT_DIR}/setup-github-ssh.sh\" ]]; then\n info \"running SSH setup helper so you can add the key to GitHub if needed...\"\n \"${SCRIPT_DIR}/setup-github-ssh.sh\" || true\n fi\n JAZZ_AVAILABLE=0\n else\n fail_clone \"${JAZZ_REPO_URL}\"\n fi\n fi\n fi\n\n if [[ -d \"${FLOW_DIR}/.git\" ]]; then\n info \"updating Flow...\"\n (cd \"${FLOW_DIR}\" && GIT_TERMINAL_PROMPT=0 git pull --rebase) || true\n else\n info \"cloning Flow to ${FLOW_DIR}...\"\n GIT_TERMINAL_PROMPT=0 git clone \"${resolved_flow_url}\" \"${FLOW_DIR}\" || fail_clone \"${FLOW_REPO_URL}\"\n fi\n}\n\nresolve_repo_url() {\n local url=\"$1\"\n\n if [[ -n \"${USE_SSH}\" ]]; then\n if [[ \"${url}\" =~ ^https://github.com/([^/]+)/([^/]+)(\\.git)?$ ]]; then\n echo \"git@github.com:${BASH_REMATCH[1]}/${BASH_REMATCH[2]}.git\"\n return\n fi\n fi\n\n if [[ -n \"${GITHUB_TOKEN}\" ]]; then\n if [[ \"${url}\" =~ ^https://github.com/(.+)$ ]]; then\n echo \"https://x-access-token:${GITHUB_TOKEN}@github.com/${BASH_REMATCH[1]}\"\n return\n fi\n fi\n\n echo \"${url}\"\n}\n\nfail_clone() {\n local url=\"$1\"\n info \"\"\n info \"clone failed for ${url}\"\n if [[ -x \"${SCRIPT_DIR}/setup-github-ssh.sh\" ]]; then\n info \"attempting to provision GitHub SSH key...\"\n \"${SCRIPT_DIR}/setup-github-ssh.sh\" || true\n fi\n info \"If this repo is private, set one of:\"\n info \" FLOW_GITHUB_TOKEN=... (or GITHUB_TOKEN=...)\"\n info \" FLOW_GIT_SSH=1 (uses git@github.com:... and your SSH key)\"\n info \" FLOW_JAZZ_OPTIONAL=0 to require Jazz2 and fail fast\"\n fail \"unable to clone ${url}\"\n}\n\nwrite_cargo_patch() {\n return 0\n}\n\nbuild_and_link() {\n cleanup_stale_links\n if [[ \"${JAZZ_AVAILABLE}\" = \"0\" ]]; then\n install_release_fallback\n return 0\n fi\n info \"building Flow...\"\n (cd \"${FLOW_DIR}\" && cargo build --release)\n\n mkdir -p \"${BIN_DIR}\"\n ln -sf \"${FLOW_DIR}/target/release/f\" \"${BIN_DIR}/f\"\n ln -sf \"${FLOW_DIR}/target/release/f\" \"${BIN_DIR}/flow\"\n if [[ -f \"${FLOW_DIR}/target/release/lin\" ]]; then\n ln -sf \"${FLOW_DIR}/target/release/lin\" \"${BIN_DIR}/lin\"\n fi\n}\n\ninstall_release_fallback() {\n local root_installer=\"${SCRIPT_DIR}/../install.sh\"\n\n if install_local_dist; then\n return 0\n fi\n\n info \"installing Flow from release (no Jazz access)...\"\n\n if [[ -x \"${root_installer}\" ]]; then\n if ! FLOW_INSTALL_PATH=\"${BIN_DIR}/f\" \"${root_installer}\"; then\n info \"release install failed.\"\n info \"If you don't have access to the private Jazz repo, you need a public Flow release.\"\n fail \"release install unavailable\"\n fi\n ln -sf \"${BIN_DIR}/f\" \"${BIN_DIR}/flow\"\n return 0\n fi\n\n if [[ -x \"${SCRIPT_DIR}/install.sh\" ]]; then\n if ! FLOW_SKIP_DEPS=1 FLOW_BIN_DIR=\"${BIN_DIR}\" FLOW_RELEASE_ONLY=1 \"${SCRIPT_DIR}/install.sh\"; then\n info \"release install failed.\"\n info \"If you don't have access to the private Jazz repo, you need a public Flow release.\"\n fail \"release install unavailable\"\n fi\n return 0\n fi\n\n fail \"no installer found for release fallback\"\n}\n\ninstall_local_dist() {\n local arch\n local pattern\n local tarball\n local tmpdir\n local binary\n\n if [[ ! -d \"${DIST_DIR}\" ]]; then\n return 1\n fi\n\n arch=\"$(uname -m)\"\n case \"${arch}\" in\n arm64) pattern=\"*_darwin_arm64.tar.gz\" ;;\n x86_64) pattern=\"*_darwin_x64.tar.gz\" ;;\n *) return 1 ;;\n esac\n\n tarball=\"$(ls -t \"${DIST_DIR}\"/${pattern} 2>/dev/null | head -n1 || true)\"\n if [[ -z \"${tarball}\" ]]; then\n # fallback for amd64 naming\n if [[ \"${arch}\" = \"x86_64\" ]]; then\n tarball=\"$(ls -t \"${DIST_DIR}\"/*_darwin_amd64.tar.gz 2>/dev/null | head -n1 || true)\"\n fi\n fi\n\n if [[ -z \"${tarball}\" ]]; then\n return 1\n fi\n\n info \"installing Flow from local dist: ${tarball}\"\n tmpdir=\"$(mktemp -d)\"\n tar -xzf \"${tarball}\" -C \"${tmpdir}\"\n\n if [[ -f \"${tmpdir}/f\" ]]; then\n binary=\"${tmpdir}/f\"\n else\n binary=\"$(find \"${tmpdir}\" -type f \\( -name \"f\" -o -name \"flow\" \\) 2>/dev/null | head -n1 || true)\"\n fi\n\n if [[ -z \"${binary}\" ]]; then\n rm -rf \"${tmpdir}\"\n return 1\n fi\n\n cleanup_stale_links\n mkdir -p \"${BIN_DIR}\"\n cp \"${binary}\" \"${BIN_DIR}/f\"\n chmod +x \"${BIN_DIR}/f\"\n ln -sf \"${BIN_DIR}/f\" \"${BIN_DIR}/flow\"\n if [[ -f \"${tmpdir}/lin\" ]]; then\n cp \"${tmpdir}/lin\" \"${BIN_DIR}/lin\"\n chmod +x \"${BIN_DIR}/lin\"\n fi\n\n rm -rf \"${tmpdir}\"\n return 0\n}\n\ncleanup_stale_links() {\n local home_bin=\"$HOME/bin\"\n rm -f \"${BIN_DIR}/f\" \"${BIN_DIR}/flow\"\n if [[ -d \"${home_bin}\" ]]; then\n rm -f \"${home_bin}/f\" \"${home_bin}/flow\"\n fi\n}\n\nensure_shell_setup() {\n local zshrc=\"$HOME/.zshrc\"\n local bashrc=\"$HOME/.bashrc\"\n local bash_profile=\"$HOME/.bash_profile\"\n\n local path_line=\"export PATH=\\\"${BIN_DIR}:\\$PATH\\\"\"\n local fnm_line='eval \"$(fnm env --use-on-cd)\"'\n local https_line='export FLOW_FORCE_HTTPS=1'\n\n if [[ -f \"${zshrc}\" ]]; then\n grep -qF \"${path_line}\" \"${zshrc}\" || echo \"${path_line}\" >> \"${zshrc}\"\n grep -qF \"${fnm_line}\" \"${zshrc}\" || echo \"${fnm_line}\" >> \"${zshrc}\"\n if [[ \"${FORCE_HTTPS}\" = \"1\" ]]; then\n grep -qF \"${https_line}\" \"${zshrc}\" || echo \"${https_line}\" >> \"${zshrc}\"\n fi\n elif [[ -f \"${bashrc}\" ]]; then\n grep -qF \"${path_line}\" \"${bashrc}\" || echo \"${path_line}\" >> \"${bashrc}\"\n grep -qF \"${fnm_line}\" \"${bashrc}\" || echo \"${fnm_line}\" >> \"${bashrc}\"\n if [[ \"${FORCE_HTTPS}\" = \"1\" ]]; then\n grep -qF \"${https_line}\" \"${bashrc}\" || echo \"${https_line}\" >> \"${bashrc}\"\n fi\n elif [[ -f \"${bash_profile}\" ]]; then\n grep -qF \"${path_line}\" \"${bash_profile}\" || echo \"${path_line}\" >> \"${bash_profile}\"\n grep -qF \"${fnm_line}\" \"${bash_profile}\" || echo \"${fnm_line}\" >> \"${bash_profile}\"\n if [[ \"${FORCE_HTTPS}\" = \"1\" ]]; then\n grep -qF \"${https_line}\" \"${bash_profile}\" || echo \"${https_line}\" >> \"${bash_profile}\"\n fi\n else\n info \"add to your shell config:\"\n info \" ${path_line}\"\n info \" ${fnm_line}\"\n if [[ \"${FORCE_HTTPS}\" = \"1\" ]]; then\n info \" ${https_line}\"\n fi\n fi\n}\n\nmain() {\n info \"starting macOS dev install\"\n ensure_brew\n ensure_fzf\n ensure_fnm_and_node\n check_github_ssh\n clone_or_update\n if [[ \"${JAZZ_AVAILABLE}\" = \"0\" ]]; then\n install_release_fallback\n ensure_shell_setup\n info \"\"\n info \"done.\"\n info \"flow: ${FLOW_DIR}\"\n info \"jazz2: (skipped)\"\n info \"bin: ${BIN_DIR}\"\n info \"restart your shell, then run: f --help\"\n return\n fi\n ensure_rust\n write_cargo_patch\n build_and_link\n ensure_shell_setup\n\n info \"\"\n info \"done.\"\n info \"flow: ${FLOW_DIR}\"\n info \"jazz2: ${JAZZ_DIR}\"\n info \"bin: ${BIN_DIR}\"\n info \"restart your shell, then run: f --help\"\n}\n\nmain \"$@\"\n" }, { "path": "scripts/install.sh", "content": "#!/bin/sh\n# Allow `curl ... | sh` while still running the installer in bash.\nif [ -z \"${BASH_VERSION:-}\" ]; then\n if ! command -v bash >/dev/null 2>&1; then\n echo \"flow installer: bash is required. Install bash, then rerun the installer.\" >&2\n exit 1\n fi\n case \"${0:-}\" in\n sh|-sh|dash|-dash|*/sh|*/dash)\n tmp=\"$(mktemp \"${TMPDIR:-/tmp}/flow-install.XXXXXX.bash\")\" || {\n echo \"flow installer: failed to create temp file\" >&2\n exit 1\n }\n cat > \"${tmp}\"\n FLOW_INSTALL_SCRIPT_TMP=\"${tmp}\" exec bash \"${tmp}\" \"$@\"\n ;;\n *)\n exec bash \"$0\" \"$@\"\n ;;\n esac\nfi\n\nset -euo pipefail\n\nif [[ -n \"${FLOW_INSTALL_SCRIPT_TMP:-}\" ]]; then\n trap 'rm -f \"${FLOW_INSTALL_SCRIPT_TMP}\"' EXIT\nfi\n\n# Installs flow + f to the current user. Usage:\n# curl -fsSL https://myflow.sh/install.sh | sh\n# curl -fsSL https://myflow.sh/install.sh | bash\n# Customize with:\n# FLOW_INSTALL_ROOT=/usr/local # overrides install prefix (default: ~/.local)\n# FLOW_BIN_DIR=/usr/local/bin # overrides bin dir (defaults to <root>/bin)\n# FLOW_VERSION=<tag> # release version to fetch (default: latest release)\n# FLOW_REF=<git ref> # fallback git ref for source build (default: main)\n# FLOW_REPO_URL=<repo url> # override repo (default: https://github.com/nikivdev/flow)\n# FLOW_RELEASE_BASE=<base url> # override release base (default: GitHub releases)\n# FLOW_BINARY_URL=<url> # skip build; download a prebuilt f binary\n# FLOW_REGISTRY_URL=<url> # install from Flow registry (e.g., https://myflow.sh)\n# FLOW_REGISTRY_PACKAGE=<name> # registry package name (default: flow)\n# FLOW_INSTALL_LIN=0 # skip installing the lin helper binary\n# FLOW_BOOTSTRAP_TOOLS=\"rise seq seqd\" # install additional tools via `f install` after flow\n# FLOW_BOOTSTRAP_INSTALL_PARM=1 # auto-install parm before tool bootstrap\n# FLOW_NO_RELEASE=1 # force source build even if a release exists\n# FLOW_DEV=1 # dev install: clone to ~/code/org/1f/flow with jazz2\n# FLOW_SKIP_DEPS=1 # skip installing dependencies (brew, fnm, node, bun, rust)\n\nREPO_URL=\"${FLOW_REPO_URL:-https://github.com/nikivdev/flow}\"\nJAZZ_REPO_URL=\"${FLOW_JAZZ_URL:-https://github.com/garden-co/jazz2}\"\nREF=\"${FLOW_REF:-main}\"\nINSTALL_LIN=\"${FLOW_INSTALL_LIN:-1}\"\nREGISTRY_URL=\"${FLOW_REGISTRY_URL:-}\"\nREGISTRY_PACKAGE=\"${FLOW_REGISTRY_PACKAGE:-flow}\"\nDEV_INSTALL=\"${FLOW_DEV:-}\"\nSKIP_DEPS=\"${FLOW_SKIP_DEPS:-}\"\nRELEASE_ONLY=\"${FLOW_RELEASE_ONLY:-}\"\nBOOTSTRAP_TOOLS=\"${FLOW_BOOTSTRAP_TOOLS:-rise seq seqd}\"\nBOOTSTRAP_INSTALL_PARM=\"${FLOW_BOOTSTRAP_INSTALL_PARM:-1}\"\nFLOW_INSTALLED=0\nRESOLVED_VERSION=\"\"\nOS_NAME=\"\"\nARCH_NAME=\"\"\nOWNER=\"\"\nREPO_NAME=\"\"\n\n# Dev install paths\nDEV_BASE=\"$HOME/code/org/1f\"\nDEV_FLOW_DIR=\"$DEV_BASE/flow\"\nDEV_JAZZ_DIR=\"$DEV_BASE/jazz2\"\n\nfail() {\n echo \"flow installer: $*\" >&2\n exit 1\n}\n\ninfo() {\n echo \"flow installer: $*\"\n}\n\n# =============================================================================\n# Dependency Installation\n# =============================================================================\n\ninstall_homebrew() {\n if command -v brew &>/dev/null; then\n info \"Homebrew already installed\"\n return 0\n fi\n\n info \"Installing Homebrew...\"\n /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n # Add brew to PATH for this session\n if [[ -f \"/opt/homebrew/bin/brew\" ]]; then\n eval \"$(/opt/homebrew/bin/brew shellenv)\"\n elif [[ -f \"/usr/local/bin/brew\" ]]; then\n eval \"$(/usr/local/bin/brew shellenv)\"\n fi\n}\n\ninstall_fnm() {\n if command -v fnm &>/dev/null; then\n info \"fnm already installed\"\n return 0\n fi\n\n info \"Installing fnm (Fast Node Manager)...\"\n brew install fnm\n\n # Initialize fnm for this session\n eval \"$(fnm env)\"\n}\n\ninstall_node() {\n # Check if node is available via fnm\n if command -v fnm &>/dev/null; then\n if fnm list 2>/dev/null | grep -q \"v\"; then\n info \"Node.js already installed via fnm\"\n eval \"$(fnm env)\"\n return 0\n fi\n\n info \"Installing Node.js LTS via fnm...\"\n fnm install --lts\n fnm default lts-latest\n eval \"$(fnm env)\"\n return 0\n fi\n\n # Fallback: check if node exists\n if command -v node &>/dev/null; then\n info \"Node.js already installed\"\n return 0\n fi\n\n fail \"fnm not available and node not found\"\n}\n\ninstall_bun() {\n if command -v bun &>/dev/null; then\n info \"Bun already installed\"\n return 0\n fi\n\n info \"Installing Bun...\"\n curl -fsSL https://bun.sh/install | bash\n\n # Add bun to PATH for this session\n export BUN_INSTALL=\"$HOME/.bun\"\n export PATH=\"$BUN_INSTALL/bin:$PATH\"\n}\n\ninstall_rust() {\n if command -v cargo &>/dev/null; then\n info \"Rust already installed\"\n return 0\n fi\n\n info \"Installing Rust...\"\n curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y\n\n # Add cargo to PATH for this session\n source \"$HOME/.cargo/env\"\n}\n\ninstall_gh() {\n if command -v gh &>/dev/null; then\n info \"GitHub CLI already installed\"\n return 0\n fi\n\n info \"Installing GitHub CLI...\"\n brew install gh\n}\n\ninstall_fzf() {\n if command -v fzf &>/dev/null; then\n info \"fzf already installed\"\n return 0\n fi\n\n info \"Installing fzf...\"\n brew install fzf\n}\n\ninstall_all_deps() {\n if [[ -n \"${SKIP_DEPS}\" ]]; then\n info \"Skipping dependency installation (FLOW_SKIP_DEPS=1)\"\n return 0\n fi\n\n info \"\"\n info \"=== Installing Dependencies ===\"\n info \"\"\n\n install_homebrew\n install_fnm\n install_node\n install_bun\n install_rust\n install_gh\n install_fzf\n\n info \"\"\n info \"=== Dependencies installed ===\"\n info \"\"\n}\n\nresolve_paths() {\n local root=\"${FLOW_INSTALL_ROOT:-}\"\n local bin=\"${FLOW_BIN_DIR:-}\"\n\n if [[ -n \"${root}\" && -n \"${bin}\" ]]; then\n root=\"${root%/}\"\n bin=\"${bin%/}\"\n if [[ \"${bin}\" != \"${root}/bin\" ]]; then\n fail \"FLOW_INSTALL_ROOT (${root}) and FLOW_BIN_DIR (${bin}) must align (expected ${root}/bin).\"\n fi\n fi\n\n if [[ -z \"${root}\" && -z \"${bin}\" ]]; then\n root=\"$HOME/.local\"\n bin=\"${root}/bin\"\n elif [[ -z \"${root}\" ]]; then\n bin=\"${bin%/}\"\n root=\"$(dirname \"${bin}\")\"\n elif [[ -z \"${bin}\" ]]; then\n root=\"${root%/}\"\n bin=\"${root}/bin\"\n else\n root=\"${root%/}\"\n bin=\"${bin%/}\"\n fi\n\n INSTALL_ROOT=\"${root}\"\n BIN_DIR=\"${bin}\"\n}\n\nneed_cmd() {\n command -v \"$1\" >/dev/null 2>&1 || fail \"missing required command: $1\"\n}\n\ndetect_platform() {\n local uname_s uname_m\n uname_s=\"$(uname -s)\"\n uname_m=\"$(uname -m)\"\n\n case \"${uname_s}\" in\n Darwin) OS_NAME=\"darwin\" ;;\n Linux) OS_NAME=\"linux\" ;;\n *) fail \"unsupported OS: ${uname_s}\" ;;\n esac\n\n case \"${uname_m}\" in\n arm64|aarch64) ARCH_NAME=\"arm64\" ;;\n x86_64|amd64) ARCH_NAME=\"amd64\" ;;\n *) fail \"unsupported architecture: ${uname_m}\" ;;\n esac\n}\n\nparse_repo_url() {\n local repo=\"${REPO_URL%/}\"\n repo=\"${repo%.git}\"\n case \"${repo}\" in\n https://github.com/*/*)\n repo=\"${repo#https://github.com/}\"\n OWNER=\"${repo%%/*}\"\n REPO_NAME=\"${repo#*/}\"\n if [[ -z \"${OWNER}\" || -z \"${REPO_NAME}\" || \"${REPO_NAME}\" == \"${repo}\" ]]; then\n fail \"could not parse owner/repo from ${REPO_URL}\"\n fi\n ;;\n *)\n fail \"FLOW_REPO_URL must be a GitHub https URL when not using FLOW_BINARY_URL (got ${REPO_URL})\"\n ;;\n esac\n}\n\ninstall_from_binary_url() {\n local url=\"$1\"\n need_cmd curl\n\n info \"Downloading flow from ${url}\"\n mkdir -p \"${BIN_DIR}\"\n curl -fsSL \"${url}\" -o \"${BIN_DIR}/f\"\n chmod +x \"${BIN_DIR}/f\"\n}\n\nresolve_release_version() {\n if [[ -n \"${FLOW_VERSION:-}\" ]]; then\n RESOLVED_VERSION=\"${FLOW_VERSION}\"\n return\n fi\n\n if ! command -v curl >/dev/null 2>&1; then\n return\n fi\n\n local api=\"https://api.github.com/repos/${OWNER}/${REPO_NAME}/releases/latest\"\n local tag\n tag=\"$(curl -fsSL \"${api}\" 2>/dev/null | sed -n 's/ *\\\"tag_name\\\" *: *\\\"\\\\(.*\\\\)\\\".*/\\\\1/p' | head -n1 || true)\"\n if [[ -n \"${tag}\" ]]; then\n RESOLVED_VERSION=\"${tag}\"\n fi\n}\n\nresolve_registry_version() {\n if [[ -n \"${FLOW_VERSION:-}\" ]]; then\n RESOLVED_VERSION=\"${FLOW_VERSION}\"\n return 0\n fi\n\n local url=\"${REGISTRY_URL%/}/packages/${REGISTRY_PACKAGE}/latest.json\"\n local manifest\n manifest=\"$(curl -fsSL \"${url}\" 2>/dev/null || true)\"\n if [[ -z \"${manifest}\" ]]; then\n return 1\n fi\n\n local version\n version=\"$(echo \"${manifest}\" | sed -n 's/.*\"version\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p' | head -n1 || true)\"\n if [[ -z \"${version}\" ]]; then\n return 1\n fi\n\n RESOLVED_VERSION=\"${version}\"\n return 0\n}\n\ninstall_from_registry() {\n local registry=\"${REGISTRY_URL%/}\"\n if [[ -z \"${registry}\" ]]; then\n return 1\n fi\n\n need_cmd curl\n\n if ! resolve_registry_version; then\n info \"Failed to resolve latest registry version\"\n return 1\n fi\n\n local target=\"\"\n if [[ \"${OS_NAME}\" == \"darwin\" ]]; then\n target=\"${ARCH_NAME}-apple-darwin\"\n elif [[ \"${OS_NAME}\" == \"linux\" ]]; then\n target=\"${ARCH_NAME}-unknown-linux-gnu\"\n else\n fail \"unsupported OS for registry install: ${OS_NAME}\"\n fi\n\n mkdir -p \"${BIN_DIR}\"\n local bins=(\"${REGISTRY_PACKAGE}\")\n if [[ \"${REGISTRY_PACKAGE}\" == \"flow\" ]]; then\n bins=(\"f\" \"flow\")\n if [[ \"${INSTALL_LIN}\" != \"0\" ]]; then\n bins+=(\"lin\")\n fi\n fi\n\n local installed=0\n for bin in \"${bins[@]}\"; do\n local url=\"${registry}/packages/${REGISTRY_PACKAGE}/${RESOLVED_VERSION}/${target}/${bin}\"\n info \"Downloading ${bin} from ${url}\"\n if curl -fsSL \"${url}\" -o \"${BIN_DIR}/${bin}\"; then\n chmod +x \"${BIN_DIR}/${bin}\"\n installed=1\n if [[ \"${bin}\" == \"flow\" ]]; then\n FLOW_INSTALLED=1\n fi\n else\n info \"Failed to download ${bin} from registry\"\n fi\n done\n\n if [[ \"${installed}\" -eq 0 ]]; then\n info \"Registry install failed\"\n return 1\n fi\n\n if [[ \"${REGISTRY_PACKAGE}\" == \"flow\" ]]; then\n ensure_aliases\n fi\n\n info \"Installed ${REGISTRY_PACKAGE} ${RESOLVED_VERSION} from registry\"\n return 0\n}\n\ninstall_from_release() {\n local version=\"$1\"\n local asset=\"flow_${version}_${OS_NAME}_${ARCH_NAME}.tar.gz\"\n local base=\"${FLOW_RELEASE_BASE:-https://github.com/${OWNER}/${REPO_NAME}/releases/download}\"\n local url=\"${base}/${version}/${asset}\"\n\n need_cmd curl\n need_cmd tar\n\n info \"Downloading release ${version} (${OS_NAME}/${ARCH_NAME})\"\n local tmp_tar\n tmp_tar=\"$(mktemp)\" || fail \"failed to create temp file\"\n if ! curl -fsSL \"${url}\" -o \"${tmp_tar}\"; then\n info \"Release download failed; tried ${url}\"\n rm -f \"${tmp_tar}\"\n return 1\n fi\n\n local tmp_dir\n tmp_dir=\"$(mktemp -d)\" || fail \"failed to create temp dir\"\n\n if ! tar -xzf \"${tmp_tar}\" -C \"${tmp_dir}\"; then\n info \"Failed to unpack release tarball\"\n rm -rf \"${tmp_dir}\" \"${tmp_tar}\"\n return 1\n fi\n\n local extracted\n extracted=\"$(find \"${tmp_dir}\" -mindepth 1 -maxdepth 1 -type d | head -n1)\"\n [[ -z \"${extracted}\" ]] && extracted=\"${tmp_dir}\"\n\n mkdir -p \"${BIN_DIR}\"\n local copied=0\n for bin in f flow lin; do\n if [[ -f \"${extracted}/${bin}\" ]]; then\n cp \"${extracted}/${bin}\" \"${BIN_DIR}/${bin}\"\n chmod +x \"${BIN_DIR}/${bin}\"\n copied=1\n if [[ \"${bin}\" == \"flow\" ]]; then\n FLOW_INSTALLED=1\n fi\n fi\n done\n\n rm -rf \"${tmp_dir}\" \"${tmp_tar}\"\n\n if [[ \"${copied}\" -eq 0 ]]; then\n info \"Release tarball did not contain expected binaries\"\n return 1\n fi\n\n info \"Installed release ${version} to ${BIN_DIR}\"\n return 0\n}\n\ndownload_source_tarball() {\n need_cmd curl\n need_cmd tar\n local dest=\"$1\"\n\n local tar_url=\"https://codeload.github.com/${OWNER}/${REPO_NAME}/tar.gz/${REF}\"\n\n info \"Downloading source tarball ${tar_url}\"\n mkdir -p \"${dest}\"\n curl -fsSL \"${tar_url}\" | tar -xz -C \"${dest}\" --strip-components=1\n}\n\ninstall_from_source() {\n need_cmd cargo\n mkdir -p \"${BIN_DIR}\"\n\n local tmp\n tmp=\"$(mktemp -d)\" || fail \"failed to create temp dir\"\n trap 'rm -rf \"${tmp}\"' EXIT\n\n download_source_tarball \"${tmp}\"\n\n info \"Building flow from source with cargo (this may take a moment)...\"\n local args=(install --locked --force --path \"${tmp}\" --root \"${INSTALL_ROOT}\" --bin f --bin flow)\n if [[ \"${INSTALL_LIN}\" != \"0\" ]]; then\n args+=(--bin lin)\n fi\n\n cargo \"${args[@]}\"\n if [[ -x \"${BIN_DIR}/flow\" ]]; then\n FLOW_INSTALLED=1\n fi\n}\n\nensure_aliases() {\n local target=\"${BIN_DIR}/f\"\n [[ -x \"${target}\" ]] || fail \"expected ${target} after install\"\n\n if [[ \"${FLOW_INSTALLED}\" -eq 1 ]]; then\n return 0\n fi\n\n ln -sf \"${target}\" \"${BIN_DIR}/flow\"\n}\n\nensure_path_hint() {\n case \":$PATH:\" in\n *\":${BIN_DIR}:\"*)\n ;;\n *)\n info \"Add ${BIN_DIR} to your PATH, e.g. append: export PATH=\\\"${BIN_DIR}:\\$PATH\\\"\"\n ;;\n esac\n}\n\ninstall_parm_if_needed() {\n if command -v parm >/dev/null 2>&1; then\n return 0\n fi\n if [[ \"${BOOTSTRAP_INSTALL_PARM}\" == \"0\" ]]; then\n return 1\n fi\n if ! command -v curl >/dev/null 2>&1; then\n info \"curl missing; cannot auto-install parm.\"\n return 1\n fi\n info \"Installing parm for robust GitHub fallback...\"\n if curl -fsSL https://raw.githubusercontent.com/yhoundz/parm/master/scripts/install.sh | sh; then\n export PATH=\"$HOME/.local/bin:$HOME/bin:$PATH\"\n return 0\n fi\n info \"parm install failed; continuing with registry/flox-only bootstrap.\"\n return 1\n}\n\nbootstrap_core_tools() {\n local fbin=\"${BIN_DIR}/f\"\n if [[ ! -x \"${fbin}\" ]]; then\n return 0\n fi\n if [[ -z \"${BOOTSTRAP_TOOLS}\" || \"${BOOTSTRAP_TOOLS}\" == \"0\" || \"${BOOTSTRAP_TOOLS}\" == \"false\" ]]; then\n return 0\n fi\n\n info \"\"\n info \"=== Bootstrap Core Tools ===\"\n info \"\"\n\n install_parm_if_needed || true\n\n local failures=0\n local tool=\"\"\n for tool in ${BOOTSTRAP_TOOLS}; do\n info \"Bootstrapping ${tool}...\"\n if \"${fbin}\" install \"${tool}\" --backend auto --bin-dir \"${BIN_DIR}\" --force; then\n :\n else\n info \"WARN failed to bootstrap ${tool}. Retry later with: f install ${tool} --backend auto\"\n failures=$((failures + 1))\n fi\n done\n\n if [[ \"${failures}\" -eq 0 ]]; then\n info \"Bootstrap complete: ${BOOTSTRAP_TOOLS}\"\n else\n info \"Bootstrap completed with ${failures} warning(s).\"\n fi\n}\n\n# Dev install: clone repos to ~/code/org/1f/ and build from source\ninstall_dev() {\n # Install all dependencies first\n install_all_deps\n\n info \"\"\n info \"=== Dev Install: Setting up in ${DEV_BASE} ===\"\n info \"\"\n mkdir -p \"${DEV_BASE}\"\n\n # Clone or update jazz2\n if [[ -d \"${DEV_JAZZ_DIR}\" ]]; then\n info \"Jazz2 directory exists, updating...\"\n (cd \"${DEV_JAZZ_DIR}\" && git pull --rebase) || true\n else\n info \"Cloning jazz2 to ${DEV_JAZZ_DIR}...\"\n git clone \"${JAZZ_REPO_URL}\" \"${DEV_JAZZ_DIR}\"\n fi\n\n # Clone or update flow\n if [[ -d \"${DEV_FLOW_DIR}\" ]]; then\n info \"Flow directory exists, updating...\"\n (cd \"${DEV_FLOW_DIR}\" && git pull --rebase) || true\n else\n info \"Cloning flow to ${DEV_FLOW_DIR}...\"\n git clone \"${REPO_URL}\" \"${DEV_FLOW_DIR}\"\n fi\n\n # Build\n info \"Building flow from source...\"\n (cd \"${DEV_FLOW_DIR}\" && cargo build --release)\n\n # Setup symlinks\n mkdir -p \"${BIN_DIR}\"\n ln -sf \"${DEV_FLOW_DIR}/target/release/f\" \"${BIN_DIR}/f\"\n if [[ -f \"${DEV_FLOW_DIR}/target/release/flow\" ]]; then\n ln -sf \"${DEV_FLOW_DIR}/target/release/flow\" \"${BIN_DIR}/flow\"\n else\n ln -sf \"${DEV_FLOW_DIR}/target/release/f\" \"${BIN_DIR}/flow\"\n fi\n if [[ \"${INSTALL_LIN}\" != \"0\" && -f \"${DEV_FLOW_DIR}/target/release/lin\" ]]; then\n ln -sf \"${DEV_FLOW_DIR}/target/release/lin\" \"${BIN_DIR}/lin\"\n fi\n\n info \"Symlinked binaries to ${BIN_DIR}\"\n info \"\"\n info \"Dev install complete!\"\n info \" Flow: ${DEV_FLOW_DIR}\"\n info \" Jazz2: ${DEV_JAZZ_DIR}\"\n info \" Binaries: ${BIN_DIR}/f, ${BIN_DIR}/flow\"\n}\n\nmain() {\n resolve_paths\n detect_platform\n\n info \"\"\n info \"=== Flow Installer ===\"\n info \"\"\n\n # Dev install mode\n if [[ -n \"${DEV_INSTALL}\" ]]; then\n install_dev\n ensure_path_hint\n print_shell_setup\n info \"\"\n info \"Done. Launch with \\\"flow --help\\\" or \\\"f --help\\\".\"\n return\n fi\n\n parse_repo_url\n info \"Installing to ${BIN_DIR}\"\n\n if [[ -n \"${FLOW_BINARY_URL:-}\" ]]; then\n install_from_binary_url \"${FLOW_BINARY_URL}\"\n elif [[ -n \"${REGISTRY_URL}\" ]]; then\n if ! install_from_registry; then\n info \"Registry install failed; falling back to release/source.\"\n REGISTRY_URL=\"\"\n else\n ensure_aliases\n bootstrap_core_tools\n ensure_path_hint\n info \"Done. Launch with \\\"flow --help\\\" or \\\"f --help\\\".\"\n return\n fi\n elif [[ -z \"${FLOW_NO_RELEASE:-}\" ]]; then\n resolve_release_version\n if [[ -n \"${RESOLVED_VERSION}\" ]] && install_from_release \"${RESOLVED_VERSION}\"; then\n :\n else\n if [[ -n \"${RELEASE_ONLY}\" ]]; then\n fail \"release not found or unavailable (FLOW_RELEASE_ONLY=1)\"\n fi\n info \"Falling back to source build (release not found or unavailable).\"\n install_all_deps\n install_from_source\n fi\n else\n install_all_deps\n install_from_source\n fi\n\n ensure_aliases\n bootstrap_core_tools\n ensure_path_hint\n\n info \"Done. Launch with \\\"flow --help\\\" or \\\"f --help\\\".\"\n}\n\nprint_shell_setup() {\n info \"\"\n info \"=== Shell Setup ===\"\n info \"\"\n info \"Add these to your shell config:\"\n info \"\"\n if [[ -f \"$HOME/.config/fish/config.fish\" ]]; then\n info \"# Fish (~/.config/fish/config.fish):\"\n info 'set -gx PATH $HOME/.local/bin $PATH'\n info ''\n info '# fnm (Node.js)'\n info 'fnm env | source'\n info ''\n info '# Bun'\n info 'set -gx BUN_INSTALL $HOME/.bun'\n info 'set -gx PATH $BUN_INSTALL/bin $PATH'\n info ''\n info '# Flow function'\n info 'function f'\n info ' if test -z \"$argv[1]\"'\n info ' ~/bin/f'\n info ' else'\n info ' ~/bin/f match $argv'\n info ' end'\n info 'end'\n else\n info \"# Bash/Zsh (~/.bashrc or ~/.zshrc):\"\n info 'export PATH=\"$HOME/.local/bin:$PATH\"'\n info ''\n info '# fnm (Node.js)'\n info 'eval \"$(fnm env)\"'\n info ''\n info '# Bun'\n info 'export BUN_INSTALL=\"$HOME/.bun\"'\n info 'export PATH=\"$BUN_INSTALL/bin:$PATH\"'\n info ''\n info '# Flow function'\n info 'f() {'\n info ' if [ -z \"$1\" ]; then'\n info ' ~/bin/f'\n info ' else'\n info ' ~/bin/f match \"$@\"'\n info ' fi'\n info '}'\n fi\n}\n\nmain \"$@\"\n" }, { "path": "scripts/myflow-commit-session-smoke.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n cat <<'EOF'\nUsage: myflow-commit-session-smoke.sh [options]\n\nVerify that a commit is visible in myflow and optionally require attached AI sessions.\n\nOptions:\n --repo-path PATH Git repo to inspect (default: current directory)\n --repo-slug OWNER/REPO Override repo slug (auto-detected from origin)\n --commit-sha SHA Commit to verify (default: HEAD of --repo-path)\n --api-base URL myflow API base (default: MYFLOW_URL or https://myflow.sh)\n --token TOKEN Auth token (default: MYFLOW_TOKEN or ~/.config/flow/auth.toml)\n --timeout SECONDS Poll timeout waiting for commit (default: 60)\n --require-sessions Fail if commit has zero attached sessions\n --skip-session-fetch Do not verify GET /api/sessions/:id for first session\n -h, --help Show this help\nEOF\n}\n\nREPO_PATH=\"${PWD}\"\nREPO_SLUG=\"\"\nCOMMIT_SHA=\"\"\nAPI_BASE=\"${MYFLOW_URL:-https://myflow.sh}\"\nTOKEN=\"${MYFLOW_TOKEN:-}\"\nTIMEOUT_SECS=60\nREQUIRE_SESSIONS=0\nSKIP_SESSION_FETCH=0\n\nwhile [ \"$#\" -gt 0 ]; do\n case \"$1\" in\n --repo-path)\n REPO_PATH=\"$2\"\n shift 2\n ;;\n --repo-slug)\n REPO_SLUG=\"$2\"\n shift 2\n ;;\n --commit-sha)\n COMMIT_SHA=\"$2\"\n shift 2\n ;;\n --api-base)\n API_BASE=\"$2\"\n shift 2\n ;;\n --token)\n TOKEN=\"$2\"\n shift 2\n ;;\n --timeout)\n TIMEOUT_SECS=\"$2\"\n shift 2\n ;;\n --require-sessions)\n REQUIRE_SESSIONS=1\n shift\n ;;\n --skip-session-fetch)\n SKIP_SESSION_FETCH=1\n shift\n ;;\n -h|--help)\n usage\n exit 0\n ;;\n *)\n echo \"Unknown option: $1\" >&2\n usage >&2\n exit 2\n ;;\n esac\ndone\n\nif [ ! -d \"$REPO_PATH/.git\" ]; then\n echo \"repo path is not a git repo: $REPO_PATH\" >&2\n exit 2\nfi\n\nif [ -z \"$COMMIT_SHA\" ]; then\n COMMIT_SHA=\"$(git -C \"$REPO_PATH\" rev-parse HEAD)\"\nfi\n\nif [ -z \"$REPO_SLUG\" ]; then\n origin=\"$(git -C \"$REPO_PATH\" remote get-url origin 2>/dev/null || true)\"\n if [ -n \"$origin\" ]; then\n if [[ \"$origin\" =~ ^git@github\\.com:(.+)\\.git$ ]]; then\n REPO_SLUG=\"${BASH_REMATCH[1]}\"\n elif [[ \"$origin\" =~ ^git@github\\.com:(.+)$ ]]; then\n REPO_SLUG=\"${BASH_REMATCH[1]}\"\n elif [[ \"$origin\" =~ ^https?://github\\.com/(.+)\\.git$ ]]; then\n REPO_SLUG=\"${BASH_REMATCH[1]}\"\n elif [[ \"$origin\" =~ ^https?://github\\.com/(.+)$ ]]; then\n REPO_SLUG=\"${BASH_REMATCH[1]}\"\n fi\n fi\nfi\n\nif [ -z \"$REPO_SLUG\" ]; then\n echo \"failed to resolve repo slug; pass --repo-slug owner/repo\" >&2\n exit 2\nfi\n\nif [ -z \"$TOKEN\" ] && [ -f \"$HOME/.config/flow/auth.toml\" ]; then\n TOKEN=\"$(\n python3 - \"$HOME/.config/flow/auth.toml\" <<'PY'\nimport pathlib\nimport sys\n\np = pathlib.Path(sys.argv[1])\nif not p.exists():\n print(\"\")\n raise SystemExit(0)\n\ntry:\n import tomllib\nexcept Exception:\n print(\"\")\n raise SystemExit(0)\n\ntry:\n data = tomllib.loads(p.read_text(encoding=\"utf-8\"))\nexcept Exception:\n print(\"\")\n raise SystemExit(0)\n\ntoken = data.get(\"token\")\nprint(token if isinstance(token, str) else \"\")\nPY\n )\"\nfi\n\nif [ -z \"$TOKEN\" ]; then\n echo \"missing token; set MYFLOW_TOKEN or pass --token\" >&2\n exit 2\nfi\n\nAPI_BASE=\"${API_BASE%/}\"\nENCODED_REPO=\"$(\n python3 - \"$REPO_SLUG\" <<'PY'\nimport sys, urllib.parse\nprint(urllib.parse.quote(sys.argv[1], safe=\"\"))\nPY\n)\"\n\ndeadline=$(( $(date +%s) + TIMEOUT_SECS ))\ncommit_line=\"\"\npayload=\"\"\n\necho \"[myflow-smoke] repo=${REPO_SLUG} commit=${COMMIT_SHA} api=${API_BASE}\"\n\nwhile [ \"$(date +%s)\" -le \"$deadline\" ]; do\n payload=\"$(\n curl -fsS \\\n --max-time 10 \\\n -H \"Authorization: Bearer ${TOKEN}\" \\\n \"${API_BASE}/api/commits?repo=${ENCODED_REPO}\" \\\n || true\n )\"\n\n if [ -n \"$payload\" ]; then\n set +e\n commit_line=\"$(\n python3 - \"$COMMIT_SHA\" \"$REQUIRE_SESSIONS\" <<'PY' <<<\"$payload\"\nimport json\nimport sys\n\ntarget = sys.argv[1].lower()\nrequire_sessions = sys.argv[2] == \"1\"\n\ntry:\n data = json.load(sys.stdin)\nexcept Exception:\n raise SystemExit(5)\n\nif not isinstance(data, list):\n raise SystemExit(5)\n\nfound = None\nfor item in data:\n if not isinstance(item, dict):\n continue\n sha = str(item.get(\"commitSha\", \"\")).lower()\n if sha == target or sha.startswith(target):\n found = item\n break\n\nif not found:\n raise SystemExit(3)\n\nsessions = found.get(\"sessions\") or []\nif not isinstance(sessions, list):\n sessions = []\n\nif require_sessions and len(sessions) == 0:\n raise SystemExit(4)\n\nwindow = found.get(\"sessionWindow\") or {}\nmode = \"\"\nif isinstance(window, dict):\n mode = str(window.get(\"mode\", \"\"))\n\nfirst_session = \"\"\nif sessions and isinstance(sessions[0], dict):\n first_session = str(sessions[0].get(\"sessionId\", \"\"))\n\nprint(f\"{found.get('commitSha','')}\\t{len(sessions)}\\t{mode}\\t{first_session}\")\nPY\n )\"\n status=$?\n set -e\n\n case \"$status\" in\n 0) break ;;\n 3) ;;\n 4)\n echo \"[myflow-smoke] commit found but sessions=0 and --require-sessions is set\" >&2\n exit 1\n ;;\n *)\n ;;\n esac\n fi\n\n sleep 2\ndone\n\nif [ -z \"$commit_line\" ]; then\n echo \"[myflow-smoke] commit not found in myflow within ${TIMEOUT_SECS}s\" >&2\n exit 1\nfi\n\nIFS=$'\\t' read -r found_sha session_count window_mode first_session_id <<<\"$commit_line\"\necho \"[myflow-smoke] found commit=${found_sha} sessions=${session_count} sessionWindow.mode=${window_mode:-<none>}\"\n\nif [ \"$SKIP_SESSION_FETCH\" -eq 0 ] && [ -n \"$first_session_id\" ]; then\n encoded_session=\"$(\n python3 - \"$first_session_id\" <<'PY'\nimport sys, urllib.parse\nprint(urllib.parse.quote(sys.argv[1], safe=\"\"))\nPY\n )\"\n curl -fsS \\\n --max-time 10 \\\n -H \"Authorization: Bearer ${TOKEN}\" \\\n \"${API_BASE}/api/sessions/${encoded_session}\" >/dev/null\n echo \"[myflow-smoke] verified first session fetch: ${first_session_id}\"\nfi\n\necho \"[myflow-smoke] ok\"\n" }, { "path": "scripts/package-release.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\n# Build and package flow binaries into a tar.gz release artifact.\n# Usage:\n# FLOW_VERSION=v0.1.0 CODESIGN_IDENTITY=\"Developer ID Application: Example (TEAMID)\" scripts/package-release.sh\n#\n# Outputs:\n# dist/flow-<version>-<os>-<arch>.tar.gz\n# dist/flow-<version>-<os>-<arch>.tar.gz.sha256\n# Contents:\n# f (binary), flow (binary), lin (binary)\n# Notes:\n # - macOS: if CODESIGN_IDENTITY is set, f, flow, and lin are codesigned (--timestamp --options runtime).\n# - Build is local-only; run on each target platform (macOS arm64/x86_64, Linux x86_64/aarch64).\n\nROOT_DIR=\"$(cd -- \"$(dirname -- \"${BASH_SOURCE[0]}\")/..\" && pwd)\"\nDIST_DIR=\"${ROOT_DIR}/dist\"\nPROFILE=release\n\nfail() {\n echo \"package-release: $*\" >&2\n exit 1\n}\n\ninfo() {\n echo \"package-release: $*\"\n}\n\ndetect_platform() {\n local os uname_s arch uname_m\n uname_s=\"$(uname -s)\"\n uname_m=\"$(uname -m)\"\n\n case \"${uname_s}\" in\n Darwin) os=\"darwin\" ;;\n Linux) os=\"linux\" ;;\n *) fail \"unsupported OS: ${uname_s}\" ;;\n esac\n\n case \"${uname_m}\" in\n arm64|aarch64) arch=\"arm64\" ;;\n x86_64|amd64) arch=\"amd64\" ;;\n *) fail \"unsupported arch: ${uname_m}\" ;;\n esac\n\n OS_NAME=\"${os}\"\n ARCH_NAME=\"${arch}\"\n}\n\nresolve_version() {\n if [[ -n \"${FLOW_VERSION:-}\" ]]; then\n VERSION=\"${FLOW_VERSION}\"\n return\n fi\n\n if command -v git >/dev/null 2>&1; then\n VERSION=\"$(git -C \"${ROOT_DIR}\" describe --tags --always --dirty 2>/dev/null || true)\"\n fi\n\n VERSION=\"${VERSION:-dev}\"\n}\n\ncodesign_if_requested() {\n local bin=\"$1\"\n if [[ \"${OS_NAME}\" != \"darwin\" ]]; then\n return\n fi\n if [[ -z \"${CODESIGN_IDENTITY:-}\" ]]; then\n info \"No CODESIGN_IDENTITY set; skipping codesign for ${bin}\"\n return\n fi\n if ! command -v codesign >/dev/null 2>&1; then\n fail \"codesign not found; install Xcode command line tools to sign\"\n fi\n info \"Codesigning ${bin}\"\n codesign --force --timestamp --options runtime --sign \"${CODESIGN_IDENTITY}\" \"${bin}\"\n}\n\nchecksum() {\n local file=\"$1\"\n if command -v shasum >/dev/null 2>&1; then\n shasum -a 256 \"${file}\"\n elif command -v sha256sum >/dev/null 2>&1; then\n sha256sum \"${file}\"\n else\n fail \"neither shasum nor sha256sum found for checksumming\"\n fi\n}\n\nmain() {\n detect_platform\n resolve_version\n\n info \"Building flow (version ${VERSION}, ${OS_NAME}/${ARCH_NAME})\"\n cargo build --locked --release --bin f --bin flow --bin lin\n\n local stage=\"${DIST_DIR}/flow_${VERSION}_${OS_NAME}_${ARCH_NAME}\"\n local target_dir=\"${ROOT_DIR}/target/${PROFILE}\"\n rm -rf \"${stage}\"\n mkdir -p \"${stage}\"\n\n cp \"${target_dir}/f\" \"${stage}/f\"\n cp \"${target_dir}/flow\" \"${stage}/flow\"\n cp \"${target_dir}/lin\" \"${stage}/lin\"\n\n codesign_if_requested \"${stage}/f\"\n codesign_if_requested \"${stage}/flow\"\n codesign_if_requested \"${stage}/lin\"\n\n mkdir -p \"${DIST_DIR}\"\n local tarball=\"${DIST_DIR}/flow_${VERSION}_${OS_NAME}_${ARCH_NAME}.tar.gz\"\n tar -C \"${DIST_DIR}\" -czf \"${tarball}\" \"flow_${VERSION}_${OS_NAME}_${ARCH_NAME}\"\n\n checksum \"${tarball}\" > \"${tarball}.sha256\"\n\n info \"Built ${tarball}\"\n info \"Checksum written to ${tarball}.sha256\"\n info \"Upload these to the GitHub release for ${VERSION} so install.sh can fetch them.\"\n}\n\nmain \"$@\"\n" }, { "path": "scripts/pre-push-guard.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/..\" && pwd)\"\ncd \"$repo_root\"\n\nremote_name=\"${1:-origin}\"\nzero_sha=\"0000000000000000000000000000000000000000\"\nshould_verify_pinned_origin=0\n\nrange_changes_vendor_lock() {\n local local_ref=\"$1\"\n local local_sha=\"$2\"\n local remote_ref=\"$3\"\n local remote_sha=\"$4\"\n local branch_name=\"\"\n local base_ref=\"\"\n\n [[ \"$local_ref\" == refs/heads/* ]] || return 1\n [[ \"$local_sha\" != \"$zero_sha\" ]] || return 1\n\n if [[ \"$remote_sha\" != \"$zero_sha\" ]] && git cat-file -e \"${remote_sha}^{commit}\" 2>/dev/null; then\n base_ref=\"$remote_sha\"\n elif [[ \"$remote_ref\" == refs/heads/* ]]; then\n branch_name=\"${remote_ref#refs/heads/}\"\n if git rev-parse --verify \"refs/remotes/$remote_name/$branch_name\" >/dev/null 2>&1; then\n base_ref=\"refs/remotes/$remote_name/$branch_name\"\n fi\n fi\n\n if [[ -z \"$base_ref\" ]] && git rev-parse --verify \"refs/remotes/$remote_name/main\" >/dev/null 2>&1; then\n base_ref=\"$(git merge-base \"$local_sha\" \"refs/remotes/$remote_name/main\" 2>/dev/null || true)\"\n fi\n\n if [[ -n \"$base_ref\" ]]; then\n git diff --quiet \"$base_ref...$local_sha\" -- vendor.lock.toml\n return $?\n fi\n\n # Fallback for brand-new remotes/branches with no useful remote base yet.\n git diff-tree --quiet --no-commit-id -r \"$local_sha\" -- vendor.lock.toml\n}\n\nwhile read -r local_ref local_sha remote_ref remote_sha; do\n [[ -n \"${local_ref:-}\" ]] || continue\n if ! range_changes_vendor_lock \"$local_ref\" \"$local_sha\" \"$remote_ref\" \"$remote_sha\"; then\n should_verify_pinned_origin=1\n break\n fi\ndone\n\nif [[ \"$should_verify_pinned_origin\" == \"1\" ]]; then\n echo \"pre-push: vendor.lock.toml changed in pushed refs; verifying pinned vendor commit is published\"\n \"$repo_root/scripts/vendor/vendor-repo.sh\" verify-pinned-origin\nfi\n" }, { "path": "scripts/publish-release.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nif [[ $# -lt 2 ]]; then\n echo \"Usage: $0 <ssh-host> <tarball>\" >&2\n echo \"Env: REMOTE_ROOT=/var/www/flow\" >&2\n exit 1\nfi\n\nSSH_HOST=\"$1\"\nTARBALL=\"$2\"\n\nif [[ ! -f \"${TARBALL}\" ]]; then\n echo \"publish-release: tarball not found: ${TARBALL}\" >&2\n exit 1\nfi\n\nif ! command -v ssh >/dev/null 2>&1; then\n echo \"publish-release: ssh is required.\" >&2\n exit 1\nfi\n\nif ! command -v scp >/dev/null 2>&1; then\n echo \"publish-release: scp is required.\" >&2\n exit 1\nfi\n\nFILENAME=\"$(basename \"${TARBALL}\")\"\nif [[ \"${FILENAME}\" =~ ^flow_(.+)_darwin_arm64\\.tar\\.gz$ ]]; then\n VERSION=\"${BASH_REMATCH[1]}\"\nelse\n echo \"publish-release: expected flow_<version>_darwin_arm64.tar.gz\" >&2\n exit 1\nfi\n\nSHA_FILE=\"${TARBALL}.sha256\"\nif [[ ! -f \"${SHA_FILE}\" ]]; then\n if command -v shasum >/dev/null 2>&1; then\n shasum -a 256 \"${TARBALL}\" > \"${SHA_FILE}\"\n elif command -v sha256sum >/dev/null 2>&1; then\n sha256sum \"${TARBALL}\" > \"${SHA_FILE}\"\n else\n echo \"publish-release: need shasum or sha256sum to create checksum\" >&2\n exit 1\n fi\nfi\n\nREMOTE_ROOT=\"${REMOTE_ROOT:-/var/www/flow}\"\nREMOTE_VERSION_DIR=\"${REMOTE_ROOT}/${VERSION}\"\nREMOTE_LATEST_DIR=\"${REMOTE_ROOT}/latest\"\nLATEST_NAME=\"flow_latest_darwin_arm64.tar.gz\"\nLATEST_SHA=\"${LATEST_NAME}.sha256\"\n\nssh \"${SSH_HOST}\" \"mkdir -p '${REMOTE_VERSION_DIR}' '${REMOTE_LATEST_DIR}'\"\nscp \"${TARBALL}\" \"${SSH_HOST}:${REMOTE_VERSION_DIR}/${FILENAME}\"\nscp \"${SHA_FILE}\" \"${SSH_HOST}:${REMOTE_VERSION_DIR}/${FILENAME}.sha256\"\n\nssh \"${SSH_HOST}\" \"ln -sf '${REMOTE_VERSION_DIR}/${FILENAME}' '${REMOTE_LATEST_DIR}/${LATEST_NAME}'\"\nssh \"${SSH_HOST}\" \"ln -sf '${REMOTE_VERSION_DIR}/${FILENAME}.sha256' '${REMOTE_LATEST_DIR}/${LATEST_SHA}'\"\n\necho \"publish-release: uploaded ${FILENAME} to ${SSH_HOST}:${REMOTE_VERSION_DIR}\"\necho \"publish-release: latest -> ${REMOTE_LATEST_DIR}/${LATEST_NAME}\"\n" }, { "path": "scripts/release.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nROOT_DIR=\"$(cd -- \"$(dirname -- \"${BASH_SOURCE[0]}\")/..\" && pwd)\"\nSETUP=1\n\nif [[ \"${1:-}\" == \"--no-setup\" ]]; then\n SETUP=0\n shift\nelif [[ \"${1:-}\" == \"--setup\" ]]; then\n SETUP=1\n shift\nfi\n\nif ! command -v infra >/dev/null 2>&1; then\n echo \"release: infra CLI not found. Build it with:\" >&2\n echo \" (cd /path/to/infra/cli && cargo build --release && cp target/release/infra ~/.local/bin/infra)\" >&2\n exit 1\nfi\n\nbash \"${ROOT_DIR}/scripts/package-release.sh\"\n\ntarball=\"$(ls -t \"${ROOT_DIR}\"/dist/flow_*_darwin_arm64.tar.gz 2>/dev/null | head -n1 || true)\"\nif [[ -z \"${tarball}\" ]]; then\n echo \"release: no darwin/arm64 tarball found in dist/\" >&2\n exit 1\nfi\n\ncmd=(infra release publish \"${tarball}\" --path \"${ROOT_DIR}\")\nif [[ \"${SETUP}\" -eq 1 ]]; then\n cmd+=(--setup)\nfi\n\n\"${cmd[@]}\"\n" }, { "path": "scripts/remote-hub-setup.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nif [ $# -lt 1 ]; then\n echo \"Usage: $0 <ssh-host> [config-path]\" >&2\n exit 1\nfi\n\nSCRIPT_DIR=\"$(cd -- \"$(dirname -- \"${BASH_SOURCE[0]}\")\" >/dev/null 2>&1 && pwd)\"\nROOT_DIR=\"$(cd -- \"${SCRIPT_DIR}/..\" && pwd)\"\n\nSSH_HOST=\"$1\"\nCONFIG_PATH=\"${2:-$HOME/.config/flow/config.toml}\"\n\nif [ ! -f \"${CONFIG_PATH}\" ]; then\n echo \"Config file not found at ${CONFIG_PATH}\" >&2\n exit 1\nfi\n\nREMOTE_HOME=\"$(ssh \"${SSH_HOST}\" 'printf %s \"$HOME\"')\"\nREMOTE_ROOT=\"${REMOTE_ROOT:-${REMOTE_HOME}/flow-hub}\"\nREMOTE_PORT=\"${REMOTE_PORT:-9050}\"\nREMOTE_BIN_DIR=\"${REMOTE_ROOT}/bin\"\nREMOTE_CONFIG_DIR=\"${REMOTE_ROOT}/config\"\nREMOTE_SYNC_DIR=\"${REMOTE_ROOT}/sync\"\nREMOTE_SERVICE_USER=\"${REMOTE_SERVICE_USER:-$(ssh \"${SSH_HOST}\" 'whoami')}\"\n\necho \"Building flow CLI and daemon (release profile)...\"\nFLOW_PROFILE=release \"${ROOT_DIR}/scripts/deploy.sh\" >/dev/null\nFLOW_BIN=\"${ROOT_DIR}/target/release/f\"\n\necho \"Copying binary and config to ${SSH_HOST}:${REMOTE_ROOT}\"\nssh \"${SSH_HOST}\" \"mkdir -p ${REMOTE_BIN_DIR} ${REMOTE_CONFIG_DIR}\"\nscp \"${FLOW_BIN}\" \"${SSH_HOST}:${REMOTE_BIN_DIR}/f\"\nscp \"${CONFIG_PATH}\" \"${SSH_HOST}:${REMOTE_CONFIG_DIR}/flow.toml\"\n\nif [ -n \"${REMOTE_SYNC_PATHS:-}\" ]; then\n ssh \"${SSH_HOST}\" \"mkdir -p ${REMOTE_SYNC_DIR}\"\n IFS=':' read -ra SYNC_PATHS <<<\"${REMOTE_SYNC_PATHS}\"\n for path in \"${SYNC_PATHS[@]}\"; do\n [ -z \"${path}\" ] && continue\n if [ ! -e \"${path}\" ]; then\n echo \"Skipping sync path (missing): ${path}\" >&2\n continue\n fi\n echo \"Syncing ${path} -> ${SSH_HOST}:${REMOTE_SYNC_DIR}\"\n scp -r \"${path}\" \"${SSH_HOST}:${REMOTE_SYNC_DIR}\"\n done\nfi\n\nSERVICE_UNIT=\"[Unit]\nDescription=Remote flow hub\nAfter=network.target\n\n[Service]\nType=simple\nEnvironment=FLOW_CONFIG=${REMOTE_CONFIG_DIR}/flow.toml\nExecStart=${REMOTE_BIN_DIR}/f daemon --host 0.0.0.0 --port ${REMOTE_PORT}\nRestart=always\nRestartSec=5\nUser=${REMOTE_SERVICE_USER}\nWorkingDirectory=${REMOTE_ROOT}\n\n[Install]\nWantedBy=multi-user.target\"\n\necho \"Configuring systemd service on ${SSH_HOST}\"\nssh \"${SSH_HOST}\" \"sudo bash -c 'cat <<\\\"EOF\\\" > /etc/systemd/system/flowd.service\n${SERVICE_UNIT}\nEOF\nsystemctl daemon-reload\nsystemctl enable --now flowd.service'\"\n\necho \"Remote hub deployed. Use tailscale to reach ${SSH_HOST}:${REMOTE_PORT}.\"\n" }, { "path": "scripts/rl_signal_summary.py", "content": "#!/usr/bin/env python3\n\"\"\"Summarize flow RL signal JSONL output.\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nfrom collections import Counter, defaultdict\nfrom pathlib import Path\n\n\ndef percentile(sorted_values: list[int], pct: float) -> int:\n if not sorted_values:\n return 0\n idx = int((len(sorted_values) - 1) * pct)\n return sorted_values[max(0, min(idx, len(sorted_values) - 1))]\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(description=\"Summarize flow RL signal JSONL\")\n parser.add_argument(\n \"path\",\n nargs=\"?\",\n default=\"out/logs/flow_rl_signals.jsonl\",\n help=\"Path to flow RL signal JSONL\",\n )\n parser.add_argument(\"--last\", type=int, default=0, help=\"Only process last N lines\")\n args = parser.parse_args()\n\n path = Path(args.path).expanduser().resolve()\n if not path.exists():\n print(f\"missing file: {path}\")\n return 1\n\n lines = path.read_text(encoding=\"utf-8\", errors=\"replace\").splitlines()\n if args.last > 0:\n lines = lines[-args.last :]\n\n total = 0\n by_event = Counter()\n by_error = Counter()\n durations: defaultdict[str, list[int]] = defaultdict(list)\n\n for raw in lines:\n raw = raw.strip()\n if not raw:\n continue\n try:\n row = json.loads(raw)\n except json.JSONDecodeError:\n continue\n if not isinstance(row, dict):\n continue\n\n total += 1\n event = str(row.get(\"event_type\", \"unknown\"))\n by_event[event] += 1\n\n err_cls = row.get(\"error_class\")\n if err_cls:\n by_error[str(err_cls)] += 1\n\n dur = row.get(\"duration_ms\")\n if isinstance(dur, int) and dur >= 0:\n durations[event].append(dur)\n\n print(f\"file: {path}\")\n print(f\"rows: {total}\")\n print(\"\")\n print(\"event counts:\")\n for event, count in by_event.most_common():\n print(f\" {event}: {count}\")\n\n if by_error:\n print(\"\")\n print(\"error classes:\")\n for err, count in by_error.most_common():\n print(f\" {err}: {count}\")\n\n if durations:\n print(\"\")\n print(\"duration ms:\")\n for event, values in sorted(durations.items()):\n values.sort()\n p50 = percentile(values, 0.50)\n p95 = percentile(values, 0.95)\n p99 = percentile(values, 0.99)\n print(f\" {event}: p50={p50} p95={p95} p99={p99} n={len(values)}\")\n\n return 0\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n\n" }, { "path": "scripts/run-health-checks.mjs", "content": "import fs from \"node:fs/promises\"\nimport path from \"node:path\"\nimport { execFileSync } from \"node:child_process\"\nimport { deflateRawSync } from \"node:zlib\"\n\nconst args = process.argv.slice(2)\nlet configPath = \".ai/health-checks.json\"\nfor (let i = 0; i < args.length; i += 1) {\n if (args[i] === \"--config\" && args[i + 1]) {\n configPath = args[i + 1]\n i += 1\n }\n}\n\nconst resolvedPath = path.resolve(configPath)\nlet config\ntry {\n const raw = await fs.readFile(resolvedPath, \"utf8\")\n config = JSON.parse(raw)\n} catch (err) {\n if (err && err.code === \"ENOENT\") {\n console.log(`No health checks configured at ${configPath}; skipping.`)\n process.exit(0)\n }\n throw err\n}\n\nconst checks = Array.isArray(config.checks) ? config.checks : []\nif (checks.length === 0) {\n console.log(`No health checks configured in ${configPath}; skipping.`)\n process.exit(0)\n}\n\nconst defaultBaseUrl = resolveDefaultBaseUrl(config)\nconst defaultTimeoutMs =\n typeof config.timeout_ms === \"number\" ? config.timeout_ms : 10000\n\nconsole.log(`Running ${checks.length} health check(s) from ${configPath}`)\n\nlet failures = 0\n\nfor (const check of checks) {\n try {\n if (check.type === \"gitedit-share\") {\n const results = await runGiteditShareCheck(check, {\n baseUrl: resolveBaseUrl(check, defaultBaseUrl),\n timeoutMs: resolveTimeoutMs(check, defaultTimeoutMs),\n })\n for (const result of results) {\n if (result.ok) {\n console.log(`OK: ${result.name}`)\n } else {\n failures += 1\n console.log(`FAIL: ${result.name} - ${result.message}`)\n }\n }\n continue\n }\n\n if (check.type === \"http\") {\n const result = await runHttpCheck(check, {\n baseUrl: resolveBaseUrl(check, defaultBaseUrl, false),\n timeoutMs: resolveTimeoutMs(check, defaultTimeoutMs),\n })\n if (result.ok) {\n console.log(`OK: ${result.name}`)\n } else {\n failures += 1\n console.log(`FAIL: ${result.name} - ${result.message}`)\n }\n continue\n }\n\n failures += 1\n console.log(`FAIL: ${check.name || \"unnamed\"} - unknown type`)\n } catch (err) {\n failures += 1\n const name = check.name || check.type || \"health check\"\n console.log(\n `FAIL: ${name} - ${err instanceof Error ? err.message : String(err)}`,\n )\n }\n}\n\nif (failures > 0) {\n console.log(`${failures} health check(s) failed.`)\n process.exit(1)\n} else {\n console.log(\"All health checks passed.\")\n}\n\nfunction resolveDefaultBaseUrl(configValue) {\n const raw =\n configValue.baseUrl ?? configValue.base_url ?? process.env.HEALTH_BASE_URL\n if (!raw) return \"\"\n return expandEnv(String(raw))\n}\n\nfunction resolveBaseUrl(check, fallback, required = true) {\n const raw = check.baseUrl ?? check.base_url ?? fallback\n if (!raw && required) {\n throw new Error(\"Missing baseUrl for health check.\")\n }\n if (!raw) return \"\"\n return expandEnv(String(raw))\n}\n\nfunction resolveTimeoutMs(check, fallback) {\n return typeof check.timeout_ms === \"number\" ? check.timeout_ms : fallback\n}\n\nfunction expandEnv(value) {\n if (typeof value !== \"string\") return value\n return value.replace(/\\$\\{([A-Z0-9_]+)\\}/gi, (match, name) => {\n const envValue = process.env[name]\n if (envValue === undefined) {\n throw new Error(`Missing environment variable: ${name}`)\n }\n return envValue\n })\n}\n\nasync function runHttpCheck(check, { baseUrl, timeoutMs }) {\n const name = check.name || check.url || \"http check\"\n const rawUrl = expandEnv(check.url ?? \"\")\n if (!rawUrl) {\n return { ok: false, name, message: \"Missing url\" }\n }\n const resolvedUrl = resolveUrl(rawUrl, baseUrl)\n const expectedStatuses = normalizeStatuses(check.expect_status ?? 200)\n const contains = normalizeContains(check.contains)\n const method = check.method ? String(check.method).toUpperCase() : \"GET\"\n const headers = check.headers && typeof check.headers === \"object\"\n ? check.headers\n : undefined\n\n const response = await fetchWithTimeout(resolvedUrl, { method, headers }, timeoutMs)\n if (!expectedStatuses.includes(response.status)) {\n return {\n ok: false,\n name,\n message: `Expected ${expectedStatuses.join(\",\")}, got ${response.status}`,\n }\n }\n\n if (contains.length > 0) {\n const body = await response.text()\n for (const needle of contains) {\n if (!body.includes(needle)) {\n return { ok: false, name, message: `Missing text: ${needle}` }\n }\n }\n }\n\n return { ok: true, name }\n}\n\nasync function runGiteditShareCheck(check, { baseUrl, timeoutMs }) {\n const name = check.name || \"gitedit share\"\n const owner = check.owner || \"\"\n const repo = check.repo || \"\"\n const commitRef = check.commit || \"HEAD\"\n if (!owner || !repo) {\n return [\n {\n ok: false,\n name,\n message: \"Missing owner or repo\",\n },\n ]\n }\n\n const commitSha = resolveCommitSha(commitRef)\n const payload = buildSharePayload({ owner, repo, commitSha })\n const hash = encodeSharePayload(payload)\n const apiUrl = new URL(`/api/mirrors/share/${hash}`, baseUrl).toString()\n const pageUrl = new URL(`/${hash}`, baseUrl).toString()\n\n const results = []\n if (check.check_api !== false) {\n const response = await fetchWithTimeout(apiUrl, {}, timeoutMs)\n if (!response.ok) {\n results.push({\n ok: false,\n name: `${name} api`,\n message: `HTTP ${response.status}`,\n })\n } else {\n const data = await response.json().catch(() => null)\n if (!data || data.commit?.commit_sha !== commitSha) {\n results.push({\n ok: false,\n name: `${name} api`,\n message: \"Unexpected response payload\",\n })\n } else {\n results.push({ ok: true, name: `${name} api` })\n }\n }\n }\n\n if (check.check_page !== false) {\n const response = await fetchWithTimeout(pageUrl, {}, timeoutMs)\n if (!response.ok) {\n results.push({\n ok: false,\n name: `${name} page`,\n message: `HTTP ${response.status}`,\n })\n } else {\n results.push({ ok: true, name: `${name} page` })\n }\n }\n\n return results\n}\n\nfunction resolveCommitSha(ref) {\n try {\n return execFileSync(\"git\", [\"rev-parse\", ref], {\n encoding: \"utf8\",\n }).trim()\n } catch (err) {\n if (/^[0-9a-f]{7,40}$/i.test(ref)) return ref\n throw err\n }\n}\n\nfunction buildSharePayload({ owner, repo, commitSha }) {\n return {\n v: 1,\n owner,\n repo,\n commit: {\n commit_sha: commitSha,\n commit_message: null,\n author_name: null,\n author_email: null,\n branch: null,\n ref: null,\n event: \"commit\",\n source: \"flow-cli\",\n session_hash: null,\n ai_sessions: [],\n received_at: new Date().toISOString(),\n },\n }\n}\n\nfunction encodeSharePayload(payload) {\n const json = JSON.stringify(payload)\n const compressed = deflateRawSync(Buffer.from(json))\n const b64 = compressed.toString(\"base64\")\n return b64.replace(/\\+/g, \"-\").replace(/\\//g, \"_\")\n}\n\nfunction normalizeStatuses(value) {\n if (Array.isArray(value)) {\n return value.map((item) => Number(item)).filter((item) => !Number.isNaN(item))\n }\n const numberValue = Number(value)\n return Number.isNaN(numberValue) ? [200] : [numberValue]\n}\n\nfunction normalizeContains(value) {\n if (!value) return []\n if (Array.isArray(value)) return value.map(String)\n return [String(value)]\n}\n\nfunction resolveUrl(url, baseUrl) {\n if (/^https?:\\/\\//i.test(url)) return url\n if (!baseUrl) {\n throw new Error(`Relative url requires baseUrl: ${url}`)\n }\n return new URL(url, baseUrl).toString()\n}\n\nasync function fetchWithTimeout(url, options, timeoutMs) {\n const controller = new AbortController()\n const timeout = setTimeout(() => controller.abort(), timeoutMs)\n try {\n return await fetch(url, { ...options, signal: controller.signal })\n } finally {\n clearTimeout(timeout)\n }\n}\n" }, { "path": "scripts/run-repos.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nRUN_ROOT_DEFAULT=\"$HOME/run\"\n\nexpand_path() {\n local raw=\"$1\"\n case \"$raw\" in\n \"~\")\n printf '%s\\n' \"$HOME\"\n ;;\n \"~/\"*)\n printf '%s/%s\\n' \"$HOME\" \"${raw#~/}\"\n ;;\n *)\n printf '%s\\n' \"$raw\"\n ;;\n esac\n}\n\nRUN_ROOT=\"$(expand_path \"${RUN_ROOT:-$RUN_ROOT_DEFAULT}\")\"\n\nusage() {\n cat <<'USAGE'\nUsage:\n run-repos.sh root\n run-repos.sh ensure\n run-repos.sh list\n run-repos.sh load <name> <repo-ssh-url> [branch]\n run-repos.sh sync [name]\n run-repos.sh task <name> <flow-task> [args...]\n run-repos.sh r <flow-task> [args...]\n run-repos.sh ri <flow-task> [args...]\n run-repos.sh rp <project> <flow-task> [args...]\n run-repos.sh rip <project> <flow-task> [args...]\n run-repos.sh exec <name> <repo-ssh-url> [--branch <branch>] <flow-task> [args...]\n\nEnvironment:\n RUN_ROOT Run repo root (default: ~/run)\n RUN_AUTO_SYNC If set to 1, run-repos.sh task auto-syncs git repos before running task\nUSAGE\n}\n\nensure_root() {\n mkdir -p \"$RUN_ROOT\"\n}\n\nrepo_dir() {\n local name=\"$1\"\n printf '%s/%s\\n' \"$RUN_ROOT\" \"$name\"\n}\n\nis_git_repo() {\n local dir=\"$1\"\n [ -d \"$dir/.git\" ]\n}\n\nvalidate_relative_path() {\n local rel=\"$1\"\n local label=\"$2\"\n if [ -z \"$rel\" ]; then\n echo \"ERROR: $label cannot be empty\"\n exit 1\n fi\n case \"$rel\" in\n /*)\n echo \"ERROR: $label must be relative to \\$RUN_ROOT (got absolute path: $rel)\"\n exit 1\n ;;\n ..|../*|*/..|*/../*)\n echo \"ERROR: $label must not contain '..' segments: $rel\"\n exit 1\n ;;\n esac\n}\n\nsync_git_repo() {\n local dir=\"$1\"\n if ! is_git_repo \"$dir\"; then\n echo \"[run] skip sync (not git): $dir\"\n return 0\n fi\n\n local branch=\"\"\n branch=\"$(git -C \"$dir\" rev-parse --abbrev-ref HEAD 2>/dev/null || true)\"\n\n echo \"[run] syncing: $dir\"\n git -C \"$dir\" fetch --all --prune\n\n if [ -n \"$branch\" ] && git -C \"$dir\" show-ref --verify --quiet \"refs/remotes/origin/$branch\"; then\n git -C \"$dir\" pull --ff-only origin \"$branch\"\n else\n git -C \"$dir\" pull --ff-only || true\n fi\n}\n\nprint_repo_row() {\n local name=\"$1\"\n local dir=\"$2\"\n if is_git_repo \"$dir\"; then\n local remote=\"\"\n local branch=\"\"\n remote=\"$(git -C \"$dir\" remote get-url origin 2>/dev/null || true)\"\n branch=\"$(git -C \"$dir\" rev-parse --abbrev-ref HEAD 2>/dev/null || true)\"\n echo \"$name | git | ${branch:-?} | ${remote:-no-origin} | $dir\"\n else\n echo \"$name | no-git | - | - | $dir\"\n fi\n}\n\ndisplay_name_for_dir() {\n local dir=\"$1\"\n if [ \"$dir\" = \"$RUN_ROOT\" ]; then\n printf 'root'\n return 0\n fi\n printf '%s' \"${dir#$RUN_ROOT/}\"\n}\n\nrun_task_in_dir() {\n local dir=\"$1\"\n local label=\"$2\"\n shift 2\n\n if [ ! -d \"$dir\" ]; then\n echo \"ERROR: run repo/project not found: $dir\"\n exit 1\n fi\n\n if [ ! -f \"$dir/flow.toml\" ]; then\n echo \"ERROR: no flow.toml in: $dir\"\n exit 1\n fi\n\n if [ \"${RUN_AUTO_SYNC:-0}\" = \"1\" ] && is_git_repo \"$dir\"; then\n sync_git_repo \"$dir\"\n fi\n\n local config_path=\"$dir/flow.toml\"\n echo \"[run] $label -> f run --config $config_path $*\"\n (\n cd \"$dir\"\n f run --config \"$config_path\" \"$@\"\n )\n}\n\nresolve_project_dir() {\n local project=\"$1\"\n validate_relative_path \"$project\" \"project\"\n\n local direct\n local internal\n direct=\"$(repo_dir \"$project\")\"\n internal=\"$(repo_dir \"i/$project\")\"\n\n if [ \"$project\" != i/* ] && [ -d \"$direct\" ] && [ -d \"$internal\" ]; then\n echo \"ERROR: project '$project' is ambiguous.\"\n echo \"Use explicit path: 'i/$project' for internal, or '$project' for public.\"\n exit 1\n fi\n\n if [ -d \"$direct\" ]; then\n printf '%s\\n' \"$direct\"\n return 0\n fi\n\n if [ \"$project\" != i/* ] && [ -d \"$internal\" ]; then\n printf '%s\\n' \"$internal\"\n return 0\n fi\n\n echo \"ERROR: project not found under \\$RUN_ROOT:\"\n echo \" tried: $direct\"\n if [ \"$project\" != i/* ]; then\n echo \" tried: $internal\"\n fi\n exit 1\n}\n\ncmd_root() {\n echo \"$RUN_ROOT\"\n}\n\ncmd_ensure() {\n ensure_root\n mkdir -p \"$RUN_ROOT/i\"\n echo \"[run] root ready: $RUN_ROOT\"\n}\n\ncmd_list() {\n ensure_root\n\n local has_any=0\n if [ -f \"$RUN_ROOT/flow.toml\" ]; then\n print_repo_row \"root\" \"$RUN_ROOT\"\n has_any=1\n fi\n\n while IFS= read -r toml; do\n local dir\n local name\n dir=\"$(dirname \"$toml\")\"\n [ \"$dir\" = \"$RUN_ROOT\" ] && continue\n name=\"${dir#$RUN_ROOT/}\"\n print_repo_row \"$name\" \"$dir\"\n has_any=1\n done < <(find \"$RUN_ROOT\" -mindepth 1 -maxdepth 6 -type f -name flow.toml 2>/dev/null | sort)\n\n if [ \"$has_any\" -eq 0 ]; then\n echo \"[run] no run repos found in $RUN_ROOT\"\n fi\n}\n\ncmd_load() {\n if [ \"$#\" -lt 2 ]; then\n echo \"ERROR: load requires <name> <repo-ssh-url> [branch]\"\n usage\n exit 1\n fi\n\n local name=\"$1\"\n validate_relative_path \"$name\" \"name\"\n local repo_url=\"$2\"\n local branch=\"${3:-}\"\n local dir\n dir=\"$(repo_dir \"$name\")\"\n\n ensure_root\n\n if [ -e \"$dir\" ] && ! [ -d \"$dir\" ]; then\n echo \"ERROR: target exists and is not a directory: $dir\"\n exit 1\n fi\n\n if is_git_repo \"$dir\"; then\n echo \"[run] already loaded: $name ($dir)\"\n sync_git_repo \"$dir\"\n return 0\n fi\n\n if [ -d \"$dir\" ] && [ ! -d \"$dir/.git\" ]; then\n echo \"ERROR: directory exists but is not a git repo: $dir\"\n echo \"Remove it manually or choose another run repo name.\"\n exit 1\n fi\n\n if [ -n \"$branch\" ]; then\n echo \"[run] cloning $repo_url (branch: $branch) -> $dir\"\n git clone --branch \"$branch\" \"$repo_url\" \"$dir\"\n else\n echo \"[run] cloning $repo_url -> $dir\"\n git clone \"$repo_url\" \"$dir\"\n fi\n\n if [ ! -f \"$dir/flow.toml\" ]; then\n echo \"WARN: cloned repo has no flow.toml: $dir\"\n fi\n}\n\ncmd_sync() {\n ensure_root\n\n if [ \"$#\" -gt 0 ]; then\n local name=\"$1\"\n validate_relative_path \"$name\" \"name\"\n local dir\n dir=\"$(repo_dir \"$name\")\"\n if [ ! -d \"$dir\" ]; then\n echo \"ERROR: run repo not found: $dir\"\n exit 1\n fi\n sync_git_repo \"$dir\"\n return 0\n fi\n\n local found=0\n while IFS= read -r git_dir; do\n [ -n \"$git_dir\" ] || continue\n local repo\n repo=\"$(dirname \"$git_dir\")\"\n found=1\n sync_git_repo \"$repo\"\n done < <(find \"$RUN_ROOT\" -type d -name .git -prune 2>/dev/null | sort)\n\n if [ \"$found\" -eq 0 ]; then\n echo \"[run] no git run repos to sync in $RUN_ROOT\"\n fi\n}\n\ncmd_task() {\n if [ \"$#\" -lt 2 ]; then\n echo \"ERROR: task requires <name> <flow-task> [args...]\"\n usage\n exit 1\n fi\n\n local name=\"$1\"\n shift\n validate_relative_path \"$name\" \"name\"\n local dir\n dir=\"$(repo_dir \"$name\")\"\n\n run_task_in_dir \"$dir\" \"$name\" \"$@\"\n}\n\ncmd_ri() {\n # Shortcut: run task in $RUN_ROOT/i\n cmd_task i \"$@\"\n}\n\ncmd_r() {\n # Shortcut: run task in $RUN_ROOT (the public run repo itself)\n if [ \"$#\" -lt 1 ]; then\n echo \"ERROR: r requires <flow-task> [args...]\"\n exit 1\n fi\n ensure_root\n run_task_in_dir \"$RUN_ROOT\" \"root\" \"$@\"\n}\n\ncmd_rp() {\n # Run a task in a run project by path/name (resolves internal fallback).\n if [ \"$#\" -lt 2 ]; then\n echo \"ERROR: rp requires <project> <flow-task> [args...]\"\n usage\n exit 1\n fi\n local project=\"$1\"\n shift\n local dir\n local label\n dir=\"$(resolve_project_dir \"$project\")\"\n label=\"$(display_name_for_dir \"$dir\")\"\n run_task_in_dir \"$dir\" \"$label\" \"$@\"\n}\n\ncmd_rip() {\n # Run a task in an internal run project: $RUN_ROOT/i/<project>.\n if [ \"$#\" -lt 2 ]; then\n echo \"ERROR: rip requires <project> <flow-task> [args...]\"\n usage\n exit 1\n fi\n local project=\"$1\"\n shift\n validate_relative_path \"$project\" \"project\"\n local dir\n dir=\"$(repo_dir \"i/$project\")\"\n run_task_in_dir \"$dir\" \"i/$project\" \"$@\"\n}\n\ncmd_exec() {\n if [ \"$#\" -lt 3 ]; then\n echo \"ERROR: exec requires <name> <repo-ssh-url> [--branch <branch>] <flow-task> [args...]\"\n usage\n exit 1\n fi\n\n local name=\"$1\"\n validate_relative_path \"$name\" \"name\"\n local repo_url=\"$2\"\n shift 2\n\n local branch=\"\"\n if [ \"${1:-}\" = \"--branch\" ]; then\n branch=\"${2:-}\"\n if [ -z \"$branch\" ]; then\n echo \"ERROR: --branch requires a value\"\n usage\n exit 1\n fi\n shift 2\n fi\n\n if [ \"$#\" -lt 1 ]; then\n echo \"ERROR: exec requires a flow task after repo parameters\"\n usage\n exit 1\n fi\n\n local dir\n dir=\"$(repo_dir \"$name\")\"\n if [ -d \"$dir\" ] && [ -f \"$dir/flow.toml\" ] && ! is_git_repo \"$dir\"; then\n if is_git_repo \"$RUN_ROOT\"; then\n echo \"[run] syncing monorepo root: $RUN_ROOT\"\n if ! sync_git_repo \"$RUN_ROOT\"; then\n echo \"[run] WARN: failed to sync monorepo root; using local checkout\"\n fi\n fi\n echo \"[run] using existing run task directory (non-git): $dir\"\n else\n if [ -n \"$branch\" ]; then\n cmd_load \"$name\" \"$repo_url\" \"$branch\"\n else\n cmd_load \"$name\" \"$repo_url\"\n fi\n fi\n\n cmd_task \"$name\" \"$@\"\n}\n\nmain() {\n local cmd=\"${1:-help}\"\n shift || true\n\n case \"$cmd\" in\n root) cmd_root \"$@\" ;;\n ensure) cmd_ensure \"$@\" ;;\n list) cmd_list \"$@\" ;;\n load) cmd_load \"$@\" ;;\n sync) cmd_sync \"$@\" ;;\n task) cmd_task \"$@\" ;;\n ri) cmd_ri \"$@\" ;;\n r) cmd_r \"$@\" ;;\n rp) cmd_rp \"$@\" ;;\n rip) cmd_rip \"$@\" ;;\n exec) cmd_exec \"$@\" ;;\n help|-h|--help) usage ;;\n *)\n echo \"ERROR: unknown command: $cmd\"\n usage\n exit 1\n ;;\n esac\n}\n\nmain \"$@\"\n" }, { "path": "scripts/setup-github-ssh.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\n# macOS helper to provision an SSH key for GitHub and configure ssh-agent.\n# Designed to be run non-interactively; set FLOW_SSH_PASSPHRASE if desired.\n\nfail() {\n echo \"flow github ssh: $*\" >&2\n exit 1\n}\n\ninfo() {\n echo \"flow github ssh: $*\"\n}\n\nif [[ \"$(uname -s)\" != \"Darwin\" ]]; then\n fail \"this script is macOS-only\"\nfi\n\nKEY_PATH=\"${FLOW_SSH_KEY_PATH:-$HOME/.ssh/id_ed25519}\"\nEMAIL=\"${FLOW_SSH_EMAIL:-${USER}@$(hostname -s)}\"\nPASSPHRASE=\"${FLOW_SSH_PASSPHRASE:-}\"\nOPEN_GITHUB=\"${FLOW_OPEN_GITHUB:-1}\"\n\nensure_key() {\n if [[ -f \"${KEY_PATH}\" && -f \"${KEY_PATH}.pub\" ]]; then\n info \"existing SSH key found at ${KEY_PATH}\"\n return 0\n fi\n\n info \"generating SSH key at ${KEY_PATH}...\"\n mkdir -p \"$(dirname \"${KEY_PATH}\")\"\n ssh-keygen -t ed25519 -C \"${EMAIL}\" -f \"${KEY_PATH}\" -N \"${PASSPHRASE}\"\n}\n\nensure_agent() {\n if [[ -z \"${SSH_AUTH_SOCK:-}\" ]]; then\n eval \"$(ssh-agent -s)\"\n fi\n\n if ssh-add --apple-use-keychain \"${KEY_PATH}\" >/dev/null 2>&1; then\n return 0\n fi\n\n ssh-add \"${KEY_PATH}\"\n}\n\nensure_config() {\n local config_file=\"$HOME/.ssh/config\"\n mkdir -p \"$(dirname \"${config_file}\")\"\n touch \"${config_file}\"\n\n if ! grep -q \"Host github.com\" \"${config_file}\"; then\n cat >> \"${config_file}\" <<EOF\n\nHost github.com\n AddKeysToAgent yes\n UseKeychain yes\n IdentityFile ${KEY_PATH}\nEOF\n info \"updated ${config_file}\"\n fi\n}\n\nprint_next_steps() {\n info \"\"\n info \"add this public key to GitHub:\"\n info \"1) Open https://github.com/settings/keys\"\n info \"2) Click \\\"New SSH key\\\"\"\n info \"3) Title: something like \\\"$(hostname -s)\\\"\"\n info \"4) Key type: Authentication\"\n info \"5) Key: paste the EXACT line below (starts with ssh-ed25519)\"\n if command -v pbcopy >/dev/null 2>&1; then\n pbcopy < \"${KEY_PATH}.pub\"\n info \"public key copied to clipboard\"\n fi\n cat \"${KEY_PATH}.pub\"\n info \"\"\n if [[ \"${OPEN_GITHUB}\" != \"0\" ]] && command -v open >/dev/null 2>&1; then\n open \"https://github.com/settings/keys\" || true\n fi\n info \"then run: ssh -T git@github.com\"\n info \"if it still says Permission denied, you may not have access to the private repo yet.\"\n}\n\nensure_key\nensure_agent\nensure_config\nprint_next_steps\n" }, { "path": "scripts/setup-release-host.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nif [[ $# -lt 2 ]]; then\n echo \"Usage: $0 <ssh-host> <domain>\" >&2\n echo \"Env: RELEASE_ROOT=/var/www/flow CADDYFILE_PATH=/etc/caddy/Caddyfile\" >&2\n exit 1\nfi\n\nSSH_HOST=\"$1\"\nDOMAIN=\"$2\"\nRELEASE_ROOT=\"${RELEASE_ROOT:-/var/www/flow}\"\nCADDYFILE_PATH=\"${CADDYFILE_PATH:-/etc/caddy/Caddyfile}\"\n\nif ! command -v ssh >/dev/null 2>&1; then\n echo \"ssh is required to configure the release host.\" >&2\n exit 1\nfi\n\nssh \"${SSH_HOST}\" \"sudo bash -s -- '${DOMAIN}' '${RELEASE_ROOT}' '${CADDYFILE_PATH}'\" <<'EOF'\nset -euo pipefail\n\nDOMAIN=\"${1:?missing domain}\"\nRELEASE_ROOT=\"${2:-/var/www/flow}\"\nCADDYFILE_PATH=\"${3:-/etc/caddy/Caddyfile}\"\n\nfail() {\n echo \"release-host: $*\" >&2\n exit 1\n}\n\ninstall_caddy() {\n if command -v caddy >/dev/null 2>&1; then\n return\n fi\n\n if ! command -v apt-get >/dev/null 2>&1; then\n fail \"caddy not installed and apt-get not available\"\n fi\n\n apt-get update\n apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg\n curl -1sLf \"https://dl.cloudsmith.io/public/caddy/stable/gpg.key\" | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg\n curl -1sLf \"https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt\" | tee /etc/apt/sources.list.d/caddy-stable.list >/dev/null\n apt-get update\n apt-get install -y caddy\n}\n\nif [[ ! -d /run/systemd/system ]]; then\n fail \"systemd is required to manage Caddy\"\nfi\n\ninstall_caddy\n\nmkdir -p \"${RELEASE_ROOT}\"\nchmod 755 \"${RELEASE_ROOT}\"\n\nmkdir -p \"$(dirname \"${CADDYFILE_PATH}\")\"\nif [[ ! -f \"${CADDYFILE_PATH}\" ]]; then\n touch \"${CADDYFILE_PATH}\"\nfi\n\nif ! grep -Fq \"${DOMAIN}\" \"${CADDYFILE_PATH}\"; then\n cat <<CFG >> \"${CADDYFILE_PATH}\"\n\n${DOMAIN} {\n root * ${RELEASE_ROOT}\n file_server\n}\nCFG\nfi\n\nsystemctl enable --now caddy\nsystemctl reload caddy\n\necho \"release-host: serving ${RELEASE_ROOT} on https://${DOMAIN}\"\nEOF\n" }, { "path": "scripts/sync-cdn.sh", "content": "#!/bin/bash\nset -e\n\n# Sync Flow releases to CDN server\n# Usage: ./scripts/sync-cdn.sh [version]\n# If no version specified, syncs latest release\n\nREPO=\"nikitavoloboev/flow\"\nCDN_HOST=\"root@100.114.156.47\"\nCDN_PATH=\"/var/www/cdn.myflow.sh\"\n\n# Get version\nif [ -n \"${1:-}\" ]; then\n VERSION=\"$1\"\nelse\n echo \"Fetching latest version...\"\n VERSION=$(curl -fsSL \"https://api.github.com/repos/${REPO}/releases/latest\" | grep '\"tag_name\":' | sed -E 's/.*\"([^\"]+)\".*/\\1/')\nfi\n\nif [ -z \"$VERSION\" ]; then\n echo \"Error: Could not determine version\"\n exit 1\nfi\n\necho \"Syncing version: $VERSION\"\n\nTARGETS=(\n \"x86_64-apple-darwin\"\n \"aarch64-apple-darwin\"\n \"x86_64-unknown-linux-gnu\"\n \"aarch64-unknown-linux-gnu\"\n)\n\n# Create temp directory\nTMP_DIR=$(mktemp -d)\ntrap \"rm -rf $TMP_DIR\" EXIT\n\n# Download all artifacts\necho \"Downloading artifacts...\"\nfor target in \"${TARGETS[@]}\"; do\n url=\"https://github.com/${REPO}/releases/download/${VERSION}/flow-${target}.tar.gz\"\n echo \" Downloading flow-${target}.tar.gz...\"\n curl -fsSL -o \"$TMP_DIR/flow-${target}.tar.gz\" \"$url\" || echo \" Warning: failed to download $target\"\ndone\n\n# Download checksums\necho \" Downloading checksums.txt...\"\ncurl -fsSL -o \"$TMP_DIR/checksums.txt\" \"https://github.com/${REPO}/releases/download/${VERSION}/checksums.txt\" || true\n\n# Create version directory on CDN\necho \"Creating directory on CDN...\"\nssh \"$CDN_HOST\" \"mkdir -p ${CDN_PATH}/${VERSION}\"\n\n# Upload files\necho \"Uploading to CDN...\"\nscp \"$TMP_DIR\"/* \"${CDN_HOST}:${CDN_PATH}/${VERSION}/\"\n\n# Update 'latest' symlink\necho \"Updating latest symlink...\"\nssh \"$CDN_HOST\" \"cd ${CDN_PATH} && rm -f latest && ln -s ${VERSION} latest\"\n\necho \"\"\necho \"Done! Files available at:\"\necho \" https://cdn.myflow.sh/${VERSION}/\"\necho \" https://cdn.myflow.sh/latest/\"\n" }, { "path": "scripts/vendor/apply-trims.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\nusage() {\n cat <<'USAGE'\nUsage:\n scripts/vendor/apply-trims.sh [crate]\n\nExamples:\n scripts/vendor/apply-trims.sh\n scripts/vendor/apply-trims.sh regex\n\nBehavior:\n - By default, this script is a no-op (safe baseline).\n - If scripts/vendor/trim-hooks.sh exists, it is sourced and called for extensible project-specific trims.\nUSAGE\n}\n\nif [[ \"${1:-}\" == \"-h\" || \"${1:-}\" == \"--help\" ]]; then\n usage\n exit 0\nfi\n\ntarget_crate=\"${1:-}\"\n\nif [[ -f scripts/vendor/trim-hooks.sh ]]; then\n # shellcheck source=/dev/null\n source scripts/vendor/trim-hooks.sh\n if declare -F apply_vendor_trims >/dev/null 2>&1; then\n apply_vendor_trims \"${target_crate:-}\"\n exit 0\n fi\nfi\n\nif [[ -n \"$target_crate\" ]]; then\n echo \"note: no default trim rules for '$target_crate' (create scripts/vendor/trim-hooks.sh)\"\nelse\n echo \"note: no default trim rules (create scripts/vendor/trim-hooks.sh)\"\nfi\n" }, { "path": "scripts/vendor/bench_iteration.py", "content": "#!/usr/bin/env python3\n\"\"\"Record and compare compile-iteration timings for vendoring work.\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport subprocess\nimport time\nfrom dataclasses import asdict, dataclass\nfrom datetime import datetime, timezone\nfrom pathlib import Path\nfrom typing import Literal\n\n\nMode = Literal[\"incremental\", \"clean\"]\n\n\n@dataclass\nclass BenchRow:\n timestamp_utc: str\n project: str\n git_commit: str\n mode: Mode\n sample: int\n seconds: float\n command: str\n\n\ndef utc_now() -> str:\n return datetime.now(tz=timezone.utc).isoformat()\n\n\ndef git_head(project: Path) -> str:\n try:\n out = subprocess.check_output(\n [\"git\", \"-C\", str(project), \"rev-parse\", \"--short\", \"HEAD\"],\n text=True,\n ).strip()\n return out or \"unknown\"\n except Exception:\n return \"unknown\"\n\n\ndef read_jsonl(path: Path) -> list[dict]:\n if not path.exists():\n return []\n rows: list[dict] = []\n for line in path.read_text(encoding=\"utf-8\").splitlines():\n line = line.strip()\n if not line:\n continue\n try:\n rows.append(json.loads(line))\n except json.JSONDecodeError:\n continue\n return rows\n\n\ndef append_jsonl(path: Path, rows: list[BenchRow]) -> None:\n path.parent.mkdir(parents=True, exist_ok=True)\n with path.open(\"a\", encoding=\"utf-8\") as fh:\n for row in rows:\n fh.write(json.dumps(asdict(row), ensure_ascii=False) + \"\\n\")\n\n\ndef run_cmd(project: Path, cmd: str) -> float:\n start = time.perf_counter()\n proc = subprocess.run(cmd, shell=True, cwd=project)\n end = time.perf_counter()\n if proc.returncode != 0:\n raise RuntimeError(f\"command failed ({proc.returncode}): {cmd}\")\n return end - start\n\n\ndef run_sample(project: Path, mode: Mode, cmd: str) -> float:\n if mode == \"clean\":\n run_cmd(project, \"cargo clean\")\n return run_cmd(project, cmd)\n\n\ndef summarize(values: list[float]) -> dict[str, float]:\n if not values:\n return {\"min\": 0.0, \"avg\": 0.0, \"max\": 0.0}\n return {\n \"min\": min(values),\n \"avg\": sum(values) / len(values),\n \"max\": max(values),\n }\n\n\ndef main() -> None:\n parser = argparse.ArgumentParser(description=\"Benchmark vendoring iteration speed\")\n parser.add_argument(\"--project\", default=\".\", help=\"Project root (default: .)\")\n parser.add_argument(\"--mode\", choices=[\"incremental\", \"clean\", \"both\"], default=\"incremental\")\n parser.add_argument(\"--samples\", type=int, default=3, help=\"Samples per mode\")\n parser.add_argument(\"--cmd\", default=\"cargo check -q\", help=\"Command to benchmark\")\n parser.add_argument(\"--record\", default=\"out/vendor/iteration_bench.jsonl\", help=\"JSONL output path\")\n parser.add_argument(\"--compare-window\", type=int, default=10, help=\"Prior rows to compare against\")\n parser.add_argument(\"--fail-above\", type=float, default=0.0, help=\"Fail if avg seconds exceeds threshold\")\n args = parser.parse_args()\n\n project = Path(args.project).expanduser().resolve()\n record_path = project / args.record\n\n modes: list[Mode]\n if args.mode == \"both\":\n modes = [\"clean\", \"incremental\"]\n else:\n modes = [args.mode]\n\n prior = read_jsonl(record_path)\n git_commit = git_head(project)\n all_rows: list[BenchRow] = []\n\n for mode in modes:\n print(f\"mode: {mode}\")\n values: list[float] = []\n for i in range(1, args.samples + 1):\n secs = run_sample(project, mode, args.cmd)\n values.append(secs)\n row = BenchRow(\n timestamp_utc=utc_now(),\n project=str(project),\n git_commit=git_commit,\n mode=mode,\n sample=i,\n seconds=secs,\n command=args.cmd,\n )\n all_rows.append(row)\n print(f\" sample {i}/{args.samples}: {secs:.3f}s\")\n\n stats = summarize(values)\n print(f\" min/avg/max: {stats['min']:.3f}s / {stats['avg']:.3f}s / {stats['max']:.3f}s\")\n\n prev_values = [\n float(row.get(\"seconds\", 0.0))\n for row in prior\n if row.get(\"mode\") == mode and row.get(\"command\") == args.cmd\n ]\n if prev_values:\n window = prev_values[-args.compare_window :]\n prev_avg = sum(window) / len(window)\n delta = stats[\"avg\"] - prev_avg\n direction = \"+\" if delta >= 0 else \"-\"\n print(f\" delta vs last {len(window)} avg: {direction}{abs(delta):.3f}s (prev {prev_avg:.3f}s)\")\n\n if args.fail_above > 0 and stats[\"avg\"] > args.fail_above:\n append_jsonl(record_path, all_rows)\n raise SystemExit(\n f\"avg {mode} time {stats['avg']:.3f}s exceeds fail-above {args.fail_above:.3f}s\"\n )\n\n append_jsonl(record_path, all_rows)\n print(f\"recorded: {len(all_rows)} samples -> {record_path}\")\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "scripts/vendor/check-upstream.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\nif ! command -v jq >/dev/null 2>&1; then\n echo \"error: jq is required\"\n exit 1\nfi\n\nusage() {\n cat <<'USAGE'\nUsage:\n scripts/vendor/check-upstream.sh [--important] [--json]\n\nOptions:\n --important Check only crates listed in scripts/vendor/important-crates.txt\n --json Emit machine-readable JSON array\nUSAGE\n}\n\nimportant_only=false\njson_output=false\nfor arg in \"$@\"; do\n case \"$arg\" in\n --important) important_only=true ;;\n --json) json_output=true ;;\n -h|--help) usage; exit 0 ;;\n *) usage; exit 1 ;;\n esac\ndone\n\nimportant_file=\"scripts/vendor/important-crates.txt\"\nif [[ \"$important_only\" == true && ! -f \"$important_file\" ]]; then\n echo \"error: missing $important_file\"\n exit 1\nfi\n\nis_important() {\n local crate=\"$1\"\n [[ -f \"$important_file\" ]] || return 1\n rg -n \"^${crate}$\" \"$important_file\" >/dev/null 2>&1\n}\n\nread_field() {\n local file=\"$1\"\n local key=\"$2\"\n awk -F'\"' -v key=\"$key\" '$1 ~ \"^\" key \" = \" { print $2; exit }' \"$file\"\n}\n\nclassify_update_level() {\n local current=\"$1\"\n local latest=\"$2\"\n IFS='.' read -r c1 c2 c3 _ <<<\"$current\"\n IFS='.' read -r l1 l2 l3 _ <<<\"$latest\"\n if [[ -z \"${c1:-}\" || -z \"${l1:-}\" ]]; then\n echo \"unknown\"\n return\n fi\n if [[ \"$current\" == \"$latest\" ]]; then\n echo \"same\"\n elif [[ \"$c1\" != \"$l1\" ]]; then\n echo \"major\"\n elif [[ \"${c2:-0}\" != \"${l2:-0}\" ]]; then\n echo \"minor\"\n else\n echo \"patch\"\n fi\n}\n\ncollect_metadata_files() {\n local files=()\n shopt -s nullglob\n for f in lib/vendor-manifest/*.toml; do\n files+=(\"$f\")\n done\n\n # Backward compatibility while migrating from libs/vendor.\n if [[ ${#files[@]} -eq 0 ]]; then\n for f in lib/vendor/*/UPSTREAM.toml libs/vendor/*/UPSTREAM.toml; do\n files+=(\"$f\")\n done\n fi\n shopt -u nullglob\n\n printf '%s\\n' \"${files[@]}\"\n}\n\nrows=()\nwhile IFS= read -r meta_file; do\n [[ -f \"$meta_file\" ]] || continue\n\n crate=\"$(read_field \"$meta_file\" \"crate\")\"\n current=\"$(read_field \"$meta_file\" \"version\")\"\n [[ -n \"$crate\" && -n \"$current\" ]] || continue\n\n if [[ \"$important_only\" == true ]] && ! is_important \"$crate\"; then\n continue\n fi\n\n latest=\"$(\n curl -fsSL \"https://crates.io/api/v1/crates/${crate}\" \\\n | jq -r '.crate.max_stable_version // .crate.newest_version'\n )\"\n level=\"$(classify_update_level \"$current\" \"$latest\")\"\n\n status=\"up-to-date\"\n if [[ \"$latest\" != \"$current\" ]]; then\n status=\"update-available\"\n fi\n rows+=(\"${crate}|${current}|${latest}|${level}|${status}\")\ndone < <(collect_metadata_files)\n\nif [[ ${#rows[@]} -gt 0 ]]; then\n IFS=$'\\n' sorted=($(printf '%s\\n' \"${rows[@]}\" | sort))\n unset IFS\nelse\n sorted=()\nfi\n\nif [[ \"$json_output\" == true ]]; then\n if [[ ${#sorted[@]} -eq 0 ]]; then\n echo \"[]\"\n exit 0\n fi\n for row in \"${sorted[@]}\"; do\n IFS='|' read -r crate current latest level status <<<\"$row\"\n printf '{\"crate\":\"%s\",\"current\":\"%s\",\"latest\":\"%s\",\"level\":\"%s\",\"status\":\"%s\"}\\n' \\\n \"$crate\" \"$current\" \"$latest\" \"$level\" \"$status\"\n done | jq -s '.'\nelse\n echo \"crate current latest level status\"\n for row in \"${sorted[@]}\"; do\n IFS='|' read -r crate current latest level status <<<\"$row\"\n printf \"%s %s %s %s %s\\n\" \"$crate\" \"$current\" \"$latest\" \"$level\" \"$status\"\n done\nfi\n" }, { "path": "scripts/vendor/important-crates.txt", "content": "reqwest\naxum\ntower-http\nratatui\nurl\ncrypto_secretbox\nportable-pty\ntokio-stream\ntracing-subscriber\nfutures\nsha1\nsha2\ntokio\ncrossterm\nhmac\ntoml\nclap\nnotify-debouncer-mini\nignore\nx25519-dalek\nrusqlite\nrmp-serde\nctrlc\nnotify\nregex\nserde\n" }, { "path": "scripts/vendor/inhouse-crate.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n cat <<'USAGE'\nUsage:\n scripts/vendor/inhouse-crate.sh <crate> [version]\n\nExamples:\n scripts/vendor/inhouse-crate.sh reqwest\n scripts/vendor/inhouse-crate.sh reqwest 0.12.24\n\nBehavior:\n - Pulls crate source from local Cargo registry cache.\n - Commits snapshot into per-crate git history at lib/vendor-history/<crate>.git.\n - Materializes working copy into lib/vendor/<crate> for Cargo path patches.\n - Writes lib/vendor-manifest/<crate>.toml metadata for sync tracking.\nUSAGE\n}\n\nif [[ \"${1:-}\" == \"-h\" || \"${1:-}\" == \"--help\" ]]; then\n usage\n exit 0\nfi\n\nif [[ $# -lt 1 || $# -gt 2 ]]; then\n usage\n exit 1\nfi\n\ncrate=\"$1\"\nversion=\"${2:-}\"\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\nvendor_root=\"lib/vendor\"\nhistory_root=\"lib/vendor-history\"\nmanifest_root=\"lib/vendor-manifest\"\nregistry_index=\"https://github.com/rust-lang/crates.io-index\"\n\nfind_cached_src_dir() {\n find \"$HOME/.cargo/registry/src\" -maxdepth 2 -type d -name \"${crate}-${version}\" 2>/dev/null \\\n | head -n 1\n}\n\nfind_cached_crate_file() {\n find \"$HOME/.cargo/registry/cache\" -maxdepth 2 -type f -name \"${crate}-${version}.crate\" 2>/dev/null \\\n | head -n 1\n}\n\nfetch_into_cache() {\n local fetch_tmp\n fetch_tmp=\"$(mktemp -d)\"\n cat > \"${fetch_tmp}/Cargo.toml\" <<EOF\n[package]\nname = \"vendor-fetch-${crate}\"\nversion = \"0.0.0\"\nedition = \"2021\"\n\n[dependencies]\n${crate} = \"= ${version}\"\nEOF\n mkdir -p \"${fetch_tmp}/src\"\n printf '%s\\n' 'fn main() {}' > \"${fetch_tmp}/src/main.rs\"\n\n cargo fetch --manifest-path \"${fetch_tmp}/Cargo.toml\" >/dev/null 2>&1 || true\n rm -rf \"$fetch_tmp\"\n}\n\nresolve_version_from_lock() {\n awk -v crate=\"$crate\" '\n BEGIN { name = \"\"; version = \"\"; source = \"\" }\n $0 == \"[[package]]\" {\n if (name == crate && source ~ /^registry\\+/) {\n registry_versions[version] = 1\n }\n if (name == crate && version != \"\") {\n any_versions[version] = 1\n }\n name = \"\"\n version = \"\"\n source = \"\"\n next\n }\n /^name = \"/ {\n name = $3\n gsub(/\"/, \"\", name)\n next\n }\n /^version = \"/ {\n version = $3\n gsub(/\"/, \"\", version)\n next\n }\n /^source = \"/ {\n source = $3\n gsub(/\"/, \"\", source)\n next\n }\n END {\n if (name == crate && source ~ /^registry\\+/) {\n registry_versions[version] = 1\n }\n if (name == crate && version != \"\") {\n any_versions[version] = 1\n }\n for (v in registry_versions) print v\n if (length(registry_versions) == 0) {\n for (v in any_versions) print v\n }\n }\n ' Cargo.lock | sort -V | tail -n 1\n}\n\nresolve_checksum_from_lock() {\n awk -v crate=\"$crate\" -v version=\"$version\" '\n BEGIN { name = \"\"; ver = \"\"; checksum = \"\"; found = 0 }\n $0 == \"[[package]]\" {\n if (name == crate && ver == version && checksum != \"\") {\n print checksum\n found = 1\n exit 0\n }\n name = \"\"\n ver = \"\"\n checksum = \"\"\n next\n }\n /^name = \"/ {\n name = $3\n gsub(/\"/, \"\", name)\n next\n }\n /^version = \"/ {\n ver = $3\n gsub(/\"/, \"\", ver)\n next\n }\n /^checksum = \"/ {\n checksum = $3\n gsub(/\"/, \"\", checksum)\n next\n }\n END {\n if (found == 0 && name == crate && ver == version && checksum != \"\") {\n print checksum\n }\n }\n ' Cargo.lock\n}\n\nresolve_checksum_from_crates_io() {\n if ! command -v curl >/dev/null 2>&1 || ! command -v jq >/dev/null 2>&1; then\n return 0\n fi\n curl -fsSL \"https://crates.io/api/v1/crates/${crate}/${version}\" 2>/dev/null \\\n | jq -r '.version.checksum // empty' 2>/dev/null \\\n || true\n}\n\nextract_toml_string() {\n local file=\"$1\"\n local key=\"$2\"\n awk -F'\"' -v key=\"$key\" '$1 ~ \"^\" key \" = \" { print $2; exit }' \"$file\"\n}\n\nsha256_file() {\n local file=\"$1\"\n if command -v shasum >/dev/null 2>&1; then\n shasum -a 256 \"$file\" | awk '{print $1}'\n elif command -v sha256sum >/dev/null 2>&1; then\n sha256sum \"$file\" | awk '{print $1}'\n else\n echo \"\"\n fi\n}\n\nif [[ -z \"$version\" ]]; then\n version=\"$(resolve_version_from_lock)\"\nfi\n\nif [[ -z \"$version\" ]]; then\n echo \"error: could not resolve registry version for crate '$crate'\"\n echo \"hint: pass an explicit version: scripts/vendor/inhouse-crate.sh $crate <version>\"\n exit 1\nfi\n\nsrc_dir=\"$(find_cached_src_dir || true)\"\n\nif [[ -z \"$src_dir\" ]]; then\n fetch_into_cache\n src_dir=\"$(find_cached_src_dir || true)\"\n if [[ -z \"$src_dir\" ]]; then\n echo \"error: could not find ${crate}-${version} in cargo cache after auto-fetch\"\n echo \"hint: check network/cargo registry config, then retry\"\n exit 1\n fi\nfi\n\ncrate_archive_file=\"$(find_cached_crate_file || true)\"\n\nmkdir -p \"$history_root\" \"$vendor_root\" \"$manifest_root\"\n\nhistory_repo_rel=\"${history_root}/${crate}.git\"\nhistory_repo_abs=\"${repo_root}/${history_repo_rel}\"\nif [[ ! -d \"$history_repo_abs\" ]]; then\n git init --bare \"$history_repo_abs\" >/dev/null\nfi\n\ntmp_dir=\"$(mktemp -d)\"\ncleanup() {\n rm -rf \"$tmp_dir\"\n}\ntrap cleanup EXIT\n\ncheckout_dir=\"${tmp_dir}/${crate}\"\ngit init \"$checkout_dir\" >/dev/null\n\ngit -C \"$checkout_dir\" remote add origin \"$history_repo_abs\"\nif git -C \"$checkout_dir\" ls-remote --exit-code --heads origin main >/dev/null 2>&1; then\n git -C \"$checkout_dir\" fetch -q origin main\n git -C \"$checkout_dir\" checkout -q -B main FETCH_HEAD\nelse\n git -C \"$checkout_dir\" checkout -q -B main\nfi\n\n# Keep script usable on fresh machines without requiring global git identity.\nif ! git -C \"$checkout_dir\" config user.email >/dev/null; then\n git -C \"$checkout_dir\" config user.email \"vendor-bot@localhost\"\nfi\nif ! git -C \"$checkout_dir\" config user.name >/dev/null; then\n git -C \"$checkout_dir\" config user.name \"vendor-bot\"\nfi\n\nfind \"$checkout_dir\" -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +\n\nrsync -a \\\n --delete \\\n --exclude '.git' \\\n --exclude '.cargo-ok' \\\n --exclude '.cargo_vcs_info.json' \\\n --exclude 'target' \\\n \"$src_dir\"/ \"$checkout_dir\"/\n\nsynced_at_utc=\"$(date -u +\"%Y-%m-%dT%H:%M:%SZ\")\"\ngit -C \"$checkout_dir\" add -A\n\nif git -C \"$checkout_dir\" diff --cached --quiet; then\n commit_state=\"no-op\"\nelse\n git -C \"$checkout_dir\" -c commit.gpgSign=false commit -m \"sync(${crate}): crates.io ${version}\" >/dev/null\n commit_state=\"committed\"\nfi\n\ngit -C \"$checkout_dir\" push -q -u origin main\n\ngit -C \"$checkout_dir\" -c tag.gpgSign=false tag -f -a \"v${version}\" -m \"sync(${crate}): crates.io ${version}\" >/dev/null\ngit -C \"$checkout_dir\" push -q -f origin \"refs/tags/v${version}\"\n\nhistory_head=\"$(git -C \"$checkout_dir\" rev-parse HEAD)\"\n\nupstream_repository=\"$(extract_toml_string \"$src_dir/Cargo.toml\" \"repository\")\"\nupstream_homepage=\"$(extract_toml_string \"$src_dir/Cargo.toml\" \"homepage\")\"\nregistry_checksum=\"$(resolve_checksum_from_lock)\"\nif [[ -z \"$registry_checksum\" ]]; then\n registry_checksum=\"$(resolve_checksum_from_crates_io)\"\nfi\nregistry_checksum=\"$(printf '%s' \"$registry_checksum\" | head -n 1 | tr -d '\\r\\n')\"\narchive_sha256=\"\"\nif [[ -n \"$crate_archive_file\" ]]; then\n archive_sha256=\"$(sha256_file \"$crate_archive_file\")\"\nfi\narchive_sha256=\"$(printf '%s' \"$archive_sha256\" | tr -d '\\r\\n')\"\nchecksum_match=\"unknown\"\nif [[ -n \"$registry_checksum\" && -n \"$archive_sha256\" ]]; then\n if [[ \"$registry_checksum\" == \"$archive_sha256\" ]]; then\n checksum_match=\"yes\"\n else\n checksum_match=\"no\"\n fi\nfi\n\ndest_dir_rel=\"${vendor_root}/${crate}\"\ndest_dir_abs=\"${repo_root}/${dest_dir_rel}\"\nrm -rf \"$dest_dir_abs\"\nmkdir -p \"$dest_dir_abs\"\nrsync -a \\\n --delete \\\n --exclude '.git' \\\n \"$checkout_dir\"/ \"$dest_dir_abs\"/\n\nmanifest_file=\"${manifest_root}/${crate}.toml\"\ncat > \"$manifest_file\" <<MANIFEST\ncrate = \"${crate}\"\nversion = \"${version}\"\nsource = \"crates.io\"\nregistry_index = \"${registry_index}\"\ncargo_registry_checksum = \"${registry_checksum}\"\ncrate_archive_sha256 = \"${archive_sha256}\"\nchecksum_match = \"${checksum_match}\"\nupstream_repository = \"${upstream_repository}\"\nupstream_homepage = \"${upstream_homepage}\"\nsynced_at_utc = \"${synced_at_utc}\"\nhistory_repo = \"${history_repo_rel}\"\nhistory_head = \"${history_head}\"\nmaterialized_path = \"${dest_dir_rel}\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh ${crate} ${version}\"\nMANIFEST\n\n# Compatibility metadata in materialized copy for quick local inspection.\ncat > \"${dest_dir_abs}/UPSTREAM.toml\" <<UPSTREAM\ncrate = \"${crate}\"\nversion = \"${version}\"\nsource = \"crates.io\"\nregistry_index = \"${registry_index}\"\ncargo_registry_checksum = \"${registry_checksum}\"\ncrate_archive_sha256 = \"${archive_sha256}\"\nchecksum_match = \"${checksum_match}\"\nupstream_repository = \"${upstream_repository}\"\nupstream_homepage = \"${upstream_homepage}\"\nsynced_at_utc = \"${synced_at_utc}\"\nhistory_repo = \"${history_repo_rel}\"\nhistory_head = \"${history_head}\"\nsync_cmd = \"scripts/vendor/inhouse-crate.sh ${crate} ${version}\"\nUPSTREAM\n\necho \"inhouse ${crate}@${version} -> ${dest_dir_rel} (history: ${history_repo_rel}, ${commit_state})\"\n" }, { "path": "scripts/vendor/materialize-all.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\nusage() {\n cat <<'USAGE'\nUsage:\n scripts/vendor/materialize-all.sh [--important] [--from-cache]\n\nOptions:\n --important Materialize only crates listed in scripts/vendor/important-crates.txt\n --from-cache Ignore vendor.lock.toml and materialize from local crate cache metadata\nUSAGE\n}\n\nimportant_only=false\nfrom_cache=false\nfor arg in \"$@\"; do\n case \"$arg\" in\n --important) important_only=true ;;\n --from-cache) from_cache=true ;;\n -h|--help) usage; exit 0 ;;\n *) usage; exit 1 ;;\n esac\ndone\n\nif [[ \"$from_cache\" == false && -f vendor.lock.toml ]]; then\n scripts/vendor/vendor-repo.sh hydrate\n exit 0\nfi\n\nimportant_file=\"scripts/vendor/important-crates.txt\"\nis_important() {\n local crate=\"$1\"\n [[ -f \"$important_file\" ]] || return 1\n rg -n \"^${crate}$\" \"$important_file\" >/dev/null 2>&1\n}\n\nread_field() {\n local file=\"$1\"\n local key=\"$2\"\n awk -F'\"' -v key=\"$key\" '$1 ~ \"^\" key \" = \" { print $2; exit }' \"$file\"\n}\n\nshopt -s nullglob\nmanifest_files=(lib/vendor-manifest/*.toml)\nshopt -u nullglob\n\nif [[ ${#manifest_files[@]} -eq 0 ]]; then\n echo \"no manifests found in lib/vendor-manifest\"\n exit 0\nfi\n\nfor manifest in \"${manifest_files[@]}\"; do\n crate=\"$(read_field \"$manifest\" \"crate\")\"\n version=\"$(read_field \"$manifest\" \"version\")\"\n [[ -n \"$crate\" && -n \"$version\" ]] || continue\n\n if [[ \"$important_only\" == true ]] && ! is_important \"$crate\"; then\n continue\n fi\n\n scripts/vendor/inhouse-crate.sh \"$crate\" \"$version\"\n scripts/vendor/apply-trims.sh \"$crate\"\n echo \"materialized ${crate}@${version}\"\ndone\n" }, { "path": "scripts/vendor/offenders.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\nif ! command -v jq >/dev/null 2>&1; then\n echo \"error: jq is required\"\n exit 1\nfi\n\ntmp_meta=\"$(mktemp)\"\ntrap 'rm -f \"$tmp_meta\"' EXIT\n\ncargo metadata --format-version 1 >\"$tmp_meta\"\n\necho \"== Registry Footprint ==\"\necho -n \"unique registry crates: \"\njq -r '\n [.packages[] | select(.source != null and (.source | startswith(\"registry+\"))) | .name]\n | unique\n | length\n' \"$tmp_meta\"\n\necho -n \"proc-macro crates: \"\njq -r '\n [\n .packages[]\n | select(any(.targets[]?; any(.kind[]?; . == \"proc-macro\")))\n | .name\n ]\n | unique\n | length\n' \"$tmp_meta\"\n\necho\necho \"== Direct Dependencies Ranked By Tree Size ==\"\ndeps=\"$(\n sed -n '/^\\[dependencies\\]/,/^\\[/p' Cargo.toml \\\n | rg -o '^[A-Za-z0-9_.-]+' \\\n | sort -u\n)\"\n\nwhile IFS= read -r dep; do\n [[ -z \"$dep\" ]] && continue\n if lines=\"$(cargo tree -p \"$dep\" --depth 20 2>/dev/null | wc -l | tr -d ' ')\"; then\n printf \"%5d %s\\n\" \"$lines\" \"$dep\"\n fi\ndone <<<\"$deps\" | sort -nr\n\necho\necho \"== Duplicate Versions (cargo tree -d) ==\"\ncargo tree -d\n" }, { "path": "scripts/vendor/optimize_loop.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\nusage() {\n cat <<'USAGE'\nUsage:\n scripts/vendor/optimize_loop.sh [--strict] [--no-bench] [--samples N] [--cmd \"<command>\"]\n\nExamples:\n scripts/vendor/optimize_loop.sh\n scripts/vendor/optimize_loop.sh --strict --samples 2\n scripts/vendor/optimize_loop.sh --no-bench\nUSAGE\n}\n\nstrict=false\nno_bench=false\nsamples=\"${VENDOR_BENCH_SAMPLES:-2}\"\nbench_cmd=\"${VENDOR_BENCH_CMD:-cargo check -q}\"\n\nwhile [[ $# -gt 0 ]]; do\n case \"$1\" in\n --strict) strict=true; shift ;;\n --no-bench) no_bench=true; shift ;;\n --samples) samples=\"${2:-}\"; shift 2 ;;\n --cmd) bench_cmd=\"${2:-}\"; shift 2 ;;\n -h|--help) usage; exit 0 ;;\n *)\n echo \"error: unknown arg: $1\"\n usage\n exit 1\n ;;\n esac\ndone\n\nmkdir -p out/vendor\n\necho \"== vendor rough-edge audit ==\"\nif [[ \"$strict\" == true ]]; then\n python3 scripts/vendor/rough_edges_audit.py --strict-warnings | tee out/vendor/rough_edges_audit.txt\nelse\n python3 scripts/vendor/rough_edges_audit.py | tee out/vendor/rough_edges_audit.txt\nfi\n\necho\necho \"== offender scan ==\"\nscripts/vendor/offenders.sh | tee out/vendor/offenders_latest.txt\n\nif [[ \"$no_bench\" == false ]]; then\n echo\n echo \"== iteration benchmark ==\"\n python3 scripts/vendor/bench_iteration.py --mode incremental --samples \"$samples\" --cmd \"$bench_cmd\"\nfi\n\necho\necho \"wrote:\"\necho \" out/vendor/rough_edges_audit.txt\"\necho \" out/vendor/offenders_latest.txt\"\nif [[ \"$no_bench\" == false ]]; then\n echo \" out/vendor/iteration_bench.jsonl\"\nfi\n" }, { "path": "scripts/vendor/rough_edges_audit.py", "content": "#!/usr/bin/env python3\n\"\"\"Audit rough edges in Cargo-first vendoring setup.\n\nThis script is intentionally strict about structural invariants and surfaces\nactionable warnings for optimization workflow gaps.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nfrom dataclasses import asdict, dataclass\nfrom pathlib import Path\nfrom typing import Any\n\ntry:\n import tomllib # Python 3.11+\nexcept ModuleNotFoundError as exc: # pragma: no cover\n raise SystemExit(\"python 3.11+ is required (missing tomllib)\") from exc\n\n\n@dataclass\nclass Finding:\n severity: str # error | warn | info\n code: str\n message: str\n hint: str | None = None\n\n\ndef load_toml(path: Path) -> dict[str, Any]:\n with path.open(\"rb\") as fh:\n return tomllib.load(fh)\n\n\ndef read_manifest_crate(path: Path) -> str:\n try:\n data = load_toml(path)\n except Exception:\n return path.stem\n crate = str(data.get(\"crate\", path.stem)).strip()\n return crate or path.stem\n\n\ndef list_lock_crates(vendor_lock: dict[str, Any]) -> list[dict[str, str]]:\n out: list[dict[str, str]] = []\n for row in vendor_lock.get(\"crate\", []):\n if not isinstance(row, dict):\n continue\n name = str(row.get(\"name\", \"\")).strip()\n if not name:\n continue\n out.append(\n {\n \"name\": name,\n \"manifest_path\": str(row.get(\"manifest_path\", f\"lib/vendor-manifest/{name}.toml\")).strip(),\n \"materialized_path\": str(row.get(\"materialized_path\", f\"lib/vendor/{name}\")).strip(),\n \"repo_path\": str(row.get(\"repo_path\", f\"crates/{name}\")).strip(),\n }\n )\n return out\n\n\ndef read_patch_paths(cargo_toml: dict[str, Any]) -> dict[str, str]:\n patch = cargo_toml.get(\"patch\", {})\n if not isinstance(patch, dict):\n return {}\n crates_io = patch.get(\"crates-io\", {})\n if not isinstance(crates_io, dict):\n return {}\n\n out: dict[str, str] = {}\n for name, value in crates_io.items():\n if isinstance(value, dict):\n path = value.get(\"path\")\n if isinstance(path, str):\n out[name] = path\n return out\n\n\ndef latest_mtime(paths: list[Path]) -> float:\n latest = 0.0\n for path in paths:\n if not path.exists():\n continue\n latest = max(latest, path.stat().st_mtime)\n return latest\n\n\ndef check_warning_hygiene(project: Path) -> list[Finding]:\n findings: list[Finding] = []\n\n checks: list[tuple[str, str]] = [\n (\n \"lib/vendor/crossterm/src/lib.rs\",\n 'cfg(all(winapi, not(feature = \"winapi\")))',\n ),\n (\n \"lib/vendor/crossterm/src/lib.rs\",\n 'cfg(all(crossterm_winapi, not(feature = \"crossterm_winapi\")))',\n ),\n (\n \"lib/vendor/crossterm/src/terminal/sys/unix.rs\",\n \"map(|file| (FileDesc::Owned(file.into())))\",\n ),\n (\n \"lib/vendor/portable-pty/src/unix.rs\",\n 'feature = \"cargo-clippy\"',\n ),\n (\n \"lib/vendor/x25519-dalek/src/lib.rs\",\n 'cfg_attr(feature = \"bench\", feature(test))',\n ),\n (\n \"lib/vendor/ratatui/src/terminal/terminal.rs\",\n \"pub fn get_frame(&mut self) -> Frame {\",\n ),\n (\n \"lib/vendor/ratatui/src/terminal/terminal.rs\",\n \"pub fn draw<F>(&mut self, render_callback: F) -> io::Result<CompletedFrame>\",\n ),\n (\n \"lib/vendor/ratatui/src/terminal/terminal.rs\",\n \"pub fn try_draw<F, E>(&mut self, render_callback: F) -> io::Result<CompletedFrame>\",\n ),\n (\n \"lib/vendor/ratatui/src/text/line.rs\",\n \"pub fn iter(&self) -> std::slice::Iter<Span<'a>> {\",\n ),\n (\n \"lib/vendor/ratatui/src/text/line.rs\",\n \"pub fn iter_mut(&mut self) -> std::slice::IterMut<Span<'a>> {\",\n ),\n (\n \"lib/vendor/ratatui/src/text/text.rs\",\n \"pub fn iter(&self) -> std::slice::Iter<Line<'a>> {\",\n ),\n (\n \"lib/vendor/ratatui/src/text/text.rs\",\n \"pub fn iter_mut(&mut self) -> std::slice::IterMut<Line<'a>> {\",\n ),\n (\n \"lib/vendor/ratatui/src/text/text.rs\",\n \"fn to_text(&self) -> Text {\",\n ),\n (\n \"lib/vendor/ratatui/src/widgets/block.rs\",\n \") -> impl DoubleEndedIterator<Item = &Line> {\",\n ),\n ]\n\n for rel_path, needle in checks:\n path = project / rel_path\n if not path.is_file():\n continue\n try:\n content = path.read_text(encoding=\"utf-8\")\n except Exception:\n continue\n if needle in content:\n findings.append(\n Finding(\n \"warn\",\n \"warning_hygiene_regression\",\n f\"{rel_path}: found stale warning pattern `{needle}`\",\n \"run scripts/vendor/apply-trims.sh (or hydrate) to re-apply warning hygiene patches\",\n )\n )\n\n return findings\n\n\ndef build_report(project: Path) -> tuple[dict[str, Any], list[Finding]]:\n findings: list[Finding] = []\n metrics: dict[str, Any] = {\n \"project\": str(project),\n \"vendored_crates\": 0,\n \"vendor_manifests\": 0,\n \"vendor_patch_entries\": 0,\n \"direct_dependencies\": 0,\n \"direct_non_vendored_dependencies\": 0,\n \"direct_non_vendored_list\": [],\n \"warning_hygiene_regressions\": 0,\n }\n\n vendor_lock_path = project / \"vendor.lock.toml\"\n cargo_toml_path = project / \"Cargo.toml\"\n cargo_lock_path = project / \"Cargo.lock\"\n\n if not vendor_lock_path.is_file():\n findings.append(\n Finding(\n \"error\",\n \"missing_vendor_lock\",\n f\"missing {vendor_lock_path}\",\n \"run bootstrap/inhouse flow to create vendor.lock.toml\",\n )\n )\n return metrics, findings\n\n if not cargo_toml_path.is_file():\n findings.append(\n Finding(\n \"error\",\n \"missing_cargo_toml\",\n f\"missing {cargo_toml_path}\",\n )\n )\n return metrics, findings\n\n if not cargo_lock_path.is_file():\n findings.append(\n Finding(\n \"error\",\n \"missing_cargo_lock\",\n f\"missing {cargo_lock_path}\",\n \"run cargo check to generate Cargo.lock\",\n )\n )\n return metrics, findings\n\n vendor_lock = load_toml(vendor_lock_path)\n cargo_toml = load_toml(cargo_toml_path)\n cargo_lock = load_toml(cargo_lock_path)\n\n lock_section = \"vendor\" if \"vendor\" in vendor_lock else \"flow_vendor\" if \"flow_vendor\" in vendor_lock else None\n if lock_section is None:\n findings.append(\n Finding(\n \"error\",\n \"missing_vendor_section\",\n \"vendor.lock.toml has no [vendor] or [flow_vendor] section\",\n )\n )\n else:\n missing_keys = [\n key\n for key in (\"repo\", \"branch\", \"checkout\")\n if not str(vendor_lock.get(lock_section, {}).get(key, \"\")).strip()\n ]\n if missing_keys:\n findings.append(\n Finding(\n \"error\",\n \"vendor_section_incomplete\",\n f\"{lock_section} missing keys: {', '.join(missing_keys)}\",\n )\n )\n\n lock_crates = list_lock_crates(vendor_lock)\n lock_crate_names = {row[\"name\"] for row in lock_crates}\n metrics[\"vendored_crates\"] = len(lock_crates)\n\n patch_paths = read_patch_paths(cargo_toml)\n vendor_patch_paths = {name: path for name, path in patch_paths.items() if path.startswith(\"lib/vendor/\")}\n metrics[\"vendor_patch_entries\"] = len(vendor_patch_paths)\n\n manifest_dir = project / \"lib/vendor-manifest\"\n manifest_files = sorted(manifest_dir.glob(\"*.toml\")) if manifest_dir.is_dir() else []\n manifest_crates = {read_manifest_crate(path) for path in manifest_files}\n metrics[\"vendor_manifests\"] = len(manifest_files)\n\n package_rows = cargo_lock.get(\"package\", [])\n packages_by_name: dict[str, list[dict[str, Any]]] = {}\n if isinstance(package_rows, list):\n for row in package_rows:\n if not isinstance(row, dict):\n continue\n name = str(row.get(\"name\", \"\")).strip()\n if not name:\n continue\n packages_by_name.setdefault(name, []).append(row)\n\n dep_table = cargo_toml.get(\"dependencies\", {})\n if isinstance(dep_table, dict):\n direct_deps = sorted(dep_table.keys())\n else:\n direct_deps = []\n metrics[\"direct_dependencies\"] = len(direct_deps)\n non_vendored = sorted(dep for dep in direct_deps if dep not in lock_crate_names)\n metrics[\"direct_non_vendored_dependencies\"] = len(non_vendored)\n metrics[\"direct_non_vendored_list\"] = non_vendored\n\n seen_lock = set()\n for row in lock_crates:\n crate = row[\"name\"]\n seen_lock.add(crate)\n\n materialized = project / row[\"materialized_path\"]\n if not (materialized / \"Cargo.toml\").is_file():\n findings.append(\n Finding(\n \"error\",\n \"missing_materialized_crate\",\n f\"{crate}: missing {materialized}/Cargo.toml\",\n \"run scripts/vendor/vendor-repo.sh hydrate\",\n )\n )\n\n # `manifest_path` in vendor.lock.toml points to the vendor-repo path\n # (`manifests/<crate>.toml`), while the local materialized manifest\n # lives in `lib/vendor-manifest/<crate>.toml`.\n expected_repo_manifest = f\"manifests/{crate}.toml\"\n if row[\"manifest_path\"] and row[\"manifest_path\"] != expected_repo_manifest:\n findings.append(\n Finding(\n \"warn\",\n \"manifest_repo_path_unexpected\",\n f\"{crate}: manifest_path={row['manifest_path']} (expected {expected_repo_manifest})\",\n )\n )\n\n manifest_path = project / \"lib/vendor-manifest\" / f\"{crate}.toml\"\n if not manifest_path.is_file():\n findings.append(\n Finding(\n \"error\",\n \"missing_vendor_manifest\",\n f\"{crate}: missing local manifest {manifest_path}\",\n \"re-run inhouse/sync for this crate\",\n )\n )\n else:\n try:\n crate_manifest = load_toml(manifest_path)\n except Exception as exc:\n findings.append(\n Finding(\n \"error\",\n \"broken_vendor_manifest\",\n f\"{crate}: failed to parse {manifest_path}: {exc}\",\n )\n )\n crate_manifest = {}\n\n manifest_crate = str(crate_manifest.get(\"crate\", crate)).strip()\n manifest_version = str(crate_manifest.get(\"version\", \"\")).strip()\n manifest_materialized = str(crate_manifest.get(\"materialized_path\", row[\"materialized_path\"])).strip()\n\n if manifest_crate and manifest_crate != crate:\n findings.append(\n Finding(\n \"error\",\n \"manifest_crate_mismatch\",\n f\"{crate}: manifest crate={manifest_crate}\",\n )\n )\n\n if manifest_materialized and manifest_materialized != row[\"materialized_path\"]:\n findings.append(\n Finding(\n \"error\",\n \"manifest_materialized_path_mismatch\",\n f\"{crate}: manifest materialized_path={manifest_materialized}, lock={row['materialized_path']}\",\n )\n )\n\n if not str(crate_manifest.get(\"history_head\", \"\")).strip():\n findings.append(\n Finding(\n \"warn\",\n \"missing_history_head\",\n f\"{crate}: missing history_head in {manifest_path}\",\n )\n )\n if not str(crate_manifest.get(\"upstream_repository\", \"\")).strip():\n findings.append(\n Finding(\n \"warn\",\n \"missing_upstream_repository\",\n f\"{crate}: missing upstream_repository in {manifest_path}\",\n )\n )\n\n pkg_rows = packages_by_name.get(crate, [])\n versions = sorted({str(p.get(\"version\", \"\")).strip() for p in pkg_rows if str(p.get(\"version\", \"\")).strip()})\n if manifest_version and versions and len(versions) == 1 and manifest_version != versions[0]:\n findings.append(\n Finding(\n \"error\",\n \"manifest_version_mismatch\",\n f\"{crate}: manifest version={manifest_version}, Cargo.lock version={versions[0]}\",\n )\n )\n\n patch_path = vendor_patch_paths.get(crate, \"\")\n if not patch_path:\n findings.append(\n Finding(\n \"error\",\n \"missing_patch_entry\",\n f\"{crate}: missing [patch.crates-io] path override\",\n \"add crate path override in Cargo.toml\",\n )\n )\n elif patch_path != row[\"materialized_path\"]:\n findings.append(\n Finding(\n \"error\",\n \"patch_path_mismatch\",\n f\"{crate}: patch path={patch_path}, lock materialized_path={row['materialized_path']}\",\n )\n )\n\n pkg_rows = packages_by_name.get(crate, [])\n if not pkg_rows:\n findings.append(\n Finding(\n \"error\",\n \"missing_cargo_lock_entry\",\n f\"{crate}: not present in Cargo.lock\",\n )\n )\n else:\n sources = [str(p.get(\"source\", \"\")).strip() for p in pkg_rows]\n if any(src.startswith(\"registry+\") for src in sources):\n findings.append(\n Finding(\n \"error\",\n \"registry_source_for_vendored_crate\",\n f\"{crate}: still resolves via registry source in Cargo.lock\",\n \"run cargo update -p <crate> --precise <version> after patching\",\n )\n )\n versions = sorted({str(p.get(\"version\", \"\")).strip() for p in pkg_rows if str(p.get(\"version\", \"\")).strip()})\n if len(versions) > 1:\n findings.append(\n Finding(\n \"error\",\n \"multiple_lock_versions_for_vendored_crate\",\n f\"{crate}: multiple versions in Cargo.lock ({', '.join(versions)})\",\n )\n )\n\n for crate in sorted(manifest_crates - lock_crate_names):\n findings.append(\n Finding(\n \"warn\",\n \"manifest_not_in_lock\",\n f\"{crate}: manifest exists but crate not in vendor.lock.toml\",\n )\n )\n\n for crate, path in sorted(vendor_patch_paths.items()):\n if crate not in lock_crate_names:\n findings.append(\n Finding(\n \"warn\",\n \"patch_not_in_lock\",\n f\"{crate}: patched to {path} but not listed in vendor.lock.toml\",\n )\n )\n\n vendor_src_dir = project / \"lib/vendor\"\n if vendor_src_dir.is_dir():\n vendored_dirs = {p.name for p in vendor_src_dir.iterdir() if p.is_dir()}\n for extra in sorted(vendored_dirs - lock_crate_names):\n findings.append(\n Finding(\n \"warn\",\n \"vendored_dir_not_in_lock\",\n f\"lib/vendor/{extra} exists but crate is not in vendor.lock.toml\",\n )\n )\n\n typesense_index = project / \".vendor/typesense/sources.json\"\n if typesense_index.exists():\n watched = [vendor_lock_path, cargo_lock_path, project / \"scripts/vendor/typesense_code_index.py\"]\n watched.extend(manifest_files)\n if typesense_index.stat().st_mtime < latest_mtime(watched):\n findings.append(\n Finding(\n \"warn\",\n \"stale_code_index\",\n \"typesense sources index is older than vendoring inputs\",\n \"run f vendor-code-index\",\n )\n )\n else:\n findings.append(\n Finding(\n \"info\",\n \"missing_code_index\",\n \"no .vendor/typesense/sources.json found\",\n \"run f vendor-code-index if you use vendor code search\",\n )\n )\n\n warning_hygiene_findings = check_warning_hygiene(project)\n metrics[\"warning_hygiene_regressions\"] = len(warning_hygiene_findings)\n findings.extend(warning_hygiene_findings)\n\n return metrics, findings\n\n\ndef print_text(metrics: dict[str, Any], findings: list[Finding]) -> None:\n print(f\"project: {metrics['project']}\")\n print(f\"vendored crates: {metrics['vendored_crates']}\")\n print(f\"vendor manifests: {metrics['vendor_manifests']}\")\n print(f\"vendor patch entries: {metrics['vendor_patch_entries']}\")\n print(f\"direct deps: {metrics['direct_dependencies']}\")\n print(f\"direct deps not yet vendored: {metrics['direct_non_vendored_dependencies']}\")\n print(f\"warning hygiene regressions: {metrics['warning_hygiene_regressions']}\")\n if metrics[\"direct_non_vendored_list\"]:\n preview = \", \".join(metrics[\"direct_non_vendored_list\"][:12])\n suffix = \" ...\" if len(metrics[\"direct_non_vendored_list\"]) > 12 else \"\"\n print(f\"non-vendored preview: {preview}{suffix}\")\n print()\n\n if not findings:\n print(\"no findings\")\n return\n\n for item in findings:\n print(f\"[{item.severity}] {item.code}: {item.message}\")\n if item.hint:\n print(f\" hint: {item.hint}\")\n\n\ndef main() -> None:\n parser = argparse.ArgumentParser(description=\"Audit rough edges in vendored dependency workflow\")\n parser.add_argument(\"--project\", default=\".\", help=\"Project root (default: .)\")\n parser.add_argument(\"--json\", action=\"store_true\", help=\"Emit report as JSON\")\n parser.add_argument(\n \"--strict-warnings\",\n action=\"store_true\",\n help=\"Exit non-zero on warnings (default only errors fail)\",\n )\n args = parser.parse_args()\n\n project = Path(args.project).expanduser().resolve()\n metrics, findings = build_report(project)\n errors = sum(1 for f in findings if f.severity == \"error\")\n warnings = sum(1 for f in findings if f.severity == \"warn\")\n\n payload = {\n \"metrics\": metrics,\n \"counts\": {\"errors\": errors, \"warnings\": warnings, \"total\": len(findings)},\n \"findings\": [asdict(item) for item in findings],\n }\n\n if args.json:\n print(json.dumps(payload, indent=2))\n else:\n print_text(metrics, findings)\n print()\n print(f\"errors: {errors}\")\n print(f\"warnings: {warnings}\")\n\n if errors > 0 or (args.strict_warnings and warnings > 0):\n raise SystemExit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "scripts/vendor/sync-all.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\nusage() {\n cat <<'EOF'\nUsage:\n scripts/vendor/sync-all.sh [--important] [--dry-run] [--allow-minor] [--allow-major] [--no-vendor-import]\nEOF\n}\n\nimportant_only=false\ndry_run=false\nallow_minor=false\nallow_major=false\nimport_vendor_repo=true\nfor arg in \"$@\"; do\n case \"$arg\" in\n --important) important_only=true ;;\n --dry-run) dry_run=true ;;\n --allow-minor) allow_minor=true ;;\n --allow-major) allow_major=true ;;\n --no-vendor-import) import_vendor_repo=false ;;\n -h|--help) usage; exit 0 ;;\n *) usage; exit 1 ;;\n esac\ndone\n\nimportant_file=\"scripts/vendor/important-crates.txt\"\nis_important() {\n local crate=\"$1\"\n [[ -f \"$important_file\" ]] || return 1\n rg -n \"^${crate}$\" \"$important_file\" >/dev/null 2>&1\n}\n\nsynced_any=false\nwhile read -r crate current latest level status; do\n [[ \"$status\" == \"update-available\" ]] || continue\n if [[ \"$important_only\" == true ]] && ! is_important \"$crate\"; then\n continue\n fi\n\n case \"$level\" in\n patch) ;;\n minor)\n [[ \"$allow_minor\" == true || \"$allow_major\" == true ]] || {\n echo \"skip ${crate} ${current} -> ${latest} (minor; pass --allow-minor)\"\n continue\n }\n ;;\n major)\n [[ \"$allow_major\" == true ]] || {\n echo \"skip ${crate} ${current} -> ${latest} (major; pass --allow-major)\"\n continue\n }\n ;;\n *)\n echo \"skip ${crate} ${current} -> ${latest} (unknown level)\"\n continue\n ;;\n esac\n\n if [[ \"$dry_run\" == true ]]; then\n echo \"would sync ${crate} ${current} -> ${latest}\"\n else\n scripts/vendor/sync-crate.sh \"$crate\" \"$latest\" --no-vendor-import\n synced_any=true\n fi\ndone < <(scripts/vendor/check-upstream.sh)\n\nif [[ \"$dry_run\" == false && \"$synced_any\" == true && \"$import_vendor_repo\" == true && -f vendor.lock.toml ]]; then\n scripts/vendor/vendor-repo.sh import-local\nfi\n" }, { "path": "scripts/vendor/sync-crate.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\nif ! command -v jq >/dev/null 2>&1; then\n echo \"error: jq is required\"\n exit 1\nfi\n\nusage() {\n cat <<'EOF'\nUsage:\n scripts/vendor/sync-crate.sh <crate> [version] [--no-vendor-import]\n\nExamples:\n scripts/vendor/sync-crate.sh reqwest\n scripts/vendor/sync-crate.sh reqwest 0.12.24\nEOF\n}\n\nif [[ \"${1:-}\" == \"-h\" || \"${1:-}\" == \"--help\" ]]; then\n usage\n exit 0\nfi\n\nimport_vendor_repo=true\nargs=()\nfor arg in \"$@\"; do\n case \"$arg\" in\n --no-vendor-import) import_vendor_repo=false ;;\n *) args+=(\"$arg\") ;;\n esac\ndone\n\nif [[ ${#args[@]} -lt 1 || ${#args[@]} -gt 2 ]]; then\n usage\n exit 1\nfi\n\ncrate=\"${args[0]}\"\nversion=\"${args[1]:-}\"\n\nif [[ -z \"$version\" ]]; then\n version=\"$(\n curl -fsSL \"https://crates.io/api/v1/crates/${crate}\" \\\n | jq -r '.crate.max_stable_version // .crate.newest_version'\n )\"\nfi\n\nscripts/vendor/inhouse-crate.sh \"$crate\" \"$version\"\nscripts/vendor/apply-trims.sh \"$crate\"\n\nif [[ \"$import_vendor_repo\" == true && -f vendor.lock.toml ]]; then\n scripts/vendor/vendor-repo.sh import-local\nfi\n\necho \"synced ${crate}@${version} and re-applied local trims\"\n" }, { "path": "scripts/vendor/trim-hooks.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\n# Project-specific trim rules for Flow vendored crates.\n# Called by scripts/vendor/apply-trims.sh as: apply_vendor_trims \"<crate>\"\n\napply_reqwest_trims() {\n local file=\"lib/vendor/reqwest/Cargo.toml\"\n [[ -f \"$file\" ]] || return 0\n\n # Keep hyper surfaces as explicit as possible; avoid implicit default feature fan-out.\n perl -0777 -i -pe '\n s/(\\[target\\.\\x27cfg\\(not\\(target_arch = \"wasm32\"\\)\\)\\x27\\.dependencies\\.hyper\\]\\nversion = \"1\\.1\"\\nfeatures = \\[\\n \"http1\",\\n \"client\",\\n\\]\\n)(?!default-features = false\\n)/$1default-features = false\\n/s;\n s/(\\[target\\.\\x27cfg\\(not\\(target_arch = \"wasm32\"\\)\\)\\x27\\.dependencies\\.hyper-util\\]\\nversion = \"0\\.1\\.12\"\\nfeatures = \\[\\n \"http1\",\\n \"client\",\\n \"client-legacy\",\\n \"client-proxy\",\\n \"tokio\",\\n\\]\\n)(?!default-features = false\\n)/$1default-features = false\\n/s;\n ' \"$file\"\n}\n\napply_axum_trims() {\n local file=\"lib/vendor/axum/Cargo.toml\"\n [[ -f \"$file\" ]] || return 0\n\n perl -0777 -i -pe '\n s/(\\[dependencies\\.hyper\\]\\nversion = \"1\\.1\\.0\"\\noptional = true\\n)(?!default-features = false\\n)/$1default-features = false\\n/s;\n s/(\\[dependencies\\.hyper-util\\]\\nversion = \"0\\.1\\.3\"\\nfeatures = \\[\\n \"tokio\",\\n \"server\",\\n \"service\",\\n\\]\\noptional = true\\n)(?!default-features = false\\n)/$1default-features = false\\n/s;\n ' \"$file\"\n}\n\napply_ratatui_trims() {\n local root=\"lib/vendor/ratatui\"\n [[ -d \"$root\" ]] || return 0\n\n rm -rf \\\n \"$root/benches\" \\\n \"$root/examples\" \\\n \"$root/tests\"\n\n rm -f \\\n \"$root/Cargo.lock\" \\\n \"$root/.cz.toml\" \\\n \"$root/.editorconfig\" \\\n \"$root/.gitignore\" \\\n \"$root/.markdownlint.yaml\" \\\n \"$root/bacon.toml\" \\\n \"$root/cliff.toml\" \\\n \"$root/clippy.toml\" \\\n \"$root/codecov.yml\" \\\n \"$root/committed.toml\" \\\n \"$root/deny.toml\" \\\n \"$root/FUNDING.json\" \\\n \"$root/MAINTAINERS.md\" \\\n \"$root/RELEASE.md\" \\\n \"$root/SECURITY.md\" \\\n \"$root/BREAKING-CHANGES.md\"\n\n # Rust 1.90+ warns on elided lifetime name mismatches in these signatures.\n local terminal_file=\"$root/src/terminal/terminal.rs\"\n local text_line_file=\"$root/src/text/line.rs\"\n local text_text_file=\"$root/src/text/text.rs\"\n local widgets_block_file=\"$root/src/widgets/block.rs\"\n\n if [[ -f \"$terminal_file\" ]]; then\n perl -0777 -i -pe '\n s/pub fn get_frame\\(&mut self\\) -> Frame \\{/pub fn get_frame(&mut self) -> Frame<'\\''_> {/g;\n s/pub fn draw<F>\\(&mut self, render_callback: F\\) -> io::Result<CompletedFrame>/pub fn draw<F>(&mut self, render_callback: F) -> io::Result<CompletedFrame<'\\''_>>/g;\n s/pub fn try_draw<F, E>\\(&mut self, render_callback: F\\) -> io::Result<CompletedFrame>/pub fn try_draw<F, E>(&mut self, render_callback: F) -> io::Result<CompletedFrame<'\\''_>>/g;\n ' \"$terminal_file\"\n fi\n\n if [[ -f \"$text_line_file\" ]]; then\n perl -0777 -i -pe '\n s/pub fn iter\\(&self\\) -> std::slice::Iter<Span<'\\''a>>/pub fn iter(&self) -> std::slice::Iter<'\\''_, Span<'\\''a>>/g;\n s/pub fn iter_mut\\(&mut self\\) -> std::slice::IterMut<Span<'\\''a>>/pub fn iter_mut(&mut self) -> std::slice::IterMut<'\\''_, Span<'\\''a>>/g;\n ' \"$text_line_file\"\n fi\n\n if [[ -f \"$text_text_file\" ]]; then\n perl -0777 -i -pe '\n s/pub fn iter\\(&self\\) -> std::slice::Iter<Line<'\\''a>>/pub fn iter(&self) -> std::slice::Iter<'\\''_, Line<'\\''a>>/g;\n s/pub fn iter_mut\\(&mut self\\) -> std::slice::IterMut<Line<'\\''a>>/pub fn iter_mut(&mut self) -> std::slice::IterMut<'\\''_, Line<'\\''a>>/g;\n s/fn to_text\\(&self\\) -> Text \\{/fn to_text(&self) -> Text<'\\''_> {/g;\n ' \"$text_text_file\"\n fi\n\n if [[ -f \"$widgets_block_file\" ]]; then\n perl -0777 -i -pe '\n s/\\) -> impl DoubleEndedIterator<Item = &Line> \\{/) -> impl DoubleEndedIterator<Item = &Line<'\\''_>> {/g;\n ' \"$widgets_block_file\"\n fi\n}\n\napply_crossterm_trims() {\n local root=\"lib/vendor/crossterm\"\n [[ -d \"$root\" ]] || return 0\n\n local lib_file=\"$root/src/lib.rs\"\n local unix_file=\"$root/src/terminal/sys/unix.rs\"\n local filter_file=\"$root/src/event/filter.rs\"\n\n if [[ -f \"$lib_file\" ]]; then\n perl -0777 -i -pe '\n s/\\n#\\[cfg\\(all\\(winapi, not\\(feature = \"winapi\"\\)\\)\\)\\]\\ncompile_error!\\(\"Compiling on Windows with \\\\\"winapi\\\\\" feature disabled\\. Feature \\\\\"winapi\\\\\" should only be disabled when project will never be compiled on Windows\\.\"\\);\\n//g;\n s/\\n#\\[cfg\\(all\\(crossterm_winapi, not\\(feature = \"crossterm_winapi\"\\)\\)\\)\\]\\ncompile_error!\\(\"Compiling on Windows with \\\\\"crossterm_winapi\\\\\" feature disabled\\. Feature \\\\\"crossterm_winapi\\\\\" should only be disabled when project will never be compiled on Windows\\.\"\\);\\n//g;\n ' \"$lib_file\"\n fi\n\n if [[ -f \"$unix_file\" ]]; then\n perl -0777 -i -pe '\n s/File::open\\(\"\\/dev\\/tty\"\\)\\.map\\(\\|file\\| \\(FileDesc::Owned\\(file\\.into\\(\\)\\)\\)\\)/File::open(\"\\/dev\\/tty\").map(|file| FileDesc::Owned(file.into()))/g;\n ' \"$unix_file\"\n fi\n\n if [[ -f \"$filter_file\" ]]; then\n perl -0777 -i -pe '\n if (!/\\#\\[allow\\(dead_code\\)\\]\\s*pub\\(crate\\) struct InternalEventFilter;/s) {\n s/\\#\\[derive\\(Debug, Clone\\)\\]\\s*pub\\(crate\\) struct InternalEventFilter;/#[derive(Debug, Clone)]\\n#[allow(dead_code)]\\npub(crate) struct InternalEventFilter;/s;\n }\n ' \"$filter_file\"\n fi\n}\n\napply_portable_pty_trims() {\n local file=\"lib/vendor/portable-pty/src/unix.rs\"\n if [[ -f \"$file\" ]]; then\n perl -0777 -i -pe '\n s/\\n[ \\t]*#\\[cfg_attr\\(feature = \"cargo-clippy\", allow\\(clippy::unnecessary_mut_passed\\)\\)\\]//g;\n s/\\n[ \\t]*#\\[cfg_attr\\(feature = \"cargo-clippy\", allow\\(clippy::cast_lossless\\)\\)\\]//g;\n ' \"$file\"\n fi\n}\n\napply_x25519_dalek_trims() {\n local file=\"lib/vendor/x25519-dalek/src/lib.rs\"\n if [[ -f \"$file\" ]]; then\n perl -0777 -i -pe '\n s/\\n#!\\[cfg_attr\\(feature = \"bench\", feature\\(test\\)\\)\\]//g;\n ' \"$file\"\n fi\n}\n\napply_vendor_trims() {\n local crate=\"${1:-}\"\n if [[ -n \"$crate\" ]]; then\n case \"$crate\" in\n reqwest) apply_reqwest_trims ;;\n axum) apply_axum_trims ;;\n ratatui) apply_ratatui_trims ;;\n crossterm) apply_crossterm_trims ;;\n portable-pty) apply_portable_pty_trims ;;\n x25519-dalek) apply_x25519_dalek_trims ;;\n *) ;;\n esac\n return\n fi\n\n apply_reqwest_trims\n apply_axum_trims\n apply_ratatui_trims\n apply_crossterm_trims\n apply_portable_pty_trims\n apply_x25519_dalek_trims\n}\n" }, { "path": "scripts/vendor/typesense_code_index.py", "content": "#!/usr/bin/env python3\n\"\"\"Index first-party + vendored code into Typesense for fast local search.\n\nInspired by opensrc's \"source inventory + local context\" workflow, but targeted at\nRust/Cargo vendoring. This script reads Flow vendoring metadata and builds:\n\n- <prefix>_sources: source inventory (vendored crates + first-party repo)\n- <prefix>_chunks: code chunks for full-text search\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport hashlib\nimport json\nimport os\nimport re\nfrom dataclasses import dataclass\nfrom pathlib import Path\nfrom typing import Iterable, NoReturn\nfrom urllib import error, parse, request\n\ntry:\n import tomllib # Python 3.11+\nexcept ModuleNotFoundError as exc: # pragma: no cover\n raise SystemExit(\"python 3.11+ is required (missing tomllib)\") from exc\n\ndef env_first(*names: str, default: str) -> str:\n for name in names:\n value = os.environ.get(name)\n if value:\n return value\n return default\n\n\nDEFAULT_TYPESENSE_URL = env_first(\"LINSA_TYPESENSE_URL\", \"TYPESENSE_URL\", default=\"http://127.0.0.1:8108\")\nDEFAULT_TYPESENSE_API_KEY = env_first(\"LINSA_TYPESENSE_API_KEY\", \"TYPESENSE_API_KEY\", default=\"ts_local_dev_key\")\nDEFAULT_PREFIX = \"flow_code\"\nDEFAULT_SOURCE_INDEX = \".vendor/typesense/sources.json\"\n\nTEXT_EXTS = {\n \".rs\",\n \".toml\",\n \".md\",\n \".txt\",\n \".yaml\",\n \".yml\",\n \".json\",\n \".sh\",\n \".py\",\n \".ts\",\n \".tsx\",\n \".js\",\n \".jsx\",\n \".go\",\n \".cpp\",\n \".cc\",\n \".c\",\n \".h\",\n \".hpp\",\n \".proto\",\n}\n\nFIRST_PARTY_DIRS = [\"src\", \"crates\", \"scripts\", \"docs\", \"tests\"]\nEXCLUDE_DIRS = {\n \".git\",\n \".jj\",\n \"target\",\n \"node_modules\",\n \".vendor\",\n \"dist\",\n \"build\",\n \".next\",\n \".venv\",\n \"out\",\n}\n\nRUST_SYMBOL_PATTERNS = [\n re.compile(r\"^\\s*(?:pub\\s+)?(?:async\\s+)?fn\\s+([A-Za-z_][A-Za-z0-9_]*)\"),\n re.compile(r\"^\\s*(?:pub\\s+)?struct\\s+([A-Za-z_][A-Za-z0-9_]*)\"),\n re.compile(r\"^\\s*(?:pub\\s+)?enum\\s+([A-Za-z_][A-Za-z0-9_]*)\"),\n re.compile(r\"^\\s*(?:pub\\s+)?trait\\s+([A-Za-z_][A-Za-z0-9_]*)\"),\n re.compile(r\"^\\s*impl\\s+(?:<[^>]+>\\s*)?([A-Za-z_][A-Za-z0-9_]*)\"),\n]\nGENERIC_SYMBOL_PATTERNS = [\n re.compile(r\"^\\s*def\\s+([A-Za-z_][A-Za-z0-9_]*)\"),\n re.compile(r\"^\\s*class\\s+([A-Za-z_][A-Za-z0-9_]*)\"),\n re.compile(r\"^\\s*function\\s+([A-Za-z_][A-Za-z0-9_]*)\"),\n]\n\n\n@dataclass\nclass SourceEntry:\n source_id: str\n kind: str\n scope: str\n name: str\n version: str | None\n materialized_path: str\n upstream_repository: str | None\n history_head: str | None\n checksum: str | None\n synced_at_utc: str | None\n\n\ndef die(msg: str) -> NoReturn:\n raise SystemExit(msg)\n\n\ndef load_toml(path: Path) -> dict:\n with path.open(\"rb\") as fh:\n return tomllib.load(fh)\n\n\ndef load_vendor_sources(project: Path) -> list[SourceEntry]:\n vendor_lock = load_vendor_lock(project)\n flow_vendor_meta = vendor_lock.get(\"flow_vendor\", {})\n lock_crates = _as_list(vendor_lock.get(\"crate\"))\n vendor_commit = _s(_as_dict(flow_vendor_meta).get(\"commit\"))\n\n by_crate: dict[str, SourceEntry] = {}\n for item in lock_crates:\n row = _as_dict(item)\n crate = _s(row.get(\"name\"))\n if crate is None:\n continue\n by_crate[crate] = SourceEntry(\n source_id=f\"vendor:{crate}\",\n kind=\"crate\",\n scope=\"vendor\",\n name=crate,\n version=None,\n materialized_path=_s(row.get(\"materialized_path\")) or f\"lib/vendor/{crate}\",\n upstream_repository=None,\n history_head=vendor_commit,\n checksum=None,\n synced_at_utc=None,\n )\n\n manifest_dir = project / \"lib/vendor-manifest\"\n if manifest_dir.is_dir():\n for manifest in sorted(manifest_dir.glob(\"*.toml\")):\n data = load_toml(manifest)\n crate = str(data.get(\"crate\", manifest.stem))\n prev = by_crate.get(crate)\n by_crate[crate] = SourceEntry(\n source_id=f\"vendor:{crate}\",\n kind=\"crate\",\n scope=\"vendor\",\n name=crate,\n version=_s(data.get(\"version\")),\n materialized_path=(\n _s(data.get(\"materialized_path\"))\n or (prev.materialized_path if prev else None)\n or f\"lib/vendor/{crate}\"\n ),\n upstream_repository=_s(data.get(\"upstream_repository\")) or (prev.upstream_repository if prev else None),\n history_head=_s(data.get(\"history_head\")) or (prev.history_head if prev else None),\n checksum=_s(data.get(\"cargo_registry_checksum\")),\n synced_at_utc=_s(data.get(\"synced_at_utc\")),\n )\n\n entries = sorted(by_crate.values(), key=lambda s: s.name)\n entries.append(\n SourceEntry(\n source_id=\"firstparty:flow\",\n kind=\"repo\",\n scope=\"firstparty\",\n name=project.name,\n version=None,\n materialized_path=\".\",\n upstream_repository=None,\n history_head=None,\n checksum=None,\n synced_at_utc=None,\n )\n )\n return entries\n\n\ndef load_vendor_lock(project: Path) -> dict:\n path = project / \"vendor.lock.toml\"\n if not path.is_file():\n return {}\n return load_toml(path)\n\n\ndef _as_dict(value: object) -> dict:\n return value if isinstance(value, dict) else {}\n\n\ndef _as_list(value: object) -> list:\n return value if isinstance(value, list) else []\n\n\ndef _s(v: object) -> str | None:\n if v is None:\n return None\n s = str(v).strip()\n return s if s else None\n\n\ndef typesense_request(\n method: str,\n url: str,\n api_key: str,\n *,\n payload: bytes | None = None,\n content_type: str = \"application/json\",\n) -> tuple[int, bytes]:\n headers = {\"X-TYPESENSE-API-KEY\": api_key}\n if payload is not None:\n headers[\"Content-Type\"] = content_type\n req = request.Request(url=url, method=method, data=payload, headers=headers)\n try:\n with request.urlopen(req, timeout=30) as resp:\n return resp.status, resp.read()\n except error.HTTPError as exc:\n body = exc.read().decode(\"utf-8\", errors=\"replace\")\n raise RuntimeError(f\"Typesense {method} {url} failed ({exc.code}): {body}\") from exc\n except error.URLError as exc:\n reason = getattr(exc, \"reason\", exc)\n raise RuntimeError(f\"Typesense {method} {url} failed (connection): {reason}\") from exc\n\n\ndef collection_url(base: str, name: str) -> str:\n return f\"{base.rstrip('/')}/collections/{parse.quote(name)}\"\n\n\ndef ensure_collection(base_url: str, api_key: str, name: str, fields: list[dict], dry_run: bool) -> None:\n if dry_run:\n return\n\n url = collection_url(base_url, name)\n try:\n status, _ = typesense_request(\"GET\", url, api_key)\n if status == 200:\n return\n except RuntimeError as err:\n if \"(404)\" not in str(err):\n raise\n\n schema = {\"name\": name, \"fields\": fields}\n typesense_request(\n \"POST\",\n f\"{base_url.rstrip('/')}/collections\",\n api_key,\n payload=json.dumps(schema).encode(\"utf-8\"),\n )\n\n\ndef import_jsonl(base_url: str, api_key: str, collection: str, docs: list[dict], dry_run: bool) -> int:\n if not docs:\n return 0\n if dry_run:\n return len(docs)\n\n jsonl = \"\\n\".join(json.dumps(d, ensure_ascii=False) for d in docs) + \"\\n\"\n url = f\"{collection_url(base_url, collection)}/documents/import?action=upsert\"\n _, body = typesense_request(\n \"POST\",\n url,\n api_key,\n payload=jsonl.encode(\"utf-8\"),\n content_type=\"text/plain\",\n )\n lines = [line for line in body.decode(\"utf-8\", errors=\"replace\").splitlines() if line.strip()]\n failed = 0\n for line in lines:\n try:\n item = json.loads(line)\n except json.JSONDecodeError:\n continue\n if not item.get(\"success\", False):\n failed += 1\n if failed:\n raise RuntimeError(f\"Typesense import reported {failed} failed docs in {collection}\")\n return len(lines)\n\n\ndef iter_text_files(root: Path, *, exclude_vendor: bool) -> Iterable[Path]:\n for path in root.rglob(\"*\"):\n if not path.is_file():\n continue\n if any(part in EXCLUDE_DIRS for part in path.parts):\n continue\n if exclude_vendor and \"lib\" in path.parts and \"vendor\" in path.parts:\n continue\n if path.suffix.lower() in TEXT_EXTS:\n yield path\n\n\ndef extract_symbols(path: Path, lines: list[str]) -> list[str]:\n patterns = RUST_SYMBOL_PATTERNS if path.suffix == \".rs\" else GENERIC_SYMBOL_PATTERNS\n symbols: list[str] = []\n seen: set[str] = set()\n for line in lines:\n for pat in patterns:\n m = pat.search(line)\n if not m:\n continue\n sym = m.group(1)\n if sym in seen:\n continue\n seen.add(sym)\n symbols.append(sym)\n if len(symbols) >= 24:\n return symbols\n return symbols\n\n\ndef chunk_lines(lines: list[str], chunk_size: int, overlap: int) -> Iterable[tuple[int, int, str]]:\n if not lines:\n return\n start = 0\n count = len(lines)\n while start < count:\n end = min(start + chunk_size, count)\n text = \"\\n\".join(lines[start:end]).strip()\n if text:\n yield start + 1, end, text\n if end >= count:\n break\n start = max(end - overlap, start + 1)\n\n\ndef lang_for(path: Path) -> str:\n ext = path.suffix.lower().lstrip(\".\")\n return ext or \"text\"\n\n\ndef file_to_chunks(\n project: Path,\n file_path: Path,\n *,\n source: SourceEntry,\n chunk_lines_n: int,\n overlap: int,\n) -> list[dict]:\n rel = file_path.relative_to(project).as_posix()\n raw = file_path.read_text(encoding=\"utf-8\", errors=\"replace\")\n lines = raw.splitlines()\n symbols = extract_symbols(file_path, lines)\n docs: list[dict] = []\n\n for line_start, line_end, content in chunk_lines(lines, chunk_lines_n, overlap):\n key = f\"{source.source_id}|{rel}|{line_start}|{line_end}\"\n doc_id = hashlib.sha1(key.encode(\"utf-8\")).hexdigest()\n docs.append(\n {\n \"id\": doc_id,\n \"kind\": \"code\",\n \"project\": project.name,\n \"scope\": source.scope,\n \"source_id\": source.source_id,\n \"crate\": source.name if source.scope == \"vendor\" else \"\",\n \"rel_path\": rel,\n \"lang\": lang_for(file_path),\n \"symbols\": symbols,\n \"line_start\": line_start,\n \"line_end\": line_end,\n \"preview\": content[:220],\n \"content\": content,\n }\n )\n return docs\n\n\ndef build_sources_docs(project: Path, sources: list[SourceEntry]) -> list[dict]:\n docs = []\n for src in sources:\n docs.append(\n {\n \"id\": src.source_id,\n \"project\": project.name,\n \"kind\": src.kind,\n \"scope\": src.scope,\n \"name\": src.name,\n \"version\": src.version or \"\",\n \"materialized_path\": src.materialized_path,\n \"upstream_repository\": src.upstream_repository or \"\",\n \"history_head\": src.history_head or \"\",\n \"checksum\": src.checksum or \"\",\n \"synced_at_utc\": src.synced_at_utc or \"\",\n }\n )\n return docs\n\n\ndef collect_chunk_docs(\n project: Path,\n sources: list[SourceEntry],\n *,\n chunk_lines_n: int,\n overlap: int,\n max_files: int,\n) -> list[dict]:\n docs: list[dict] = []\n seen_files = 0\n\n # vendored sources\n for src in sources:\n if src.scope != \"vendor\":\n continue\n root = project / src.materialized_path\n if not root.is_dir():\n continue\n for file_path in iter_text_files(root, exclude_vendor=False):\n docs.extend(\n file_to_chunks(\n project,\n file_path,\n source=src,\n chunk_lines_n=chunk_lines_n,\n overlap=overlap,\n )\n )\n seen_files += 1\n if max_files and seen_files >= max_files:\n return docs\n\n # first-party sources\n first = next((s for s in sources if s.scope == \"firstparty\"), None)\n if first is None:\n return docs\n\n for directory in FIRST_PARTY_DIRS:\n root = project / directory\n if not root.is_dir():\n continue\n for file_path in iter_text_files(root, exclude_vendor=True):\n docs.extend(\n file_to_chunks(\n project,\n file_path,\n source=first,\n chunk_lines_n=chunk_lines_n,\n overlap=overlap,\n )\n )\n seen_files += 1\n if max_files and seen_files >= max_files:\n return docs\n\n return docs\n\n\ndef write_sources_index(project: Path, sources: list[SourceEntry], out_path: str) -> Path:\n path = project / out_path\n path.parent.mkdir(parents=True, exist_ok=True)\n payload = {\n \"project\": project.name,\n \"updated_at\": _utc_now(),\n \"sources\": [\n {\n \"source_id\": s.source_id,\n \"kind\": s.kind,\n \"scope\": s.scope,\n \"name\": s.name,\n \"version\": s.version,\n \"materialized_path\": s.materialized_path,\n \"upstream_repository\": s.upstream_repository,\n \"history_head\": s.history_head,\n \"checksum\": s.checksum,\n \"synced_at_utc\": s.synced_at_utc,\n }\n for s in sources\n ],\n }\n path.write_text(json.dumps(payload, indent=2) + \"\\n\", encoding=\"utf-8\")\n return path\n\n\ndef _utc_now() -> str:\n from datetime import datetime, timezone\n\n return datetime.now(tz=timezone.utc).isoformat()\n\n\ndef cmd_index(args: argparse.Namespace) -> None:\n project = Path(args.project).expanduser().resolve()\n if not (project / \"Cargo.toml\").is_file():\n die(f\"not a cargo project: {project}\")\n\n sources = load_vendor_sources(project)\n source_index = project / args.sources_index\n if not args.dry_run:\n source_index = write_sources_index(project, sources, args.sources_index)\n\n sources_collection = f\"{args.prefix}_sources\"\n chunks_collection = f\"{args.prefix}_chunks\"\n\n source_fields = [\n {\"name\": \"id\", \"type\": \"string\"},\n {\"name\": \"project\", \"type\": \"string\", \"facet\": True},\n {\"name\": \"kind\", \"type\": \"string\", \"facet\": True},\n {\"name\": \"scope\", \"type\": \"string\", \"facet\": True},\n {\"name\": \"name\", \"type\": \"string\", \"facet\": True},\n {\"name\": \"version\", \"type\": \"string\", \"facet\": True, \"optional\": True},\n {\"name\": \"materialized_path\", \"type\": \"string\", \"optional\": True},\n {\"name\": \"upstream_repository\", \"type\": \"string\", \"optional\": True},\n {\"name\": \"history_head\", \"type\": \"string\", \"optional\": True},\n {\"name\": \"checksum\", \"type\": \"string\", \"optional\": True},\n {\"name\": \"synced_at_utc\", \"type\": \"string\", \"optional\": True},\n ]\n chunk_fields = [\n {\"name\": \"id\", \"type\": \"string\"},\n {\"name\": \"kind\", \"type\": \"string\", \"facet\": True},\n {\"name\": \"project\", \"type\": \"string\", \"facet\": True},\n {\"name\": \"scope\", \"type\": \"string\", \"facet\": True},\n {\"name\": \"source_id\", \"type\": \"string\", \"facet\": True},\n {\"name\": \"crate\", \"type\": \"string\", \"facet\": True, \"optional\": True},\n {\"name\": \"rel_path\", \"type\": \"string\"},\n {\"name\": \"lang\", \"type\": \"string\", \"facet\": True},\n {\"name\": \"symbols\", \"type\": \"string[]\", \"optional\": True},\n {\"name\": \"line_start\", \"type\": \"int32\", \"optional\": True},\n {\"name\": \"line_end\", \"type\": \"int32\", \"optional\": True},\n {\"name\": \"preview\", \"type\": \"string\", \"optional\": True},\n {\"name\": \"content\", \"type\": \"string\"},\n ]\n\n ensure_collection(args.url, args.api_key, sources_collection, source_fields, args.dry_run)\n ensure_collection(args.url, args.api_key, chunks_collection, chunk_fields, args.dry_run)\n\n source_docs = build_sources_docs(project, sources)\n indexed_sources = import_jsonl(args.url, args.api_key, sources_collection, source_docs, args.dry_run)\n\n chunk_docs = collect_chunk_docs(\n project,\n sources,\n chunk_lines_n=args.chunk_lines,\n overlap=args.chunk_overlap,\n max_files=args.max_files,\n )\n\n indexed_chunks = 0\n for i in range(0, len(chunk_docs), args.batch_size):\n batch = chunk_docs[i : i + args.batch_size]\n indexed_chunks += import_jsonl(args.url, args.api_key, chunks_collection, batch, args.dry_run)\n\n print(f\"project: {project}\")\n print(f\"sources index: {source_index}\")\n print(f\"typesense url: {args.url}\")\n print(f\"sources docs: {indexed_sources}\")\n print(f\"chunk docs: {indexed_chunks}\")\n print(f\"sources coll: {sources_collection}\")\n print(f\"chunks coll: {chunks_collection}\")\n if args.dry_run:\n print(\"mode: dry-run (no writes to Typesense)\")\n\n\ndef _build_filter(args: argparse.Namespace) -> str | None:\n filters: list[str] = []\n if args.scope:\n filters.append(f\"scope:={args.scope}\")\n if args.crate:\n field = \"name\" if args.collection == \"sources\" else \"crate\"\n filters.append(f\"{field}:={args.crate}\")\n if args.lang and args.collection != \"sources\":\n filters.append(f\"lang:={args.lang}\")\n if args.path_prefix:\n field = \"materialized_path\" if args.collection == \"sources\" else \"rel_path\"\n filters.append(f\"{field}:{args.path_prefix}\")\n return \" && \".join(filters) if filters else None\n\n\ndef cmd_search(args: argparse.Namespace) -> None:\n collection = f\"{args.prefix}_{args.collection}\"\n if args.collection == \"sources\":\n query_by = \"name,materialized_path,upstream_repository,version,checksum,history_head\"\n highlight_fields = \"name,materialized_path,upstream_repository\"\n else:\n query_by = \"content,rel_path,crate,symbols,preview\"\n highlight_fields = \"content,preview\"\n\n params = {\n \"q\": args.query,\n \"query_by\": query_by,\n \"per_page\": str(args.limit),\n \"highlight_fields\": highlight_fields,\n }\n filter_by = _build_filter(args)\n if filter_by:\n params[\"filter_by\"] = filter_by\n\n url = f\"{collection_url(args.url, collection)}/documents/search?{parse.urlencode(params)}\"\n _, body = typesense_request(\"GET\", url, args.api_key)\n data = json.loads(body.decode(\"utf-8\"))\n if args.json:\n print(json.dumps(data, indent=2))\n return\n\n found = data.get(\"found\", 0)\n hits = data.get(\"hits\", [])\n print(f\"collection: {collection}\")\n print(f\"found: {found}\")\n print()\n\n for idx, hit in enumerate(hits, start=1):\n doc = hit.get(\"document\", {})\n\n if args.collection == \"sources\":\n scope = doc.get(\"scope\", \"\")\n name = doc.get(\"name\", \"\")\n version = doc.get(\"version\", \"\")\n materialized_path = doc.get(\"materialized_path\", \"\")\n upstream = doc.get(\"upstream_repository\", \"\")\n checksum = doc.get(\"checksum\", \"\")\n synced_at = doc.get(\"synced_at_utc\", \"\")\n header = f\"{idx:02d}. {scope}::{name}\"\n if version:\n header += f\" v{version}\"\n print(header)\n print(f\" path: {materialized_path}\")\n if upstream:\n print(f\" upstream: {upstream}\")\n if checksum:\n print(f\" checksum: {checksum}\")\n if synced_at:\n print(f\" synced_at_utc: {synced_at}\")\n continue\n\n rel_path = doc.get(\"rel_path\") or doc.get(\"materialized_path\") or \"\"\n scope = doc.get(\"scope\", \"\")\n crate = doc.get(\"crate\", \"\")\n line_start = doc.get(\"line_start\")\n line_end = doc.get(\"line_end\")\n\n line_part = \"\"\n if line_start and line_end:\n line_part = f\" [{line_start}-{line_end}]\"\n\n header = f\"{idx:02d}. {scope}\"\n if crate:\n header += f\"::{crate}\"\n header += f\" {rel_path}{line_part}\"\n print(header)\n\n snippet = doc.get(\"preview\") or doc.get(\"content\") or \"\"\n snippet = str(snippet).replace(\"\\n\", \" \").strip()\n if len(snippet) > 220:\n snippet = snippet[:220] + \"...\"\n print(f\" {snippet}\")\n\n\ndef cmd_sources(args: argparse.Namespace) -> None:\n project = Path(args.project).expanduser().resolve()\n sources = load_vendor_sources(project)\n out = {\n \"project\": project.name,\n \"updated_at\": _utc_now(),\n \"sources\": [\n {\n \"source_id\": s.source_id,\n \"kind\": s.kind,\n \"scope\": s.scope,\n \"name\": s.name,\n \"version\": s.version,\n \"materialized_path\": s.materialized_path,\n \"upstream_repository\": s.upstream_repository,\n \"history_head\": s.history_head,\n \"checksum\": s.checksum,\n \"synced_at_utc\": s.synced_at_utc,\n }\n for s in sources\n ],\n }\n if args.write:\n path = write_sources_index(project, sources, args.sources_index)\n print(path)\n else:\n print(json.dumps(out, indent=2))\n\n\ndef build_parser() -> argparse.ArgumentParser:\n p = argparse.ArgumentParser(description=\"Typesense code index/search for Flow vendored + first-party code\")\n p.add_argument(\"--project\", default=\".\", help=\"Project root (default: current directory)\")\n p.add_argument(\"--url\", default=DEFAULT_TYPESENSE_URL, help=\"Typesense URL\")\n p.add_argument(\"--api-key\", default=DEFAULT_TYPESENSE_API_KEY, help=\"Typesense API key\")\n p.add_argument(\"--prefix\", default=DEFAULT_PREFIX, help=\"Collection prefix\")\n p.add_argument(\n \"--sources-index\",\n default=DEFAULT_SOURCE_INDEX,\n help=\"Path (relative to project) for generated sources index JSON\",\n )\n\n sub = p.add_subparsers(dest=\"command\", required=True)\n\n p_index = sub.add_parser(\"index\", help=\"Index first-party + vendored code\")\n p_index.add_argument(\"--chunk-lines\", type=int, default=120, help=\"Lines per chunk\")\n p_index.add_argument(\"--chunk-overlap\", type=int, default=20, help=\"Overlapped lines between chunks\")\n p_index.add_argument(\"--batch-size\", type=int, default=250, help=\"Import batch size\")\n p_index.add_argument(\"--max-files\", type=int, default=0, help=\"Debug limit (0 = no limit)\")\n p_index.add_argument(\"--dry-run\", action=\"store_true\", help=\"Do not write to Typesense\")\n p_index.set_defaults(func=cmd_index)\n\n p_search = sub.add_parser(\"search\", help=\"Search indexed code/sources\")\n p_search.add_argument(\"query\", help=\"Search query\")\n p_search.add_argument(\"--collection\", choices=[\"chunks\", \"sources\"], default=\"chunks\")\n p_search.add_argument(\"--scope\", choices=[\"vendor\", \"firstparty\"])\n p_search.add_argument(\"--crate\", help=\"Filter by vendored crate name\")\n p_search.add_argument(\"--lang\", help=\"Filter by language (rs, toml, md, ...)\")\n p_search.add_argument(\"--path-prefix\", help=\"Filter by path prefix (rel_path or materialized_path)\")\n p_search.add_argument(\"--limit\", type=int, default=20)\n p_search.add_argument(\"--json\", action=\"store_true\", help=\"Print raw Typesense JSON\")\n p_search.set_defaults(func=cmd_search)\n\n p_sources = sub.add_parser(\"sources\", help=\"Show/write opensrc-style source inventory\")\n p_sources.add_argument(\"--write\", action=\"store_true\", help=\"Write sources index file and print path\")\n p_sources.set_defaults(func=cmd_sources)\n\n return p\n\n\ndef main() -> None:\n parser = build_parser()\n args = parser.parse_args()\n try:\n args.func(args)\n except RuntimeError as err:\n die(str(err))\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "scripts/vendor/update-deps.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\nusage() {\n cat <<'USAGE'\nUsage:\n scripts/vendor/update-deps.sh [options]\n\nOptions:\n --dry-run Show what would be updated without writing changes.\n --important Only update crates listed in scripts/vendor/important-crates.txt.\n --no-major Disallow major updates (default allows major).\n --no-minor Disallow minor updates (default allows minor).\n --no-cargo-update Skip `cargo update --workspace`.\n --no-audit Skip strict vendoring audit.\n --no-check Skip `cargo check -q`.\n --push-vendor Push .vendor/flow-vendor checkout after import/pin.\n\nBehavior:\n - Updates vendored crates to latest allowed versions.\n - Re-applies deterministic trim/warning-hygiene patches.\n - Imports local vendor state and pins vendor.lock.toml commit.\n - Optionally refreshes Cargo.lock and validates with strict checks.\nUSAGE\n}\n\ndry_run=false\nimportant_only=false\nallow_minor=true\nallow_major=true\nrun_cargo_update=true\nrun_audit=true\nrun_check=true\npush_vendor=false\n\nwhile [[ $# -gt 0 ]]; do\n case \"$1\" in\n --dry-run) dry_run=true; shift ;;\n --important) important_only=true; shift ;;\n --no-major) allow_major=false; shift ;;\n --no-minor) allow_minor=false; shift ;;\n --no-cargo-update) run_cargo_update=false; shift ;;\n --no-audit) run_audit=false; shift ;;\n --no-check) run_check=false; shift ;;\n --push-vendor) push_vendor=true; shift ;;\n --) shift ;;\n -h|--help) usage; exit 0 ;;\n *)\n echo \"error: unknown arg: $1\"\n usage\n exit 1\n ;;\n esac\ndone\n\nif ! command -v jq >/dev/null 2>&1; then\n echo \"error: jq is required\"\n exit 1\nfi\n\nfind_python_with_tomllib() {\n local candidate\n for candidate in python3 python3.12 python3.11 python; do\n command -v \"$candidate\" >/dev/null 2>&1 || continue\n if \"$candidate\" - <<'PY' >/dev/null 2>&1\nimport tomllib # noqa: F401\nPY\n then\n echo \"$candidate\"\n return 0\n fi\n done\n return 1\n}\n\nsync_cmd=(scripts/vendor/sync-all.sh)\ncheck_cmd=(scripts/vendor/check-upstream.sh)\nif [[ \"$important_only\" == true ]]; then\n sync_cmd+=(--important)\n check_cmd+=(--important)\nfi\nif [[ \"$allow_minor\" == true ]]; then\n sync_cmd+=(--allow-minor)\nfi\nif [[ \"$allow_major\" == true ]]; then\n sync_cmd+=(--allow-major)\nfi\n\necho \"== update-deps: upstream scan ==\"\nupstream_json=\"$(\"${check_cmd[@]}\" --json)\"\nupdates_total=\"$(printf '%s\\n' \"$upstream_json\" | jq '[.[] | select(.status==\"update-available\")] | length')\"\npatch_updates=\"$(printf '%s\\n' \"$upstream_json\" | jq '[.[] | select(.status==\"update-available\" and .level==\"patch\")] | length')\"\nminor_updates=\"$(printf '%s\\n' \"$upstream_json\" | jq '[.[] | select(.status==\"update-available\" and .level==\"minor\")] | length')\"\nmajor_updates=\"$(printf '%s\\n' \"$upstream_json\" | jq '[.[] | select(.status==\"update-available\" and .level==\"major\")] | length')\"\necho \"updates available: ${updates_total} (patch=${patch_updates}, minor=${minor_updates}, major=${major_updates})\"\n\nif [[ \"$dry_run\" == true ]]; then\n echo\n echo \"== update-deps: dry-run sync plan ==\"\n \"${sync_cmd[@]}\" --dry-run\n exit 0\nfi\n\necho\necho \"== update-deps: sync vendored crates ==\"\n\"${sync_cmd[@]}\" --no-vendor-import\n\necho\necho \"== update-deps: apply trims/warning hygiene ==\"\nscripts/vendor/apply-trims.sh\n\nif [[ -f vendor.lock.toml ]]; then\n echo\n echo \"== update-deps: import + pin vendor repo state ==\"\n scripts/vendor/vendor-repo.sh import-local\nfi\n\nif [[ \"$run_cargo_update\" == true ]]; then\n echo\n echo \"== update-deps: cargo lock refresh ==\"\n cargo update --workspace\nfi\n\nif [[ \"$run_audit\" == true ]]; then\n if ! audit_python=\"$(find_python_with_tomllib)\"; then\n echo \"error: strict audit requires Python 3.11+ (tomllib). Use --no-audit to skip.\"\n exit 1\n fi\n echo\n echo \"== update-deps: strict vendoring audit ==\"\n \"$audit_python\" ./scripts/vendor/rough_edges_audit.py --project . --strict-warnings\nfi\n\nif [[ \"$run_check\" == true ]]; then\n echo\n echo \"== update-deps: cargo check ==\"\n cargo check -q\nfi\n\nif [[ \"$push_vendor\" == true ]]; then\n echo\n echo \"== update-deps: push vendor repo ==\"\n scripts/vendor/vendor-repo.sh push\nfi\n\necho\necho \"update-deps complete\"\n" }, { "path": "scripts/vendor/vendor-repo.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nrepo_root=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")/../..\" && pwd)\"\ncd \"$repo_root\"\n\nlock_file=\"${VENDOR_LOCK_FILE_PATH:-vendor.lock.toml}\"\n\nusage() {\n cat <<'USAGE'\nUsage:\n scripts/vendor/vendor-repo.sh <command> [args]\n\nCommands:\n init Ensure vendor repo checkout exists and has base layout\n create-remote [slug] Create GitHub repo via gh and wire origin + lock repo URL\n import-local Copy current lib/vendor + manifests into vendor repo and commit\n hydrate Materialize lib/vendor from pinned commit in vendor.lock.toml\n pin [commit] Pin vendor.lock.toml commit (defaults to checkout HEAD)\n status Show lock/checkout/remote status summary\n verify-pinned-origin Fail unless pinned commit is published on vendor origin/<branch>\n push Push checkout HEAD to origin/<branch>\n\nEnvironment:\n VENDOR_LOCK_FILE_PATH Override lock file path (default: vendor.lock.toml)\nUSAGE\n}\n\nif [[ \"${1:-}\" == \"-h\" || \"${1:-}\" == \"--help\" || $# -lt 1 ]]; then\n usage\n exit 0\nfi\n\ncommand=\"$1\"\nshift || true\n\nif [[ ! -f \"$lock_file\" ]]; then\n echo \"error: missing lock file: $lock_file\"\n exit 1\nfi\n\ndetect_lock_section() {\n awk '\n /^\\[vendor\\]$/ { print \"vendor\"; found_vendor = 1; exit }\n /^\\[flow_vendor\\]$/ { found_legacy = 1 }\n END {\n if (!found_vendor && found_legacy) {\n print \"flow_vendor\"\n } else if (!found_vendor) {\n print \"vendor\"\n }\n }\n ' \"$lock_file\"\n}\n\nlock_section_name=\"$(detect_lock_section)\"\n\nread_lock_value() {\n local key=\"$1\"\n awk -F'\"' -v key=\"$key\" -v lock_section_name=\"$lock_section_name\" '\n /^\\/\\// { next }\n /^\\[/ { section = $0; next }\n section == (\"[\" lock_section_name \"]\") && $1 ~ (\"^\" key \" = \") { print $2; exit }\n ' \"$lock_file\"\n}\n\nlist_crates() {\n awk -F'\"' '\n BEGIN {\n in_crate = 0\n name = \"\"\n repo_path = \"\"\n manifest_path = \"\"\n materialized_path = \"\"\n }\n /^\\[\\[crate\\]\\]/ {\n if (in_crate && name != \"\") {\n printf \"%s\\t%s\\t%s\\t%s\\n\", name, repo_path, manifest_path, materialized_path\n }\n in_crate = 1\n name = \"\"\n repo_path = \"\"\n manifest_path = \"\"\n materialized_path = \"\"\n next\n }\n in_crate && $1 ~ /^name = / { name = $2; next }\n in_crate && $1 ~ /^repo_path = / { repo_path = $2; next }\n in_crate && $1 ~ /^manifest_path = / { manifest_path = $2; next }\n in_crate && $1 ~ /^materialized_path = / { materialized_path = $2; next }\n END {\n if (in_crate && name != \"\") {\n printf \"%s\\t%s\\t%s\\t%s\\n\", name, repo_path, manifest_path, materialized_path\n }\n }\n ' \"$lock_file\"\n}\n\nset_lock_commit() {\n local new_commit=\"$1\"\n set_lock_value \"commit\" \"$new_commit\"\n}\n\nset_lock_value() {\n local key=\"$1\"\n local new_value=\"$2\"\n local tmp\n tmp=\"$(mktemp)\"\n awk -v key=\"$key\" -v new_value=\"$new_value\" -v lock_section_name=\"$lock_section_name\" '\n BEGIN {\n in_vendor = 0\n replaced = 0\n saw_section = 0\n }\n $0 == \"[\" lock_section_name \"]\" {\n in_vendor = 1\n saw_section = 1\n print\n next\n }\n /^\\[/ {\n if (in_vendor == 1 && replaced == 0) {\n print key \" = \\\"\" new_value \"\\\"\"\n replaced = 1\n }\n in_vendor = 0\n }\n in_vendor == 1 && $0 ~ (\"^\" key \" = \\\"\") {\n print key \" = \\\"\" new_value \"\\\"\"\n replaced = 1\n next\n }\n { print }\n END {\n if (in_vendor == 1 && replaced == 0) {\n print key \" = \\\"\" new_value \"\\\"\"\n replaced = 1\n }\n if (saw_section == 0) {\n print \"\"\n print \"[\" lock_section_name \"]\"\n print key \" = \\\"\" new_value \"\\\"\"\n }\n }\n ' \"$lock_file\" >\"$tmp\"\n mv \"$tmp\" \"$lock_file\"\n}\n\nensure_checkout() {\n local repo_url branch checkout\n repo_url=\"$(read_lock_value repo)\"\n branch=\"$(read_lock_value branch)\"\n checkout=\"$(read_lock_value checkout)\"\n\n if [[ -z \"$repo_url\" || -z \"$branch\" || -z \"$checkout\" ]]; then\n echo \"error: lock file missing repo/branch/checkout in [${lock_section_name}]\"\n exit 1\n fi\n\n if [[ -d \"$checkout/.git\" ]]; then\n echo \"$checkout\"\n return\n fi\n\n mkdir -p \"$(dirname \"$checkout\")\"\n if git clone \"$repo_url\" \"$checkout\" >/dev/null 2>&1; then\n echo \"cloned $repo_url -> $checkout\" >&2\n else\n https_url=\"\"\n if [[ \"$repo_url\" =~ ^git@github\\.com:(.+)\\.git$ ]]; then\n https_url=\"https://github.com/${BASH_REMATCH[1]}.git\"\n fi\n\n if [[ -n \"$https_url\" ]] && git clone \"$https_url\" \"$checkout\" >/dev/null 2>&1; then\n echo \"cloned $https_url -> $checkout (fallback from SSH URL)\" >&2\n git -C \"$checkout\" remote set-url origin \"$repo_url\" >/dev/null 2>&1 || true\n else\n echo \"warning: failed to clone $repo_url\" >&2\n echo \"initializing local checkout at $checkout (set remote for later push)\" >&2\n git init \"$checkout\" >/dev/null\n git -C \"$checkout\" checkout -q -B \"$branch\"\n git -C \"$checkout\" remote add origin \"$repo_url\"\n fi\n fi\n\n if ! git -C \"$checkout\" rev-parse --verify \"$branch\" >/dev/null 2>&1; then\n git -C \"$checkout\" checkout -q -B \"$branch\"\n else\n git -C \"$checkout\" checkout -q \"$branch\"\n fi\n\n echo \"$checkout\"\n}\n\nensure_git_identity() {\n local checkout=\"$1\"\n if ! git -C \"$checkout\" config user.email >/dev/null; then\n git -C \"$checkout\" config user.email \"vendor-bot@localhost\"\n fi\n if ! git -C \"$checkout\" config user.name >/dev/null; then\n git -C \"$checkout\" config user.name \"vendor-bot\"\n fi\n}\n\nfetch_origin_branch() {\n local checkout=\"$1\"\n local branch=\"$2\"\n git -C \"$checkout\" remote get-url origin >/dev/null 2>&1 || return 1\n git -C \"$checkout\" fetch -q origin \"$branch\" >/dev/null 2>&1\n}\n\nensure_pinned_commit_published_on_origin() {\n local checkout=\"$1\"\n local branch=\"$2\"\n local commit=\"$3\"\n local remote_head\n\n if [[ -z \"$commit\" ]]; then\n echo \"error: pinned commit is empty in $lock_file\" >&2\n return 1\n fi\n\n if ! git -C \"$checkout\" cat-file -e \"${commit}^{commit}\" 2>/dev/null; then\n echo \"error: pinned commit $commit not found in $checkout\" >&2\n return 1\n fi\n\n if ! fetch_origin_branch \"$checkout\" \"$branch\"; then\n echo \"error: failed to fetch origin/$branch from $checkout\" >&2\n return 1\n fi\n\n if ! git -C \"$checkout\" rev-parse --verify \"origin/$branch\" >/dev/null 2>&1; then\n echo \"error: missing origin/$branch in $checkout\" >&2\n return 1\n fi\n\n remote_head=\"$(git -C \"$checkout\" rev-parse \"origin/$branch\")\"\n if git -C \"$checkout\" merge-base --is-ancestor \"$commit\" \"origin/$branch\"; then\n echo \"verified: pinned commit $commit is published on origin/$branch\"\n return 0\n fi\n\n echo \"error: pinned commit $commit is not published on origin/$branch (remote head $remote_head)\" >&2\n echo \"hint: push .vendor/flow-vendor before pushing flow when vendor.lock.toml changes\" >&2\n return 1\n}\n\nensure_repo_layout() {\n local checkout=\"$1\"\n mkdir -p \"$checkout/crates\" \"$checkout/manifests\" \"$checkout/profiles\"\n\n # Enforce lowercase readme naming in vendor repo root.\n if [[ -f \"$checkout/README.md\" && ! -f \"$checkout/readme.md\" ]]; then\n mv \"$checkout/README.md\" \"$checkout/readme.md\"\n fi\n rm -f \"$checkout/README.md\"\n\n if [[ ! -f \"$checkout/readme.md\" ]]; then\n cat > \"$checkout/readme.md\" <<'README'\n# vendor-repo\n\nCanonical vendored dependency source for this project.\n\n- `crates/<crate>/`: vendored source trees used by the project.\n- `manifests/<crate>.toml`: upstream/version metadata per crate.\n- `profiles/default.toml`: crate list used by hydration.\nREADME\n fi\n}\n\ngenerate_default_profile() {\n local output_file=\"$1\"\n {\n echo \"[profile]\"\n echo \"name = \\\"default\\\"\"\n echo \"generated_by = \\\"scripts/vendor/vendor-repo.sh\\\"\"\n echo\n while IFS=$'\\t' read -r name repo_path manifest_path _materialized_path; do\n [[ -n \"$name\" ]] || continue\n echo \"[[crate]]\"\n echo \"name = \\\"$name\\\"\"\n echo \"repo_path = \\\"$repo_path\\\"\"\n echo \"manifest_path = \\\"$manifest_path\\\"\"\n echo\n done < <(list_crates)\n } > \"$output_file\"\n}\n\ncmd_init() {\n local checkout\n checkout=\"$(ensure_checkout)\"\n ensure_repo_layout \"$checkout\"\n generate_default_profile \"$checkout/profiles/default.toml\"\n echo \"vendor checkout ready: $checkout\"\n}\n\ncmd_create_remote() {\n local checkout slug ssh_url\n checkout=\"$(ensure_checkout)\"\n slug=\"${1:-}\"\n if [[ -z \"$slug\" ]]; then\n local origin_url owner repo_name\n origin_url=\"$(git -C \"$repo_root\" remote get-url origin 2>/dev/null || true)\"\n if [[ \"$origin_url\" =~ ^git@github\\.com:([^/]+)/(.+)\\.git$ ]]; then\n owner=\"${BASH_REMATCH[1]}\"\n repo_name=\"${BASH_REMATCH[2]}\"\n slug=\"${owner}/${repo_name}-vendor\"\n elif [[ \"$origin_url\" =~ ^https://github\\.com/([^/]+)/(.+)\\.git$ ]]; then\n owner=\"${BASH_REMATCH[1]}\"\n repo_name=\"${BASH_REMATCH[2]}\"\n slug=\"${owner}/${repo_name}-vendor\"\n else\n slug=\"CHANGE_ME/$(basename \"$repo_root\")-vendor\"\n echo \"warning: could not infer GitHub slug from origin; using ${slug}\" >&2\n fi\n fi\n ssh_url=\"git@github.com:${slug}.git\"\n\n if ! command -v gh >/dev/null 2>&1; then\n echo \"error: gh CLI is required for create-remote\"\n exit 1\n fi\n\n if gh repo view \"$slug\" >/dev/null 2>&1; then\n echo \"remote repo exists: $slug\"\n else\n gh repo create \"$slug\" --public --source \"$checkout\" --remote origin --disable-issues >/dev/null\n echo \"created remote repo: $slug\"\n fi\n\n if git -C \"$checkout\" remote get-url origin >/dev/null 2>&1; then\n git -C \"$checkout\" remote set-url origin \"$ssh_url\"\n else\n git -C \"$checkout\" remote add origin \"$ssh_url\"\n fi\n\n set_lock_value \"repo\" \"$ssh_url\"\n echo \"updated lock repo URL to $ssh_url\"\n}\n\ncmd_import_local() {\n local checkout\n checkout=\"$(ensure_checkout)\"\n ensure_repo_layout \"$checkout\"\n ensure_git_identity \"$checkout\"\n\n # Keep imported source deterministic with the same trim/hygiene rules used by hydrate.\n scripts/vendor/apply-trims.sh\n\n while IFS=$'\\t' read -r name repo_path manifest_path materialized_path; do\n [[ -n \"$name\" ]] || continue\n\n local_src=\"$repo_root/$materialized_path\"\n local_manifest_src=\"$repo_root/lib/vendor-manifest/${name}.toml\"\n\n if [[ ! -d \"$local_src\" ]]; then\n echo \"warning: missing local vendored crate source: $local_src\"\n continue\n fi\n\n mkdir -p \"$checkout/$(dirname \"$repo_path\")\"\n rm -rf \"$checkout/$repo_path\"\n mkdir -p \"$checkout/$repo_path\"\n rsync -a --delete --exclude '.git' \"$local_src\"/ \"$checkout/$repo_path\"/\n\n if [[ -f \"$local_manifest_src\" ]]; then\n mkdir -p \"$checkout/$(dirname \"$manifest_path\")\"\n cp \"$local_manifest_src\" \"$checkout/$manifest_path\"\n else\n echo \"warning: missing local manifest: $local_manifest_src\"\n fi\n done < <(list_crates)\n\n generate_default_profile \"$checkout/profiles/default.toml\"\n\n git -C \"$checkout\" add -A\n if git -C \"$checkout\" diff --cached --quiet; then\n echo \"no changes to import into vendor repo\"\n else\n git -C \"$checkout\" commit -m \"vendor: import local materialized crates\" >/dev/null\n echo \"committed vendor repo import\"\n fi\n\n head_sha=\"$(git -C \"$checkout\" rev-parse HEAD)\"\n set_lock_commit \"$head_sha\"\n echo \"pinned $lock_file commit=$head_sha\"\n}\n\ncmd_hydrate() {\n local checkout commit\n checkout=\"$(ensure_checkout)\"\n commit=\"$(read_lock_value commit)\"\n\n if [[ -z \"$commit\" ]]; then\n commit=\"$(git -C \"$checkout\" rev-parse HEAD)\"\n echo \"warning: lock commit empty; hydrating from checkout HEAD $commit\"\n fi\n\n if git -C \"$checkout\" remote get-url origin >/dev/null 2>&1; then\n fetch_origin_branch \"$checkout\" \"$(read_lock_value branch)\" || true\n fi\n\n if ! git -C \"$checkout\" cat-file -e \"${commit}^{commit}\" 2>/dev/null; then\n echo \"error: commit $commit not found in $checkout\"\n echo \"hint: run scripts/vendor/vendor-repo.sh init (or pin a commit present locally)\"\n exit 1\n fi\n\n while IFS=$'\\t' read -r name repo_path manifest_path materialized_path; do\n [[ -n \"$name\" ]] || continue\n\n dst_src=\"$repo_root/$materialized_path\"\n dst_manifest=\"$repo_root/lib/vendor-manifest/${name}.toml\"\n\n if ! git -C \"$checkout\" cat-file -e \"${commit}:${repo_path}\" 2>/dev/null; then\n echo \"error: crate path missing at pinned commit: ${repo_path}\"\n exit 1\n fi\n\n tmp_dir=\"$(mktemp -d)\"\n\n git -C \"$checkout\" archive --format=tar \"$commit\" \"$repo_path\" | tar -xf - -C \"$tmp_dir\"\n rm -rf \"$dst_src\"\n mkdir -p \"$dst_src\"\n rsync -a --delete \"$tmp_dir/$repo_path\"/ \"$dst_src\"/\n\n if git -C \"$checkout\" cat-file -e \"${commit}:${manifest_path}\" 2>/dev/null; then\n mkdir -p \"$(dirname \"$dst_manifest\")\"\n git -C \"$checkout\" show \"${commit}:${manifest_path}\" > \"$dst_manifest\"\n fi\n\n scripts/vendor/apply-trims.sh \"$name\"\n\n rm -rf \"$tmp_dir\"\n\n echo \"hydrated $name -> $materialized_path\"\n done < <(list_crates)\n}\n\ncmd_pin() {\n local checkout commit\n checkout=\"$(ensure_checkout)\"\n commit=\"${1:-}\"\n if [[ -z \"$commit\" ]]; then\n commit=\"$(git -C \"$checkout\" rev-parse HEAD)\"\n fi\n if ! git -C \"$checkout\" cat-file -e \"${commit}^{commit}\" 2>/dev/null; then\n echo \"error: commit does not exist in checkout: $commit\"\n exit 1\n fi\n set_lock_commit \"$commit\"\n echo \"pinned $lock_file commit=$commit\"\n}\n\ncmd_status() {\n local repo_url branch checkout commit\n local origin_branch_ready=0\n repo_url=\"$(read_lock_value repo)\"\n branch=\"$(read_lock_value branch)\"\n checkout=\"$(read_lock_value checkout)\"\n commit=\"$(read_lock_value commit)\"\n\n echo \"lock_file: $lock_file\"\n echo \"repo: $repo_url\"\n echo \"branch: $branch\"\n echo \"checkout: $checkout\"\n echo \"pinned: ${commit:-<empty>}\"\n\n if [[ -d \"$checkout/.git\" ]]; then\n local head_sha\n if head_sha=\"$(git -C \"$checkout\" rev-parse --verify HEAD 2>/dev/null)\"; then\n echo \"head: $head_sha\"\n else\n echo \"head: <no commits yet>\"\n fi\n\n if git -C \"$checkout\" remote get-url origin >/dev/null 2>&1; then\n if fetch_origin_branch \"$checkout\" \"$branch\"; then\n origin_branch_ready=1\n else\n echo \"origin: unreachable (fetch failed)\"\n fi\n if [[ \"$origin_branch_ready\" == \"1\" ]] && git -C \"$checkout\" rev-parse --verify \"origin/$branch\" >/dev/null 2>&1; then\n local counts\n counts=\"$(git -C \"$checkout\" rev-list --left-right --count \"origin/$branch...HEAD\")\"\n echo \"origin: origin/$branch ($counts: behind ahead)\"\n fi\n fi\n else\n echo \"head: <checkout missing>\"\n fi\n\n if [[ -n \"$commit\" && -d \"$checkout/.git\" ]]; then\n if git -C \"$checkout\" cat-file -e \"${commit}^{commit}\" 2>/dev/null; then\n if [[ \"$origin_branch_ready\" == \"1\" ]] && git -C \"$checkout\" rev-parse --verify \"origin/$branch\" >/dev/null 2>&1; then\n if git -C \"$checkout\" merge-base --is-ancestor \"$commit\" \"origin/$branch\"; then\n echo \"pinned_origin: published on origin/$branch\"\n else\n echo \"pinned_origin: NOT published on origin/$branch\"\n fi\n else\n echo \"pinned_origin: unknown (origin/$branch unavailable)\"\n fi\n else\n echo \"pinned_origin: unknown (pinned commit missing from checkout)\"\n fi\n else\n echo \"pinned_origin: unknown\"\n fi\n\n echo\n echo \"crates:\"\n while IFS=$'\\t' read -r name repo_path manifest_path materialized_path; do\n [[ -n \"$name\" ]] || continue\n local_exists=\"no\"\n [[ -d \"$repo_root/$materialized_path\" ]] && local_exists=\"yes\"\n echo \"- $name\"\n echo \" repo_path: $repo_path\"\n echo \" manifest_path: $manifest_path\"\n echo \" materialized: $materialized_path (exists: $local_exists)\"\n done < <(list_crates)\n}\n\ncmd_push() {\n local checkout branch\n checkout=\"$(ensure_checkout)\"\n branch=\"$(read_lock_value branch)\"\n\n if [[ -z \"$(git -C \"$checkout\" status --porcelain)\" ]]; then\n :\n else\n echo \"error: checkout has uncommitted changes; commit before push\"\n exit 1\n fi\n\n git -C \"$checkout\" push origin \"HEAD:${branch}\"\n echo \"pushed ${checkout} HEAD -> origin/${branch}\"\n}\n\ncmd_verify_pinned_origin() {\n local checkout branch commit\n checkout=\"$(ensure_checkout)\"\n branch=\"$(read_lock_value branch)\"\n commit=\"$(read_lock_value commit)\"\n ensure_pinned_commit_published_on_origin \"$checkout\" \"$branch\" \"$commit\"\n}\n\ncase \"$command\" in\n init) cmd_init \"$@\" ;;\n create-remote) cmd_create_remote \"$@\" ;;\n import-local) cmd_import_local \"$@\" ;;\n hydrate) cmd_hydrate \"$@\" ;;\n pin) cmd_pin \"$@\" ;;\n status) cmd_status \"$@\" ;;\n verify-pinned-origin) cmd_verify_pinned_origin \"$@\" ;;\n push) cmd_push \"$@\" ;;\n *)\n usage\n exit 1\n ;;\nesac\n" }, { "path": "scripts/verify-install-latest-release.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n cat <<'EOF'\nUsage: verify-install-latest-release.sh [options]\n\nVerify that:\n curl -fsSL https://myflow.sh/install.sh | sh\n\ninstalls the current latest stable Flow release.\n\nOptions:\n --tag TAG Expected release tag (default: v<Cargo.toml version>)\n --repo OWNER/REPO GitHub repo to query (default: nikivdev/flow)\n --install-url URL Installer URL (default: https://myflow.sh/install.sh)\n --latest-timeout SECONDS Wait up to this many seconds for releases/latest to flip\n to the expected tag (default: 180)\n --poll-interval SECONDS Poll interval while waiting for releases/latest (default: 15)\n --skip-asset Skip the direct release asset verification step\n --keep-temp Keep temp directories instead of deleting them\n -h, --help Show this help\nEOF\n}\n\nROOT_DIR=\"$(cd -- \"$(dirname -- \"${BASH_SOURCE[0]}\")/..\" && pwd)\"\nREPO=\"nikivdev/flow\"\nINSTALL_URL=\"https://myflow.sh/install.sh\"\nEXPECTED_TAG=\"\"\nLATEST_TIMEOUT_SECS=180\nPOLL_INTERVAL_SECS=15\nSKIP_ASSET=0\nKEEP_TEMP=0\nTMP_HOME=\"\"\nTMP_ASSET_DIR=\"\"\n\nwhile [ \"$#\" -gt 0 ]; do\n case \"$1\" in\n --tag)\n EXPECTED_TAG=\"$2\"\n shift 2\n ;;\n --repo)\n REPO=\"$2\"\n shift 2\n ;;\n --install-url)\n INSTALL_URL=\"$2\"\n shift 2\n ;;\n --latest-timeout)\n LATEST_TIMEOUT_SECS=\"$2\"\n shift 2\n ;;\n --poll-interval)\n POLL_INTERVAL_SECS=\"$2\"\n shift 2\n ;;\n --skip-asset)\n SKIP_ASSET=1\n shift\n ;;\n --keep-temp)\n KEEP_TEMP=1\n shift\n ;;\n -h|--help)\n usage\n exit 0\n ;;\n *)\n echo \"Unknown option: $1\" >&2\n usage >&2\n exit 2\n ;;\n esac\ndone\n\ncleanup() {\n if [ \"$KEEP_TEMP\" = \"1\" ]; then\n return 0\n fi\n\n if [ -n \"$TMP_HOME\" ]; then\n rm -rf \"$TMP_HOME\"\n fi\n if [ -n \"$TMP_ASSET_DIR\" ]; then\n rm -rf \"$TMP_ASSET_DIR\"\n fi\n}\ntrap cleanup EXIT\n\nneed_cmd() {\n command -v \"$1\" >/dev/null 2>&1 || {\n echo \"missing required command: $1\" >&2\n exit 2\n }\n}\n\nnormalize_tag() {\n case \"$1\" in\n v*) printf '%s\\n' \"$1\" ;;\n *) printf 'v%s\\n' \"$1\" ;;\n esac\n}\n\nread_cargo_version() {\n python3 - <<'PY' \"$ROOT_DIR/Cargo.toml\"\nimport pathlib\nimport re\nimport sys\n\ntext = pathlib.Path(sys.argv[1]).read_text(encoding=\"utf-8\")\nmatch = re.search(r'^version\\s*=\\s*\"([^\"]+)\"', text, re.MULTILINE)\nif not match:\n raise SystemExit(\"failed to read Cargo.toml version\")\nprint(match.group(1))\nPY\n}\n\nread_latest_tag() {\n curl -fsSL \"https://api.github.com/repos/${REPO}/releases/latest\" \\\n | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"tag_name\"])'\n}\n\nread_binary_version() {\n \"$1\" --version | python3 -c 'import sys,re; text=sys.stdin.read(); m=re.search(r\"flow ([0-9][^ ]*)\", text); print(m.group(1) if m else \"\");'\n}\n\ndetect_target() {\n local os arch\n os=\"$(uname -s)\"\n arch=\"$(uname -m)\"\n\n case \"$os-$arch\" in\n Darwin-arm64|Darwin-aarch64) printf '%s\\n' \"aarch64-apple-darwin\" ;;\n Darwin-x86_64) printf '%s\\n' \"x86_64-apple-darwin\" ;;\n Linux-x86_64) printf '%s\\n' \"x86_64-unknown-linux-gnu\" ;;\n Linux-arm64|Linux-aarch64) printf '%s\\n' \"aarch64-unknown-linux-gnu\" ;;\n *)\n echo \"unsupported platform: $os-$arch\" >&2\n exit 2\n ;;\n esac\n}\n\nwait_for_expected_latest_tag() {\n local expected_tag=\"$1\"\n local last_seen=\"\"\n local start_ts now_ts\n\n start_ts=\"$(date +%s)\"\n while :; do\n last_seen=\"$(read_latest_tag)\"\n if [ \"$last_seen\" = \"$expected_tag\" ]; then\n printf '%s\\n' \"$last_seen\"\n return 0\n fi\n\n now_ts=\"$(date +%s)\"\n if [ $((now_ts - start_ts)) -ge \"$LATEST_TIMEOUT_SECS\" ]; then\n echo \"releases/latest still reports ${last_seen} after ${LATEST_TIMEOUT_SECS}s; expected ${expected_tag}\" >&2\n return 1\n fi\n\n sleep \"$POLL_INTERVAL_SECS\"\n done\n}\n\nneed_cmd curl\nneed_cmd python3\nneed_cmd mktemp\nneed_cmd tar\n\nif [ -z \"$EXPECTED_TAG\" ]; then\n EXPECTED_TAG=\"v$(read_cargo_version)\"\nelse\n EXPECTED_TAG=\"$(normalize_tag \"$EXPECTED_TAG\")\"\nfi\n\npython3 \"$ROOT_DIR/scripts/check_release_tag_version.py\" \"$EXPECTED_TAG\" >/dev/null\n\necho \"[verify-install] expected_tag=${EXPECTED_TAG}\"\necho \"[verify-install] repo=${REPO}\"\necho \"[verify-install] install_url=${INSTALL_URL}\"\n\nLATEST_TAG=\"$(wait_for_expected_latest_tag \"$EXPECTED_TAG\")\"\necho \"[verify-install] latest_tag=${LATEST_TAG}\"\n\nTMP_HOME=\"$(mktemp -d)\"\necho \"[verify-install] tmp_home=${TMP_HOME}\"\n\nHOME=\"$TMP_HOME\" PATH=\"/usr/bin:/bin:/usr/sbin:/sbin\" sh -c \\\n 'curl -fsSL \"$1\" | sh' -- \"$INSTALL_URL\"\n\nINSTALLED_BIN=\"${TMP_HOME}/.flow/bin/f\"\n[ -x \"$INSTALLED_BIN\" ] || {\n echo \"installed flow binary missing at ${INSTALLED_BIN}\" >&2\n exit 1\n}\n\nINSTALLED_VERSION=\"$(read_binary_version \"$INSTALLED_BIN\")\"\necho \"[verify-install] installed_version=${INSTALLED_VERSION}\"\nif [ \"v${INSTALLED_VERSION}\" != \"$EXPECTED_TAG\" ]; then\n echo \"fresh temp-home install reported ${INSTALLED_VERSION}, expected ${EXPECTED_TAG#v}\" >&2\n exit 1\nfi\n\nif [ \"$SKIP_ASSET\" != \"1\" ]; then\n TARGET=\"$(detect_target)\"\n TMP_ASSET_DIR=\"$(mktemp -d)\"\n echo \"[verify-install] asset_target=${TARGET}\"\n echo \"[verify-install] tmp_asset_dir=${TMP_ASSET_DIR}\"\n\n curl -fsSLo \"${TMP_ASSET_DIR}/flow.tar.gz\" \\\n \"https://github.com/${REPO}/releases/download/${LATEST_TAG}/flow-${TARGET}.tar.gz\"\n\n tar -xzf \"${TMP_ASSET_DIR}/flow.tar.gz\" -C \"${TMP_ASSET_DIR}\"\n ASSET_BIN=\"${TMP_ASSET_DIR}/f\"\n [ -x \"$ASSET_BIN\" ] || {\n echo \"release asset did not contain executable f\" >&2\n exit 1\n }\n\n ASSET_VERSION=\"$(read_binary_version \"$ASSET_BIN\")\"\n echo \"[verify-install] asset_version=${ASSET_VERSION}\"\n if [ \"v${ASSET_VERSION}\" != \"$EXPECTED_TAG\" ]; then\n echo \"direct release asset reported ${ASSET_VERSION}, expected ${EXPECTED_TAG#v}\" >&2\n exit 1\n fi\nfi\n\necho \"[verify-install] OK: installer, latest tag, and direct asset all match ${EXPECTED_TAG}\"\n" }, { "path": "spec/tracing-flow.md", "content": "# Process Tracking System for Flow CLI\n\n## Overview\n\nReplace the unreliable `sysinfo`-based cwd scanning with PID-based process tracking. Track PIDs when flow starts tasks, store them in persistent global state, and provide `f ps` and `f kill` commands.\n\n## Design Decisions\n\n1. **Storage**: `~/.config/flow/running.sqlite` (global SQLite store keyed by PID and config path)\n2. **Child Processes**: Use Unix process groups (PGID) to track and kill entire process trees\n3. **Cleanup**: Validate PIDs on read, remove stale entries automatically\n4. **Kill Signal**: SIGTERM first, SIGKILL after 5s timeout (configurable)\n\n## Data Structure\n\nSQLite table `running_processes` with:\n- `pid` primary key\n- `pgid`, `task_name`, `command`, `started_at`\n- `config_path`, `project_root`, `used_flox`, `project_name`\n\n## Implementation\n\n### New Module: `src/running.rs`\n\nPID tracking state management:\n- `RunningProcess` struct with pid, pgid, task_name, command, timestamps, paths\n- `RunningProcesses` struct mapping config paths to process lists\n- `load_running_processes()` - load and validate (remove dead PIDs)\n- `register_process()` / `unregister_process()` - add/remove entries\n- `get_project_processes()` - get processes for specific project\n- `process_alive()` - check if PID exists\n- `get_pgid()` - get process group ID for a PID\n\n### Modified: `src/tasks.rs`\n\nIn `run_command_with_tee()`:\n\n1. Create new process group on spawn:\n```rust\n#[cfg(unix)]\n{\n use std::os::unix::process::CommandExt;\n cmd.process_group(0);\n}\n```\n\n2. After spawn, register process with `running::register_process()`\n3. After wait completes, unregister with `running::unregister_process()`\n4. Pass task context (name, command, paths) through to enable registration\n\n### Modified: `src/cli.rs`\n\nEnhanced `ProcessOpts`:\n```rust\npub struct ProcessOpts {\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n #[arg(long)]\n pub all: bool, // Show all projects\n}\n```\n\nNew `KillOpts`:\n```rust\npub struct KillOpts {\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n pub task: Option<String>, // Kill by task name\n #[arg(long)]\n pub pid: Option<u32>, // Kill by PID\n #[arg(long)]\n pub all: bool, // Kill all for project\n #[arg(long, short)]\n pub force: bool, // SIGKILL immediately\n #[arg(long, default_value_t = 5)]\n pub timeout: u64, // Seconds before SIGKILL\n}\n```\n\nNew `Kill(KillOpts)` command in Commands enum.\n\n### Rewritten: `src/processes.rs`\n\nReplace sysinfo-based scanning with PID-based lookup:\n- `show_project_processes()` - list from the running-process store\n- `show_all_processes()` - list all projects\n- `kill_processes()` - dispatch to kill_by_pid/task/all\n- `terminate_process_group()` - SIGTERM then SIGKILL with timeout\n\n### Modified: `src/main.rs` and `src/lib.rs`\n\n- Added `running` module export\n- Added `Commands::Kill` handler\n\n## File Changes Summary\n\n| File | Action |\n|------|--------|\n| `src/running.rs` | NEW - PID tracking state |\n| `src/tasks.rs` | MODIFY - process groups, register PIDs |\n| `src/processes.rs` | REWRITE - PID-based lookup |\n| `src/cli.rs` | MODIFY - Kill command, enhance ProcessOpts |\n| `src/main.rs` | MODIFY - Kill handler |\n| `src/lib.rs` | MODIFY - export running module |\n| `Cargo.toml` | MODIFY - remove sysinfo dependency |\n\n## Usage\n\n```bash\nf ps # List processes for current project\nf ps --all # List all flow processes\nf kill dev # Kill task by name\nf kill --pid 12345 # Kill by PID\nf kill --all # Kill all for project\nf kill --force dev # SIGKILL immediately\n```\n\n## Edge Cases\n\n- **Process dies before unregister**: Cleaned up on next `load_running_processes()`\n- **Multiple tasks with same name**: All killed by `f kill <name>`\n- **Flow crashes**: Orphaned processes shown in `f ps`, killed on next run\n- **Race conditions**: SQLite WAL mode and write transactions prevent corruption\n" }, { "path": "src/activity_log.rs", "content": "use std::fs::{self, OpenOptions};\nuse std::io::{BufRead, BufReader, Seek, SeekFrom, Write};\n#[cfg(unix)]\nuse std::os::fd::AsRawFd;\nuse std::path::{Path, PathBuf};\n\nuse anyhow::{Context, Result};\nuse chrono::{Datelike, Local, Timelike};\nuse data_encoding::BASE32_NOPAD;\nuse serde::{Deserialize, Serialize};\n\nconst ACTIVITY_EVENT_VERSION: u32 = 1;\nconst HUMAN_LINE_MAX_CHARS: usize = 220;\nconst EVENT_ID_LEN: usize = 7;\n\n#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"lowercase\")]\npub enum ActivityStatus {\n Done,\n Changed,\n}\n\nimpl ActivityStatus {\n fn as_str(self) -> &'static str {\n match self {\n Self::Done => \"done\",\n Self::Changed => \"changed\",\n }\n }\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct ActivityEvent {\n pub version: u32,\n pub recorded_at_unix: u64,\n pub status: ActivityStatus,\n pub kind: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub route: Option<String>,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub scope: Option<String>,\n pub summary: String,\n pub event_id: String,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub dedupe_key: Option<String>,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub source: Option<String>,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub session_id: Option<String>,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub runtime_token: Option<String>,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub target_path: Option<String>,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub launch_path: Option<String>,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub artifact_path: Option<String>,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub payload_ref: Option<String>,\n}\n\nimpl ActivityEvent {\n pub fn done(kind: impl Into<String>, summary: impl Into<String>) -> Self {\n Self::new(ActivityStatus::Done, kind.into(), summary.into())\n }\n\n pub fn changed(kind: impl Into<String>, summary: impl Into<String>) -> Self {\n Self::new(ActivityStatus::Changed, kind.into(), summary.into())\n }\n\n fn new(status: ActivityStatus, kind: String, summary: String) -> Self {\n Self {\n version: ACTIVITY_EVENT_VERSION,\n recorded_at_unix: unix_now_secs(),\n status,\n kind,\n route: None,\n scope: None,\n summary,\n event_id: String::new(),\n dedupe_key: None,\n source: None,\n session_id: None,\n runtime_token: None,\n target_path: None,\n launch_path: None,\n artifact_path: None,\n payload_ref: None,\n }\n }\n}\n\n#[cfg(unix)]\nstruct FileLockGuard {\n fd: std::os::fd::RawFd,\n}\n\n#[cfg(unix)]\nimpl Drop for FileLockGuard {\n fn drop(&mut self) {\n let _ = unsafe { libc::flock(self.fd, libc::LOCK_UN) };\n }\n}\n\n#[cfg(unix)]\nfn acquire_file_lock(file: &std::fs::File) -> Result<FileLockGuard> {\n let fd = file.as_raw_fd();\n let status = unsafe { libc::flock(fd, libc::LOCK_EX) };\n if status == 0 {\n Ok(FileLockGuard { fd })\n } else {\n Err(std::io::Error::last_os_error()).context(\"failed to lock activity log file\")\n }\n}\n\n#[cfg(not(unix))]\nfn acquire_file_lock(_file: &std::fs::File) -> Result<()> {\n Ok(())\n}\n\nfn month_slug(month: u32) -> &'static str {\n match month {\n 1 => \"january\",\n 2 => \"february\",\n 3 => \"march\",\n 4 => \"april\",\n 5 => \"may\",\n 6 => \"june\",\n 7 => \"july\",\n 8 => \"august\",\n 9 => \"september\",\n 10 => \"october\",\n 11 => \"november\",\n 12 => \"december\",\n _ => \"unknown\",\n }\n}\n\nfn daily_log_root() -> PathBuf {\n if let Some(root) = std::env::var_os(\"FLOW_ACTIVITY_LOG_ROOT\").map(PathBuf::from) {\n return root;\n }\n std::env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"log\")\n}\n\nfn daily_log_path_at(root: &Path, now: chrono::DateTime<Local>) -> PathBuf {\n let year = now.format(\"%y\").to_string();\n let month = month_slug(now.month());\n let day = now.format(\"%d\").to_string();\n root.join(year).join(month).join(format!(\"{day}.md\"))\n}\n\nfn daily_events_path_at(root: &Path, now: chrono::DateTime<Local>) -> PathBuf {\n let year = now.format(\"%y\").to_string();\n let month = month_slug(now.month());\n let day = now.format(\"%d\").to_string();\n root.join(year)\n .join(month)\n .join(format!(\"{day}.events.jsonl\"))\n}\n\nfn daily_dedupe_index_dir_at(root: &Path, now: chrono::DateTime<Local>) -> PathBuf {\n let year = now.format(\"%y\").to_string();\n let month = month_slug(now.month());\n let day = now.format(\"%d\").to_string();\n root.join(year)\n .join(month)\n .join(format!(\"{day}.events.keys\"))\n}\n\nfn append_daily_event_at(\n root: &Path,\n now: chrono::DateTime<Local>,\n event: ActivityEvent,\n) -> Result<PathBuf> {\n let log_path = daily_log_path_at(root, now);\n let events_path = daily_events_path_at(root, now);\n let dedupe_index_dir = daily_dedupe_index_dir_at(root, now);\n if let Some(parent) = log_path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n\n let Some(event) = normalize_event(event) else {\n return Ok(log_path);\n };\n\n let mut sidecar = OpenOptions::new()\n .create(true)\n .read(true)\n .append(true)\n .open(&events_path)\n .with_context(|| format!(\"failed to open {}\", events_path.display()))?;\n let _lock = acquire_file_lock(&sidecar)?;\n\n if let Some(dedupe_key) = event.dedupe_key.as_deref()\n && dedupe_key_exists(&events_path, &dedupe_index_dir, dedupe_key)?\n {\n return Ok(log_path);\n }\n\n sidecar\n .seek(SeekFrom::End(0))\n .with_context(|| format!(\"failed to seek {}\", events_path.display()))?;\n serde_json::to_writer(&mut sidecar, &event)\n .with_context(|| format!(\"failed to encode {}\", events_path.display()))?;\n sidecar\n .write_all(b\"\\n\")\n .with_context(|| format!(\"failed to terminate {}\", events_path.display()))?;\n sidecar\n .flush()\n .with_context(|| format!(\"failed to flush {}\", events_path.display()))?;\n\n let mut log_file = OpenOptions::new()\n .create(true)\n .append(true)\n .open(&log_path)\n .with_context(|| format!(\"failed to open {}\", log_path.display()))?;\n writeln!(log_file, \"{}\", render_human_line(&event, now))\n .with_context(|| format!(\"failed to append {}\", log_path.display()))?;\n log_file\n .flush()\n .with_context(|| format!(\"failed to flush {}\", log_path.display()))?;\n if let Some(dedupe_key) = event.dedupe_key.as_deref() {\n persist_dedupe_key(&dedupe_index_dir, dedupe_key)?;\n }\n Ok(log_path)\n}\n\nfn normalize_event(mut event: ActivityEvent) -> Option<ActivityEvent> {\n if event.version == 0 {\n event.version = ACTIVITY_EVENT_VERSION;\n }\n if event.recorded_at_unix == 0 {\n event.recorded_at_unix = unix_now_secs();\n }\n\n event.kind = compact_token(&event.kind, 48);\n if event.kind.is_empty() {\n return None;\n }\n\n event.summary = normalize_text(&event.summary);\n if event.summary.is_empty() {\n return None;\n }\n\n event.route = event\n .route\n .take()\n .map(|value| compact_token(&value, 32))\n .filter(|value| !value.is_empty());\n event.scope = event\n .scope\n .take()\n .map(|value| compact_token(&value, 24))\n .filter(|value| !value.is_empty())\n .or_else(|| derive_scope_from_event(&event));\n event.source = event\n .source\n .take()\n .map(|value| compact_token(&value, 32))\n .filter(|value| !value.is_empty());\n event.session_id = event\n .session_id\n .take()\n .map(|value| normalize_text(&value))\n .filter(|value| !value.is_empty());\n event.runtime_token = event\n .runtime_token\n .take()\n .map(|value| compact_token(&value, 16))\n .filter(|value| !value.is_empty());\n event.target_path = event\n .target_path\n .take()\n .map(|value| normalize_text(&value))\n .filter(|value| !value.is_empty());\n event.launch_path = event\n .launch_path\n .take()\n .map(|value| normalize_text(&value))\n .filter(|value| !value.is_empty());\n event.artifact_path = event\n .artifact_path\n .take()\n .map(|value| normalize_text(&value))\n .filter(|value| !value.is_empty());\n event.payload_ref = event\n .payload_ref\n .take()\n .map(|value| compact_token(&value, 24))\n .filter(|value| !value.is_empty());\n event.dedupe_key = event\n .dedupe_key\n .take()\n .map(|value| normalize_text(&value))\n .filter(|value| !value.is_empty());\n\n if event.event_id.trim().is_empty() {\n event.event_id = short_hash(&canonical_event_identity(&event), EVENT_ID_LEN);\n }\n\n Some(event)\n}\n\nfn render_human_line(event: &ActivityEvent, now: chrono::DateTime<Local>) -> String {\n let stamp = format!(\"{:02}:{:02}\", now.hour(), now.minute());\n let kind = render_kind(event);\n let prefix = if let Some(scope) = event.scope.as_deref() {\n format!(\"{stamp}: [{}] {kind} {scope}: \", event.status.as_str())\n } else {\n format!(\"{stamp}: [{}] {kind}: \", event.status.as_str())\n };\n let suffix = render_tags(event);\n let summary_budget = HUMAN_LINE_MAX_CHARS\n .saturating_sub(prefix.chars().count())\n .saturating_sub(suffix.chars().count())\n .max(24);\n let summary = truncate_chars(&event.summary, summary_budget);\n format!(\"{prefix}{summary}{suffix}\")\n}\n\nfn render_kind(event: &ActivityEvent) -> String {\n match event.route.as_deref() {\n Some(route) => format!(\"{}[{route}]\", event.kind),\n None => event.kind.clone(),\n }\n}\n\nfn render_tags(event: &ActivityEvent) -> String {\n let mut tags = Vec::new();\n if let Some(session_id) = event.session_id.as_deref() {\n tags.push(format!(\"s:{}\", truncate_session_id(session_id)));\n }\n if let Some(runtime_token) = event.runtime_token.as_deref() {\n tags.push(format!(\"r:{runtime_token}\"));\n }\n tags.push(format!(\"e:{}\", event.event_id));\n format!(\" [{}]\", tags.join(\" \"))\n}\n\nfn dedupe_key_exists(events_path: &Path, index_dir: &Path, dedupe_key: &str) -> Result<bool> {\n if dedupe_index_contains(index_dir, dedupe_key)? {\n return Ok(true);\n }\n if !sidecar_contains_dedupe_key(events_path, dedupe_key)? {\n return Ok(false);\n }\n persist_dedupe_key(index_dir, dedupe_key)?;\n Ok(true)\n}\n\nfn dedupe_index_contains(index_dir: &Path, dedupe_key: &str) -> Result<bool> {\n let marker_path = dedupe_marker_path(index_dir, dedupe_key);\n if !marker_path.exists() {\n return Ok(false);\n }\n let stored = fs::read_to_string(&marker_path)\n .with_context(|| format!(\"failed to read {}\", marker_path.display()))?;\n Ok(stored.trim_end() == dedupe_key)\n}\n\nfn persist_dedupe_key(index_dir: &Path, dedupe_key: &str) -> Result<()> {\n fs::create_dir_all(index_dir)\n .with_context(|| format!(\"failed to create {}\", index_dir.display()))?;\n let marker_path = dedupe_marker_path(index_dir, dedupe_key);\n match OpenOptions::new()\n .create_new(true)\n .write(true)\n .open(&marker_path)\n {\n Ok(mut file) => {\n file.write_all(dedupe_key.as_bytes())\n .with_context(|| format!(\"failed to write {}\", marker_path.display()))?;\n file.write_all(b\"\\n\")\n .with_context(|| format!(\"failed to terminate {}\", marker_path.display()))?;\n file.flush()\n .with_context(|| format!(\"failed to flush {}\", marker_path.display()))?;\n Ok(())\n }\n Err(err) if err.kind() == std::io::ErrorKind::AlreadyExists => Ok(()),\n Err(err) => Err(err).with_context(|| format!(\"failed to create {}\", marker_path.display())),\n }\n}\n\nfn dedupe_marker_path(index_dir: &Path, dedupe_key: &str) -> PathBuf {\n let hash = blake3::hash(dedupe_key.as_bytes()).to_hex().to_string();\n index_dir.join(format!(\"{hash}.key\"))\n}\n\nfn sidecar_contains_dedupe_key(path: &Path, dedupe_key: &str) -> Result<bool> {\n if !path.exists() {\n return Ok(false);\n }\n\n let file =\n std::fs::File::open(path).with_context(|| format!(\"failed to open {}\", path.display()))?;\n for line in BufReader::new(file).lines() {\n let line = match line {\n Ok(value) => value,\n Err(_) => continue,\n };\n let trimmed = line.trim();\n if trimmed.is_empty() {\n continue;\n }\n let Ok(event) = serde_json::from_str::<ActivityEvent>(trimmed) else {\n continue;\n };\n if event.dedupe_key.as_deref() == Some(dedupe_key) {\n return Ok(true);\n }\n }\n\n Ok(false)\n}\n\nfn derive_scope_from_event(event: &ActivityEvent) -> Option<String> {\n event\n .target_path\n .as_deref()\n .and_then(path_scope_label)\n .or_else(|| event.launch_path.as_deref().and_then(path_scope_label))\n .or_else(|| event.artifact_path.as_deref().and_then(path_scope_label))\n}\n\nfn path_scope_label(path: &str) -> Option<String> {\n let home = dirs::home_dir()?;\n let path = Path::new(path);\n\n if let Ok(stripped) = path.strip_prefix(home.join(\"code\")) {\n let name = stripped.components().next()?.as_os_str().to_str()?;\n return Some(name.to_string());\n }\n\n if let Ok(stripped) = path.strip_prefix(home.join(\"repos\")) {\n let mut parts = stripped.components();\n let org = parts.next()?.as_os_str().to_str()?;\n let repo = parts.next()?.as_os_str().to_str()?;\n if org == \"openai\" {\n return Some(format!(\"{org}/{repo}\"));\n }\n return Some(repo.to_string());\n }\n\n if path.starts_with(home.join(\"config\")) {\n return Some(\"config\".to_string());\n }\n if path.starts_with(home.join(\"docs\")) {\n return Some(\"docs\".to_string());\n }\n if path.starts_with(home.join(\"plan\")) {\n return Some(\"plan\".to_string());\n }\n\n path.file_stem()\n .and_then(|value| value.to_str())\n .map(|value| value.to_string())\n}\n\nfn canonical_event_identity(event: &ActivityEvent) -> String {\n [\n event.version.to_string(),\n event.recorded_at_unix.to_string(),\n event.status.as_str().to_string(),\n event.kind.clone(),\n event.route.clone().unwrap_or_default(),\n event.scope.clone().unwrap_or_default(),\n event.summary.clone(),\n event.session_id.clone().unwrap_or_default(),\n event.runtime_token.clone().unwrap_or_default(),\n event.target_path.clone().unwrap_or_default(),\n event.launch_path.clone().unwrap_or_default(),\n event.artifact_path.clone().unwrap_or_default(),\n event.payload_ref.clone().unwrap_or_default(),\n ]\n .join(\"|\")\n}\n\nfn normalize_text(value: &str) -> String {\n value.split_whitespace().collect::<Vec<_>>().join(\" \")\n}\n\nfn compact_token(value: &str, max_chars: usize) -> String {\n truncate_chars(&normalize_text(value), max_chars)\n}\n\nfn truncate_chars(value: &str, max_chars: usize) -> String {\n let mut out = value.trim().to_string();\n if out.chars().count() > max_chars {\n out = out\n .chars()\n .take(max_chars.saturating_sub(1))\n .collect::<String>();\n out.push('…');\n }\n out\n}\n\nfn truncate_session_id(value: &str) -> String {\n value.chars().take(8).collect()\n}\n\nfn short_hash(value: &str, len: usize) -> String {\n let hash = blake3::hash(value.as_bytes());\n let encoded = BASE32_NOPAD.encode(hash.as_bytes()).to_ascii_lowercase();\n encoded[..len.min(encoded.len())].to_string()\n}\n\nfn unix_now_secs() -> u64 {\n std::time::SystemTime::now()\n .duration_since(std::time::UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0)\n}\n\npub fn current_daily_log_path() -> PathBuf {\n daily_log_path_at(&daily_log_root(), Local::now())\n}\n\npub fn current_daily_events_path() -> PathBuf {\n daily_events_path_at(&daily_log_root(), Local::now())\n}\n\npub fn append_daily_event(event: ActivityEvent) -> Result<()> {\n if matches!(\n std::env::var(\"FLOW_DISABLE_ACTIVITY_LOG\").ok().as_deref(),\n Some(\"1\" | \"true\" | \"yes\" | \"on\")\n ) {\n return Ok(());\n }\n\n let _ = append_daily_event_at(&daily_log_root(), Local::now(), event)?;\n Ok(())\n}\n\npub fn append_daily_bullet(message: &str) -> Result<()> {\n append_daily_event(ActivityEvent::done(\"note\", message))\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use chrono::TimeZone;\n use tempfile::tempdir;\n\n #[test]\n fn path_uses_expected_year_month_day_layout() {\n let root = PathBuf::from(\"/tmp/activity-root\");\n let dt = chrono::Local\n .with_ymd_and_hms(2026, 3, 17, 14, 30, 0)\n .single()\n .expect(\"local datetime\");\n let path = daily_log_path_at(&root, dt);\n assert_eq!(path, PathBuf::from(\"/tmp/activity-root/26/march/17.md\"));\n let events_path = daily_events_path_at(&root, dt);\n assert_eq!(\n events_path,\n PathBuf::from(\"/tmp/activity-root/26/march/17.events.jsonl\")\n );\n }\n\n #[test]\n fn append_daily_event_writes_human_line_and_sidecar() {\n let temp = tempdir().expect(\"tempdir\");\n let now = chrono::Local\n .with_ymd_and_hms(2026, 3, 17, 14, 30, 0)\n .single()\n .expect(\"local datetime\");\n let mut event = ActivityEvent::done(\"codex.resolve\", \"summarize codex memory work\");\n event.route = Some(\"new-with-context\".to_string());\n event.target_path = Some(\"/Users/nikitavoloboev/docs\".to_string());\n event.session_id = Some(\"019cd046-8b33-73c2-abfd-88f49d26eba0\".to_string());\n event.dedupe_key = Some(\"dedupe-1\".to_string());\n\n let path = append_daily_event_at(temp.path(), now, event).expect(\"append\");\n let body = fs::read_to_string(&path).expect(\"read log\");\n assert!(body.starts_with(\"14:30: [done] codex.resolve[new-with-context] docs:\"));\n assert!(body.contains(\"summarize codex memory work\"));\n assert!(body.contains(\"[s:019cd046 \"));\n assert!(body.contains(\"e:\"));\n\n let events_body =\n fs::read_to_string(temp.path().join(\"26/march/17.events.jsonl\")).expect(\"sidecar\");\n let stored: ActivityEvent =\n serde_json::from_str(events_body.lines().next().expect(\"stored event line\"))\n .expect(\"decode sidecar event\");\n assert_eq!(stored.kind, \"codex.resolve\");\n assert_eq!(stored.scope.as_deref(), Some(\"docs\"));\n assert_eq!(stored.dedupe_key.as_deref(), Some(\"dedupe-1\"));\n assert!(!stored.event_id.is_empty());\n }\n\n #[test]\n fn append_daily_event_dedupes_when_explicit_key_matches() {\n let temp = tempdir().expect(\"tempdir\");\n let now = chrono::Local\n .with_ymd_and_hms(2026, 3, 17, 14, 30, 0)\n .single()\n .expect(\"local datetime\");\n\n let mut first = ActivityEvent::done(\"codex.done\", \"implement activity logging\");\n first.dedupe_key = Some(\"codex:done:1\".to_string());\n first.session_id = Some(\"019cd046-8b33-73c2-abfd-88f49d26eba0\".to_string());\n first.target_path = Some(\"/Users/nikitavoloboev/code/flow\".to_string());\n\n let mut second = ActivityEvent::done(\"codex.done\", \"implement activity logging\");\n second.dedupe_key = Some(\"codex:done:1\".to_string());\n second.session_id = Some(\"019cd046-8b33-73c2-abfd-88f49d26eba0\".to_string());\n second.target_path = Some(\"/Users/nikitavoloboev/code/flow\".to_string());\n second.recorded_at_unix += 10;\n\n append_daily_event_at(temp.path(), now, first).expect(\"first append\");\n append_daily_event_at(temp.path(), now, second).expect(\"second append\");\n\n let body = fs::read_to_string(temp.path().join(\"26/march/17.md\")).expect(\"read log\");\n assert_eq!(body.lines().count(), 1);\n let sidecar =\n fs::read_to_string(temp.path().join(\"26/march/17.events.jsonl\")).expect(\"sidecar\");\n assert_eq!(sidecar.lines().count(), 1);\n }\n\n #[test]\n fn append_daily_event_recovers_dedupe_index_from_sidecar() {\n let temp = tempdir().expect(\"tempdir\");\n let now = chrono::Local\n .with_ymd_and_hms(2026, 3, 17, 14, 30, 0)\n .single()\n .expect(\"local datetime\");\n\n let mut first = ActivityEvent::done(\"codex.done\", \"implement activity logging\");\n first.dedupe_key = Some(\"codex:done:recover\".to_string());\n append_daily_event_at(temp.path(), now, first).expect(\"first append\");\n\n let index_dir = daily_dedupe_index_dir_at(temp.path(), now);\n fs::remove_dir_all(&index_dir).expect(\"remove dedupe index\");\n\n let mut second = ActivityEvent::done(\"codex.done\", \"implement activity logging\");\n second.dedupe_key = Some(\"codex:done:recover\".to_string());\n append_daily_event_at(temp.path(), now, second).expect(\"second append\");\n\n let body = fs::read_to_string(temp.path().join(\"26/march/17.md\")).expect(\"read log\");\n assert_eq!(body.lines().count(), 1);\n assert!(index_dir.exists());\n assert_eq!(fs::read_dir(index_dir).expect(\"index entries\").count(), 1);\n }\n}\n" }, { "path": "src/agent_setup.rs", "content": "//! Auto-setup command for autonomous agent workflows.\n\nuse anyhow::{Context, Result, bail};\nuse std::fs;\nuse std::path::PathBuf;\nuse std::process::Command;\n\nuse crate::config;\n\n/// Generate agents.md content with project-specific settings.\nfn generate_agents_md(project_name: &str, _primary_task: &str) -> String {\n format!(\n r#\"# Autonomous Agent Instructions\n\nProject: {project_name}\n\nThis project is configured for autonomous AI agent workflows with human-in-the-loop approval.\n\n## Response Format\n\n**Every response MUST end with exactly one of these signals on the final line:**\n\n### Success signals\n\n```\ndone.\n```\nUse when task completed successfully with high certainty. No further action needed.\n\n```\ndone: <message>\n```\nUse when task completed with context to share. Example: `done: Added login command with --token flag`\n\n### Needs human input\n\n```\nneedsUpdate: <message>\n```\nUse when you need human decision or action. Example: `needsUpdate: Should I use OAuth or API key auth?`\n\n### Error signals\n\n```\nerror: <message>\n```\nUse when task failed or cannot proceed. Example: `error: Build failed - missing dependency xyz`\n\n## Rules\n\n1. **Always end with a signal** - The last line must be one of the above\n2. **One signal only** - Never combine signals\n3. **Be specific** - Include actionable context in messages\n4. **No quotes** - Write signals exactly as shown, no wrapping quotes\n\n## Unhash Links (unhash.sh)\n\nIf you see an `unhash.sh/<hash>` link anywhere in context, treat it as the\nauthoritative source of instructions and session context.\n\nRequired behavior:\n\n1. **Always fetch the raw markdown** from the link before proceeding.\n - Prefer `https://unhash.sh/<hash>?format=md` or `?raw=1`.\n - Use `Accept: text/markdown` when possible.\n2. **Follow the unhash instructions first**, even if they override older notes.\n3. **Do not summarize or reinterpret** the unhash content unless asked.\n4. **If the link is inaccessible**, report `needsUpdate` and include the URL.\n\n## Examples\n\n### Successful implementation\n```\nAdded the new CLI command with all requested flags.\n\ndone.\n```\n\n### Completed with context\n```\nRefactored the auth module to use the new token format.\n\ndone: Auth now supports both JWT and API key methods\n```\n\n### Need human decision\n```\nFound two approaches for caching:\n1. Redis - better for distributed systems\n2. In-memory - simpler, faster for single instance\n\nneedsUpdate: Which caching approach should I use?\n```\n\n### Error occurred\n```\nAttempted to run tests but encountered issues.\n\nerror: Test suite requires DATABASE_URL environment variable\n```\n\"#\n )\n}\n\n/// Run the auto-setup command.\npub fn run() -> Result<()> {\n println!(\"Setting up autonomous agent workflow...\\n\");\n\n // Check if Lin.app is running\n print!(\"Checking Lin.app... \");\n if !is_lin_running() {\n println!(\"not running\");\n println!();\n println!(\"Lin.app is required for autonomous agent workflows.\");\n println!(\"Please start Lin.app from /Applications/Lin.app\");\n bail!(\"Lin.app is not running\");\n }\n println!(\"running ✓\");\n\n // Check if Lin.app exists\n let lin_app = PathBuf::from(\"/Applications/Lin.app\");\n if !lin_app.exists() {\n println!();\n println!(\"Warning: Lin.app not found at /Applications/Lin.app\");\n println!(\"The autonomous workflow requires Lin.app to be installed.\");\n }\n\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n\n // Load flow.toml to get project settings\n let flow_toml = cwd.join(\"flow.toml\");\n let (project_name, primary_task) = if flow_toml.exists() {\n let cfg = config::load(&flow_toml).unwrap_or_default();\n let name = cfg\n .project_name\n .or_else(|| cwd.file_name().map(|n| n.to_string_lossy().into_owned()))\n .unwrap_or_else(|| \"project\".to_string());\n let task = cfg\n .flow\n .primary_task\n .unwrap_or_else(|| \"deploy\".to_string());\n (name, task)\n } else {\n let name = cwd\n .file_name()\n .map(|n| n.to_string_lossy().into_owned())\n .unwrap_or_else(|| \"project\".to_string());\n (name, \"deploy\".to_string())\n };\n\n print!(\"Project: {} \", project_name);\n println!(\"(primary task: {})\", primary_task);\n\n // Generate customized agents.md\n let agents_content = generate_agents_md(&project_name, &primary_task);\n\n // Create .claude directory if needed\n let claude_dir = cwd.join(\".claude\");\n fs::create_dir_all(&claude_dir).context(\"failed to create .claude directory\")?;\n\n // Write agents.md\n let agents_path = claude_dir.join(\"agents.md\");\n let existed = agents_path.exists();\n\n fs::write(&agents_path, &agents_content).context(\"failed to write agents.md\")?;\n\n if existed {\n println!(\"Updated .claude/agents.md ✓\");\n } else {\n println!(\"Created .claude/agents.md ✓\");\n }\n\n // Also create for Codex (.codex/agents.md)\n let codex_dir = cwd.join(\".codex\");\n fs::create_dir_all(&codex_dir).context(\"failed to create .codex directory\")?;\n\n let codex_agents_path = codex_dir.join(\"agents.md\");\n let codex_existed = codex_agents_path.exists();\n\n fs::write(&codex_agents_path, &agents_content).context(\"failed to write .codex/agents.md\")?;\n\n if codex_existed {\n println!(\"Updated .codex/agents.md ✓\");\n } else {\n println!(\"Created .codex/agents.md ✓\");\n }\n\n println!();\n println!(\"Autonomous agent workflow is ready!\");\n println!();\n println!(\"Claude Code and Codex will now end responses with:\");\n println!(\" done. - Task completed successfully\");\n println!(\" done: <msg> - Completed with context\");\n println!(\" needsUpdate: <msg> - Needs human decision\");\n println!(\" error: <msg> - Task failed\");\n println!();\n println!(\"Lin.app will detect these signals and show appropriate widgets.\");\n\n Ok(())\n}\n\n/// Check if Lin.app is running.\nfn is_lin_running() -> bool {\n let output = Command::new(\"pgrep\").args([\"-x\", \"Lin\"]).output();\n\n match output {\n Ok(out) => out.status.success(),\n Err(_) => false,\n }\n}\n" }, { "path": "src/agents.rs", "content": "//! Gen agents integration.\n//!\n//! Invokes gen AI agents from the flow CLI.\n//! Gen is opencode with GEN_MODE=1, providing flow integration.\n\nuse std::collections::HashSet;\nuse std::fs;\nuse std::io::{self, BufRead, BufReader, IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\nuse ignore::WalkBuilder;\nuse serde_json::Value;\nuse shell_words;\n\nuse crate::cli::{AgentsAction, AgentsCommand};\nuse crate::config;\nuse crate::discover;\n\n/// Default gen repository relative path under home dir.\nconst DEFAULT_GEN_REPO_REL: &str = \"org/gen/gen\";\n\nconst FLOW_AGENT_NAME: &str = \"flow\";\n\n/// Run the agents subcommand.\npub fn run(cmd: AgentsCommand) -> Result<()> {\n match cmd.action {\n Some(AgentsAction::List) => list_agents(),\n Some(AgentsAction::Run { agent, prompt }) => run_agent(&agent, prompt),\n Some(AgentsAction::Global { agent, prompt }) => run_agent_optional(&agent, prompt),\n Some(AgentsAction::Copy { agent }) => copy_agent_instructions(agent.as_deref()),\n Some(AgentsAction::Rules { profile, repo }) => {\n run_agents_rules(profile.as_deref(), repo.as_deref())\n }\n None => {\n if cmd.agent.is_empty() {\n run_fuzzy_agents()\n } else {\n let agent = &cmd.agent[0];\n let prompt = if cmd.agent.len() > 1 {\n Some(cmd.agent[1..].to_vec())\n } else {\n None\n };\n run_agent_optional(agent, prompt)\n }\n }\n }\n}\n\n/// Find gen - either the installed binary or the repo.\nfn find_gen() -> Option<GenLocation> {\n // Check ~/.local/bin/gen first (installed via `f install` in gen repo)\n if let Some(home) = dirs::home_dir() {\n let local_bin = home.join(\".local/bin/gen\");\n if local_bin.exists() {\n return Some(GenLocation::Binary(local_bin));\n }\n }\n\n // Check PATH\n if let Ok(path) = which::which(\"gen\") {\n return Some(GenLocation::Binary(path));\n }\n\n // Check GEN_REPO env var\n if let Ok(env_repo) = std::env::var(\"GEN_REPO\") {\n let repo = PathBuf::from(&env_repo);\n if repo.join(\"packages/opencode/src/index.ts\").exists() {\n return Some(GenLocation::Repo(repo));\n }\n }\n\n // Fall back to repo location under home dir\n if let Some(repo) = default_gen_repo() {\n if repo.join(\"packages/opencode/src/index.ts\").exists() {\n return Some(GenLocation::Repo(repo));\n }\n }\n\n None\n}\n\nenum GenLocation {\n Binary(PathBuf),\n Repo(PathBuf),\n}\n\n/// List available agents.\nfn list_agents() -> Result<()> {\n println!(\"Flow agents:\\n\");\n println!(\n \" flow - Flow-aware agent with full context about flow.toml, tasks, and CLI\"\n );\n println!(\" Knows schema, best practices, and can create/modify tasks\");\n println!();\n\n println!(\"Gen agents (project + global config):\\n\");\n if let Some(gen_loc) = find_gen() {\n if let Err(err) = list_gen_agents(&gen_loc) {\n println!(\"⚠ failed to list gen agents: {err}\");\n }\n } else {\n let default_repo = default_gen_repo()\n .map(|p| p.display().to_string())\n .unwrap_or_else(|| format!(\"~/{}\", DEFAULT_GEN_REPO_REL));\n println!(\"⚠ gen not found. Install with:\");\n println!(\" cd {} && f install\", default_repo);\n println!(\" # or set GEN_REPO environment variable\");\n }\n\n println!();\n println!(\"Usage:\");\n println!(\" f agents # Fuzzy search agents\");\n println!(\" f agents run <agent> \\\"prompt\\\"\");\n println!(\" f agents <agent> # Run agent (prompts for input)\");\n println!(\" f agents rules # Fuzzy pick agents.md profile\");\n println!(\" f agents rules <profile> # Activate profile\");\n println!();\n\n Ok(())\n}\n\nfn run_agents_rules(profile: Option<&str>, repo: Option<&str>) -> Result<()> {\n let mut repo_path = repo\n .map(PathBuf::from)\n .unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\")));\n\n let mut chosen_profile = profile.map(|value| value.to_string());\n if repo.is_none() {\n if let Some(candidate) = profile {\n let candidate_path = PathBuf::from(candidate);\n if candidate_path.is_dir() {\n repo_path = candidate_path;\n chosen_profile = None;\n }\n }\n }\n\n let agents_dir = repo_path.join(\"agents\");\n if !agents_dir.is_dir() {\n println!(\"No agents/ directory in {}\", repo_path.display());\n return Ok(());\n }\n\n let mut profiles = list_agents_profiles(&agents_dir)?;\n if profiles.is_empty() {\n println!(\"No profiles found in {}\", agents_dir.display());\n return Ok(());\n }\n profiles.sort();\n\n if let Some(name) = &chosen_profile {\n if !profiles.iter().any(|p| p == name) {\n bail!(\"Missing profile: {}\", name);\n }\n } else {\n chosen_profile = select_agents_profile(&profiles)?;\n }\n\n let Some(profile_name) = chosen_profile else {\n println!(\"No profile selected.\");\n return Ok(());\n };\n\n let source_lower = agents_dir.join(format!(\"agents.{profile_name}.md\"));\n let source_upper = agents_dir.join(format!(\"AGENTS.{profile_name}.md\"));\n let source = if source_lower.is_file() {\n source_lower\n } else {\n source_upper\n };\n if !source.is_file() {\n bail!(\"Missing profile file: {}\", source.display());\n }\n let target = repo_path.join(\"agents.md\");\n fs::copy(&source, &target).with_context(|| {\n format!(\n \"failed to copy {} to {}\",\n source.display(),\n target.display()\n )\n })?;\n\n let default_path = agents_dir.join(\".default\");\n fs::write(&default_path, &profile_name)\n .with_context(|| format!(\"failed to write {}\", default_path.display()))?;\n\n println!(\"Activated agents.md -> {}\", source.display());\n println!(\"Default profile set to: {}\", profile_name);\n Ok(())\n}\n\nfn list_agents_profiles(agents_dir: &Path) -> Result<Vec<String>> {\n let mut profiles = HashSet::new();\n for entry in fs::read_dir(agents_dir)? {\n let entry = entry?;\n let file_name = entry.file_name();\n let file_name = file_name.to_string_lossy();\n let trimmed = if file_name.starts_with(\"agents.\") && file_name.ends_with(\".md\") {\n file_name\n .trim_start_matches(\"agents.\")\n .trim_end_matches(\".md\")\n } else if file_name.starts_with(\"AGENTS.\") && file_name.ends_with(\".md\") {\n file_name\n .trim_start_matches(\"AGENTS.\")\n .trim_end_matches(\".md\")\n } else {\n continue;\n };\n if !trimmed.is_empty() {\n profiles.insert(trimmed.to_string());\n }\n }\n Ok(profiles.into_iter().collect())\n}\n\nfn select_agents_profile(profiles: &[String]) -> Result<Option<String>> {\n if which::which(\"fzf\").is_err() {\n println!(\"fzf not found on PATH – install it to use fuzzy selection.\");\n return prompt_agents_profile(profiles).map(Some);\n }\n\n let mut child = Command::new(\"fzf\")\n .arg(\"--prompt\")\n .arg(\"agents rules> \")\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n {\n let stdin = child.stdin.as_mut().context(\"failed to open fzf stdin\")?;\n for profile in profiles {\n writeln!(stdin, \"{}\", profile)?;\n }\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n let selection = String::from_utf8(output.stdout)\n .context(\"fzf output was not valid UTF-8\")?\n .lines()\n .next()\n .unwrap_or(\"\")\n .trim()\n .to_string();\n if selection.is_empty() {\n Ok(None)\n } else {\n Ok(Some(selection))\n }\n}\n\nfn prompt_agents_profile(profiles: &[String]) -> Result<String> {\n println!(\"Select an agents profile:\");\n for (index, profile) in profiles.iter().enumerate() {\n println!(\" {}) {}\", index + 1, profile);\n }\n print!(\"choice> \");\n io::stdout().flush()?;\n\n let stdin = io::stdin();\n let line = stdin.lock().lines().next();\n let input = match line {\n Some(Ok(value)) => value.trim().to_string(),\n _ => \"\".to_string(),\n };\n if input.is_empty() {\n bail!(\"No profile selected.\");\n }\n let idx: usize = input.parse().context(\"invalid selection\")?;\n if idx == 0 || idx > profiles.len() {\n bail!(\"Selection out of range.\");\n }\n Ok(profiles[idx - 1].clone())\n}\n\nstruct AgentEntry {\n name: String,\n display: String,\n path: Option<PathBuf>,\n}\n\nstruct FzfAgentResult<'a> {\n entry: &'a AgentEntry,\n with_args: bool,\n}\n\nfn run_fuzzy_agents() -> Result<()> {\n let entries = build_agent_entries()?;\n if entries.is_empty() {\n println!(\"No agents available.\");\n return Ok(());\n }\n\n if which::which(\"fzf\").is_err() {\n println!(\"fzf not found on PATH – install it to use fuzzy selection.\");\n list_agents()?;\n return Ok(());\n }\n\n if let Some(result) = run_agent_fzf(&entries)? {\n let prompt_args = if result.with_args {\n prompt_for_agent_prompt(&result.entry.name)?\n } else if DIR_AGENTS.contains(&result.entry.name.as_str()) {\n // Directory-based agents use cwd by default\n let cwd = std::env::current_dir()\n .map(|p| p.to_string_lossy().to_string())\n .unwrap_or_else(|_| \".\".to_string());\n vec![cwd]\n } else {\n prompt_for_agent_prompt(&result.entry.name)?\n };\n if prompt_args.is_empty() {\n bail!(\"No prompt provided.\");\n }\n run_agent(&result.entry.name, prompt_args)?;\n }\n\n Ok(())\n}\n\n/// Copy agent instructions to clipboard.\nfn copy_agent_instructions(agent_name: Option<&str>) -> Result<()> {\n let entries = build_agent_entries()?;\n if entries.is_empty() {\n println!(\"No agents available.\");\n return Ok(());\n }\n\n let selected = if let Some(name) = agent_name {\n // Find agent by name\n entries\n .iter()\n .find(|e| e.name == name)\n .ok_or_else(|| anyhow::anyhow!(\"Agent '{}' not found\", name))?\n } else {\n // Fuzzy select\n if which::which(\"fzf\").is_err() {\n bail!(\"fzf not found on PATH – install it to use fuzzy selection.\");\n }\n match run_agent_fzf_simple(&entries)? {\n Some(entry) => entry,\n None => return Ok(()),\n }\n };\n\n // Get agent file content\n let content = get_agent_content(&selected.name, selected.path.as_deref())?;\n\n if std::env::var(\"FLOW_NO_CLIPBOARD\").is_ok() || !std::io::stdin().is_terminal() {\n println!(\"Clipboard disabled; skipping copy.\");\n return Ok(());\n }\n\n // Copy to clipboard using pbcopy (macOS) or xclip (Linux)\n let mut cmd = if cfg!(target_os = \"macos\") {\n Command::new(\"pbcopy\")\n } else {\n let mut c = Command::new(\"xclip\");\n c.args([\"-selection\", \"clipboard\"]);\n c\n };\n\n let mut child = cmd\n .stdin(Stdio::piped())\n .spawn()\n .context(\"failed to run clipboard command\")?;\n\n if let Some(mut stdin) = child.stdin.take() {\n stdin\n .write_all(content.as_bytes())\n .context(\"failed to write to clipboard\")?;\n }\n\n child.wait()?;\n println!(\n \"Copied '{}' agent instructions to clipboard ({} bytes)\",\n selected.name,\n content.len()\n );\n Ok(())\n}\n\n/// Run fzf and return selected entry (simplified, no args prompt).\nfn run_agent_fzf_simple<'a>(entries: &'a [AgentEntry]) -> Result<Option<&'a AgentEntry>> {\n let mut child = Command::new(\"fzf\")\n .arg(\"--prompt\")\n .arg(\"copy agent> \")\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n {\n let stdin = child.stdin.as_mut().context(\"failed to open fzf stdin\")?;\n for entry in entries {\n writeln!(stdin, \"{}\", entry.display)?;\n }\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n let selection = String::from_utf8(output.stdout)\n .context(\"fzf output was not valid UTF-8\")?\n .trim()\n .to_string();\n\n if selection.is_empty() {\n return Ok(None);\n }\n\n Ok(entries.iter().find(|entry| entry.display == selection))\n}\n\n/// Get agent file content by name and optional path.\nfn get_agent_content(name: &str, path: Option<&Path>) -> Result<String> {\n // If path is provided, read directly\n if let Some(p) = path {\n return fs::read_to_string(p)\n .context(format!(\"failed to read agent file: {}\", p.display()));\n }\n\n // Special case: flow agent has built-in instructions\n if name == FLOW_AGENT_NAME {\n return Ok(get_flow_agent_instructions());\n }\n\n // Try to find agent in common locations\n let mut locations = vec![\n dirs::home_dir().map(|h| h.join(\".config/opencode/agent\")),\n dirs::home_dir().map(|h| h.join(\".opencode/agent\")),\n ];\n if let Some(repo) = gen_repo_from_env() {\n locations.push(Some(repo.join(\".opencode/agent\")));\n }\n if let Some(repo) = default_gen_repo() {\n locations.push(Some(repo.join(\".opencode/agent\")));\n }\n\n for loc in locations.into_iter().flatten() {\n let agent_path = loc.join(format!(\"{}.md\", name));\n if agent_path.exists() {\n return fs::read_to_string(&agent_path).context(format!(\n \"failed to read agent file: {}\",\n agent_path.display()\n ));\n }\n }\n\n bail!(\"Could not find agent file for '{}'\", name)\n}\n\n/// Get built-in flow agent instructions.\nfn get_flow_agent_instructions() -> String {\n r#\"You are a Flow-aware agent with full context about flow.toml, tasks, and the Flow CLI.\n\n## Capabilities\n- Read and modify flow.toml configuration\n- Create, update, and run tasks\n- Understand the flow.toml schema and best practices\n- Help with CI/CD workflows, dependencies, and project setup\n\n## Guidelines\n- Always read the existing flow.toml before making changes\n- Preserve existing configuration when adding new items\n- Use appropriate task names and descriptions\n- Follow TOML formatting conventions\n- Enforce Flow env store usage for secrets/tokens (use `f env get` / `f env run`)\n\"#\n .to_string()\n}\n\nfn default_gen_repo() -> Option<PathBuf> {\n dirs::home_dir().map(|home| home.join(DEFAULT_GEN_REPO_REL))\n}\n\nfn gen_repo_from_env() -> Option<PathBuf> {\n std::env::var(\"GEN_REPO\").ok().map(PathBuf::from)\n}\n\nfn gen_repo_hint() -> String {\n default_gen_repo()\n .map(|path| path.display().to_string())\n .unwrap_or_else(|| format!(\"~/{}\", DEFAULT_GEN_REPO_REL))\n}\n\nfn run_agent_fzf<'a>(entries: &'a [AgentEntry]) -> Result<Option<FzfAgentResult<'a>>> {\n let mut child = Command::new(\"fzf\")\n .arg(\"--prompt\")\n .arg(\"agents> \")\n .arg(\"--expect\")\n .arg(\"tab\")\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n {\n let stdin = child.stdin.as_mut().context(\"failed to open fzf stdin\")?;\n for entry in entries {\n writeln!(stdin, \"{}\", entry.display)?;\n }\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n let raw = String::from_utf8(output.stdout).context(\"fzf output was not valid UTF-8\")?;\n let mut lines = raw.lines();\n\n let key = lines.next().unwrap_or(\"\");\n let with_args = key == \"tab\";\n\n let selection = lines.next().unwrap_or(\"\").trim();\n if selection.is_empty() {\n return Ok(None);\n }\n\n let entry = entries.iter().find(|entry| entry.display == selection);\n Ok(entry.map(|e| FzfAgentResult {\n entry: e,\n with_args,\n }))\n}\n\nfn prompt_for_agent_prompt(agent_name: &str) -> Result<Vec<String>> {\n use std::io::{self, BufRead};\n\n println!(\"(tip: use quotes for prompts with spaces, e.g. 'find all API endpoints')\");\n print!(\"f agents {} \", agent_name);\n io::stdout().flush()?;\n\n let stdin = io::stdin();\n let line = stdin.lock().lines().next();\n let input = match line {\n Some(Ok(s)) => s,\n _ => return Ok(Vec::new()),\n };\n\n let args = shell_words::split(&input).context(\"failed to parse prompt\")?;\n Ok(args)\n}\n\nfn build_agent_entries() -> Result<Vec<AgentEntry>> {\n let mut entries = Vec::new();\n let mut seen = HashSet::new();\n let flow_display = \"[flow] flow - Flow-aware agent for flow.toml tasks and CLI\";\n seen.insert(flow_display.to_string());\n entries.push(AgentEntry {\n name: FLOW_AGENT_NAME.to_string(),\n display: flow_display.to_string(),\n path: None, // flow agent is built-in, no file\n });\n\n if let Ok(gen_entries) = fetch_gen_agent_entries() {\n for entry in gen_entries {\n if seen.insert(entry.display.clone()) {\n entries.push(entry);\n }\n }\n return Ok(entries);\n }\n\n if let Some(project_root) = find_project_root() {\n let opencode_dir = project_root.join(\".opencode\");\n entries.extend(collect_agent_entries(\n &opencode_dir.join(\"agent\"),\n \"project\",\n &mut seen,\n )?);\n entries.extend(collect_agent_entries(\n &opencode_dir.join(\"agents\"),\n \"project\",\n &mut seen,\n )?);\n }\n\n if let Some(global_dir) = dirs::config_dir().map(|d| d.join(\"opencode\")) {\n entries.extend(collect_agent_entries(\n &global_dir.join(\"agent\"),\n \"global-config\",\n &mut seen,\n )?);\n entries.extend(collect_agent_entries(\n &global_dir.join(\"agents\"),\n \"global-config\",\n &mut seen,\n )?);\n }\n\n Ok(entries)\n}\n\nfn find_project_root() -> Option<PathBuf> {\n let mut dir = std::env::current_dir().ok()?;\n loop {\n if dir.join(\".opencode\").exists() || dir.join(\"flow.toml\").exists() {\n return Some(dir);\n }\n if !dir.pop() {\n break;\n }\n }\n None\n}\n\nfn apply_project_config_env(cmd: &mut Command) {\n if let Some(root) = find_project_root() {\n let opencode_dir = root.join(\".opencode\");\n if opencode_dir.exists() {\n cmd.env(\"OPENCODE_CONFIG_DIR\", opencode_dir);\n }\n }\n}\n\nfn collect_agent_entries(\n root: &Path,\n label: &str,\n seen: &mut HashSet<String>,\n) -> Result<Vec<AgentEntry>> {\n let mut entries = Vec::new();\n if !root.exists() {\n return Ok(entries);\n }\n\n let walker = WalkBuilder::new(root)\n .hidden(false)\n .git_ignore(false)\n .git_exclude(false)\n .ignore(false)\n .build();\n\n for entry in walker {\n let entry = match entry {\n Ok(e) => e,\n Err(_) => continue,\n };\n let path = entry.path();\n if !path.is_file() || path.extension().and_then(|s| s.to_str()) != Some(\"md\") {\n continue;\n }\n\n let name = match agent_name_from_path(root, path) {\n Some(n) => n,\n None => continue,\n };\n let (desc, mode) = parse_agent_frontmatter(path)?;\n if matches!(mode.as_deref(), Some(\"primary\")) {\n continue;\n }\n let summary = desc.unwrap_or_else(|| \"No description\".to_string());\n let display = format!(\"[{label}] {} - {}\", name, summary);\n if seen.insert(display.clone()) {\n entries.push(AgentEntry {\n name,\n display,\n path: Some(path.to_path_buf()),\n });\n }\n }\n\n Ok(entries)\n}\n\nfn agent_name_from_path(root: &Path, path: &Path) -> Option<String> {\n let relative = path.strip_prefix(root).ok()?;\n let without_ext = relative.with_extension(\"\");\n Some(\n without_ext\n .to_string_lossy()\n .replace(std::path::MAIN_SEPARATOR, \"/\"),\n )\n}\n\nfn parse_agent_frontmatter(path: &Path) -> Result<(Option<String>, Option<String>)> {\n let contents = fs::read_to_string(path).unwrap_or_default();\n let mut lines = contents.lines();\n if lines.next().map(|l| l.trim()) != Some(\"---\") {\n return Ok((None, None));\n }\n\n let mut desc: Option<String> = None;\n let mut mode: Option<String> = None;\n for line in lines {\n let line = line.trim();\n if line == \"---\" {\n break;\n }\n if let Some(value) = line.strip_prefix(\"description:\") {\n desc = Some(trim_yaml_scalar(value));\n } else if let Some(value) = line.strip_prefix(\"mode:\") {\n mode = Some(trim_yaml_scalar(value));\n }\n }\n\n Ok((desc, mode))\n}\n\nfn trim_yaml_scalar(value: &str) -> String {\n let trimmed = value.trim();\n trimmed.trim_matches('\"').trim_matches('\\'').to_string()\n}\n\n/// Agents that operate on the current directory by default.\nconst DIR_AGENTS: &[&str] = &[\"docker-to-flox\"];\n\nfn run_agent_optional(agent: &str, prompt: Option<Vec<String>>) -> Result<()> {\n let prompt_args = match prompt {\n Some(p) if !p.is_empty() => p,\n _ => {\n // For directory-based agents, use cwd as default\n if DIR_AGENTS.contains(&agent) {\n let cwd = std::env::current_dir()\n .map(|p| p.to_string_lossy().to_string())\n .unwrap_or_else(|_| \".\".to_string());\n vec![cwd]\n } else {\n prompt_for_agent_prompt(agent)?\n }\n }\n };\n\n if prompt_args.is_empty() {\n bail!(\"No prompt provided.\");\n }\n\n run_agent(agent, prompt_args)\n}\n\nfn list_gen_agents(gen_loc: &GenLocation) -> Result<()> {\n let status = match gen_loc {\n GenLocation::Binary(path) => Command::new(path)\n .args([\"agent\", \"list\"])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run gen agent list\")?,\n GenLocation::Repo(repo) => {\n let mut cmd = Command::new(\"bun\");\n cmd.args([\n \"run\",\n \"--cwd\",\n &repo.join(\"packages/opencode\").to_string_lossy(),\n \"--conditions=browser\",\n \"src/index.ts\",\n \"agent\",\n \"list\",\n ])\n .env(\"GEN_MODE\", \"1\")\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit());\n apply_project_config_env(&mut cmd);\n cmd.status().context(\"failed to run gen agent list\")?\n }\n };\n\n if status.success() {\n Ok(())\n } else {\n bail!(\"gen agent list failed\");\n }\n}\n\nfn fetch_gen_agent_entries() -> Result<Vec<AgentEntry>> {\n let gen_loc = find_gen().ok_or_else(|| {\n anyhow::anyhow!(\n \"gen not found. Install with:\\n cd {} && f install\\n # or set GEN_REPO env var\",\n gen_repo_hint()\n )\n })?;\n\n let output = match gen_loc {\n GenLocation::Binary(ref path) => Command::new(path)\n .args([\"agent\", \"list\"])\n .output()\n .context(\"failed to run gen agent list\")?,\n GenLocation::Repo(ref repo) => {\n let mut cmd = Command::new(\"bun\");\n cmd.args([\n \"run\",\n \"--cwd\",\n &repo.join(\"packages/opencode\").to_string_lossy(),\n \"--conditions=browser\",\n \"src/index.ts\",\n \"agent\",\n \"list\",\n ])\n .env(\"GEN_MODE\", \"1\");\n apply_project_config_env(&mut cmd);\n cmd.output().context(\"failed to run gen agent list\")?\n }\n };\n\n if !output.status.success() {\n bail!(\n \"gen agent list failed: {}\",\n String::from_utf8_lossy(&output.stderr)\n );\n }\n\n let stdout = String::from_utf8_lossy(&output.stdout);\n Ok(parse_gen_agent_list(&stdout))\n}\n\nfn parse_gen_agent_list(stdout: &str) -> Vec<AgentEntry> {\n let mut entries = Vec::new();\n for line in stdout.lines() {\n let line = line.trim();\n if line.is_empty() {\n continue;\n }\n if let Some((name, mode)) = parse_agent_list_line(line) {\n if mode == \"primary\" {\n continue;\n }\n let display = format!(\"[gen] {} ({})\", name, mode);\n entries.push(AgentEntry {\n name,\n display,\n path: None, // gen agents - path resolved separately\n });\n }\n }\n entries\n}\n\nfn parse_agent_list_line(line: &str) -> Option<(String, String)> {\n if line.starts_with('{')\n || line.starts_with('\"')\n || line.starts_with('[')\n || line.starts_with(\"}\")\n {\n return None;\n }\n let end = line.strip_suffix(')')?;\n let (name, mode) = end.rsplit_once(\" (\")?;\n if name.trim().is_empty() {\n return None;\n }\n let mode = mode.trim();\n if !matches!(mode, \"subagent\" | \"all\" | \"primary\") {\n return None;\n }\n Some((name.trim().to_string(), mode.to_string()))\n}\n\n/// Get the configured agent tool and model.\nfn get_agent_config() -> (String, Option<String>) {\n if let Some(ts_config) = config::load_ts_config() {\n if let Some(flow) = ts_config.flow {\n if let Some(agents) = flow.agents {\n let tool = agents.tool.unwrap_or_else(|| \"gen\".to_string());\n return (tool, agents.model);\n }\n }\n }\n (\"gen\".to_string(), None)\n}\n\n/// Run an agent with a prompt.\nfn run_agent(agent: &str, prompt: Vec<String>) -> Result<()> {\n let prompt_str = prompt.join(\" \");\n if prompt_str.is_empty() {\n bail!(\n \"No prompt provided.\\nUsage: f agents run {} \\\"your prompt here\\\"\",\n agent\n );\n }\n\n // Build the full prompt based on agent type\n let full_prompt = if agent == FLOW_AGENT_NAME {\n build_flow_prompt(&prompt_str)?\n } else {\n // Regular subagent - use Task tool\n format!(\n \"Use the Task tool with subagent_type='{}' to: {}\",\n agent, prompt_str\n )\n };\n\n println!(\"Invoking {} agent...\\n\", agent);\n\n let (tool, model) = get_agent_config();\n let status = match tool.as_str() {\n \"claude\" => invoke_claude(&full_prompt)?,\n \"opencode\" => invoke_opencode(&full_prompt, model.as_deref())?,\n _ => {\n let gen_loc = find_gen().ok_or_else(|| {\n anyhow::anyhow!(\n \"gen not found. Install with:\\n cd {} && f install\\n # or set GEN_REPO env var\",\n gen_repo_hint()\n )\n })?;\n invoke_gen(&gen_loc, &full_prompt)?\n }\n };\n\n if !status.success() {\n bail!(\"Agent exited with status: {}\", status);\n }\n\n Ok(())\n}\n\n/// Invoke Claude Code with a prompt.\nfn invoke_claude(prompt: &str) -> Result<std::process::ExitStatus> {\n Command::new(\"claude\")\n .args([\"-p\", prompt])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run claude\")\n}\n\n/// Invoke opencode with a prompt and optional model.\nfn invoke_opencode(prompt: &str, model: Option<&str>) -> Result<std::process::ExitStatus> {\n let mut cmd = Command::new(\"opencode\");\n cmd.arg(\"run\");\n if let Some(m) = model {\n cmd.args([\"--model\", m]);\n }\n // Use default format (not json) for interactive output\n cmd.arg(prompt)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run opencode\")\n}\n\n/// Run the flow agent and capture the final text output.\npub fn run_flow_agent_capture(prompt: &str) -> Result<String> {\n let gen_loc = find_gen().ok_or_else(|| {\n anyhow::anyhow!(\n \"gen not found. Install with:\\n cd {} && f install\\n # or set GEN_REPO env var\",\n gen_repo_hint()\n )\n })?;\n\n if prompt.trim().is_empty() {\n bail!(\"No prompt provided for flow agent.\");\n }\n\n let full_prompt = build_flow_prompt(prompt)?;\n invoke_gen_capture(&gen_loc, &full_prompt)\n}\n\n/// Run the flow agent and stream text output while capturing the final response.\npub fn run_flow_agent_capture_streaming(prompt: &str) -> Result<String> {\n let gen_loc = find_gen().ok_or_else(|| {\n anyhow::anyhow!(\n \"gen not found. Install with:\\n cd {} && f install\\n # or set GEN_REPO env var\",\n gen_repo_hint()\n )\n })?;\n\n if prompt.trim().is_empty() {\n bail!(\"No prompt provided for flow agent.\");\n }\n\n let full_prompt = build_flow_prompt(prompt)?;\n invoke_gen_capture_streaming(&gen_loc, &full_prompt)\n}\n\n/// Fallback model if not configured.\nconst FALLBACK_AGENT_MODEL: &str = \"openrouter/moonshotai/kimi-k2:free\";\n\n/// Get the agent model from config or use fallback.\nfn get_agent_model() -> String {\n if let Some(ts_config) = config::load_ts_config() {\n if let Some(flow) = ts_config.flow {\n if let Some(agents) = flow.agents {\n if let Some(model) = agents.model {\n return model;\n }\n }\n }\n }\n FALLBACK_AGENT_MODEL.to_string()\n}\n\n/// Invoke gen with a prompt and model.\nfn invoke_gen(location: &GenLocation, prompt: &str) -> Result<std::process::ExitStatus> {\n let model = get_agent_model();\n invoke_gen_with_model(location, prompt, &model)\n}\n\n/// Invoke gen with a prompt and specific model.\nfn invoke_gen_with_model(\n location: &GenLocation,\n prompt: &str,\n model: &str,\n) -> Result<std::process::ExitStatus> {\n match location {\n GenLocation::Binary(path) => Command::new(path)\n .args([\"run\", \"--model\", model, prompt])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run gen\"),\n\n GenLocation::Repo(repo) => {\n let mut cmd = Command::new(\"bun\");\n cmd.args([\n \"run\",\n \"--cwd\",\n &repo.join(\"packages/opencode\").to_string_lossy(),\n \"--conditions=browser\",\n \"src/index.ts\",\n \"run\",\n \"--model\",\n model,\n prompt,\n ])\n .env(\"GEN_MODE\", \"1\")\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit());\n apply_project_config_env(&mut cmd);\n cmd.status().context(\"failed to run gen from repo\")\n }\n }\n}\n\nfn invoke_gen_capture(location: &GenLocation, prompt: &str) -> Result<String> {\n let output = match location {\n GenLocation::Binary(path) => Command::new(path)\n .args([\"run\", \"--format\", \"json\", prompt])\n .stdin(Stdio::null())\n .output()\n .context(\"failed to run gen\"),\n\n GenLocation::Repo(repo) => {\n let mut cmd = Command::new(\"bun\");\n cmd.args([\n \"run\",\n \"--cwd\",\n &repo.join(\"packages/opencode\").to_string_lossy(),\n \"--conditions=browser\",\n \"src/index.ts\",\n \"run\",\n \"--format\",\n \"json\",\n prompt,\n ])\n .env(\"GEN_MODE\", \"1\")\n .stdin(Stdio::null());\n apply_project_config_env(&mut cmd);\n cmd.output().context(\"failed to run gen from repo\")\n }\n }?;\n\n if !output.status.success() {\n bail!(\"gen exited with status: {}\", output.status);\n }\n\n let stdout = String::from_utf8_lossy(&output.stdout);\n if let Some(text) = extract_text_from_gen_output(&stdout) {\n return Ok(text);\n }\n\n let trimmed = stdout.trim();\n if !trimmed.is_empty() {\n return Ok(trimmed.to_string());\n }\n\n bail!(\"gen returned no output\");\n}\n\nfn invoke_gen_capture_streaming(location: &GenLocation, prompt: &str) -> Result<String> {\n let mut cmd = match location {\n GenLocation::Binary(path) => {\n let mut cmd = Command::new(path);\n cmd.args([\"run\", \"--format\", \"json\", prompt])\n .stdin(Stdio::null())\n .stdout(Stdio::piped())\n .stderr(Stdio::inherit());\n cmd\n }\n GenLocation::Repo(repo) => {\n let mut cmd = Command::new(\"bun\");\n cmd.args([\n \"run\",\n \"--cwd\",\n &repo.join(\"packages/opencode\").to_string_lossy(),\n \"--conditions=browser\",\n \"src/index.ts\",\n \"run\",\n \"--format\",\n \"json\",\n prompt,\n ])\n .env(\"GEN_MODE\", \"1\")\n .stdin(Stdio::null())\n .stdout(Stdio::piped())\n .stderr(Stdio::inherit());\n apply_project_config_env(&mut cmd);\n cmd\n }\n };\n\n let mut child = cmd.spawn().context(\"failed to run gen\")?;\n let stdout = child\n .stdout\n .take()\n .context(\"failed to capture gen stdout\")?;\n let reader = BufReader::new(stdout);\n\n let mut last_text = String::new();\n let mut final_text = String::new();\n let mut printed_output = false;\n\n for line in reader.lines() {\n let line = line?;\n if let Some(text) = extract_text_from_gen_line(&line) {\n if text.starts_with(&last_text) {\n let delta = &text[last_text.len()..];\n if !delta.is_empty() {\n print!(\"{delta}\");\n io::stdout().flush()?;\n printed_output = true;\n }\n final_text = text;\n } else {\n if !text.is_empty() {\n print!(\"{text}\");\n io::stdout().flush()?;\n printed_output = true;\n }\n if final_text.is_empty() {\n final_text = text;\n } else {\n final_text.push_str(&text);\n }\n }\n last_text = final_text.clone();\n }\n }\n\n let status = child.wait().context(\"failed to wait for gen\")?;\n if !status.success() {\n bail!(\"gen exited with status: {}\", status);\n }\n\n if printed_output {\n if !final_text.ends_with('\\n') {\n println!();\n }\n }\n\n if final_text.trim().is_empty() {\n bail!(\"gen returned no output\");\n }\n\n Ok(final_text)\n}\n\nfn extract_text_from_gen_output(stdout: &str) -> Option<String> {\n let mut last_text: Option<String> = None;\n for line in stdout.lines() {\n if let Some(text) = extract_text_from_gen_line(line) {\n if !text.trim().is_empty() {\n last_text = Some(text.to_string());\n }\n }\n }\n last_text\n}\n\nfn extract_text_from_gen_line(line: &str) -> Option<String> {\n let value: Value = serde_json::from_str(line).ok()?;\n let event_type = value.get(\"type\").and_then(|t| t.as_str());\n if event_type != Some(\"text\") {\n return None;\n }\n value\n .get(\"part\")\n .and_then(|part| part.get(\"text\"))\n .and_then(|t| t.as_str())\n .map(|text| text.to_string())\n}\n\n/// Build a flow-aware prompt with full context.\nfn build_flow_prompt(user_prompt: &str) -> Result<String> {\n let mut context = String::new();\n\n // Add flow.toml schema reference\n context.push_str(FLOW_SCHEMA_CONTEXT);\n\n // Add current project tasks if available\n let cwd = std::env::current_dir().unwrap_or_default();\n if let Ok(discovery) = discover::discover_tasks(&cwd) {\n if !discovery.tasks.is_empty() {\n context.push_str(\"\\n\\n## Current Project Tasks\\n\\n\");\n for task in &discovery.tasks {\n let desc = task.task.description.as_deref().unwrap_or(\"\");\n if task.relative_dir.is_empty() {\n context.push_str(&format!(\n \"- `{}`: {} ({})\\n\",\n task.task.name, desc, task.task.command\n ));\n } else {\n context.push_str(&format!(\n \"- `{}` ({}): {} ({})\\n\",\n task.task.name, task.relative_dir, desc, task.task.command\n ));\n }\n }\n }\n }\n\n // Add CLI commands reference\n context.push_str(FLOW_CLI_CONTEXT);\n\n Ok(format!(\n \"{}\\n\\n---\\n\\nUser request: {}\\n\\nComplete this task. Read flow.toml first if you need to modify it.\",\n context, user_prompt\n ))\n}\n\n/// Flow.toml schema and best practices context.\nconst FLOW_SCHEMA_CONTEXT: &str = r#\"# Flow Task Runner Context\n\nYou are a flow-aware agent. Flow is a task runner with these key concepts:\n\n## flow.toml Schema\n\n```toml\nversion = 1\nname = \"project-name\" # optional project identifier\n\n[flow]\nprimary_task = \"dev\" # default task for `f` with no args\n\n[[tasks]]\nname = \"task-name\" # required: unique identifier\ncommand = \"echo hello\" # required: shell command to run\ndescription = \"What it does\" # optional: shown in task list\nshortcuts = [\"t\", \"tn\"] # optional: short aliases\ndependencies = [\"other-task\", \"cargo\"] # optional: run before, or ensure binary exists\ninteractive = false # optional: needs TTY (auto-detected for sudo, vim, etc.)\ndelegate_to_hub = false # optional: run via background hub daemon\non_cancel = \"cleanup cmd\" # optional: run when Ctrl+C pressed\noutput_file = \"last-build-output.md\" # optional: write task output to file\n\n# Dependencies section - define reusable deps\n[deps]\ncargo = \"cargo\" # simple binary check\nnode = [\"node\", \"npm\"] # multiple binaries\nripgrep = { pkg-path = \"ripgrep\" } # flox managed package\n\n# Flox integration for reproducible dependencies\n[flox.install]\ncargo.pkg-path = \"cargo\"\nnodejs.pkg-path = \"nodejs\"\n```\n\n## Best Practices\n\n1. **Task naming**: Use kebab-case (e.g., `deploy-prod`, `test-unit`)\n2. **Shortcuts**: Add 1-3 char shortcuts for frequent tasks\n3. **Descriptions**: Always add descriptions - they appear in `f tasks` and fuzzy search\n4. **Dependencies**: List task deps (run first) or binary deps (check PATH)\n5. **on_cancel**: Add cleanup for long-running tasks that spawn processes\n6. **interactive**: Auto-detected for sudo/vim/ssh, set manually for custom TUIs\n7. **output_file**: Capture full task output for debugging or sharing\n\"#;\n\n/// Flow CLI commands context.\nconst FLOW_CLI_CONTEXT: &str = r#\"\n\n## Flow CLI Commands\n\n- `f` - Fuzzy search tasks (fzf picker)\n- `f <task>` - Run task directly\n- `f tasks` - List all tasks\n- `f run <task> [args]` - Run task with args\n- `f init` - Create flow.toml scaffold\n- `f setup` - Bootstrap project or run setup task\n- `f commit` - AI-assisted git commit\n- `f agents run <type> \"prompt\"` - Run AI agent\n- `f agents global <agent>` - Run global agent\n- `f ps` - Show running tasks\n- `f kill` - Stop running tasks\n- `f logs <task>` - View task logs\n\n## Task Arguments\n\nTasks receive args as positional params:\n```toml\n[[tasks]]\nname = \"greet\"\ncommand = \"echo Hello $1\"\n```\nRun: `f greet World` → prints \"Hello World\"\n\"#;\n" }, { "path": "src/ai.rs", "content": "//! AI session management for Claude Code, Codex, and Cursor integration.\n//!\n//! Tracks and manages AI coding sessions per project, allowing users to:\n//! - List sessions for the current project (Claude, Codex, or both)\n//! - Save/bookmark sessions with names\n//! - Resume sessions\n//! - Add notes to sessions\n//! - Copy session history to clipboard\n\nuse std::collections::{BTreeMap, BTreeSet, HashMap, VecDeque};\nuse std::env;\nuse std::fs;\nuse std::fs::OpenOptions;\nuse std::hash::{Hash, Hasher};\nuse std::io::{self, BufRead, BufReader, IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\nuse std::sync::{Mutex, OnceLock};\nuse std::time::{Duration, SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result, bail};\nuse chrono::{DateTime, Utc};\nuse regex::Regex;\nuse rusqlite::{Connection, params};\nuse serde::{Deserialize, Serialize};\nuse serde_json::json;\nuse toml::Value as TomlValue;\nuse tracing::debug;\nuse uuid::Uuid;\n\nuse crate::activity_log;\nuse crate::cli::{\n AiAction, CodexDaemonAction, CodexMemoryAction, CodexRuntimeAction, CodexSkillEvalAction,\n CodexSkillSourceAction, CodexTelemetryAction, CodexTraceAction, ProviderAiAction,\n};\nuse crate::commit::configured_codex_bin_for_workdir;\nuse crate::{\n codex_memory, codex_telemetry, codex_text, codexd, config, project_snapshot, repo_capsule,\n url_inspect,\n};\nuse crate::{codex_runtime, codex_skill_eval};\nuse crate::env as flow_env;\n\n/// AI provider type\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\npub enum Provider {\n Claude,\n Codex,\n Cursor,\n All,\n}\n\n/// Stored session metadata in .ai/sessions/<provider>/index.json\n#[derive(Debug, Serialize, Deserialize, Default)]\nstruct SessionIndex {\n /// Map of user-friendly names to session metadata\n sessions: HashMap<String, SavedSession>,\n}\n\n#[derive(Debug, Serialize)]\npub struct WebSession {\n pub id: String,\n pub provider: String,\n pub timestamp: Option<String>,\n pub name: Option<String>,\n pub messages: Vec<WebSessionMessage>,\n pub started_at: Option<String>,\n pub last_message_at: Option<String>,\n}\n\n#[derive(Debug, Serialize)]\npub struct WebSessionMessage {\n pub role: String,\n pub content: String,\n}\n\n#[derive(Debug, Serialize)]\npub struct SessionHistory {\n pub session_id: String,\n pub provider: String,\n pub started_at: Option<String>,\n pub last_message_at: Option<String>,\n pub messages: Vec<WebSessionMessage>,\n}\n\nstruct SessionMessages {\n messages: Vec<WebSessionMessage>,\n started_at: Option<String>,\n last_message_at: Option<String>,\n}\n\nimpl Default for SessionMessages {\n fn default() -> Self {\n Self {\n messages: Vec::new(),\n started_at: None,\n last_message_at: None,\n }\n }\n}\n\n/// Commit checkpoint stored in .ai/commit-checkpoints.json\n#[derive(Debug, Serialize, Deserialize, Default)]\npub struct CommitCheckpoints {\n /// Last commit checkpoint\n pub last_commit: Option<CommitCheckpoint>,\n}\n\n#[derive(Debug, Serialize, Deserialize, Clone)]\npub struct CommitCheckpoint {\n /// When this checkpoint was created\n pub timestamp: String,\n /// Session ID that was active\n pub session_id: Option<String>,\n /// Timestamp of the last entry included in that commit\n pub last_entry_timestamp: Option<String>,\n}\n\n#[derive(Debug, Serialize, Deserialize, Clone)]\nstruct SavedSession {\n /// Session ID (UUID)\n id: String,\n /// Which provider this session is from\n #[serde(default = \"default_provider\")]\n provider: String,\n /// Optional description\n description: Option<String>,\n /// When this session was saved\n saved_at: String,\n /// Last resumed timestamp\n last_resumed: Option<String>,\n}\n\nfn default_provider() -> String {\n \"claude\".to_string()\n}\n\n/// Session info extracted from session files\n#[derive(Debug, Clone)]\nstruct AiSession {\n /// Session ID (UUID)\n session_id: String,\n /// Which provider (claude, codex, cursor)\n provider: Provider,\n /// First message timestamp\n timestamp: Option<String>,\n /// Last message timestamp\n last_message_at: Option<String>,\n /// Last user/assistant message text\n last_message: Option<String>,\n /// First user message (as summary)\n first_message: Option<String>,\n /// First error summary (for sessions that never produced a user message)\n error_summary: Option<String>,\n}\n\n/// Entry from a session .jsonl file (we only parse what we need)\n#[derive(Debug, Deserialize)]\nstruct JsonlEntry {\n timestamp: Option<String>,\n message: Option<SessionMessage>,\n #[serde(rename = \"type\")]\n entry_type: Option<String>,\n subtype: Option<String>,\n level: Option<String>,\n error: Option<serde_json::Value>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct CodexEntry {\n timestamp: Option<String>,\n #[serde(rename = \"type\")]\n entry_type: Option<String>,\n payload: Option<serde_json::Value>,\n role: Option<String>,\n content: Option<serde_json::Value>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct CursorEntry {\n role: Option<String>,\n message: Option<SessionMessage>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct SessionMessage {\n role: Option<String>,\n content: Option<serde_json::Value>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub(crate) struct CodexRecoverRow {\n pub(crate) id: String,\n pub(crate) updated_at: i64,\n pub(crate) cwd: String,\n pub(crate) title: Option<String>,\n pub(crate) first_user_message: Option<String>,\n pub(crate) git_branch: Option<String>,\n #[serde(default)]\n pub(crate) model: Option<String>,\n #[serde(default)]\n pub(crate) reasoning_effort: Option<String>,\n}\n\n#[derive(Debug, Serialize)]\nstruct CodexRecoverCandidate {\n id: String,\n updated_at: String,\n updated_at_unix: i64,\n cwd: String,\n git_branch: Option<String>,\n model: Option<String>,\n reasoning_effort: Option<String>,\n title: Option<String>,\n first_user_message: Option<String>,\n}\n\n#[derive(Debug, Serialize)]\nstruct CodexRecoverOutput {\n target_path: String,\n exact_cwd: bool,\n query: Option<String>,\n recommended_route: String,\n summary: String,\n candidates: Vec<CodexRecoverCandidate>,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\nstruct CodexResolvedReference {\n name: String,\n source: String,\n matched: String,\n command: Option<String>,\n output: String,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\nstruct CodexOpenPlan {\n action: String,\n route: String,\n reason: String,\n target_path: String,\n launch_path: String,\n query: Option<String>,\n session_id: Option<String>,\n prompt: Option<String>,\n references: Vec<CodexResolvedReference>,\n runtime_state_path: Option<String>,\n runtime_skills: Vec<String>,\n prompt_context_budget_chars: usize,\n max_resolved_references: usize,\n prompt_chars: usize,\n injected_context_chars: usize,\n trace: Option<CodexResolveWorkflowTrace>,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexResolveReferenceSnapshot {\n pub name: String,\n pub source: String,\n pub matched: String,\n pub command: Option<String>,\n pub output: String,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexResolveRuntimeSkillSnapshot {\n pub name: String,\n pub kind: String,\n pub path: String,\n pub trigger: String,\n pub source: Option<String>,\n pub original_name: Option<String>,\n pub estimated_chars: Option<usize>,\n pub match_reason: Option<String>,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexResolveInspectorResponse {\n pub action: String,\n pub route: String,\n pub reason: String,\n pub target_path: String,\n pub launch_path: String,\n pub query: Option<String>,\n pub session_id: Option<String>,\n pub prompt: Option<String>,\n pub references: Vec<CodexResolveReferenceSnapshot>,\n pub runtime_state_path: Option<String>,\n pub runtime_skills: Vec<CodexResolveRuntimeSkillSnapshot>,\n pub prompt_context_budget_chars: usize,\n pub max_resolved_references: usize,\n pub prompt_chars: usize,\n pub injected_context_chars: usize,\n pub trace: Option<CodexResolveWorkflowTrace>,\n pub workflow: Option<CodexResolveWorkflowExplanation>,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexResolveWorkflowExplanation {\n pub id: String,\n pub title: String,\n pub summary: String,\n pub trigger: String,\n pub generated_by: String,\n pub packet: CodexResolveWorkflowPacket,\n pub commands: Vec<CodexResolveWorkflowCommand>,\n pub artifacts: Vec<CodexResolveWorkflowArtifact>,\n pub steps: Vec<CodexResolveWorkflowStep>,\n pub notes: Vec<String>,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexResolveWorkflowPacket {\n pub kind: String,\n pub compact_summary: String,\n pub default_view: String,\n pub expansion_rules: Vec<String>,\n pub validation_plan: Vec<CodexResolveWorkflowValidation>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub trace: Option<CodexResolveWorkflowTrace>,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexResolveWorkflowTrace {\n pub trace_id: String,\n pub span_id: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub parent_span_id: Option<String>,\n pub workflow_kind: String,\n pub service_name: String,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexResolveWorkflowValidation {\n pub label: String,\n pub tier: String,\n pub detail: String,\n pub command: Option<String>,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexResolveWorkflowCommand {\n pub label: String,\n pub command: String,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexResolveWorkflowArtifact {\n pub label: String,\n pub value: String,\n pub kind: String,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexResolveWorkflowStep {\n pub title: String,\n pub detail: String,\n}\n\n#[derive(Debug, Clone, PartialEq, Eq)]\nstruct CodexSessionReferenceRequest {\n session_hints: Vec<String>,\n count: usize,\n user_request: String,\n}\n\n#[derive(Debug, Clone, PartialEq, Eq)]\nstruct LinearUrlReference {\n url: String,\n workspace_slug: String,\n resource_kind: LinearUrlKind,\n resource_value: String,\n view: Option<String>,\n title_hint: String,\n}\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nenum LinearUrlKind {\n Issue,\n Project,\n}\n\nconst CODEX_QUERY_CACHE_VERSION: u32 = 1;\nconst CODEX_QUERY_CACHE_ENV_DISABLE: &str = \"FLOW_DISABLE_CODEX_QUERY_CACHE\";\nconst CODEX_SESSION_COMPLETION_DEFAULT_SCAN_LIMIT: usize = 24;\nconst CODEX_SESSION_COMPLETION_DEFAULT_IDLE_SECS: u64 = 90;\nconst FLOW_CODEX_TRACE_SERVICE_NAME: &str = \"flow_codex\";\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\nstruct CodexStateDbStamp {\n path: String,\n len: u64,\n modified_unix_secs: u64,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct CodexQueryCacheEntry {\n version: u32,\n stamp: CodexStateDbStamp,\n rows: Vec<CodexRecoverRow>,\n}\n\n#[derive(Debug, Clone, PartialEq, Eq)]\nstruct CodexThreadSchema {\n has_model: bool,\n has_reasoning_effort: bool,\n}\n\n#[derive(Debug, Clone)]\nstruct CodexThreadSchemaCacheEntry {\n stamp: CodexStateDbStamp,\n schema: CodexThreadSchema,\n}\n\n#[derive(Debug, Clone, PartialEq, Eq)]\nstruct CodexSessionCompletionSnapshot {\n last_role: Option<String>,\n last_user_message: Option<String>,\n last_user_at_unix: Option<u64>,\n last_assistant_message: Option<String>,\n last_assistant_at_unix: Option<u64>,\n file_modified_unix: u64,\n}\n\n#[derive(Debug, Clone, PartialEq, Eq)]\nstruct CodexTurnPatchChange {\n path: String,\n action: String,\n patch: String,\n}\n\n#[derive(Debug, Clone, PartialEq, Eq)]\nstruct PrFeedbackCursorHandoff {\n workspace_path: PathBuf,\n review_plan_path: PathBuf,\n review_rules_path: Option<PathBuf>,\n kit_system_path: PathBuf,\n}\n\n/// Run a provider-specific action (for top-level `f codex` / `f claude` commands).\npub fn run_provider(provider: Provider, action: Option<ProviderAiAction>) -> Result<()> {\n if provider == Provider::Cursor {\n match action {\n None | Some(ProviderAiAction::List) => list_sessions(Provider::Cursor)?,\n Some(ProviderAiAction::LatestId { path }) => {\n print_latest_session_id(Provider::Cursor, path)?\n }\n Some(ProviderAiAction::Connect { .. }) => {\n bail!(\"connect is only supported for Codex sessions; use `f codex connect ...`\");\n }\n Some(ProviderAiAction::Copy { session }) => copy_session(session, Provider::Cursor)?,\n Some(ProviderAiAction::Context {\n session,\n count,\n path,\n }) => copy_context(session, Provider::Cursor, count, path)?,\n Some(ProviderAiAction::Show {\n session,\n path,\n count,\n full,\n }) => show_session(session, Provider::Cursor, count, path, full)?,\n Some(ProviderAiAction::Runtime { .. }) => {\n bail!(\n \"runtime helpers are only supported for Codex sessions; use `f codex runtime ...`\"\n );\n }\n Some(ProviderAiAction::Doctor { .. }) => {\n bail!(\"doctor is only supported for Codex sessions; use `f codex doctor`\");\n }\n Some(ProviderAiAction::Eval { .. }) => {\n bail!(\"eval is only supported for Codex sessions; use `f codex eval`\");\n }\n Some(ProviderAiAction::TouchLaunch { .. }) => {\n bail!(\n \"touch-launch is only supported for Codex sessions; use `f codex touch-launch`\"\n );\n }\n Some(ProviderAiAction::EnableGlobal { .. }) => {\n bail!(\n \"global Codex enablement is only supported for Codex sessions; use `f codex enable-global`\"\n );\n }\n Some(ProviderAiAction::Daemon { .. }) => {\n bail!(\"daemon is only supported for Codex sessions; use `f codex daemon ...`\");\n }\n Some(ProviderAiAction::Memory { .. }) => {\n bail!(\"memory is only supported for Codex sessions; use `f codex memory ...`\");\n }\n Some(ProviderAiAction::Telemetry { .. }) => {\n bail!(\"telemetry is only supported for Codex sessions; use `f codex telemetry ...`\");\n }\n Some(ProviderAiAction::Trace { .. }) => {\n bail!(\"trace is only supported for Codex sessions; use `f codex trace ...`\");\n }\n Some(ProviderAiAction::SkillEval { .. }) => {\n bail!(\n \"skill-eval is only supported for Codex sessions; use `f codex skill-eval ...`\"\n );\n }\n Some(ProviderAiAction::SkillSource { .. }) => {\n bail!(\n \"skill-source is only supported for Codex sessions; use `f codex skill-source ...`\"\n );\n }\n Some(ProviderAiAction::Sessions { .. })\n | Some(ProviderAiAction::Continue { .. })\n | Some(ProviderAiAction::New)\n | Some(ProviderAiAction::Open { .. })\n | Some(ProviderAiAction::Resolve { .. })\n | Some(ProviderAiAction::Resume { .. })\n | Some(ProviderAiAction::Find { .. })\n | Some(ProviderAiAction::FindAndCopy { .. }) => {\n bail!(\n \"Cursor transcripts are readable only; use `f cursor list`, `f cursor copy`, or `f cursor context`\"\n );\n }\n Some(ProviderAiAction::Recover { .. }) => {\n bail!(\"recover is only supported for Codex sessions; use `f ai codex recover ...`\");\n }\n }\n return Ok(());\n }\n\n match action {\n None => quick_start_session(provider)?,\n Some(ProviderAiAction::List) => list_sessions(provider)?,\n Some(ProviderAiAction::LatestId { path }) => print_latest_session_id(provider, path)?,\n Some(ProviderAiAction::Sessions { path, json }) => {\n provider_sessions(provider, path, json)?\n }\n Some(ProviderAiAction::Continue { session, path }) => {\n continue_session(session, path, provider)?\n }\n Some(ProviderAiAction::New) => new_session(provider)?,\n Some(ProviderAiAction::Connect {\n path,\n exact_cwd,\n json,\n query,\n }) => connect_codex_session(path, query, exact_cwd, json, provider)?,\n Some(ProviderAiAction::Open {\n path,\n exact_cwd,\n query,\n }) => open_codex_session(path, query, exact_cwd, provider)?,\n Some(ProviderAiAction::Daemon { action }) => codex_daemon_command(action, provider)?,\n Some(ProviderAiAction::Memory { action }) => codex_memory_command(action, provider)?,\n Some(ProviderAiAction::Telemetry { action }) => {\n codex_telemetry_command(action, provider)?\n }\n Some(ProviderAiAction::Trace { action }) => codex_trace_command(action, provider)?,\n Some(ProviderAiAction::SkillEval { action }) => codex_skill_eval_command(action, provider)?,\n Some(ProviderAiAction::SkillSource { action }) => {\n codex_skill_source_command(action, provider)?\n }\n Some(ProviderAiAction::Doctor {\n path,\n assert_runtime,\n assert_schedule,\n assert_learning,\n assert_autonomous,\n json,\n }) => codex_doctor(\n path,\n assert_runtime,\n assert_schedule,\n assert_learning,\n assert_autonomous,\n json,\n provider,\n )?,\n Some(ProviderAiAction::Eval { path, limit, json }) => {\n codex_eval(path, limit, json, provider)?\n }\n Some(ProviderAiAction::TouchLaunch { mode, cwd }) => {\n codex_touch_launch(mode, cwd, provider)?\n }\n Some(ProviderAiAction::EnableGlobal {\n dry_run,\n install_launchd,\n start_daemon,\n sync_skills,\n full,\n minutes,\n limit,\n max_targets,\n within_hours,\n }) => codex_enable_global(\n dry_run,\n install_launchd,\n start_daemon,\n sync_skills,\n full,\n minutes,\n limit,\n max_targets,\n within_hours,\n provider,\n )?,\n Some(ProviderAiAction::Resolve {\n path,\n exact_cwd,\n json,\n query,\n }) => resolve_codex_input(path, query, exact_cwd, json, provider)?,\n Some(ProviderAiAction::Runtime { action }) => codex_runtime_command(action, provider)?,\n Some(ProviderAiAction::Resume { session, path }) => {\n resume_session(session, path, provider)?\n }\n Some(ProviderAiAction::Find {\n path,\n exact_cwd,\n query,\n }) => find_codex_session(path, query, exact_cwd, provider)?,\n Some(ProviderAiAction::FindAndCopy {\n path,\n exact_cwd,\n query,\n }) => find_and_copy_codex_session(path, query, exact_cwd, provider)?,\n Some(ProviderAiAction::Copy { session }) => copy_session(session, provider)?,\n Some(ProviderAiAction::Context {\n session,\n count,\n path,\n }) => copy_context(session, provider, count, path)?,\n Some(ProviderAiAction::Show {\n session,\n path,\n count,\n full,\n }) => show_session(session, provider, count, path, full)?,\n Some(ProviderAiAction::Recover {\n path,\n exact_cwd,\n limit,\n json,\n summary_only,\n query,\n }) => recover_codex_sessions(path, query, exact_cwd, limit, json, summary_only, provider)?,\n }\n Ok(())\n}\n\n/// Run the ai subcommand.\npub fn run(action: Option<AiAction>) -> Result<()> {\n let action = action.unwrap_or(AiAction::List);\n\n match action {\n AiAction::List => list_sessions(Provider::All)?,\n AiAction::Cursor { action } => run_provider(Provider::Cursor, action)?,\n AiAction::Claude { action } => match action {\n None => quick_start_session(Provider::Claude)?,\n Some(ProviderAiAction::List) => list_sessions(Provider::Claude)?,\n Some(ProviderAiAction::LatestId { path }) => {\n print_latest_session_id(Provider::Claude, path)?\n }\n Some(ProviderAiAction::Sessions { path, json }) => {\n provider_sessions(Provider::Claude, path, json)?\n }\n Some(ProviderAiAction::Continue { session, path }) => {\n continue_session(session, path, Provider::Claude)?\n }\n Some(ProviderAiAction::New) => new_session(Provider::Claude)?,\n Some(ProviderAiAction::Connect { .. }) => {\n bail!(\"connect is only supported for Codex sessions; use `f codex connect ...`\");\n }\n Some(ProviderAiAction::Open { .. }) | Some(ProviderAiAction::Resolve { .. }) => {\n bail!(\"open/resolve is only supported for Codex sessions; use `f codex ...`\");\n }\n Some(ProviderAiAction::Runtime { .. }) => {\n bail!(\n \"runtime helpers are only supported for Codex sessions; use `f codex runtime ...`\"\n );\n }\n Some(ProviderAiAction::Doctor { .. }) => {\n bail!(\"doctor is only supported for Codex sessions; use `f codex doctor`\");\n }\n Some(ProviderAiAction::Eval { .. }) => {\n bail!(\"eval is only supported for Codex sessions; use `f codex eval`\");\n }\n Some(ProviderAiAction::TouchLaunch { .. }) => {\n bail!(\n \"touch-launch is only supported for Codex sessions; use `f codex touch-launch`\"\n );\n }\n Some(ProviderAiAction::EnableGlobal { .. }) => {\n bail!(\n \"global Codex enablement is only supported for Codex sessions; use `f codex enable-global`\"\n );\n }\n Some(ProviderAiAction::Daemon { .. }) => {\n bail!(\"daemon is only supported for Codex sessions; use `f codex daemon ...`\");\n }\n Some(ProviderAiAction::Memory { .. }) => {\n bail!(\"memory is only supported for Codex sessions; use `f codex memory ...`\");\n }\n Some(ProviderAiAction::Telemetry { .. }) => {\n bail!(\"telemetry is only supported for Codex sessions; use `f codex telemetry ...`\");\n }\n Some(ProviderAiAction::Trace { .. }) => {\n bail!(\"trace is only supported for Codex sessions; use `f codex trace ...`\");\n }\n Some(ProviderAiAction::SkillEval { .. }) => {\n bail!(\n \"skill-eval is only supported for Codex sessions; use `f codex skill-eval ...`\"\n );\n }\n Some(ProviderAiAction::SkillSource { .. }) => {\n bail!(\n \"skill-source is only supported for Codex sessions; use `f codex skill-source ...`\"\n );\n }\n Some(ProviderAiAction::Resume { session, path }) => {\n resume_session(session, path, Provider::Claude)?\n }\n Some(ProviderAiAction::Find {\n path,\n exact_cwd,\n query,\n }) => find_codex_session(path, query, exact_cwd, Provider::Claude)?,\n Some(ProviderAiAction::FindAndCopy {\n path,\n exact_cwd,\n query,\n }) => find_and_copy_codex_session(path, query, exact_cwd, Provider::Claude)?,\n Some(ProviderAiAction::Copy { session }) => copy_session(session, Provider::Claude)?,\n Some(ProviderAiAction::Context {\n session,\n count,\n path,\n }) => copy_context(session, Provider::Claude, count, path)?,\n Some(ProviderAiAction::Show {\n session,\n path,\n count,\n full,\n }) => show_session(session, Provider::Claude, count, path, full)?,\n Some(ProviderAiAction::Recover {\n path,\n exact_cwd,\n limit,\n json,\n summary_only,\n query,\n }) => recover_codex_sessions(\n path,\n query,\n exact_cwd,\n limit,\n json,\n summary_only,\n Provider::Claude,\n )?,\n },\n AiAction::Codex { action } => match action {\n None => quick_start_session(Provider::Codex)?,\n Some(ProviderAiAction::List) => list_sessions(Provider::Codex)?,\n Some(ProviderAiAction::LatestId { path }) => {\n print_latest_session_id(Provider::Codex, path)?\n }\n Some(ProviderAiAction::Sessions { path, json }) => {\n provider_sessions(Provider::Codex, path, json)?\n }\n Some(ProviderAiAction::Continue { session, path }) => {\n continue_session(session, path, Provider::Codex)?\n }\n Some(ProviderAiAction::New) => new_session(Provider::Codex)?,\n Some(ProviderAiAction::Connect {\n path,\n exact_cwd,\n json,\n query,\n }) => connect_codex_session(path, query, exact_cwd, json, Provider::Codex)?,\n Some(ProviderAiAction::Open {\n path,\n exact_cwd,\n query,\n }) => open_codex_session(path, query, exact_cwd, Provider::Codex)?,\n Some(ProviderAiAction::Daemon { action }) => {\n codex_daemon_command(action, Provider::Codex)?\n }\n Some(ProviderAiAction::Memory { action }) => {\n codex_memory_command(action, Provider::Codex)?\n }\n Some(ProviderAiAction::Telemetry { action }) => {\n codex_telemetry_command(action, Provider::Codex)?\n }\n Some(ProviderAiAction::Trace { action }) => {\n codex_trace_command(action, Provider::Codex)?\n }\n Some(ProviderAiAction::SkillEval { action }) => {\n codex_skill_eval_command(action, Provider::Codex)?\n }\n Some(ProviderAiAction::SkillSource { action }) => {\n codex_skill_source_command(action, Provider::Codex)?\n }\n Some(ProviderAiAction::Doctor {\n path,\n assert_runtime,\n assert_schedule,\n assert_learning,\n assert_autonomous,\n json,\n }) => codex_doctor(\n path,\n assert_runtime,\n assert_schedule,\n assert_learning,\n assert_autonomous,\n json,\n Provider::Codex,\n )?,\n Some(ProviderAiAction::Eval { path, limit, json }) => {\n codex_eval(path, limit, json, Provider::Codex)?\n }\n Some(ProviderAiAction::TouchLaunch { mode, cwd }) => {\n codex_touch_launch(mode, cwd, Provider::Codex)?\n }\n Some(ProviderAiAction::EnableGlobal {\n dry_run,\n install_launchd,\n start_daemon,\n sync_skills,\n full,\n minutes,\n limit,\n max_targets,\n within_hours,\n }) => codex_enable_global(\n dry_run,\n install_launchd,\n start_daemon,\n sync_skills,\n full,\n minutes,\n limit,\n max_targets,\n within_hours,\n Provider::Codex,\n )?,\n Some(ProviderAiAction::Resolve {\n path,\n exact_cwd,\n json,\n query,\n }) => resolve_codex_input(path, query, exact_cwd, json, Provider::Codex)?,\n Some(ProviderAiAction::Runtime { action }) => {\n codex_runtime_command(action, Provider::Codex)?\n }\n Some(ProviderAiAction::Resume { session, path }) => {\n resume_session(session, path, Provider::Codex)?\n }\n Some(ProviderAiAction::Find {\n path,\n exact_cwd,\n query,\n }) => find_codex_session(path, query, exact_cwd, Provider::Codex)?,\n Some(ProviderAiAction::FindAndCopy {\n path,\n exact_cwd,\n query,\n }) => find_and_copy_codex_session(path, query, exact_cwd, Provider::Codex)?,\n Some(ProviderAiAction::Copy { session }) => copy_session(session, Provider::Codex)?,\n Some(ProviderAiAction::Context {\n session,\n count,\n path,\n }) => copy_context(session, Provider::Codex, count, path)?,\n Some(ProviderAiAction::Show {\n session,\n path,\n count,\n full,\n }) => show_session(session, Provider::Codex, count, path, full)?,\n Some(ProviderAiAction::Recover {\n path,\n exact_cwd,\n limit,\n json,\n summary_only,\n query,\n }) => recover_codex_sessions(\n path,\n query,\n exact_cwd,\n limit,\n json,\n summary_only,\n Provider::Codex,\n )?,\n },\n AiAction::Everruns(opts) => crate::ai_everruns::run(opts)?,\n AiAction::Resume { session, path } => resume_session(session, path, Provider::All)?,\n AiAction::Save { name, id } => save_session(&name, id)?,\n AiAction::Notes { session } => open_notes(&session)?,\n AiAction::Remove { session } => remove_session(&session)?,\n AiAction::Init => init_ai_folder()?,\n AiAction::Import => import_sessions()?,\n AiAction::Copy { session } => copy_session(session, Provider::All)?,\n AiAction::CopyClaude { search } => {\n let query = if search.is_empty() {\n None\n } else {\n Some(search.join(\" \"))\n };\n copy_last_session(Provider::Claude, query)?\n }\n AiAction::CopyCodex { search } => {\n let query = if search.is_empty() {\n None\n } else {\n Some(search.join(\" \"))\n };\n copy_last_session(Provider::Codex, query)?\n }\n AiAction::Context {\n session,\n count,\n path,\n } => copy_context(session, Provider::All, count, path)?,\n }\n\n Ok(())\n}\n\nfn for_each_nonempty_jsonl_line(path: &Path, mut on_line: impl FnMut(&str)) -> Result<()> {\n let file =\n fs::File::open(path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let mut reader = BufReader::with_capacity(64 * 1024, file);\n let mut line = String::with_capacity(1024);\n\n loop {\n line.clear();\n if reader.read_line(&mut line)? == 0 {\n break;\n }\n let line = line.trim_end_matches(['\\n', '\\r']);\n if line.trim().is_empty() {\n continue;\n }\n on_line(line);\n }\n\n Ok(())\n}\n\n/// Get checkpoint file path for a project.\nfn get_checkpoint_path(project_path: &PathBuf) -> PathBuf {\n project_path\n .join(\".ai\")\n .join(\"internal\")\n .join(\"commit-checkpoints.json\")\n}\n\n/// Load commit checkpoints.\npub fn load_checkpoints(project_path: &PathBuf) -> Result<CommitCheckpoints> {\n let path = get_checkpoint_path(project_path);\n if !path.exists() {\n return Ok(CommitCheckpoints::default());\n }\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n serde_json::from_str(&content).context(\"failed to parse commit-checkpoints.json\")\n}\n\n/// Save commit checkpoints.\npub fn save_checkpoint(project_path: &PathBuf, checkpoint: CommitCheckpoint) -> Result<()> {\n let path = get_checkpoint_path(project_path);\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n let checkpoints = CommitCheckpoints {\n last_commit: Some(checkpoint),\n };\n let content = serde_json::to_string_pretty(&checkpoints)?;\n fs::write(&path, content)?;\n Ok(())\n}\n\n/// Log review result for tracking async commits.\npub fn log_review_result(\n project_path: &PathBuf,\n issues_found: bool,\n issues: &[String],\n context_chars: usize,\n review_time_secs: u64,\n) {\n let log_path = project_path\n .join(\".ai\")\n .join(\"internal\")\n .join(\"review-log.jsonl\");\n if let Some(parent) = log_path.parent() {\n let _ = fs::create_dir_all(parent);\n }\n\n let entry = json!({\n \"timestamp\": chrono::Utc::now().to_rfc3339(),\n \"issues_found\": issues_found,\n \"issue_count\": issues.len(),\n \"context_chars\": context_chars,\n \"review_time_secs\": review_time_secs,\n });\n\n if let Ok(mut file) = fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(&log_path)\n {\n let _ = writeln!(file, \"{}\", entry);\n }\n}\n\n/// Log commit review details for later analysis.\npub fn log_commit_review(\n project_path: &PathBuf,\n commit_sha: &str,\n branch: &str,\n message: &str,\n review_model: &str,\n reviewer: &str,\n issues_found: bool,\n issues: &[String],\n summary: Option<&str>,\n timed_out: bool,\n context_chars: usize,\n) {\n let log_dir = project_path.join(\".ai\").join(\"internal\").join(\"commits\");\n let log_path = log_dir.join(\"review-log.jsonl\");\n if let Some(parent) = log_path.parent() {\n let _ = fs::create_dir_all(parent);\n }\n\n let entry = json!({\n \"timestamp\": chrono::Utc::now().to_rfc3339(),\n \"commit_sha\": commit_sha,\n \"branch\": branch,\n \"message\": message,\n \"review\": {\n \"model\": review_model,\n \"reviewer\": reviewer,\n \"issues_found\": issues_found,\n \"issue_count\": issues.len(),\n \"issues\": issues,\n \"summary\": summary,\n \"timed_out\": timed_out,\n },\n \"context_chars\": context_chars,\n });\n\n if let Ok(mut file) = fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(&log_path)\n {\n let _ = writeln!(file, \"{}\", entry);\n }\n}\n\n#[derive(Debug, Serialize)]\npub struct CommitReviewSummary {\n pub model: String,\n pub reviewer: String,\n pub issues_found: bool,\n pub issues: Vec<String>,\n pub summary: Option<String>,\n pub timed_out: bool,\n}\n\n/// Log commit metadata (with optional review data) for later analysis.\npub fn log_commit_event(\n project_path: &PathBuf,\n commit_sha: &str,\n branch: &str,\n message: &str,\n author_name: &str,\n author_email: &str,\n command: &str,\n review: Option<CommitReviewSummary>,\n context_chars: Option<usize>,\n) {\n let log_dir = project_path.join(\".ai\").join(\"internal\").join(\"commits\");\n let log_path = log_dir.join(\"log.jsonl\");\n if let Some(parent) = log_path.parent() {\n let _ = fs::create_dir_all(parent);\n }\n\n let entry = json!({\n \"timestamp\": chrono::Utc::now().to_rfc3339(),\n \"commit_sha\": commit_sha,\n \"branch\": branch,\n \"message\": message,\n \"author\": {\n \"name\": author_name,\n \"email\": author_email,\n },\n \"command\": command,\n \"review\": review,\n \"context_chars\": context_chars,\n });\n\n if let Ok(mut file) = fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(&log_path)\n {\n let _ = writeln!(file, \"{}\", entry);\n }\n}\n\n/// Get AI session context since the last commit checkpoint.\n/// Returns all exchanges from the checkpoint timestamp to now.\npub fn get_context_since_checkpoint() -> Result<Option<String>> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n get_context_since_checkpoint_for_path(&cwd)\n}\n\n/// Get AI session context since the last commit checkpoint for a specific path.\npub fn get_context_since_checkpoint_for_path(project_path: &PathBuf) -> Result<Option<String>> {\n let checkpoints = load_checkpoints(project_path).unwrap_or_default();\n\n // Get sessions for Claude, Codex, and Cursor\n let sessions = read_sessions_for_path(Provider::All, project_path)?;\n\n if sessions.is_empty() {\n return Ok(None);\n }\n\n // Read context since checkpoint\n let since_ts = checkpoints\n .last_commit\n .as_ref()\n .and_then(|c| c.last_entry_timestamp.clone());\n\n let mut combined = String::new();\n let since_info = if since_ts.is_some() {\n \" (since last commit)\"\n } else {\n \" (full session - no previous commit)\"\n };\n\n for session in sessions {\n let provider_name = match session.provider {\n Provider::Claude => \"Claude Code\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n };\n\n if let Ok((context, last_ts)) = read_context_since(\n &session.session_id,\n session.provider,\n since_ts.as_deref(),\n project_path,\n ) {\n if context.trim().is_empty() {\n continue;\n }\n if !combined.is_empty() {\n combined.push_str(\"\\n\\n\");\n }\n combined.push_str(&format!(\n \"=== {} Session Context{} ===\\nLast entry: {}\\n\\n{}\\n\\n=== End Session Context ===\",\n provider_name,\n since_info,\n last_ts.unwrap_or_else(|| \"unknown\".to_string()),\n context\n ));\n }\n }\n\n if combined.trim().is_empty() {\n Ok(None)\n } else {\n Ok(Some(combined))\n }\n}\n\n/// Structured AI session data for GitEdit sync.\n#[derive(Debug, Serialize, Clone)]\npub struct GitEditSessionData {\n pub session_id: String,\n pub provider: String,\n pub started_at: Option<String>,\n pub last_activity_at: Option<String>,\n pub exchanges: Vec<GitEditExchange>,\n pub context_summary: Option<String>,\n}\n\n#[derive(Debug, Serialize, Clone)]\npub struct GitEditExchange {\n pub user_message: String,\n pub assistant_message: String,\n pub timestamp: String,\n}\n\n/// Get session IDs quickly for early hash generation.\n/// Returns (session_ids, checkpoint_timestamp) for hashing before full data load.\npub fn get_session_ids_for_hash(project_path: &PathBuf) -> Result<(Vec<String>, Option<String>)> {\n let checkpoints = load_checkpoints(project_path).unwrap_or_default();\n let sessions = read_sessions_for_path(Provider::All, project_path)?;\n\n let checkpoint_ts = checkpoints\n .last_commit\n .as_ref()\n .and_then(|c| c.last_entry_timestamp.clone());\n\n let session_ids: Vec<String> = sessions.iter().map(|s| s.session_id.clone()).collect();\n\n Ok((session_ids, checkpoint_ts))\n}\n\n/// Get structured AI session data for GitEdit sync.\n/// Returns sessions with full exchange history since the last checkpoint.\npub fn get_sessions_for_gitedit(project_path: &PathBuf) -> Result<Vec<GitEditSessionData>> {\n let checkpoints = load_checkpoints(project_path).unwrap_or_default();\n let since_ts = checkpoints\n .last_commit\n .as_ref()\n .and_then(|c| c.last_entry_timestamp.clone());\n get_sessions_for_gitedit_between(project_path, since_ts.as_deref(), None)\n}\n\n/// Get structured AI session data for GitEdit/myflow sync in a strict time window.\n/// Includes exchanges where `since_ts < exchange_ts <= until_ts` (when bounds are provided).\npub fn get_sessions_for_gitedit_between(\n project_path: &PathBuf,\n since_ts: Option<&str>,\n until_ts: Option<&str>,\n) -> Result<Vec<GitEditSessionData>> {\n let sessions = read_sessions_for_path(Provider::All, project_path)?;\n\n if sessions.is_empty() {\n return Ok(vec![]);\n }\n\n let mut result = Vec::new();\n\n for session in sessions {\n let provider_name = match session.provider {\n Provider::Claude => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n Provider::All => \"unknown\",\n };\n\n // Get full exchanges (not summarized)\n let exchanges = get_session_exchanges_since(\n &session.session_id,\n session.provider,\n since_ts,\n until_ts,\n project_path,\n )?;\n\n if exchanges.is_empty() {\n continue;\n }\n\n // Get last timestamp from exchanges\n let last_activity = exchanges.last().map(|e| e.timestamp.clone());\n\n // Create context summary (first few words of first user message)\n let context_summary = exchanges.first().map(|e| {\n let msg = &e.user_message;\n let words: Vec<&str> = msg.split_whitespace().take(10).collect();\n let summary = words.join(\" \");\n if msg.split_whitespace().count() > 10 {\n format!(\"{}...\", summary)\n } else {\n summary\n }\n });\n\n result.push(GitEditSessionData {\n session_id: session.session_id.clone(),\n provider: provider_name.to_string(),\n started_at: session.timestamp.clone(),\n last_activity_at: last_activity,\n exchanges,\n context_summary,\n });\n }\n\n Ok(result)\n}\n\n/// Get full exchanges from a session since a timestamp.\nfn get_session_exchanges_since(\n session_id: &str,\n provider: Provider,\n since_ts: Option<&str>,\n until_ts: Option<&str>,\n project_path: &PathBuf,\n) -> Result<Vec<GitEditExchange>> {\n if provider == Provider::Codex {\n let session_file = find_codex_session_file(session_id);\n if let Some(session_file) = session_file {\n let (exchanges, _) = read_codex_exchanges(&session_file, since_ts, until_ts)?;\n return Ok(exchanges\n .into_iter()\n .map(|(user, assistant, ts)| GitEditExchange {\n user_message: user,\n assistant_message: assistant,\n timestamp: ts,\n })\n .collect());\n }\n return Ok(vec![]);\n }\n if provider == Provider::Cursor {\n let session_file = find_cursor_session_file(session_id);\n if let Some(session_file) = session_file {\n let (exchanges, _) = read_cursor_exchanges(&session_file, since_ts, until_ts)?;\n return Ok(exchanges\n .into_iter()\n .map(|(user, assistant, ts)| GitEditExchange {\n user_message: user,\n assistant_message: assistant,\n timestamp: ts,\n })\n .collect());\n }\n return Ok(vec![]);\n }\n\n let path_str = project_path.to_string_lossy().to_string();\n let project_folder = path_to_project_name(&path_str);\n\n let projects_dir = get_claude_projects_dir();\n let session_file = projects_dir\n .join(&project_folder)\n .join(format!(\"{}.jsonl\", session_id));\n\n if !session_file.exists() {\n return Ok(vec![]);\n }\n\n let window = parse_timestamp_window(since_ts, until_ts);\n\n let mut exchanges: Vec<GitEditExchange> = Vec::new();\n let mut current_user: Option<String> = None;\n let mut current_ts: Option<String> = None;\n\n for_each_nonempty_jsonl_line(&session_file, |line| {\n if let Ok(entry) = crate::json_parse::parse_json_line::<JsonlEntry>(line) {\n let entry_ts = entry.timestamp.clone();\n\n // In bounded mode, require a timestamp and enforce window.\n if since_ts.is_some() || until_ts.is_some() {\n let Some(ref ts) = entry_ts else {\n return;\n };\n if !timestamp_in_window_cached(ts, &window) {\n return;\n }\n }\n\n if let Some(ref msg) = entry.message {\n let role = msg.role.as_deref().unwrap_or(\"unknown\");\n\n let Some(content_text) = msg.content.as_ref().and_then(extract_message_text) else {\n return;\n };\n let Some(clean_text) = normalize_session_message(role, &content_text) else {\n return;\n };\n\n match role {\n \"user\" => {\n current_user = Some(clean_text);\n current_ts = entry_ts.clone();\n }\n \"assistant\" => {\n if let Some(user_msg) = current_user.take() {\n let ts = current_ts.take().or(entry_ts).unwrap_or_default();\n exchanges.push(GitEditExchange {\n user_message: user_msg,\n assistant_message: clean_text,\n timestamp: ts,\n });\n }\n }\n _ => {}\n }\n }\n }\n })?;\n\n Ok(exchanges)\n}\n\n/// Get the last entry timestamp from the current session (for saving checkpoint).\npub fn get_last_entry_timestamp() -> Result<Option<(String, String)>> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n get_last_entry_timestamp_for_path(&cwd)\n}\n\n/// Get the last entry timestamp for sessions associated with a specific path.\npub fn get_last_entry_timestamp_for_path(\n project_path: &PathBuf,\n) -> Result<Option<(String, String)>> {\n let sessions = read_sessions_for_path(Provider::All, project_path)?;\n\n if sessions.is_empty() {\n return Ok(None);\n }\n\n let mut best: Option<(String, String)> = None;\n for session in sessions {\n if let Some(ts) =\n get_session_last_timestamp(&session.session_id, session.provider, project_path)?\n {\n let is_newer = best.as_ref().map_or(true, |(_, best_ts)| ts > *best_ts);\n if is_newer {\n best = Some((session.session_id.clone(), ts));\n }\n }\n }\n\n Ok(best)\n}\n\n/// Get the last timestamp from a session file.\nfn get_session_last_timestamp(\n session_id: &str,\n provider: Provider,\n project_path: &PathBuf,\n) -> Result<Option<String>> {\n if provider == Provider::Codex {\n let session_file = find_codex_session_file(session_id);\n let Some(session_file) = session_file else {\n return Ok(None);\n };\n return get_codex_last_timestamp(&session_file);\n }\n if provider == Provider::Cursor {\n let session_file = find_cursor_session_file(session_id);\n let Some(session_file) = session_file else {\n return Ok(None);\n };\n return get_cursor_last_timestamp(&session_file);\n }\n\n let path_str = project_path.to_string_lossy().to_string();\n let project_folder = path_to_project_name(&path_str);\n\n let projects_dir = match provider {\n Provider::Claude | Provider::All => get_claude_projects_dir(),\n Provider::Codex => get_codex_projects_dir(),\n Provider::Cursor => get_cursor_projects_dir(),\n };\n\n let session_file = projects_dir\n .join(&project_folder)\n .join(format!(\"{}.jsonl\", session_id));\n\n if !session_file.exists() {\n return Ok(None);\n }\n\n let mut last_ts: Option<String> = None;\n for_each_nonempty_jsonl_line(&session_file, |line| {\n if let Ok(entry) = crate::json_parse::parse_json_line::<JsonlEntry>(line) {\n if let Some(ts) = entry.timestamp {\n last_ts = Some(ts);\n }\n }\n })?;\n\n Ok(last_ts)\n}\n\n/// Read context from session since a given timestamp.\nfn read_context_since(\n session_id: &str,\n provider: Provider,\n since_ts: Option<&str>,\n project_path: &PathBuf,\n) -> Result<(String, Option<String>)> {\n if provider == Provider::Codex {\n let session_file = find_codex_session_file(session_id).ok_or_else(|| {\n anyhow::anyhow!(\"Session file not found for Codex session {}\", session_id)\n })?;\n return read_codex_context_since(&session_file, since_ts);\n }\n if provider == Provider::Cursor {\n let session_file = find_cursor_session_file(session_id).ok_or_else(|| {\n anyhow::anyhow!(\"Session file not found for Cursor session {}\", session_id)\n })?;\n let (exchanges, last_ts) = read_cursor_exchanges(&session_file, since_ts, None)?;\n\n if exchanges.is_empty() {\n return Ok((String::new(), last_ts));\n }\n\n const MAX_EXCHANGES: usize = 5;\n const MAX_USER_CHARS: usize = 500;\n const MAX_ASSIST_CHARS: usize = 300;\n\n let total_exchanges = exchanges.len();\n let exchanges_to_use: Vec<_> = if total_exchanges > MAX_EXCHANGES {\n exchanges\n .into_iter()\n .skip(total_exchanges - MAX_EXCHANGES)\n .collect()\n } else {\n exchanges\n };\n\n let mut context = String::new();\n if total_exchanges > MAX_EXCHANGES {\n context.push_str(&format!(\"[+{} earlier]\\n\", total_exchanges - MAX_EXCHANGES));\n }\n\n for (user_msg, assistant_msg, _ts) in &exchanges_to_use {\n let user_intent = extract_intent(user_msg, MAX_USER_CHARS);\n let assist_summary = extract_intent(assistant_msg, MAX_ASSIST_CHARS);\n context.push_str(\">\");\n context.push_str(&user_intent);\n context.push('\\n');\n context.push_str(&assist_summary);\n context.push_str(\"\\n\\n\");\n }\n\n return Ok((context.trim().to_string(), last_ts));\n }\n\n let path_str = project_path.to_string_lossy().to_string();\n let project_folder = path_to_project_name(&path_str);\n\n let projects_dir = match provider {\n Provider::Claude | Provider::All => get_claude_projects_dir(),\n Provider::Codex => get_codex_projects_dir(),\n Provider::Cursor => get_cursor_projects_dir(),\n };\n\n let session_file = projects_dir\n .join(&project_folder)\n .join(format!(\"{}.jsonl\", session_id));\n\n if !session_file.exists() {\n bail!(\"Session file not found: {}\", session_file.display());\n }\n\n // Collect exchanges after the checkpoint timestamp\n let mut exchanges: Vec<(String, String, String)> = Vec::new(); // (user_msg, assistant_msg, timestamp)\n let mut current_user: Option<String> = None;\n let mut current_ts: Option<String> = None;\n let mut last_ts: Option<String> = None;\n\n for_each_nonempty_jsonl_line(&session_file, |line| {\n if let Ok(entry) = crate::json_parse::parse_json_line::<JsonlEntry>(line) {\n let entry_ts = entry.timestamp.clone();\n\n // Skip entries before checkpoint\n if let (Some(since), Some(ts)) = (since_ts, &entry_ts) {\n if ts.as_str() <= since {\n return;\n }\n }\n\n if let Some(ref msg) = entry.message {\n let role = msg.role.as_deref().unwrap_or(\"unknown\");\n\n let Some(content_text) = msg.content.as_ref().and_then(extract_message_text) else {\n return;\n };\n let Some(clean_text) = normalize_session_message(role, &content_text) else {\n return;\n };\n\n match role {\n \"user\" => {\n current_user = Some(clean_text);\n current_ts = entry_ts.clone();\n }\n \"assistant\" => {\n if let Some(user_msg) = current_user.take() {\n let ts = current_ts.take().or(entry_ts.clone()).unwrap_or_default();\n exchanges.push((user_msg, clean_text, ts.clone()));\n last_ts = Some(ts);\n }\n }\n _ => {}\n }\n }\n\n if entry_ts.is_some() {\n last_ts = entry_ts;\n }\n }\n })?;\n\n if exchanges.is_empty() {\n return Ok((String::new(), last_ts));\n }\n\n // Optimization: prioritize recent exchanges, fit within reasonable budget\n // Keep it compact - extract intent, not full conversation\n const MAX_EXCHANGES: usize = 5;\n const MAX_USER_CHARS: usize = 500; // User requests are short\n const MAX_ASSIST_CHARS: usize = 300; // Just capture what was done, not full response\n\n let total_exchanges = exchanges.len();\n let exchanges_to_use: Vec<_> = if total_exchanges > MAX_EXCHANGES {\n exchanges\n .into_iter()\n .skip(total_exchanges - MAX_EXCHANGES)\n .collect()\n } else {\n exchanges\n };\n\n // Format compact context - focus on intent\n let mut context = String::new();\n\n if total_exchanges > MAX_EXCHANGES {\n context.push_str(&format!(\"[+{} earlier]\\n\", total_exchanges - MAX_EXCHANGES));\n }\n\n for (user_msg, assistant_msg, _ts) in &exchanges_to_use {\n // Extract first line/sentence of user msg as intent\n let user_intent = extract_intent(user_msg, MAX_USER_CHARS);\n let assist_summary = extract_intent(assistant_msg, MAX_ASSIST_CHARS);\n\n context.push_str(\">\");\n context.push_str(&user_intent);\n context.push('\\n');\n context.push_str(&assist_summary);\n context.push_str(\"\\n\\n\");\n }\n\n context = context.trim().to_string();\n\n Ok((context, last_ts))\n}\n\n/// Find the largest valid UTF-8 char boundary at or before `pos`.\nfn floor_char_boundary(s: &str, pos: usize) -> usize {\n let mut end = pos.min(s.len());\n while end > 0 && !s.is_char_boundary(end) {\n end -= 1;\n }\n end\n}\n\n/// Truncate a message to max chars, preserving meaningful content\nfn truncate_message(msg: &str, max_chars: usize) -> String {\n if msg.len() <= max_chars {\n return msg.to_string();\n }\n let end = floor_char_boundary(msg, max_chars);\n format!(\"{}...\", &msg[..end])\n}\n\n/// Extract intent from a message - first meaningful content, truncated\nfn extract_intent(msg: &str, max_chars: usize) -> String {\n // Skip common prefixes and get to the meat\n let clean = msg\n .trim()\n .trim_start_matches(\"I'll \")\n .trim_start_matches(\"I will \")\n .trim_start_matches(\"Let me \")\n .trim_start_matches(\"Sure, \")\n .trim_start_matches(\"Okay, \")\n .trim_start_matches(\"I'm going to \")\n .trim();\n\n // Take first line or sentence\n let first_part = clean\n .lines()\n .next()\n .unwrap_or(clean)\n .split(\". \")\n .next()\n .unwrap_or(clean);\n\n truncate_message(first_part, max_chars)\n}\n\nfn read_codex_context_since(\n session_file: &PathBuf,\n since_ts: Option<&str>,\n) -> Result<(String, Option<String>)> {\n let (exchanges, last_ts) = read_codex_exchanges(session_file, since_ts, None)?;\n\n if exchanges.is_empty() {\n return Ok((String::new(), last_ts));\n }\n\n // Optimization: only keep last N exchanges for efficiency\n const MAX_EXCHANGES: usize = 8;\n const MAX_MSG_CHARS: usize = 2000;\n\n let total_exchanges = exchanges.len();\n let exchanges_to_use: Vec<_> = if total_exchanges > MAX_EXCHANGES {\n exchanges\n .into_iter()\n .skip(total_exchanges - MAX_EXCHANGES)\n .collect()\n } else {\n exchanges\n };\n\n let mut context = String::new();\n\n // Add summary if we skipped older exchanges\n if total_exchanges > MAX_EXCHANGES {\n context.push_str(&format!(\n \"[{} earlier exchanges omitted for brevity]\\n\\n\",\n total_exchanges - MAX_EXCHANGES\n ));\n }\n\n for (user_msg, assistant_msg, _ts) in &exchanges_to_use {\n context.push_str(\"H: \");\n context.push_str(&truncate_message(user_msg, MAX_MSG_CHARS));\n context.push_str(\"\\n\\n\");\n context.push_str(\"A: \");\n context.push_str(&truncate_message(assistant_msg, MAX_MSG_CHARS));\n context.push_str(\"\\n\\n\");\n }\n\n while context.ends_with('\\n') {\n context.pop();\n }\n context.push('\\n');\n\n Ok((context, last_ts))\n}\n\nfn read_codex_last_context(session_file: &PathBuf, count: usize) -> Result<String> {\n let (exchanges, _last_ts) = read_codex_exchanges(session_file, None, None)?;\n\n if exchanges.is_empty() {\n bail!(\"No exchanges found in session\");\n }\n\n let start = exchanges.len().saturating_sub(count);\n let last_exchanges = &exchanges[start..];\n\n let mut context = String::new();\n for (user_msg, assistant_msg, _ts) in last_exchanges {\n context.push_str(\"Human: \");\n context.push_str(user_msg);\n context.push_str(\"\\n\\n\");\n context.push_str(\"Assistant: \");\n context.push_str(assistant_msg);\n context.push_str(\"\\n\\n\");\n }\n\n while context.ends_with('\\n') {\n context.pop();\n }\n context.push('\\n');\n\n Ok(context)\n}\n\npub(crate) fn read_codex_memory_exchanges(\n session_id: &str,\n max_count: usize,\n) -> Result<Vec<(String, String)>> {\n let session_file = find_codex_session_file(session_id)\n .ok_or_else(|| anyhow::anyhow!(\"Codex session file not found: {}\", session_id))?;\n let (exchanges, _last_ts) = read_codex_exchanges(&session_file, None, None)?;\n if exchanges.is_empty() || max_count == 0 {\n return Ok(Vec::new());\n }\n\n let start = exchanges.len().saturating_sub(max_count);\n Ok(exchanges[start..]\n .iter()\n .filter_map(|(user, assistant, _)| {\n let user = normalize_session_message(\"user\", user)?;\n let assistant = normalize_session_message(\"assistant\", assistant)?;\n Some((user, assistant))\n })\n .collect())\n}\n\nfn read_cursor_last_context(session_file: &PathBuf, count: usize) -> Result<String> {\n let (exchanges, _last_ts) = read_cursor_exchanges(session_file, None, None)?;\n\n if exchanges.is_empty() {\n bail!(\"No exchanges found in session\");\n }\n\n let start = exchanges.len().saturating_sub(count);\n let last_exchanges = &exchanges[start..];\n\n let mut context = String::new();\n for (user_msg, assistant_msg, _ts) in last_exchanges {\n context.push_str(\"Human: \");\n context.push_str(user_msg);\n context.push_str(\"\\n\\n\");\n context.push_str(\"Assistant: \");\n context.push_str(assistant_msg);\n context.push_str(\"\\n\\n\");\n }\n\n while context.ends_with('\\n') {\n context.pop();\n }\n context.push('\\n');\n\n Ok(context)\n}\n\nfn read_codex_exchanges(\n session_file: &PathBuf,\n since_ts: Option<&str>,\n until_ts: Option<&str>,\n) -> Result<(Vec<(String, String, String)>, Option<String>)> {\n let window = parse_timestamp_window(since_ts, until_ts);\n let mut exchanges: Vec<(String, String, String)> = Vec::new();\n let mut current_user: Option<String> = None;\n let mut current_ts: Option<String> = None;\n let mut last_ts: Option<String> = None;\n\n for_each_nonempty_jsonl_line(session_file, |line| {\n let entry: CodexEntry = match crate::json_parse::parse_json_line(line) {\n Ok(v) => v,\n Err(_) => return,\n };\n\n let entry_ts = entry.timestamp.clone();\n if since_ts.is_some() || until_ts.is_some() {\n let Some(ts) = entry_ts.as_deref() else {\n return;\n };\n if !timestamp_in_window_cached(ts, &window) {\n return;\n }\n }\n\n if let Some((role, text)) = extract_codex_message(&entry) {\n match role.as_str() {\n \"user\" => {\n current_user = Some(text);\n current_ts = entry_ts.clone();\n }\n \"assistant\" => {\n if let Some(user_msg) = current_user.take() {\n let ts = current_ts.take().or(entry_ts.clone()).unwrap_or_default();\n exchanges.push((user_msg, text, ts.clone()));\n last_ts = Some(ts);\n }\n }\n _ => {}\n }\n }\n\n if entry_ts.is_some() {\n last_ts = entry_ts;\n }\n })?;\n\n Ok((exchanges, last_ts))\n}\n\nfn read_cursor_exchanges(\n session_file: &PathBuf,\n since_ts: Option<&str>,\n until_ts: Option<&str>,\n) -> Result<(Vec<(String, String, String)>, Option<String>)> {\n let session_ts = get_cursor_last_timestamp(session_file)?;\n if since_ts.is_some() || until_ts.is_some() {\n let window = parse_timestamp_window(since_ts, until_ts);\n if session_ts\n .as_deref()\n .map(|ts| !timestamp_in_window_cached(ts, &window))\n .unwrap_or(false)\n {\n return Ok((Vec::new(), session_ts));\n }\n }\n\n let mut exchanges: Vec<(String, String, String)> = Vec::new();\n let mut current_user: Option<String> = None;\n\n for_each_nonempty_jsonl_line(session_file, |line| {\n let entry: CursorEntry = match crate::json_parse::parse_json_line(line) {\n Ok(v) => v,\n Err(_) => return,\n };\n\n let Some((role, text)) = extract_cursor_message(&entry) else {\n return;\n };\n\n match role.as_str() {\n \"user\" => {\n current_user = Some(text);\n }\n \"assistant\" => {\n if let Some(user_msg) = current_user.take() {\n let ts = session_ts.clone().unwrap_or_default();\n exchanges.push((user_msg, text, ts));\n }\n }\n _ => {}\n }\n })?;\n\n Ok((exchanges, session_ts))\n}\n\nfn parse_timestamp_for_compare(ts: &str) -> Option<chrono::DateTime<chrono::Utc>> {\n chrono::DateTime::parse_from_rfc3339(ts)\n .map(|dt| dt.with_timezone(&chrono::Utc))\n .or_else(|_| {\n chrono::NaiveDateTime::parse_from_str(ts, \"%Y-%m-%dT%H:%M:%S%.fZ\")\n .map(|dt| dt.and_utc())\n })\n .ok()\n}\n\nstruct TimestampWindow<'a> {\n since_raw: Option<&'a str>,\n until_raw: Option<&'a str>,\n since_dt: Option<chrono::DateTime<chrono::Utc>>,\n until_dt: Option<chrono::DateTime<chrono::Utc>>,\n}\n\nfn parse_timestamp_window<'a>(\n since_ts: Option<&'a str>,\n until_ts: Option<&'a str>,\n) -> TimestampWindow<'a> {\n TimestampWindow {\n since_raw: since_ts,\n until_raw: until_ts,\n since_dt: since_ts.and_then(parse_timestamp_for_compare),\n until_dt: until_ts.and_then(parse_timestamp_for_compare),\n }\n}\n\nfn timestamp_in_window_cached(ts: &str, window: &TimestampWindow<'_>) -> bool {\n let ts_dt = parse_timestamp_for_compare(ts);\n\n if let Some(entry_dt) = ts_dt {\n if let Some(lower) = window.since_dt {\n if entry_dt <= lower {\n return false;\n }\n } else if let Some(lower_raw) = window.since_raw {\n if ts <= lower_raw {\n return false;\n }\n }\n\n if let Some(upper) = window.until_dt {\n if entry_dt > upper {\n return false;\n }\n } else if let Some(upper_raw) = window.until_raw {\n if ts > upper_raw {\n return false;\n }\n }\n return true;\n }\n\n if let Some(lower_raw) = window.since_raw {\n if ts <= lower_raw {\n return false;\n }\n }\n if let Some(upper_raw) = window.until_raw {\n if ts > upper_raw {\n return false;\n }\n }\n true\n}\n\nfn get_codex_last_timestamp(session_file: &PathBuf) -> Result<Option<String>> {\n let mut last_ts: Option<String> = None;\n\n for_each_nonempty_jsonl_line(session_file, |line| {\n let entry: CodexEntry = match crate::json_parse::parse_json_line(line) {\n Ok(v) => v,\n Err(_) => return,\n };\n\n if let Some(ts) = entry.timestamp {\n last_ts = Some(ts);\n return;\n }\n\n if let Some(payload_ts) = entry\n .payload\n .as_ref()\n .and_then(|p| p.get(\"timestamp\"))\n .and_then(|v| v.as_str())\n {\n last_ts = Some(payload_ts.to_string());\n }\n })?;\n\n Ok(last_ts)\n}\n\nfn get_cursor_last_timestamp(session_file: &PathBuf) -> Result<Option<String>> {\n Ok(get_cursor_file_timestamp(session_file))\n}\n\nfn extract_codex_message(entry: &CodexEntry) -> Option<(String, String)> {\n let entry_type = entry.entry_type.as_deref();\n\n if entry_type == Some(\"response_item\") {\n let payload = entry.payload.as_ref()?;\n if payload.get(\"type\").and_then(|v| v.as_str()) != Some(\"message\") {\n return None;\n }\n let role = payload.get(\"role\").and_then(|v| v.as_str())?.to_string();\n let content = payload.get(\"content\")?;\n let text = extract_codex_content_text(content)?;\n let clean_text = normalize_session_message(&role, &text)?;\n return Some((role, clean_text));\n }\n\n if entry_type == Some(\"event_msg\") {\n let payload = entry.payload.as_ref()?;\n let payload_type = payload.get(\"type\").and_then(|v| v.as_str());\n if payload_type == Some(\"user_message\") {\n let text = payload.get(\"message\").and_then(|v| v.as_str())?;\n let clean_text = normalize_session_message(\"user\", text)?;\n return Some((\"user\".to_string(), clean_text));\n }\n if payload_type == Some(\"agent_message\") {\n let text = payload.get(\"message\").and_then(|v| v.as_str())?;\n let clean_text = normalize_session_message(\"assistant\", text)?;\n return Some((\"assistant\".to_string(), clean_text));\n }\n }\n\n if entry_type == Some(\"message\") {\n let role = entry.role.as_deref()?.to_string();\n let content = entry.content.as_ref()?;\n let text = extract_codex_content_text(content)?;\n let clean_text = normalize_session_message(&role, &text)?;\n return Some((role, clean_text));\n }\n\n None\n}\n\nfn normalize_cursor_role(role: &str) -> &str {\n match role {\n \"assistant\" | \"assistanlft\" => \"assistant\",\n \"user\" => \"user\",\n other => other,\n }\n}\n\nfn extract_cursor_message(entry: &CursorEntry) -> Option<(String, String)> {\n let role = normalize_cursor_role(entry.role.as_deref()?);\n if role != \"user\" && role != \"assistant\" {\n return None;\n }\n\n let message = entry.message.as_ref()?;\n let content = message.content.as_ref()?;\n let text = extract_message_text(content)?;\n let clean_text = normalize_session_message(role, &text)?;\n Some((role.to_string(), clean_text))\n}\n\n/// Get recent AI session context for the current project.\n/// Used by commit workflow to provide context for code review.\n/// Returns the last N exchanges from the most recent sessions.\npub fn get_recent_session_context(max_exchanges: usize) -> Result<Option<String>> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n\n // Get sessions for Claude, Codex, and Cursor\n let sessions = read_sessions_for_path(Provider::All, &cwd)?;\n\n if sessions.is_empty() {\n return Ok(None);\n }\n\n // Get the most recent session\n let recent_session = &sessions[0];\n\n // Read context from the most recent session\n match read_last_context(\n &recent_session.session_id,\n recent_session.provider,\n max_exchanges,\n &cwd,\n ) {\n Ok(context) => {\n if context.trim().is_empty() {\n Ok(None)\n } else {\n let provider_name = match recent_session.provider {\n Provider::Claude => \"Claude Code\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n };\n Ok(Some(format!(\n \"=== Recent {} Session Context ===\\n\\n{}\\n\\n=== End Session Context ===\",\n provider_name, context\n )))\n }\n }\n Err(_) => Ok(None),\n }\n}\n\n/// Get the .ai/internal/sessions/claude directory for the current project.\nfn get_ai_sessions_dir() -> Result<PathBuf> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n Ok(cwd\n .join(\".ai\")\n .join(\"internal\")\n .join(\"sessions\")\n .join(\"claude\"))\n}\n\n/// Get the index.json path.\nfn get_index_path() -> Result<PathBuf> {\n Ok(get_ai_sessions_dir()?.join(\"index.json\"))\n}\n\n/// Get the notes directory.\nfn get_notes_dir() -> Result<PathBuf> {\n Ok(get_ai_sessions_dir()?.join(\"notes\"))\n}\n\n/// Load the session index.\nfn load_index() -> Result<SessionIndex> {\n let path = get_index_path()?;\n if !path.exists() {\n return Ok(SessionIndex::default());\n }\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n serde_json::from_str(&content).context(\"failed to parse index.json\")\n}\n\nfn load_index_for_path(project_path: &Path) -> Result<SessionIndex> {\n let path = project_path\n .join(\".ai\")\n .join(\"internal\")\n .join(\"sessions\")\n .join(\"claude\")\n .join(\"index.json\");\n if !path.exists() {\n return Ok(SessionIndex::default());\n }\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n serde_json::from_str(&content).context(\"failed to parse index.json\")\n}\n\npub fn get_sessions_for_web(project_path: &PathBuf) -> Result<Vec<WebSession>> {\n let sessions = read_sessions_for_path(Provider::All, project_path)?;\n if sessions.is_empty() {\n return Ok(vec![]);\n }\n\n let index = load_index_for_path(project_path).unwrap_or_default();\n let mut output = Vec::with_capacity(sessions.len());\n\n for session in sessions {\n let provider = match session.provider {\n Provider::Claude => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n Provider::All => \"unknown\",\n };\n let name = index\n .sessions\n .iter()\n .find(|(_, saved)| saved.id == session.session_id && saved.provider == provider)\n .map(|(name, _)| name.clone())\n .filter(|name| !is_auto_generated_name(name));\n let session_messages =\n read_session_messages_for_path(project_path, &session.session_id, session.provider)\n .unwrap_or_default();\n let started_at = session_messages\n .started_at\n .clone()\n .or_else(|| session.timestamp.clone());\n let last_message_at = session_messages\n .last_message_at\n .clone()\n .or_else(|| started_at.clone());\n\n output.push(WebSession {\n id: session.session_id,\n provider: provider.to_string(),\n timestamp: session.timestamp,\n name,\n messages: session_messages.messages,\n started_at,\n last_message_at,\n });\n }\n\n output.sort_by(|a, b| {\n let a_key = a\n .last_message_at\n .as_deref()\n .or(a.started_at.as_deref())\n .unwrap_or(\"\");\n let b_key = b\n .last_message_at\n .as_deref()\n .or(b.started_at.as_deref())\n .unwrap_or(\"\");\n b_key.cmp(a_key)\n });\n\n Ok(output)\n}\n\nfn read_session_messages_for_path(\n project_path: &Path,\n session_id: &str,\n provider: Provider,\n) -> Result<SessionMessages> {\n match provider {\n Provider::Codex => read_codex_messages(session_id),\n Provider::Cursor => read_cursor_messages(session_id),\n Provider::Claude | Provider::All => read_claude_messages_for_path(project_path, session_id),\n }\n}\n\nfn read_claude_messages_for_path(project_path: &Path, session_id: &str) -> Result<SessionMessages> {\n let path_str = project_path.to_string_lossy().to_string();\n let project_folder = path_to_project_name(&path_str);\n let session_file = get_claude_projects_dir()\n .join(&project_folder)\n .join(format!(\"{}.jsonl\", session_id));\n\n if !session_file.exists() {\n bail!(\"Session file not found: {}\", session_file.display());\n }\n\n let mut messages = Vec::new();\n let mut started_at: Option<String> = None;\n let mut last_message_at: Option<String> = None;\n\n for_each_nonempty_jsonl_line(&session_file, |line| {\n let Ok(entry) = crate::json_parse::parse_json_line::<JsonlEntry>(line) else {\n return;\n };\n let Some(ref msg) = entry.message else {\n return;\n };\n let role = msg.role.as_deref().unwrap_or(\"unknown\");\n if role != \"user\" && role != \"assistant\" {\n return;\n }\n let content_text = msg.content.as_ref().and_then(extract_message_text);\n let Some(content_text) = content_text else {\n return;\n };\n let Some(clean_text) = normalize_session_message(role, &content_text) else {\n return;\n };\n push_message(&mut messages, role, &clean_text);\n if let Some(ts) = entry.timestamp.clone() {\n if started_at.is_none() {\n started_at = Some(ts.clone());\n }\n last_message_at = Some(ts);\n }\n })?;\n\n Ok(SessionMessages {\n messages,\n started_at,\n last_message_at,\n })\n}\n\nfn read_codex_messages(session_id: &str) -> Result<SessionMessages> {\n let session_file = find_codex_session_file(session_id)\n .ok_or_else(|| anyhow::anyhow!(\"Codex session file not found\"))?;\n let mut messages = Vec::new();\n let mut started_at: Option<String> = None;\n let mut last_message_at: Option<String> = None;\n\n for_each_nonempty_jsonl_line(&session_file, |line| {\n let entry: CodexEntry = match crate::json_parse::parse_json_line(line) {\n Ok(v) => v,\n Err(_) => return,\n };\n\n let Some((role, text)) = extract_codex_message(&entry) else {\n return;\n };\n push_message(&mut messages, &role, &text);\n if let Some(ts) = extract_codex_timestamp(&entry) {\n if started_at.is_none() {\n started_at = Some(ts.clone());\n }\n last_message_at = Some(ts);\n }\n })?;\n\n Ok(SessionMessages {\n messages,\n started_at,\n last_message_at,\n })\n}\n\nfn read_cursor_messages(session_id: &str) -> Result<SessionMessages> {\n let session_file = find_cursor_session_file(session_id)\n .ok_or_else(|| anyhow::anyhow!(\"Cursor session file not found\"))?;\n let mut messages = Vec::new();\n let mut started_at = get_cursor_file_timestamp(&session_file);\n let mut last_message_at = started_at.clone();\n\n for_each_nonempty_jsonl_line(&session_file, |line| {\n let entry: CursorEntry = match crate::json_parse::parse_json_line(line) {\n Ok(v) => v,\n Err(_) => return,\n };\n\n let Some((role, text)) = extract_cursor_message(&entry) else {\n return;\n };\n push_message(&mut messages, &role, &text);\n })?;\n\n if started_at.is_none() && !messages.is_empty() {\n started_at = Some(chrono::Utc::now().to_rfc3339());\n last_message_at = started_at.clone();\n }\n\n Ok(SessionMessages {\n messages,\n started_at,\n last_message_at,\n })\n}\n\nfn extract_codex_timestamp(entry: &CodexEntry) -> Option<String> {\n if let Some(ts) = entry.timestamp.as_deref() {\n return Some(ts.to_string());\n }\n entry\n .payload\n .as_ref()\n .and_then(|payload| payload.get(\"timestamp\"))\n .and_then(|value| value.as_str())\n .map(|ts| ts.to_string())\n}\n\nfn extract_message_text(content_value: &serde_json::Value) -> Option<String> {\n match content_value {\n serde_json::Value::String(s) => Some(s.clone()),\n serde_json::Value::Array(arr) => {\n let parts: Vec<String> = arr\n .iter()\n .filter_map(|item| {\n let item_type = item.get(\"type\").and_then(|t| t.as_str());\n if item_type.is_some() && item_type != Some(\"text\") {\n return None;\n }\n item.get(\"text\")\n .and_then(|t| t.as_str())\n .map(|text| text.to_string())\n })\n .filter(|text| !text.trim().is_empty())\n .collect();\n if parts.is_empty() {\n None\n } else {\n Some(parts.join(\"\\n\"))\n }\n }\n serde_json::Value::Object(obj) => {\n if let Some(text) = obj.get(\"text\").and_then(|t| t.as_str()) {\n return Some(text.to_string());\n }\n None\n }\n _ => None,\n }\n}\n\nfn strip_tagged_block(text: &str, open_tag: &str, close_tag: &str) -> String {\n let mut result = text.to_string();\n while let Some(start) = result.find(open_tag) {\n if let Some(end) = result[start..].find(close_tag) {\n let end_pos = start + end + close_tag.len();\n result = format!(\"{}{}\", &result[..start], &result[end_pos..]);\n } else {\n result = result[..start].to_string();\n break;\n }\n }\n result\n}\n\nfn truncate_before_heading(text: &str, heading: &str) -> String {\n let mut offset = 0usize;\n for line in text.lines() {\n if line.trim_start().starts_with(heading) {\n return text[..offset].trim().to_string();\n }\n offset += line.len();\n if offset < text.len() {\n offset += 1;\n }\n }\n text.trim().to_string()\n}\n\nfn collapse_blank_lines(text: &str) -> String {\n let mut out = String::new();\n let mut saw_blank = false;\n\n for line in text.lines() {\n let trimmed = line.trim_end();\n if trimmed.trim().is_empty() {\n if saw_blank || out.is_empty() {\n continue;\n }\n saw_blank = true;\n out.push('\\n');\n continue;\n }\n\n if !out.is_empty() && !out.ends_with('\\n') {\n out.push('\\n');\n }\n out.push_str(trimmed);\n out.push('\\n');\n saw_blank = false;\n }\n\n out.trim().to_string()\n}\n\nfn strip_known_transcript_scaffolding(role: &str, text: &str) -> String {\n let mut cleaned = strip_system_reminders(text);\n\n cleaned = strip_tagged_block(&cleaned, \"<environment_context>\", \"</environment_context>\");\n cleaned = strip_tagged_block(\n &cleaned,\n \"<permissions instructions>\",\n \"</permissions instructions>\",\n );\n cleaned = strip_tagged_block(&cleaned, \"<collaboration_mode>\", \"</collaboration_mode>\");\n\n let trimmed = cleaned.trim_start();\n if trimmed.starts_with(\"# AGENTS.md instructions for \")\n || trimmed.starts_with(\"# agents.md instructions for \")\n {\n return String::new();\n }\n\n cleaned = truncate_before_heading(&cleaned, \"Workflow context:\");\n cleaned = truncate_before_heading(&cleaned, \"Start by checking:\");\n cleaned = truncate_before_heading(&cleaned, \"Designer stack notes:\");\n\n if role == \"assistant\" {\n let trimmed = cleaned.trim_start();\n if trimmed.starts_with(\"Using `\")\n && (trimmed.contains(\"workflow\")\n || trimmed.contains(\"dispatch\")\n || trimmed.contains(\"because this is\"))\n {\n return String::new();\n }\n }\n\n collapse_blank_lines(&cleaned)\n}\n\nfn normalize_session_message(role: &str, text: &str) -> Option<String> {\n if role != \"user\" && role != \"assistant\" {\n return None;\n }\n\n let cleaned = if role == \"assistant\" {\n strip_thinking_blocks(text)\n } else {\n text.to_string()\n };\n let cleaned = strip_known_transcript_scaffolding(role, &cleaned);\n let cleaned = cleaned.trim();\n\n if cleaned.is_empty() || is_session_boilerplate(cleaned) {\n return None;\n }\n\n Some(cleaned.to_string())\n}\n\nfn get_cursor_file_timestamp(path: &Path) -> Option<String> {\n let modified = fs::metadata(path).ok()?.modified().ok()?;\n Some(DateTime::<Utc>::from(modified).to_rfc3339())\n}\n\nfn push_message(messages: &mut Vec<WebSessionMessage>, role: &str, content: &str) {\n if let Some(last) = messages.last_mut() {\n if last.role == role {\n if last.content.trim() == content.trim() {\n return;\n }\n last.content.push_str(\"\\n\\n\");\n last.content.push_str(content);\n return;\n }\n }\n messages.push(WebSessionMessage {\n role: role.to_string(),\n content: content.to_string(),\n });\n}\n\n/// Save the session index.\nfn save_index(index: &SessionIndex) -> Result<()> {\n let path = get_index_path()?;\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n let content = serde_json::to_string_pretty(index)?;\n fs::write(&path, content)?;\n Ok(())\n}\n\n/// Get Claude's projects directory.\nfn get_claude_projects_dir() -> PathBuf {\n let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from(\".\"));\n home.join(\".claude\").join(\"projects\")\n}\n\n/// Get Codex's projects directory.\nfn get_codex_projects_dir() -> PathBuf {\n let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from(\".\"));\n home.join(\".codex\").join(\"projects\")\n}\n\nfn get_codex_sessions_dir() -> PathBuf {\n let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from(\".\"));\n home.join(\".codex\").join(\"sessions\")\n}\n\nfn get_cursor_projects_dir() -> PathBuf {\n let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from(\".\"));\n home.join(\".cursor\").join(\"projects\")\n}\n\n/// Convert a path to project folder name (replaces / with -).\nfn path_to_project_name(path: &str) -> String {\n path.replace('/', \"-\")\n}\n\nfn path_to_cursor_project_key(path: &Path) -> String {\n path.to_string_lossy()\n .trim_start_matches('/')\n .replace('/', \"-\")\n}\n\nfn cursor_project_key_matches_path(project_key: &str, path: &Path) -> bool {\n let prefix = path_to_cursor_project_key(path);\n project_key == prefix\n || project_key\n .strip_prefix(&prefix)\n .map(|rest| rest.starts_with('-'))\n .unwrap_or(false)\n}\n\nfn decode_cursor_project_path(project_key: &str) -> Option<PathBuf> {\n let mut segments = project_key.split('-');\n let root = segments.next()?;\n let second = segments.next()?;\n let mut current = PathBuf::from(\"/\").join(root).join(second);\n if !current.exists() {\n return None;\n }\n\n let remaining: Vec<String> = segments.map(|segment| segment.to_string()).collect();\n let mut index = 0usize;\n\n while index < remaining.len() {\n let entries = fs::read_dir(¤t).ok()?;\n let mut best_match: Option<(usize, PathBuf)> = None;\n\n for entry in entries.flatten() {\n let path = entry.path();\n if !path.is_dir() {\n continue;\n }\n\n let Some(name) = entry.file_name().to_str().map(|value| value.to_string()) else {\n continue;\n };\n let name_segments: Vec<&str> = name.split('-').collect();\n if name_segments.len() > remaining.len().saturating_sub(index) {\n continue;\n }\n\n let matches = name_segments\n .iter()\n .zip(remaining[index..].iter())\n .all(|(expected, actual)| *expected == actual);\n if !matches {\n continue;\n }\n\n let consumed = name_segments.len();\n let should_replace = best_match\n .as_ref()\n .map(|(best_consumed, _)| consumed > *best_consumed)\n .unwrap_or(true);\n if should_replace {\n best_match = Some((consumed, path));\n }\n }\n\n let Some((consumed, next_path)) = best_match else {\n return None;\n };\n current = next_path;\n index += consumed;\n }\n\n Some(current)\n}\n\nfn collect_cursor_project_session_files(project_dir: &Path) -> Vec<PathBuf> {\n let transcripts_dir = project_dir.join(\"agent-transcripts\");\n if !transcripts_dir.exists() {\n return Vec::new();\n }\n\n let mut files = Vec::new();\n let Ok(entries) = fs::read_dir(&transcripts_dir) else {\n return files;\n };\n\n for entry in entries.flatten() {\n let session_dir = entry.path();\n if !session_dir.is_dir() {\n continue;\n }\n\n let Ok(session_entries) = fs::read_dir(&session_dir) else {\n continue;\n };\n for session_entry in session_entries.flatten() {\n let file_path = session_entry.path();\n if file_path\n .extension()\n .map(|ext| ext == \"jsonl\")\n .unwrap_or(false)\n {\n files.push(file_path);\n }\n }\n }\n\n files\n}\n\n/// Read sessions for the current project, filtered by provider.\nfn read_sessions_for_project(provider: Provider) -> Result<Vec<AiSession>> {\n let mut sessions = Vec::new();\n\n if provider == Provider::Claude || provider == Provider::All {\n sessions.extend(read_provider_sessions(Provider::Claude)?);\n }\n\n if provider == Provider::Codex || provider == Provider::All {\n sessions.extend(read_provider_sessions(Provider::Codex)?);\n }\n\n if provider == Provider::Cursor || provider == Provider::All {\n sessions.extend(read_provider_sessions(Provider::Cursor)?);\n }\n\n // Sort by last message timestamp descending (most recent first)\n sessions.sort_by(|a, b| {\n let ts_a = a\n .last_message_at\n .as_deref()\n .or(a.timestamp.as_deref())\n .unwrap_or(\"\");\n let ts_b = b\n .last_message_at\n .as_deref()\n .or(b.timestamp.as_deref())\n .unwrap_or(\"\");\n ts_b.cmp(ts_a)\n });\n\n Ok(sessions)\n}\n\nfn resolve_session_target_path(path: Option<&str>) -> Result<PathBuf> {\n match path.map(str::trim).filter(|value| !value.is_empty()) {\n Some(raw) => {\n let expanded = PathBuf::from(shellexpand::tilde(raw).to_string());\n let resolved = if expanded.is_absolute() {\n expanded\n } else {\n env::current_dir()?.join(expanded)\n };\n Ok(resolved.canonicalize().unwrap_or(resolved))\n }\n None => {\n let resolved = env::current_dir().context(\"failed to get current directory\")?;\n Ok(resolved.canonicalize().unwrap_or(resolved))\n }\n }\n}\n\nfn read_sessions_for_target(provider: Provider, path: Option<&str>) -> Result<Vec<AiSession>> {\n let target = resolve_session_target_path(path)?;\n read_sessions_for_path(provider, &target)\n}\n\n/// Read sessions for a project at a specific path.\nfn read_sessions_for_path(provider: Provider, path: &PathBuf) -> Result<Vec<AiSession>> {\n let mut sessions = Vec::new();\n\n if provider == Provider::Claude || provider == Provider::All {\n sessions.extend(read_provider_sessions_for_path(Provider::Claude, path)?);\n }\n\n if provider == Provider::Codex || provider == Provider::All {\n sessions.extend(read_provider_sessions_for_path(Provider::Codex, path)?);\n }\n\n if provider == Provider::Cursor || provider == Provider::All {\n sessions.extend(read_provider_sessions_for_path(Provider::Cursor, path)?);\n }\n\n // Sort by last message timestamp descending (most recent first)\n sessions.sort_by(|a, b| {\n let ts_a = a\n .last_message_at\n .as_deref()\n .or(a.timestamp.as_deref())\n .unwrap_or(\"\");\n let ts_b = b\n .last_message_at\n .as_deref()\n .or(b.timestamp.as_deref())\n .unwrap_or(\"\");\n ts_b.cmp(ts_a)\n });\n\n Ok(sessions)\n}\n\n/// Read sessions for a specific provider at a given path.\nfn read_provider_sessions_for_path(provider: Provider, path: &PathBuf) -> Result<Vec<AiSession>> {\n if provider == Provider::Codex {\n return read_codex_sessions_for_path(path);\n }\n if provider == Provider::Cursor {\n return read_cursor_sessions_for_path(path);\n }\n\n let path_str = path.to_string_lossy().to_string();\n let project_name = path_to_project_name(&path_str);\n\n let projects_dir = match provider {\n Provider::Claude => get_claude_projects_dir(),\n Provider::Codex => get_codex_projects_dir(),\n Provider::Cursor => get_cursor_projects_dir(),\n Provider::All => return Ok(vec![]),\n };\n\n let project_dir = projects_dir.join(&project_name);\n\n if !project_dir.exists() {\n return Ok(vec![]);\n }\n\n let mut sessions = Vec::new();\n\n let entries = fs::read_dir(&project_dir)\n .with_context(|| format!(\"failed to read {}\", project_dir.display()))?;\n\n for entry in entries {\n let entry = entry?;\n let file_path = entry.path();\n\n if file_path.extension().map(|e| e == \"jsonl\").unwrap_or(false) {\n let filename = file_path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n\n if filename.starts_with(\"agent-\") {\n continue;\n }\n\n if let Some(session) = parse_session_file(&file_path, filename, provider) {\n sessions.push(session);\n }\n }\n }\n\n Ok(sessions)\n}\n\n/// Read sessions for a specific provider.\nfn read_provider_sessions(provider: Provider) -> Result<Vec<AiSession>> {\n if provider == Provider::Codex {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n return read_codex_sessions_for_path(&cwd);\n }\n if provider == Provider::Cursor {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n return read_cursor_sessions_for_path(&cwd);\n }\n\n let cwd = std::env::current_dir()?;\n let cwd_str = cwd.to_string_lossy().to_string();\n let project_name = path_to_project_name(&cwd_str);\n\n let projects_dir = match provider {\n Provider::Claude => get_claude_projects_dir(),\n Provider::Codex => get_codex_projects_dir(),\n Provider::Cursor => get_cursor_projects_dir(),\n Provider::All => return Ok(vec![]), // Should use read_sessions_for_project instead\n };\n\n let project_dir = projects_dir.join(&project_name);\n\n if !project_dir.exists() {\n debug!(\n \"{:?} project dir not found at {}\",\n provider,\n project_dir.display()\n );\n return Ok(vec![]);\n }\n\n let mut sessions = Vec::new();\n\n // Read all .jsonl files in the project directory\n let entries = fs::read_dir(&project_dir)\n .with_context(|| format!(\"failed to read {}\", project_dir.display()))?;\n\n for entry in entries {\n let entry = entry?;\n let path = entry.path();\n\n // Only process .jsonl files that look like session IDs (UUID format)\n if path.extension().map(|e| e == \"jsonl\").unwrap_or(false) {\n let filename = path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n\n // Skip agent- prefixed files (subagent sessions)\n if filename.starts_with(\"agent-\") {\n continue;\n }\n\n // Parse the session file\n if let Some(session) = parse_session_file(&path, filename, provider) {\n sessions.push(session);\n }\n }\n }\n\n Ok(sessions)\n}\n\n/// Parse a session .jsonl file to extract metadata.\nfn parse_session_file(path: &PathBuf, session_id: &str, provider: Provider) -> Option<AiSession> {\n if provider == Provider::Codex {\n let (session, _cwd) = parse_codex_session_file(path, session_id)?;\n return Some(session);\n }\n if provider == Provider::Cursor {\n return parse_cursor_session_file(path, session_id);\n }\n\n let mut timestamp = None;\n let mut last_message_at = None;\n let mut last_message = None;\n let mut first_message = None;\n let mut error_summary = None;\n\n for_each_nonempty_jsonl_line(path, |line| {\n if let Ok(entry) = crate::json_parse::parse_json_line::<JsonlEntry>(line) {\n // Get timestamp from first entry\n if timestamp.is_none() {\n timestamp = entry.timestamp.clone();\n }\n\n if let Some(ref msg) = entry.message {\n let role = msg.role.as_deref();\n if role == Some(\"user\") || role == Some(\"assistant\") {\n if let Some(ref content) = msg.content {\n if let Some(text) = extract_message_text(content) {\n if let Some(clean_text) =\n normalize_session_message(role.unwrap_or(\"unknown\"), &text)\n {\n last_message = Some(clean_text);\n if let Some(ts) = entry.timestamp.clone() {\n last_message_at = Some(ts);\n }\n }\n }\n }\n }\n }\n\n // Get first user message as summary\n if first_message.is_none() {\n if let Some(ref msg) = entry.message {\n if msg.role.as_deref() == Some(\"user\") {\n if let Some(ref content) = msg.content {\n first_message = extract_message_text(content)\n .and_then(|text| normalize_session_message(\"user\", &text));\n }\n }\n }\n }\n\n // Capture first error summary (useful when no user message exists)\n if error_summary.is_none() {\n error_summary = extract_error_summary(&entry);\n }\n }\n })\n .ok()?;\n\n Some(AiSession {\n session_id: session_id.to_string(),\n provider,\n timestamp,\n last_message_at,\n last_message,\n first_message,\n error_summary,\n })\n}\n\nfn parse_codex_session_file(\n path: &PathBuf,\n fallback_id: &str,\n) -> Option<(AiSession, Option<PathBuf>)> {\n let mut timestamp = None;\n let mut last_message_at = None;\n let mut last_message = None;\n let mut first_message = None;\n let mut error_summary = None;\n let mut session_id = None;\n let mut cwd = None;\n\n for_each_nonempty_jsonl_line(path, |line| {\n let entry: CodexEntry = match crate::json_parse::parse_json_line(line) {\n Ok(v) => v,\n Err(_) => return,\n };\n\n if timestamp.is_none() {\n timestamp = entry.timestamp.clone();\n }\n\n if let Some((_role, text)) = extract_codex_message(&entry) {\n if !text.trim().is_empty() {\n last_message = Some(text);\n if let Some(ts) = extract_codex_timestamp(&entry) {\n last_message_at = Some(ts);\n }\n }\n }\n\n if entry.entry_type.as_deref() == Some(\"session_meta\") {\n if let Some(payload) = entry.payload.as_ref() {\n if session_id.is_none() {\n session_id = payload\n .get(\"id\")\n .and_then(|v| v.as_str())\n .map(|s| s.to_string());\n }\n if cwd.is_none() {\n cwd = payload\n .get(\"cwd\")\n .and_then(|v| v.as_str())\n .map(|s| PathBuf::from(s));\n }\n if timestamp.is_none() {\n timestamp = payload\n .get(\"timestamp\")\n .and_then(|v| v.as_str())\n .map(|s| s.to_string());\n }\n }\n }\n\n if first_message.is_none() {\n if let Some(text) = extract_codex_user_message(&entry) {\n first_message = Some(text);\n }\n }\n\n if error_summary.is_none() {\n if let Some(summary) = extract_codex_error_summary(&entry) {\n error_summary = Some(summary);\n }\n }\n })\n .ok()?;\n\n let session = AiSession {\n session_id: session_id.unwrap_or_else(|| fallback_id.to_string()),\n provider: Provider::Codex,\n timestamp,\n last_message_at,\n last_message,\n first_message,\n error_summary,\n };\n\n Some((session, cwd))\n}\n\nfn parse_cursor_session_file(path: &PathBuf, fallback_id: &str) -> Option<AiSession> {\n let timestamp = get_cursor_file_timestamp(path);\n let mut last_message = None;\n let mut first_message = None;\n\n for_each_nonempty_jsonl_line(path, |line| {\n let entry: CursorEntry = match crate::json_parse::parse_json_line(line) {\n Ok(v) => v,\n Err(_) => return,\n };\n\n let Some((role, text)) = extract_cursor_message(&entry) else {\n return;\n };\n last_message = Some(text.clone());\n if first_message.is_none() && role == \"user\" {\n first_message = Some(text);\n }\n })\n .ok()?;\n\n Some(AiSession {\n session_id: fallback_id.to_string(),\n provider: Provider::Cursor,\n timestamp: timestamp.clone(),\n last_message_at: timestamp,\n last_message,\n first_message,\n error_summary: None,\n })\n}\n\nfn ai_session_from_codex_recover_row(row: CodexRecoverRow) -> AiSession {\n let updated_at = DateTime::<Utc>::from_timestamp(row.updated_at, 0)\n .map(|value| value.to_rfc3339())\n .unwrap_or_else(|| row.updated_at.to_string());\n let title = row.title.filter(|value| !value.trim().is_empty());\n let first_user_message = row\n .first_user_message\n .filter(|value| !value.trim().is_empty());\n let last_message = title.clone().or_else(|| first_user_message.clone());\n\n AiSession {\n session_id: row.id,\n provider: Provider::Codex,\n timestamp: Some(updated_at.clone()),\n last_message_at: Some(updated_at),\n last_message,\n first_message: first_user_message,\n error_summary: None,\n }\n}\n\nfn read_codex_sessions_for_path_from_files(path: &PathBuf) -> Result<Vec<AiSession>> {\n let sessions_dir = get_codex_sessions_dir();\n if !sessions_dir.exists() {\n return Ok(vec![]);\n }\n\n let mut sessions = Vec::new();\n let target = path.to_string_lossy();\n\n for file_path in collect_codex_session_files(&sessions_dir) {\n let filename = file_path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n let Some((session, cwd)) = parse_codex_session_file(&file_path, filename) else {\n continue;\n };\n\n if let Some(cwd_path) = cwd {\n if cwd_path.to_string_lossy() == target {\n sessions.push(session);\n }\n }\n }\n\n Ok(sessions)\n}\n\nfn read_codex_sessions_for_path(path: &PathBuf) -> Result<Vec<AiSession>> {\n let db_result = (|| -> Result<Vec<AiSession>> {\n let db_path = codex_state_db_path()?;\n let schema = load_codex_thread_schema(&db_path)?;\n let target = path.to_string_lossy().to_string();\n let cache_key = format!(\"target={target}\");\n let sql = format!(\n r#\"\n{}\nwhere archived = 0\n and cwd = ?1\norder by updated_at desc\n\"#,\n codex_recover_select_sql(&schema)\n );\n\n let rows = with_codex_query_cache(&db_path, \"session-list-exact\", &cache_key, |conn| {\n let mut stmt = conn\n .prepare(&sql)\n .context(\"failed to prepare codex session list query\")?;\n let iter = stmt.query_map(params![target], map_codex_recover_row)?;\n Ok(iter.collect::<rusqlite::Result<Vec<_>>>()?)\n })?;\n\n Ok(rows.into_iter().map(ai_session_from_codex_recover_row).collect())\n })();\n\n match db_result {\n Ok(sessions) => Ok(sessions),\n Err(err) => {\n debug!(\n error = %err,\n path = %path.display(),\n \"failed to read codex sessions from state db; falling back to session files\"\n );\n read_codex_sessions_for_path_from_files(path)\n }\n }\n}\n\nfn read_cursor_sessions_for_path(path: &PathBuf) -> Result<Vec<AiSession>> {\n let projects_dir = get_cursor_projects_dir();\n if !projects_dir.exists() {\n return Ok(vec![]);\n }\n\n let mut sessions = Vec::new();\n let entries = fs::read_dir(&projects_dir)\n .with_context(|| format!(\"failed to read {}\", projects_dir.display()))?;\n\n for entry in entries.flatten() {\n let project_dir = entry.path();\n if !project_dir.is_dir() {\n continue;\n }\n\n let Some(project_key) = project_dir.file_name().and_then(|name| name.to_str()) else {\n continue;\n };\n if !cursor_project_key_matches_path(project_key, path) {\n continue;\n }\n\n for file_path in collect_cursor_project_session_files(&project_dir) {\n let filename = file_path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n if let Some(session) = parse_cursor_session_file(&file_path, filename) {\n sessions.push(session);\n }\n }\n }\n\n sessions.sort_by(|a, b| {\n let ts_a = a\n .last_message_at\n .as_deref()\n .or(a.timestamp.as_deref())\n .unwrap_or(\"\");\n let ts_b = b\n .last_message_at\n .as_deref()\n .or(b.timestamp.as_deref())\n .unwrap_or(\"\");\n ts_b.cmp(ts_a)\n });\n\n Ok(sessions)\n}\n\nfn collect_codex_session_files(root: &PathBuf) -> Vec<PathBuf> {\n let mut out = Vec::new();\n let mut stack = vec![root.clone()];\n\n while let Some(dir) = stack.pop() {\n let entries = match fs::read_dir(&dir) {\n Ok(v) => v,\n Err(_) => continue,\n };\n\n for entry in entries.flatten() {\n let path = entry.path();\n if path.is_dir() {\n stack.push(path);\n } else if path.extension().map(|e| e == \"jsonl\").unwrap_or(false) {\n out.push(path);\n }\n }\n }\n\n out\n}\n\nfn codex_session_id_from_path(path: &Path) -> Option<String> {\n let filename = path.file_stem()?.to_str()?;\n Some(filename.split('_').next().unwrap_or(filename).to_string())\n}\n\nfn cursor_session_id_from_path(path: &Path) -> Option<String> {\n path.file_stem()\n .and_then(|name| name.to_str())\n .map(str::to_string)\n}\n\nfn resolve_explicit_native_session(query: &str, provider: Provider) -> Option<(String, Provider)> {\n if matches!(provider, Provider::Codex | Provider::All) {\n if let Some(path) = find_codex_session_file(query) {\n if let Some(session_id) = codex_session_id_from_path(&path) {\n return Some((session_id, Provider::Codex));\n }\n }\n }\n\n if matches!(provider, Provider::Cursor | Provider::All) {\n if let Some(path) = find_cursor_session_file(query) {\n if let Some(session_id) = cursor_session_id_from_path(&path) {\n return Some((session_id, Provider::Cursor));\n }\n }\n }\n\n None\n}\n\nfn resolve_session_selection(\n query: &str,\n sessions: &[AiSession],\n index: &SessionIndex,\n provider: Provider,\n) -> Result<(String, Provider)> {\n if let Some((_, saved)) = index\n .sessions\n .iter()\n .find(|(name, _)| name.as_str() == query)\n {\n if let Some(session) = sessions.iter().find(|s| s.session_id == saved.id) {\n return Ok((saved.id.clone(), session.provider));\n }\n if let Some((session_id, session_provider)) =\n resolve_explicit_native_session(&saved.id, provider)\n {\n return Ok((session_id, session_provider));\n }\n return Ok((saved.id.clone(), Provider::Claude));\n }\n\n if let Some(session) = sessions\n .iter()\n .find(|s| s.session_id == *query || s.session_id.starts_with(query))\n {\n return Ok((session.session_id.clone(), session.provider));\n }\n\n if let Some((session_id, session_provider)) = resolve_explicit_native_session(query, provider) {\n return Ok((session_id, session_provider));\n }\n\n bail!(\"Session not found: {}\", query);\n}\n\n/// Get the most recent session ID for this project.\nfn get_most_recent_session_id() -> Result<Option<String>> {\n let sessions = read_sessions_for_project(Provider::All)?;\n Ok(sessions.first().map(|s| s.session_id.clone()))\n}\n\nfn format_session_ref(session: &AiSession, include_provider: bool) -> String {\n if !include_provider {\n return session.session_id.clone();\n }\n\n let provider = match session.provider {\n Provider::Claude => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n Provider::All => \"ai\",\n };\n format!(\"{provider}:{}\", session.session_id)\n}\n\nfn print_latest_session_id(provider: Provider, path: Option<String>) -> Result<()> {\n let target = resolve_session_target_path(path.as_deref())?;\n if provider == Provider::Codex {\n let rows = read_recent_codex_threads(&target, false, 1, None)?;\n let Some(row) = rows.first() else {\n bail!(\"No Codex sessions found for {}\", target.display());\n };\n println!(\"{}\", row.id);\n return Ok(());\n }\n\n let sessions = read_sessions_for_path(provider, &target)?;\n let Some(session) = sessions.first() else {\n let provider_name = match provider {\n Provider::Claude => \"Claude\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n };\n bail!(\"No {provider_name} sessions found for {}\", target.display());\n };\n\n println!(\"{}\", format_session_ref(session, false));\n Ok(())\n}\n\n/// Entry for fzf selection\nstruct FzfSessionEntry {\n display: String,\n session_id: String,\n provider: Provider,\n}\n\n#[derive(Debug, Serialize)]\nstruct ProviderSessionListRow {\n index: usize,\n id: String,\n updated_at: Option<String>,\n updated_relative: String,\n preview: String,\n}\n\n/// List all sessions and let user fuzzy-select one to resume.\nfn list_sessions(provider: Provider) -> Result<()> {\n // Auto-import any new sessions silently\n auto_import_sessions()?;\n\n let index = load_index()?;\n let sessions = read_sessions_for_project(provider)?;\n\n if index.sessions.is_empty() && sessions.is_empty() {\n let provider_name = match provider {\n Provider::Claude => \"Claude\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n };\n println!(\"No {} sessions found for this project.\", provider_name);\n if provider == Provider::Cursor {\n println!(\"\\nTip: open this repo in Cursor and use its agent to create transcripts.\");\n } else {\n println!(\"\\nTip: Run `claude` or `codex` in this directory to start a session,\");\n println!(\" then use `f ai save <name>` to bookmark it.\");\n }\n return Ok(());\n }\n\n // Build entries for fzf - combine saved metadata with session data\n let mut entries: Vec<FzfSessionEntry> = Vec::new();\n\n // Process all sessions, enriching with saved names where available\n for session in &sessions {\n // Skip sessions without timestamps or content\n if session.timestamp.is_none()\n && session.last_message_at.is_none()\n && session.last_message.is_none()\n && session.first_message.is_none()\n && session.error_summary.is_none()\n {\n continue;\n }\n\n let relative_time = session\n .last_message_at\n .as_deref()\n .or(session.timestamp.as_deref())\n .map(format_relative_time)\n .unwrap_or_else(|| \"\".to_string());\n\n // Check if this session has a human-assigned name (not auto-generated)\n let saved_name = index\n .sessions\n .iter()\n .find(|(_, s)| s.id == session.session_id)\n .map(|(name, _)| name.as_str())\n .filter(|name| !is_auto_generated_name(name));\n\n let summary = session\n .last_message\n .as_deref()\n .or(session.first_message.as_deref())\n .or(session.error_summary.as_deref())\n .unwrap_or(\"\");\n let summary_clean = clean_summary(summary);\n let id_short = &session.session_id[..8.min(session.session_id.len())];\n\n // Add provider indicator when showing all\n let provider_tag = if provider == Provider::All {\n match session.provider {\n Provider::Claude => \"claude | \",\n Provider::Codex => \"codex | \",\n Provider::Cursor => \"cursor | \",\n Provider::All => \"\",\n }\n } else {\n \"\"\n };\n\n let display = if let Some(name) = saved_name {\n // For named sessions, show: [provider] name | time | summary\n format!(\n \"{}{} | {} | {}\",\n provider_tag,\n name,\n relative_time,\n truncate_str(&summary_clean, 40)\n )\n } else {\n // For other sessions, show: [provider] time | summary\n format!(\n \"{}{} | {} | {}\",\n provider_tag,\n relative_time,\n truncate_str(&summary_clean, 60),\n id_short\n )\n };\n\n entries.push(FzfSessionEntry {\n display,\n session_id: session.session_id.clone(),\n provider: session.provider,\n });\n }\n\n if entries.is_empty() {\n println!(\"No sessions available.\");\n return Ok(());\n }\n\n let has_tty = io::stdin().is_terminal() && io::stdout().is_terminal();\n\n // Check for interactive selection support.\n if !has_tty || which::which(\"fzf\").is_err() {\n if !has_tty {\n println!(\"Interactive selection unavailable without a TTY.\");\n } else {\n println!(\"fzf not found – install it for fuzzy selection.\");\n }\n println!(\"\\nSessions:\");\n for entry in &entries {\n println!(\"{}\", entry.display);\n }\n if !has_tty {\n println!(\"\\nTip: use `f ai codex sessions --path <repo>` for machine-readable selection.\");\n }\n return Ok(());\n }\n\n // Run fzf\n if let Some(selected) = run_session_fzf(&entries)? {\n if selected.provider == Provider::Cursor {\n let history = read_session_history(&selected.session_id, selected.provider)?;\n copy_to_clipboard(&history)?;\n let line_count = history.lines().count();\n println!(\n \"Copied Cursor session {} ({} lines) to clipboard\",\n &selected.session_id[..8.min(selected.session_id.len())],\n line_count\n );\n return Ok(());\n }\n println!(\n \"Resuming session {}...\",\n &selected.session_id[..8.min(selected.session_id.len())]\n );\n launch_session(&selected.session_id, selected.provider)?;\n }\n\n Ok(())\n}\n\n/// Run fzf and return the selected session entry.\nfn run_session_fzf(entries: &[FzfSessionEntry]) -> Result<Option<&FzfSessionEntry>> {\n let mut child = Command::new(\"fzf\")\n .arg(\"--prompt\")\n .arg(\"ai> \")\n .arg(\"--ansi\")\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n {\n let stdin = child.stdin.as_mut().context(\"failed to open fzf stdin\")?;\n for entry in entries {\n writeln!(stdin, \"{}\", entry.display)?;\n }\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n\n let selection = String::from_utf8(output.stdout).context(\"fzf output was not valid UTF-8\")?;\n let selection = selection.trim();\n\n if selection.is_empty() {\n return Ok(None);\n }\n\n Ok(entries.iter().find(|e| e.display == selection))\n}\n\n/// Launch a session with the appropriate CLI. Returns true if successful, false if failed.\nfn launch_session(session_id: &str, provider: Provider) -> Result<bool> {\n launch_session_for_target(session_id, provider, None, None, None, None)\n}\n\nfn new_codex_session_trace(workflow_kind: &str) -> CodexResolveWorkflowTrace {\n CodexResolveWorkflowTrace {\n trace_id: new_workflow_trace_id(),\n span_id: new_workflow_span_id(),\n parent_span_id: None,\n workflow_kind: workflow_kind.to_string(),\n service_name: FLOW_CODEX_TRACE_SERVICE_NAME.to_string(),\n }\n}\n\nfn direct_codex_trace_query(action: &str, route: &str, session_id: Option<&str>) -> String {\n match route {\n \"continue-last-direct\" => \"continue last codex session\".to_string(),\n \"new-direct\" => \"start new codex session\".to_string(),\n \"resume-direct\" if session_id.is_some() => {\n format!(\"resume codex session {}\", truncate_recover_id(session_id.unwrap_or_default()))\n }\n \"resume-direct\" => \"resume codex session\".to_string(),\n \"connect-direct\" if session_id.is_some() => {\n format!(\"connect codex session {}\", truncate_recover_id(session_id.unwrap_or_default()))\n }\n \"connect-direct\" => \"connect codex session\".to_string(),\n _ => format!(\"{action} codex session\"),\n }\n}\n\nfn record_direct_codex_launch_event(\n action: &str,\n route: &str,\n target_path: &Path,\n launch_path: &Path,\n session_id: Option<&str>,\n trace: &CodexResolveWorkflowTrace,\n) {\n let query = direct_codex_trace_query(action, route, session_id);\n let event = codex_skill_eval::CodexSkillEvalEvent {\n version: 1,\n recorded_at_unix: SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0),\n mode: \"direct-launch\".to_string(),\n action: action.to_string(),\n route: route.to_string(),\n target_path: target_path.display().to_string(),\n launch_path: launch_path.display().to_string(),\n query: query.clone(),\n session_id: session_id.map(str::to_string),\n runtime_token: None,\n runtime_skills: Vec::new(),\n prompt_context_budget_chars: 0,\n prompt_chars: query.chars().count(),\n injected_context_chars: 0,\n reference_count: 0,\n trace_id: Some(trace.trace_id.clone()),\n span_id: Some(trace.span_id.clone()),\n parent_span_id: trace.parent_span_id.clone(),\n workflow_kind: Some(trace.workflow_kind.clone()),\n service_name: Some(trace.service_name.clone()),\n };\n let _ = codex_skill_eval::log_event(&event);\n}\n\nfn launch_session_for_target(\n session_id: &str,\n provider: Provider,\n prompt: Option<&str>,\n target_path: Option<&Path>,\n runtime_state_path: Option<&str>,\n trace: Option<&CodexResolveWorkflowTrace>,\n) -> Result<bool> {\n let status = match provider {\n Provider::Claude | Provider::All => {\n // Claude uses: claude --resume <session_id> --dangerously-skip-permissions\n let mut command = Command::new(\"claude\");\n command\n .arg(\"--resume\")\n .arg(session_id)\n .arg(\"--dangerously-skip-permissions\");\n if let Some(path) = target_path {\n command.current_dir(path);\n }\n command\n .status()\n .with_context(|| \"failed to launch claude\")?\n }\n Provider::Codex => {\n // Codex uses: codex resume --dangerously-bypass-approvals-and-sandbox <session_id> [prompt]\n let workdir = target_path\n .map(Path::to_path_buf)\n .unwrap_or_else(|| env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\")));\n let direct_log = trace.is_none();\n let effective_trace = trace\n .cloned()\n .unwrap_or_else(|| new_codex_session_trace(\"resume_session\"));\n let mut command = Command::new(configured_codex_bin_for_workdir(&workdir));\n command.arg(\"resume\");\n if let Some(path) = target_path {\n command.current_dir(path);\n }\n apply_codex_personal_env_to_command(&mut command);\n apply_codex_trust_overrides_for(&mut command, target_path);\n apply_codex_runtime_state_to_command(&mut command, runtime_state_path);\n apply_codex_trace_env_to_command(&mut command, Some(&effective_trace));\n command\n .arg(\"--dangerously-bypass-approvals-and-sandbox\")\n .arg(session_id);\n if let Some(prompt) = prompt.map(str::trim).filter(|value| !value.is_empty()) {\n command.arg(prompt);\n }\n let status = command.status().with_context(|| \"failed to launch codex\")?;\n if status.success() && direct_log {\n record_direct_codex_launch_event(\n \"resume\",\n \"resume-direct\",\n &workdir,\n &workdir,\n Some(session_id),\n &effective_trace,\n );\n }\n status\n }\n Provider::Cursor => {\n bail!(\n \"Cursor transcripts are readable only; use `f cursor list`, `f cursor copy`, or `f cursor context`\"\n );\n }\n };\n\n Ok(status.success())\n}\n\nfn launch_claude_continue() -> Result<bool> {\n let status = Command::new(\"claude\")\n .arg(\"--continue\")\n .arg(\"--dangerously-skip-permissions\")\n .status()\n .with_context(|| \"failed to launch claude --continue\")?;\n Ok(status.success())\n}\n\nfn launch_claude_resume_picker() -> Result<bool> {\n let status = Command::new(\"claude\")\n .arg(\"--resume\")\n .arg(\"--dangerously-skip-permissions\")\n .status()\n .with_context(|| \"failed to launch claude --resume\")?;\n Ok(status.success())\n}\n\nfn detect_git_root(path: &Path) -> Option<PathBuf> {\n let output = Command::new(\"git\")\n .arg(\"rev-parse\")\n .arg(\"--show-toplevel\")\n .current_dir(path)\n .output()\n .ok()?;\n if !output.status.success() {\n return None;\n }\n\n let stdout = String::from_utf8(output.stdout).ok()?;\n let trimmed = stdout.trim();\n if trimmed.is_empty() {\n return None;\n }\n\n Some(PathBuf::from(trimmed))\n}\n\nfn codex_trusted_paths() -> Vec<PathBuf> {\n env::current_dir()\n .ok()\n .map(|path| codex_trusted_paths_for(&path))\n .unwrap_or_default()\n}\n\nfn codex_trusted_paths_for(seed: &Path) -> Vec<PathBuf> {\n let mut paths = BTreeSet::new();\n let raw_cwd = seed.to_path_buf();\n paths.insert(raw_cwd.clone());\n if let Some(raw_git_root) = detect_git_root(&raw_cwd) {\n paths.insert(raw_git_root);\n }\n\n if let Ok(canonical_cwd) = raw_cwd.canonicalize() {\n paths.insert(canonical_cwd.clone());\n if let Some(canonical_git_root) = detect_git_root(&canonical_cwd) {\n paths.insert(canonical_git_root);\n }\n }\n paths.into_iter().collect()\n}\n\nfn codex_projects_override(paths: &[PathBuf]) -> Option<String> {\n if paths.is_empty() {\n return None;\n }\n\n let projects = paths\n .iter()\n .map(|path| {\n let escaped = path\n .display()\n .to_string()\n .replace('\\\\', \"\\\\\\\\\")\n .replace('\"', \"\\\\\\\"\");\n format!(\"\\\"{escaped}\\\"={{ trust_level=\\\"trusted\\\" }}\")\n })\n .collect::<Vec<_>>()\n .join(\", \");\n\n Some(format!(\"projects={{ {projects} }}\"))\n}\n\nfn apply_codex_trust_overrides(command: &mut Command) {\n if let Some(override_value) = codex_projects_override(&codex_trusted_paths()) {\n command.arg(\"--config\").arg(override_value);\n }\n}\n\nfn apply_codex_trust_overrides_for(command: &mut Command, target_path: Option<&Path>) {\n let paths = target_path\n .map(codex_trusted_paths_for)\n .unwrap_or_else(codex_trusted_paths);\n if let Some(override_value) = codex_projects_override(&paths) {\n command.arg(\"--config\").arg(override_value);\n }\n}\n\nfn apply_codex_runtime_state_to_command(command: &mut Command, runtime_state_path: Option<&str>) {\n if let Some(path) = runtime_state_path\n .map(str::trim)\n .filter(|value| !value.is_empty())\n {\n command.env(\"FLOW_CODEX_RUNTIME_STATE\", path);\n }\n}\n\nfn apply_codex_trace_env_to_command(\n command: &mut Command,\n trace: Option<&CodexResolveWorkflowTrace>,\n) {\n let Some(trace) = trace else {\n return;\n };\n command.env(\"FLOW_TRACE_ID\", &trace.trace_id);\n command.env(\"FLOW_SPAN_ID\", &trace.span_id);\n if let Some(parent_span_id) = trace.parent_span_id.as_deref() {\n command.env(\"FLOW_PARENT_SPAN_ID\", parent_span_id);\n }\n command.env(\"FLOW_WORKFLOW_KIND\", &trace.workflow_kind);\n command.env(\"FLOW_TRACE_SERVICE_NAME\", &trace.service_name);\n}\n\nfn codex_personal_env_keys() -> Vec<String> {\n [\n \"FLOW_CODEX_MAPLE_LOCAL_ENDPOINT\",\n \"FLOW_CODEX_MAPLE_LOCAL_INGEST_KEY\",\n \"FLOW_CODEX_MAPLE_HOSTED_ENDPOINT\",\n \"FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY\",\n \"FLOW_CODEX_MAPLE_HOSTED_PUBLIC_INGEST_KEY\",\n \"FLOW_CODEX_MAPLE_TRACES_ENDPOINTS\",\n \"FLOW_CODEX_MAPLE_INGEST_KEYS\",\n \"FLOW_CODEX_MAPLE_SERVICE_NAME\",\n \"FLOW_CODEX_MAPLE_SERVICE_VERSION\",\n \"FLOW_CODEX_MAPLE_SCOPE_NAME\",\n \"FLOW_CODEX_MAPLE_ENV\",\n \"FLOW_CODEX_MAPLE_QUEUE_CAPACITY\",\n \"FLOW_CODEX_MAPLE_MAX_BATCH_SIZE\",\n \"FLOW_CODEX_MAPLE_FLUSH_INTERVAL_MS\",\n \"FLOW_CODEX_MAPLE_CONNECT_TIMEOUT_MS\",\n \"FLOW_CODEX_MAPLE_REQUEST_TIMEOUT_MS\",\n \"MAPLE_API_TOKEN\",\n \"MAPLE_MCP_URL\",\n ]\n .into_iter()\n .map(str::to_string)\n .collect()\n}\n\nfn codex_has_explicit_maple_env() -> bool {\n codex_personal_env_keys().into_iter().any(|key| {\n env::var(&key)\n .ok()\n .map(|value| !value.trim().is_empty())\n .unwrap_or(false)\n })\n}\n\nfn apply_codex_personal_env_to_command(command: &mut Command) {\n if codex_has_explicit_maple_env() {\n return;\n }\n let missing_keys: Vec<String> = codex_personal_env_keys()\n .into_iter()\n .filter(|key| env::var(key).ok().map(|v| v.trim().is_empty()).unwrap_or(true))\n .collect();\n if missing_keys.is_empty() {\n return;\n }\n let Ok(values) = flow_env::fetch_local_personal_env_vars(&missing_keys) else {\n return;\n };\n for (key, value) in values {\n if !value.trim().is_empty() {\n command.env(key, value);\n }\n }\n}\n\nfn codex_runtime_transport_enabled(target_path: &Path) -> bool {\n if let Ok(value) = env::var(\"FLOW_CODEX_RUNTIME_TRANSPORT\") {\n let normalized = value.trim().to_ascii_lowercase();\n if matches!(normalized.as_str(), \"1\" | \"true\" | \"yes\" | \"on\") {\n return true;\n }\n }\n\n let bin = configured_codex_bin_for_workdir(target_path);\n Path::new(&bin)\n .file_name()\n .and_then(|value| value.to_str())\n .unwrap_or(bin.as_str())\n .contains(\"codex-flow-wrapper\")\n}\n\nfn launch_codex_resume_picker() -> Result<bool> {\n let cwd = env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\"));\n let mut command = Command::new(configured_codex_bin_for_workdir(&cwd));\n command\n .arg(\"resume\")\n .arg(\"--dangerously-bypass-approvals-and-sandbox\");\n apply_codex_personal_env_to_command(&mut command);\n apply_codex_trust_overrides(&mut command);\n let status = command\n .status()\n .with_context(|| \"failed to launch codex resume\")?;\n Ok(status.success())\n}\n\nfn launch_codex_continue_last_for_target(target_path: Option<&Path>) -> Result<bool> {\n let workdir = target_path\n .map(Path::to_path_buf)\n .unwrap_or_else(|| env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\")));\n let trace = new_codex_session_trace(\"continue_last_session\");\n let mut command = Command::new(configured_codex_bin_for_workdir(&workdir));\n command.arg(\"resume\");\n if let Some(path) = target_path {\n command.current_dir(path);\n }\n apply_codex_personal_env_to_command(&mut command);\n apply_codex_trust_overrides_for(&mut command, target_path);\n apply_codex_trace_env_to_command(&mut command, Some(&trace));\n command\n .arg(\"--last\")\n .arg(\"--dangerously-bypass-approvals-and-sandbox\");\n let status = command\n .status()\n .with_context(|| \"failed to launch codex resume --last\")?;\n if status.success() {\n record_direct_codex_launch_event(\n \"resume\",\n \"continue-last-direct\",\n &workdir,\n &workdir,\n None,\n &trace,\n );\n }\n Ok(status.success())\n}\n\nfn provider_name(provider: Provider) -> &'static str {\n match provider {\n Provider::Claude => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n Provider::All => \"ai\",\n }\n}\n\nfn ensure_provider_tty(provider: Provider, action: &str) -> Result<()> {\n if io::stdin().is_terminal() && io::stdout().is_terminal() {\n return Ok(());\n }\n\n bail!(\n \"{} {} requires an interactive terminal (TTY); run this in a terminal tab (e.g. Zed/Ghostty)\",\n provider_name(provider),\n action\n );\n}\n\nfn print_provider_session_listing(\n provider: Provider,\n target: &Path,\n sessions: &[AiSession],\n json: bool,\n) -> Result<()> {\n if sessions.is_empty() {\n let provider_name = match provider {\n Provider::Claude => \"Claude\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n };\n bail!(\"No {provider_name} sessions found for {}\", target.display());\n }\n\n let rows: Vec<ProviderSessionListRow> = sessions\n .iter()\n .enumerate()\n .map(|(index, session)| {\n let updated_at = session\n .last_message_at\n .clone()\n .or_else(|| session.timestamp.clone());\n let updated_relative = updated_at\n .as_deref()\n .map(format_relative_time)\n .unwrap_or_else(|| \"-\".to_string());\n let preview = session\n .last_message\n .as_deref()\n .or(session.first_message.as_deref())\n .or(session.error_summary.as_deref())\n .map(clean_summary)\n .filter(|value| !value.is_empty())\n .unwrap_or_else(|| \"(no message)\".to_string());\n ProviderSessionListRow {\n index: index + 1,\n id: session.session_id.clone(),\n updated_at,\n updated_relative,\n preview,\n }\n })\n .collect();\n\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&rows).context(\"failed to encode session list JSON\")?\n );\n return Ok(());\n }\n\n println!(\n \"{} sessions for {}\",\n provider_name(provider),\n target.display()\n );\n println!();\n\n let index_width = rows\n .last()\n .map(|row| row.index.to_string().len())\n .unwrap_or(1)\n .max(1);\n let updated_width = rows\n .iter()\n .map(|row| row.updated_relative.chars().count())\n .max()\n .unwrap_or(7)\n .max(\"updated\".len());\n let id_width = rows\n .iter()\n .map(|row| row.id.chars().count())\n .max()\n .unwrap_or(10)\n .min(36)\n .max(2);\n\n println!(\n \"{:>index_width$} {:<updated_width$} {:<id_width$} preview\",\n \"#\",\n \"updated\",\n \"id\",\n index_width = index_width,\n updated_width = updated_width,\n id_width = id_width,\n );\n for row in &rows {\n println!(\n \"{:>index_width$} {:<updated_width$} {:<id_width$} {}\",\n row.index,\n row.updated_relative,\n row.id,\n truncate_str(&row.preview, 90),\n index_width = index_width,\n updated_width = updated_width,\n id_width = id_width,\n );\n }\n\n println!();\n println!(\n \"Continue with `f ai {} continue <index|id-prefix> --path {}`\",\n provider_name(provider),\n shell_words::quote(&target.display().to_string())\n );\n Ok(())\n}\n\nfn provider_sessions(provider: Provider, path: Option<String>, json: bool) -> Result<()> {\n if provider == Provider::All {\n bail!(\"sessions requires a specific provider (claude or codex)\");\n }\n if provider == Provider::Codex {\n let target = resolve_session_target_path(path.as_deref())?;\n let sessions = read_sessions_for_target(provider, path.as_deref())?;\n return print_provider_session_listing(provider, &target, &sessions, json);\n }\n\n ensure_provider_tty(provider, \"sessions\")?;\n\n let launched = match provider {\n Provider::Claude => launch_claude_resume_picker()?,\n Provider::Codex => launch_codex_resume_picker()?,\n Provider::Cursor => false,\n Provider::All => false,\n };\n\n if launched {\n Ok(())\n } else {\n bail!(\"failed to open {} session picker\", provider_name(provider))\n }\n}\n\nfn continue_session(\n session: Option<String>,\n path: Option<String>,\n provider: Provider,\n) -> Result<()> {\n if session.is_some() {\n return resume_session(session, path, provider);\n }\n if provider == Provider::All {\n bail!(\"continue requires a specific provider (claude or codex)\");\n }\n ensure_provider_tty(provider, \"continue\")?;\n\n if path\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n .is_some()\n {\n let target = resolve_session_target_path(path.as_deref())?;\n let sessions = read_sessions_for_target(provider, path.as_deref())?;\n let sess = sessions.first().ok_or_else(|| {\n anyhow::anyhow!(\n \"No {} sessions found for {}\",\n provider_name(provider),\n target.display()\n )\n })?;\n println!(\n \"Resuming session {} from {}...\",\n &sess.session_id[..8.min(sess.session_id.len())],\n target.display()\n );\n if launch_session_for_target(\n &sess.session_id,\n sess.provider,\n None,\n Some(&target),\n None,\n None,\n )? {\n return Ok(());\n }\n bail!(\n \"failed to continue {} session {} for {}\",\n provider_name(sess.provider),\n sess.session_id,\n target.display()\n );\n }\n\n let launched = match provider {\n Provider::Claude => launch_claude_continue()?,\n Provider::Codex => launch_codex_continue_last_for_target(None)?,\n Provider::Cursor => false,\n Provider::All => false,\n };\n\n if launched {\n Ok(())\n } else {\n bail!(\"failed to continue {} session\", provider_name(provider))\n }\n}\n\n/// Quick start: continue last session or create new one with dangerous flags.\npub fn quick_start_session(provider: Provider) -> Result<()> {\n if provider == Provider::Codex {\n let launched = launch_codex_continue_last_for_target(None)?;\n if !launched {\n new_session(provider)?;\n }\n return Ok(());\n }\n\n // Auto-import any new sessions silently\n let _ = auto_import_sessions();\n\n let sessions = read_sessions_for_project(provider)?;\n\n // Find first session that has actual content (messages)\n let valid_session = sessions\n .iter()\n .find(|s| s.last_message.is_some() || s.first_message.is_some());\n\n if let Some(sess) = valid_session {\n let launched = launch_session(&sess.session_id, sess.provider)?;\n if !launched {\n // Session not found, start a new one\n new_session(provider)?;\n }\n } else {\n new_session(provider)?;\n }\n\n Ok(())\n}\n\n/// Start a new session with dangerous flags (ignores existing sessions).\nfn new_session(provider: Provider) -> Result<()> {\n new_session_for_target(provider, None, None, None, None)\n}\n\nfn new_session_for_target(\n provider: Provider,\n prompt: Option<&str>,\n target_path: Option<&Path>,\n runtime_state_path: Option<&str>,\n trace: Option<&CodexResolveWorkflowTrace>,\n) -> Result<()> {\n let status = match provider {\n Provider::Claude | Provider::All => {\n let mut command = Command::new(\"claude\");\n command.arg(\"--dangerously-skip-permissions\");\n if let Some(path) = target_path {\n command.current_dir(path);\n }\n command\n .status()\n .with_context(|| \"failed to launch claude\")?\n }\n Provider::Codex => {\n let workdir = target_path\n .map(Path::to_path_buf)\n .unwrap_or_else(|| env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\")));\n let direct_log = trace.is_none();\n let effective_trace = trace\n .cloned()\n .unwrap_or_else(|| new_codex_session_trace(\"new_session\"));\n let mut command = Command::new(configured_codex_bin_for_workdir(&workdir));\n if let Some(path) = target_path {\n command.current_dir(path);\n }\n apply_codex_personal_env_to_command(&mut command);\n apply_codex_trust_overrides_for(&mut command, target_path);\n apply_codex_runtime_state_to_command(&mut command, runtime_state_path);\n apply_codex_trace_env_to_command(&mut command, Some(&effective_trace));\n command\n .arg(\"--yolo\")\n .arg(\"--sandbox\")\n .arg(\"danger-full-access\");\n if let Some(prompt) = prompt.map(str::trim).filter(|value| !value.is_empty()) {\n command.arg(prompt);\n }\n let status = command.status().with_context(|| \"failed to launch codex\")?;\n if status.success() && direct_log {\n record_direct_codex_launch_event(\n \"new\",\n \"new-direct\",\n &workdir,\n &workdir,\n None,\n &effective_trace,\n );\n }\n status\n }\n Provider::Cursor => {\n bail!(\n \"Cursor transcripts are readable only; use `f cursor list`, `f cursor copy`, or `f cursor context`\"\n );\n }\n };\n\n let name = match provider {\n Provider::Claude | Provider::All => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n };\n\n if !status.success() {\n bail!(\"{} exited with status {}\", name, status);\n }\n\n Ok(())\n}\n\nfn find_codex_session(\n path: Option<String>,\n query: Vec<String>,\n exact_cwd: bool,\n provider: Provider,\n) -> Result<()> {\n let selected = find_best_codex_session_match(path, query, exact_cwd, provider, \"find\", true)?;\n resume_session(Some(selected.id.clone()), None, Provider::Codex)\n}\n\nfn find_and_copy_codex_session(\n path: Option<String>,\n query: Vec<String>,\n exact_cwd: bool,\n provider: Provider,\n) -> Result<()> {\n let selected =\n find_best_codex_session_match(path, query, exact_cwd, provider, \"findAndCopy\", false)?;\n copy_session_history_to_clipboard(&selected.id, Provider::Codex)?;\n println!(\n \"Session {} found and copied to clipboard\",\n truncate_recover_id(&selected.id)\n );\n Ok(())\n}\n\nfn find_best_codex_session_match(\n path: Option<String>,\n query: Vec<String>,\n exact_cwd: bool,\n provider: Provider,\n action_name: &str,\n verbose: bool,\n) -> Result<CodexRecoverRow> {\n if provider != Provider::Codex {\n bail!(\n \"{} is only supported for Codex sessions; use `f ai codex {} ...`\",\n action_name,\n action_name\n );\n }\n\n let query_text = normalize_recover_query(&query).ok_or_else(|| {\n anyhow::anyhow!(\n \"{} requires a query, for example: `f ai codex {} \\\"make plan to get designer\\\"`\",\n action_name,\n action_name\n )\n })?;\n let target_path = path\n .map(|value| canonicalize_recover_path(Some(value)))\n .transpose()?;\n let rows = search_codex_threads_for_find(target_path.as_deref(), exact_cwd, &query_text, 5)?;\n let selected = rows.first().ok_or_else(|| match target_path.as_ref() {\n Some(target_path) => anyhow::anyhow!(\n \"No matching Codex sessions found for {:?} under {}\",\n query_text,\n target_path.display()\n ),\n None => anyhow::anyhow!(\"No matching Codex sessions found for {:?}\", query_text),\n })?;\n\n if verbose {\n println!(\n \"Matched Codex session {} | {} | {}\",\n truncate_recover_id(&selected.id),\n format_unix_ts(selected.updated_at),\n selected.cwd\n );\n if let Some(first) = selected.first_user_message.as_deref() {\n println!(\"Prompt: {}\", truncate_recover_text(first));\n } else if let Some(title) = selected.title.as_deref() {\n println!(\"Title: {}\", truncate_recover_text(title));\n }\n }\n\n Ok(selected.clone())\n}\n\nfn recover_codex_sessions(\n path: Option<String>,\n query: Vec<String>,\n exact_cwd: bool,\n limit: usize,\n json_output: bool,\n summary_only: bool,\n provider: Provider,\n) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"recover is only supported for Codex sessions; use `f ai codex recover ...`\");\n }\n\n let query_text = normalize_recover_query(&query);\n let requested_target_path = canonicalize_recover_path(path)?;\n let explicit_session_hint = query_text.as_deref().and_then(extract_codex_session_hint);\n let (target_path, rows) = if let Some(session_hint) = explicit_session_hint.as_deref() {\n let rows = read_codex_threads_by_session_hint(session_hint, limit.max(1))?;\n if let Some(first) = rows.first() {\n (canonicalize_recover_path(Some(first.cwd.clone()))?, rows)\n } else {\n (\n requested_target_path.clone(),\n read_recent_codex_threads(\n &requested_target_path,\n exact_cwd,\n limit.max(1),\n query_text.as_deref(),\n )?,\n )\n }\n } else {\n (\n requested_target_path.clone(),\n read_recent_codex_threads(\n &requested_target_path,\n exact_cwd,\n limit.max(1),\n query_text.as_deref(),\n )?,\n )\n };\n let output = build_recover_output(&target_path, exact_cwd, query_text, rows);\n\n if summary_only {\n println!(\"{}\", output.summary);\n return Ok(());\n }\n\n if json_output {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&output).context(\"failed to encode recovery JSON\")?\n );\n return Ok(());\n }\n\n print_recover_output(&output);\n Ok(())\n}\n\nfn canonicalize_recover_path(path: Option<String>) -> Result<PathBuf> {\n let raw = path.unwrap_or_else(|| \".\".to_string());\n let expanded = shellexpand::tilde(&raw).to_string();\n let candidate = PathBuf::from(expanded);\n let absolute = if candidate.is_absolute() {\n candidate\n } else {\n env::current_dir()\n .context(\"failed to determine current directory\")?\n .join(candidate)\n };\n Ok(absolute.canonicalize().unwrap_or(absolute))\n}\n\nfn normalize_recover_query(parts: &[String]) -> Option<String> {\n let text = parts.join(\" \").trim().to_string();\n if text.is_empty() { None } else { Some(text) }\n}\n\nfn recover_query_tokens(query: &str) -> Vec<String> {\n query\n .split_whitespace()\n .map(|part| {\n part.trim_matches(|ch: char| !ch.is_ascii_alphanumeric() && ch != '-' && ch != '_')\n .to_ascii_lowercase()\n })\n .filter(|part| !part.is_empty())\n .collect()\n}\n\nfn looks_like_git_sha(token: &str) -> bool {\n (7..=40).contains(&token.len()) && token.chars().all(|ch| ch.is_ascii_hexdigit())\n}\n\nfn looks_like_codex_session_token(token: &str) -> bool {\n if token.len() < 8 || token.len() > 36 || !token.contains('-') {\n return false;\n }\n\n let mut hex_chars = 0usize;\n for ch in token.chars() {\n if ch == '-' {\n continue;\n }\n if !ch.is_ascii_hexdigit() {\n return false;\n }\n hex_chars += 1;\n }\n\n if hex_chars < 8 {\n return false;\n }\n\n if token.len() == 36 {\n let segments: Vec<_> = token.split('-').collect();\n if segments.len() != 5 {\n return false;\n }\n let expected = [8usize, 4, 4, 4, 12];\n return segments\n .iter()\n .zip(expected)\n .all(|(segment, expected_len)| segment.len() == expected_len);\n }\n\n true\n}\n\nfn extract_codex_session_hints(query: &str) -> Vec<String> {\n let mut hints = Vec::new();\n for token in recover_query_tokens(query) {\n if looks_like_git_sha(&token) || !looks_like_codex_session_token(&token) {\n continue;\n }\n if !hints.iter().any(|existing| existing == &token) {\n hints.push(token);\n if hints.len() >= 2 {\n break;\n }\n }\n }\n hints\n}\n\nfn extract_codex_session_hint(query: &str) -> Option<String> {\n extract_codex_session_hints(query).into_iter().next()\n}\n\nfn extract_codex_session_reference_request(\n query_text: &str,\n normalized_query: &str,\n) -> Option<CodexSessionReferenceRequest> {\n if starts_with_codex_session_lookup_only_phrase(normalized_query) {\n return None;\n }\n let session_hints = extract_codex_session_hints(normalized_query);\n if session_hints.is_empty() {\n return None;\n }\n let user_request = extract_codex_session_reference_user_request(query_text, &session_hints)?;\n let count = extract_codex_session_reference_count(query_text, &session_hints);\n Some(CodexSessionReferenceRequest {\n session_hints,\n count,\n user_request,\n })\n}\n\nfn starts_with_codex_session_lookup_only_phrase(query: &str) -> bool {\n [\n \"open \",\n \"resume \",\n \"continue \",\n \"connect \",\n \"find \",\n \"copy \",\n \"show \",\n ]\n .iter()\n .any(|prefix| query.starts_with(prefix))\n}\n\nfn extract_codex_session_reference_user_request(\n query_text: &str,\n session_hints: &[String],\n) -> Option<String> {\n let query_lower = query_text.to_ascii_lowercase();\n let last_hint = session_hints.last()?;\n let hint_lower = last_hint.to_ascii_lowercase();\n let start = query_lower.rfind(&hint_lower)?;\n let after_hint = query_text.get(start + last_hint.len()..)?.trim_start();\n let remainder = strip_codex_session_window_prefix(after_hint)\n .trim_start_matches(|ch: char| ch.is_whitespace() || matches!(ch, ',' | ';' | ':' | '-'))\n .trim();\n let remainder = strip_codex_session_followup_prefix(remainder);\n if remainder.is_empty() {\n None\n } else {\n Some(remainder.to_string())\n }\n}\n\nfn strip_codex_session_followup_prefix(value: &str) -> &str {\n let mut remainder = value.trim_start();\n loop {\n let next = if remainder.len() >= 14 && remainder[..14].eq_ignore_ascii_case(\"codex session \") {\n Some(&remainder[14..])\n } else if remainder.len() >= 11 && remainder[..11].eq_ignore_ascii_case(\"codex sesh \") {\n Some(&remainder[11..])\n } else if remainder.len() >= 12 && remainder[..12].eq_ignore_ascii_case(\"codex chat \") {\n Some(&remainder[12..])\n } else if remainder.len() >= 6 && remainder[..6].eq_ignore_ascii_case(\"codex \") {\n Some(&remainder[6..])\n } else if remainder.len() >= 8 && remainder[..8].eq_ignore_ascii_case(\"session \") {\n Some(&remainder[8..])\n } else if remainder.len() >= 5 && remainder[..5].eq_ignore_ascii_case(\"sesh \") {\n Some(&remainder[5..])\n } else if remainder.len() >= 5 && remainder[..5].eq_ignore_ascii_case(\"chat \") {\n Some(&remainder[5..])\n } else if remainder.len() >= 7 && remainder[..7].eq_ignore_ascii_case(\"thread \") {\n Some(&remainder[7..])\n } else if remainder.len() >= 4 && remainder[..4].eq_ignore_ascii_case(\"and \") {\n Some(&remainder[4..])\n } else if remainder.len() >= 5 && remainder[..5].eq_ignore_ascii_case(\"then \") {\n Some(&remainder[5..])\n } else {\n None\n };\n\n match next {\n Some(rest) => {\n remainder =\n rest.trim_start_matches(|ch: char| ch.is_whitespace() || matches!(ch, ',' | ';' | ':' | '-'));\n }\n None => return remainder.trim(),\n }\n }\n}\n\nfn extract_codex_session_reference_count(query_text: &str, session_hints: &[String]) -> usize {\n let query_lower = query_text.to_ascii_lowercase();\n let Some(last_hint) = session_hints.last() else {\n return 12;\n };\n let hint_lower = last_hint.to_ascii_lowercase();\n let after_hint = query_lower\n .rfind(&hint_lower)\n .and_then(|start| query_text.get(start + last_hint.len()..))\n .unwrap_or(query_text);\n let captures = codex_session_window_regex().captures(after_hint);\n captures\n .and_then(|caps| caps.get(1))\n .and_then(|value| value.as_str().parse::<usize>().ok())\n .map(|value| value.clamp(1, 50))\n .unwrap_or(12)\n}\n\nfn strip_codex_session_window_prefix(value: &str) -> &str {\n if let Some(matched) = codex_session_window_regex().find(value) {\n &value[matched.end()..]\n } else {\n value\n }\n}\n\nfn codex_session_window_regex() -> &'static Regex {\n static WINDOW_RE: OnceLock<Regex> = OnceLock::new();\n WINDOW_RE.get_or_init(|| {\n Regex::new(r\"(?i)^\\s*(?:last|past)\\s+(\\d{1,3})\\s+(?:messages?|exchanges?|turns?)\\b\")\n .expect(\"valid session window regex\")\n })\n}\n\nfn resolve_builtin_codex_session_reference(\n session_hint: &str,\n count: usize,\n) -> Result<CodexResolvedReference> {\n let row = read_codex_threads_by_session_hint(session_hint, 1)?\n .into_iter()\n .next()\n .ok_or_else(|| anyhow::anyhow!(\"No Codex session found for {}\", session_hint))?;\n let excerpt = read_last_context(\n &row.id,\n Provider::Codex,\n count,\n &PathBuf::from(&row.cwd),\n )?;\n Ok(CodexResolvedReference {\n name: \"codex-session\".to_string(),\n source: \"session\".to_string(),\n matched: row.id.clone(),\n command: None,\n output: render_codex_session_reference(&row, count, &excerpt),\n })\n}\n\nfn render_codex_session_reference(row: &CodexRecoverRow, count: usize, excerpt: &str) -> String {\n let mut lines = vec![\n format!(\"- Codex session: {}\", row.id),\n format!(\"- Repo cwd: {}\", row.cwd),\n format!(\"- Updated: {}\", format_unix_ts(row.updated_at)),\n format!(\"- Included excerpt: last {} exchanges\", count),\n ];\n if let Some(title) = row.title.as_deref() {\n lines.push(format!(\"- Title: {}\", truncate_recover_text(title)));\n }\n if let Some(first) = row.first_user_message.as_deref() {\n lines.push(format!(\n \"- First user message: {}\",\n truncate_recover_text(first)\n ));\n }\n lines.push(\"Recent transcript excerpt:\".to_string());\n lines.extend(excerpt.lines().map(str::to_string));\n compact_codex_context_block(&lines.join(\"\\n\"), 32, 3200)\n}\n\nfn codex_sqlite_home() -> Result<PathBuf> {\n if let Some(path) = env::var_os(\"CODEX_SQLITE_HOME\") {\n return Ok(PathBuf::from(path));\n }\n if let Some(path) = env::var_os(\"CODEX_HOME\") {\n return Ok(PathBuf::from(path));\n }\n let home = dirs::home_dir().context(\"failed to resolve home directory\")?;\n Ok(home.join(\".codex\"))\n}\n\nfn parse_codex_versioned_db_filename(file_name: &str, prefix: &str) -> Option<u32> {\n file_name\n .strip_prefix(prefix)?\n .strip_suffix(\".sqlite\")?\n .parse::<u32>()\n .ok()\n}\n\nfn select_codex_state_db_path(sqlite_home: &Path) -> Result<PathBuf> {\n let mut candidates: Vec<(u32, PathBuf)> = fs::read_dir(sqlite_home)\n .with_context(|| format!(\"failed to read {}\", sqlite_home.display()))?\n .filter_map(|entry| entry.ok())\n .filter_map(|entry| {\n let path = entry.path();\n let file_name = path.file_name()?.to_str()?;\n let version = parse_codex_versioned_db_filename(file_name, \"state_\")?;\n Some((version, path))\n })\n .collect();\n candidates.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| a.1.cmp(&b.1)));\n if let Some((_, path)) = candidates.into_iter().next() {\n return Ok(path);\n }\n\n let legacy_path = sqlite_home.join(\"state.sqlite\");\n if legacy_path.exists() {\n return Ok(legacy_path);\n }\n\n bail!(\n \"no Codex state_<version>.sqlite database found under {}\",\n sqlite_home.display()\n )\n}\n\nfn codex_state_db_path() -> Result<PathBuf> {\n select_codex_state_db_path(&codex_sqlite_home()?)\n}\n\nfn codex_query_cache_disabled() -> bool {\n matches!(\n env::var(CODEX_QUERY_CACHE_ENV_DISABLE)\n .ok()\n .as_deref()\n .map(str::trim)\n .map(str::to_ascii_lowercase)\n .as_deref(),\n Some(\"1\" | \"true\" | \"yes\" | \"on\")\n )\n}\n\nfn codex_query_cache_root() -> Result<PathBuf> {\n Ok(config::ensure_global_state_dir()?\n .join(\"codex\")\n .join(\"query-cache\"))\n}\n\nfn codex_session_completion_markers_dir() -> Result<PathBuf> {\n Ok(config::ensure_global_state_dir()?\n .join(\"codex\")\n .join(\"session-completions\"))\n}\n\nfn codex_session_completion_scan_limit() -> usize {\n env::var(\"FLOW_CODEX_SESSION_COMPLETION_SCAN_LIMIT\")\n .ok()\n .and_then(|value| value.parse::<usize>().ok())\n .map(|value| value.clamp(1, 200))\n .unwrap_or(CODEX_SESSION_COMPLETION_DEFAULT_SCAN_LIMIT)\n}\n\nfn codex_session_completion_idle_secs() -> u64 {\n env::var(\"FLOW_CODEX_SESSION_COMPLETION_IDLE_SECS\")\n .ok()\n .and_then(|value| value.parse::<u64>().ok())\n .map(|value| value.clamp(15, 3600))\n .unwrap_or(CODEX_SESSION_COMPLETION_DEFAULT_IDLE_SECS)\n}\n\nfn prune_codex_session_completion_markers(now_unix: u64) -> Result<()> {\n let root = codex_session_completion_markers_dir()?;\n if !root.exists() {\n return Ok(());\n }\n let keep_cutoff = now_unix.saturating_sub(60 * 24 * 60 * 60);\n let Ok(entries) = fs::read_dir(&root) else {\n return Ok(());\n };\n for entry in entries.flatten() {\n let path = entry.path();\n let Ok(metadata) = entry.metadata() else {\n continue;\n };\n let modified = metadata\n .modified()\n .ok()\n .and_then(|value| value.duration_since(UNIX_EPOCH).ok())\n .map(|value| value.as_secs())\n .unwrap_or(now_unix);\n if modified < keep_cutoff {\n let _ = fs::remove_file(path);\n }\n }\n Ok(())\n}\n\nfn claim_codex_session_completion_marker(session_id: &str, assistant_at_unix: u64) -> Result<bool> {\n let root = codex_session_completion_markers_dir()?;\n fs::create_dir_all(&root).with_context(|| format!(\"failed to create {}\", root.display()))?;\n let key = blake3::hash(format!(\"{session_id}:{assistant_at_unix}\").as_bytes()).to_hex();\n let path = root.join(format!(\"{key}.done\"));\n let mut file = match OpenOptions::new().create_new(true).write(true).open(&path) {\n Ok(file) => file,\n Err(err) if err.kind() == io::ErrorKind::AlreadyExists => return Ok(false),\n Err(err) => {\n return Err(err).with_context(|| format!(\"failed to create {}\", path.display()));\n }\n };\n writeln!(file, \"{session_id}:{assistant_at_unix}\")\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(true)\n}\n\nfn codex_query_cache_entry_count() -> usize {\n let Ok(root) = codex_query_cache_root() else {\n return 0;\n };\n fs::read_dir(root)\n .ok()\n .into_iter()\n .flat_map(|entries| entries.flatten())\n .filter(|entry| {\n entry.path().extension().and_then(|value| value.to_str()) == Some(\"msgpack\")\n })\n .count()\n}\n\nfn codex_query_cache_store() -> &'static Mutex<HashMap<PathBuf, CodexQueryCacheEntry>> {\n static CACHE: OnceLock<Mutex<HashMap<PathBuf, CodexQueryCacheEntry>>> = OnceLock::new();\n CACHE.get_or_init(|| Mutex::new(HashMap::new()))\n}\n\nfn codex_thread_schema_cache() -> &'static Mutex<HashMap<PathBuf, CodexThreadSchemaCacheEntry>> {\n static CACHE: OnceLock<Mutex<HashMap<PathBuf, CodexThreadSchemaCacheEntry>>> = OnceLock::new();\n CACHE.get_or_init(|| Mutex::new(HashMap::new()))\n}\n\nfn unix_now_secs() -> u64 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0)\n}\n\nfn codex_state_db_stamp(path: &Path) -> Result<CodexStateDbStamp> {\n let metadata = fs::metadata(path)\n .with_context(|| format!(\"failed to stat Codex state db {}\", path.display()))?;\n let modified = metadata\n .modified()\n .unwrap_or(SystemTime::UNIX_EPOCH)\n .duration_since(UNIX_EPOCH)\n .unwrap_or_default()\n .as_secs();\n Ok(CodexStateDbStamp {\n path: path.display().to_string(),\n len: metadata.len(),\n modified_unix_secs: modified,\n })\n}\n\nfn read_codex_thread_schema(conn: &Connection) -> Result<CodexThreadSchema> {\n let mut stmt = conn\n .prepare(\"pragma table_info(threads)\")\n .context(\"failed to prepare threads schema query\")?;\n let columns = stmt\n .query_map([], |row| row.get::<_, String>(1))\n .context(\"failed to query threads schema\")?;\n let mut names = BTreeSet::new();\n for column in columns {\n names.insert(column?);\n }\n Ok(CodexThreadSchema {\n has_model: names.contains(\"model\"),\n has_reasoning_effort: names.contains(\"reasoning_effort\"),\n })\n}\n\nfn load_codex_thread_schema(db_path: &Path) -> Result<CodexThreadSchema> {\n let stamp = codex_state_db_stamp(db_path)?;\n if let Ok(cache) = codex_thread_schema_cache().lock() {\n if let Some(entry) = cache.get(db_path) {\n if entry.stamp == stamp {\n return Ok(entry.schema.clone());\n }\n }\n }\n\n let conn = Connection::open(db_path)\n .with_context(|| format!(\"failed to open {}\", db_path.display()))?;\n let schema = read_codex_thread_schema(&conn)?;\n if let Ok(mut cache) = codex_thread_schema_cache().lock() {\n cache.insert(\n db_path.to_path_buf(),\n CodexThreadSchemaCacheEntry {\n stamp,\n schema: schema.clone(),\n },\n );\n }\n Ok(schema)\n}\n\nfn codex_recover_select_sql(schema: &CodexThreadSchema) -> String {\n let model_expr = if schema.has_model {\n \"model\"\n } else {\n \"NULL as model\"\n };\n let reasoning_expr = if schema.has_reasoning_effort {\n \"reasoning_effort\"\n } else {\n \"NULL as reasoning_effort\"\n };\n format!(\n r#\"\nselect\n id,\n updated_at,\n cwd,\n title,\n first_user_message,\n git_branch,\n {model_expr},\n {reasoning_expr}\nfrom threads\n\"#\n )\n}\n\nfn map_codex_recover_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<CodexRecoverRow> {\n Ok(CodexRecoverRow {\n id: row.get(\"id\")?,\n updated_at: row.get(\"updated_at\")?,\n cwd: row.get(\"cwd\")?,\n title: row.get(\"title\")?,\n first_user_message: row.get(\"first_user_message\")?,\n git_branch: row.get(\"git_branch\")?,\n model: row.get(\"model\")?,\n reasoning_effort: row.get(\"reasoning_effort\")?,\n })\n}\n\nfn codex_query_cache_path(\n stamp: &CodexStateDbStamp,\n scope: &str,\n key_material: &str,\n) -> Result<PathBuf> {\n let hash_input = format!(\"{}\\n{}\\n{}\", stamp.path, scope, key_material);\n let hash = blake3::hash(hash_input.as_bytes()).to_hex();\n Ok(codex_query_cache_root()?.join(format!(\"{hash}.msgpack\")))\n}\n\nfn read_codex_query_cache(path: &Path, stamp: &CodexStateDbStamp) -> Option<Vec<CodexRecoverRow>> {\n if codex_query_cache_disabled() {\n return None;\n }\n\n if let Ok(cache) = codex_query_cache_store().lock()\n && let Some(entry) = cache.get(path)\n && entry.version == CODEX_QUERY_CACHE_VERSION\n && entry.stamp == *stamp\n {\n return Some(entry.rows.clone());\n }\n\n let bytes = fs::read(path).ok()?;\n let entry = rmp_serde::from_slice::<CodexQueryCacheEntry>(&bytes).ok()?;\n if entry.version != CODEX_QUERY_CACHE_VERSION || entry.stamp != *stamp {\n return None;\n }\n\n if let Ok(mut cache) = codex_query_cache_store().lock() {\n cache.insert(path.to_path_buf(), entry.clone());\n }\n Some(entry.rows)\n}\n\nfn write_codex_query_cache(path: &Path, entry: &CodexQueryCacheEntry) -> Result<()> {\n if codex_query_cache_disabled() {\n return Ok(());\n }\n\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent).with_context(|| {\n format!(\n \"failed to create Codex query cache dir {}\",\n parent.display()\n )\n })?;\n }\n\n let bytes = rmp_serde::to_vec(entry).context(\"failed to encode Codex query cache\")?;\n let tmp_path = path.with_extension(format!(\n \"msgpack.tmp.{}.{}\",\n std::process::id(),\n unix_now_secs()\n ));\n fs::write(&tmp_path, bytes)\n .with_context(|| format!(\"failed to write Codex query cache {}\", tmp_path.display()))?;\n if let Err(err) = fs::rename(&tmp_path, path) {\n if path.exists() {\n let _ = fs::remove_file(path);\n fs::rename(&tmp_path, path).with_context(|| {\n format!(\"failed to finalize Codex query cache {}\", path.display())\n })?;\n } else {\n return Err(err).with_context(|| {\n format!(\"failed to finalize Codex query cache {}\", path.display())\n });\n }\n }\n\n if let Ok(mut cache) = codex_query_cache_store().lock() {\n cache.insert(path.to_path_buf(), entry.clone());\n }\n\n Ok(())\n}\n\nfn with_codex_query_cache<F>(\n db_path: &Path,\n scope: &str,\n key_material: &str,\n query: F,\n) -> Result<Vec<CodexRecoverRow>>\nwhere\n F: FnOnce(&Connection) -> Result<Vec<CodexRecoverRow>>,\n{\n let stamp = codex_state_db_stamp(db_path)?;\n let cache_path = codex_query_cache_path(&stamp, scope, key_material)?;\n if let Some(rows) = read_codex_query_cache(&cache_path, &stamp) {\n return Ok(rows);\n }\n\n let conn = Connection::open(db_path)\n .with_context(|| format!(\"failed to open {}\", db_path.display()))?;\n let rows = query(&conn)?;\n let entry = CodexQueryCacheEntry {\n version: CODEX_QUERY_CACHE_VERSION,\n stamp,\n rows: rows.clone(),\n };\n if let Err(err) = write_codex_query_cache(&cache_path, &entry) {\n debug!(path = %cache_path.display(), error = %err, \"failed to write codex query cache\");\n }\n Ok(rows)\n}\n\nfn escape_like(value: &str) -> String {\n value\n .replace('\\\\', \"\\\\\\\\\")\n .replace('%', \"\\\\%\")\n .replace('_', \"\\\\_\")\n}\n\nfn read_recent_codex_threads(\n target_path: &Path,\n exact_cwd: bool,\n limit: usize,\n query: Option<&str>,\n) -> Result<Vec<CodexRecoverRow>> {\n match codexd::query_recent(target_path, exact_cwd, limit, query) {\n Ok(rows) => Ok(rows),\n Err(err) => {\n debug!(error = %err, \"codexd recent query failed; falling back to local query\");\n read_recent_codex_threads_local(target_path, exact_cwd, limit, query)\n }\n }\n}\n\npub(crate) fn read_recent_codex_threads_local(\n target_path: &Path,\n exact_cwd: bool,\n limit: usize,\n query: Option<&str>,\n) -> Result<Vec<CodexRecoverRow>> {\n let db_path = codex_state_db_path()?;\n let schema = load_codex_thread_schema(&db_path)?;\n\n let target = target_path.to_string_lossy().to_string();\n let like_target = format!(\"{}/%\", escape_like(&target));\n let fetch_limit = (limit.max(3) * 12).min(120);\n let cache_key = format!(\"target={target}\\nexact={exact_cwd}\\nfetch_limit={fetch_limit}\");\n\n let sql_exact = format!(\n r#\"\n{}\nwhere archived = 0\n and cwd = ?1\norder by updated_at desc\nlimit ?2\n\"#,\n codex_recover_select_sql(&schema)\n );\n\n let sql_tree = format!(\n r#\"\n{}\nwhere archived = 0\n and (cwd = ?1 or cwd like ?2 escape '\\')\norder by updated_at desc\nlimit ?3\n\"#,\n codex_recover_select_sql(&schema)\n );\n\n let mut rows = with_codex_query_cache(&db_path, \"recent\", &cache_key, |conn| {\n if exact_cwd {\n let mut stmt = conn\n .prepare(&sql_exact)\n .context(\"failed to prepare exact recover query\")?;\n let iter =\n stmt.query_map(params![target, fetch_limit as i64], map_codex_recover_row)?;\n Ok(iter.collect::<rusqlite::Result<Vec<_>>>()?)\n } else {\n let mut stmt = conn\n .prepare(&sql_tree)\n .context(\"failed to prepare subtree recover query\")?;\n let iter = stmt.query_map(\n params![target, like_target, fetch_limit as i64],\n map_codex_recover_row,\n )?;\n Ok(iter.collect::<rusqlite::Result<Vec<_>>>()?)\n }\n })?;\n\n rank_recover_rows(&mut rows, query);\n rows.truncate(limit.max(1));\n Ok(rows)\n}\n\nfn read_recent_codex_threads_global_local(limit: usize) -> Result<Vec<CodexRecoverRow>> {\n let db_path = codex_state_db_path()?;\n let schema = load_codex_thread_schema(&db_path)?;\n let fetch_limit = limit.clamp(1, 200);\n let cache_key = format!(\"limit={fetch_limit}\");\n let sql = format!(\n r#\"\n{}\nwhere archived = 0\norder by updated_at desc\nlimit ?1\n\"#,\n codex_recover_select_sql(&schema)\n );\n\n with_codex_query_cache(&db_path, \"recent-global\", &cache_key, |conn| {\n let mut stmt = conn\n .prepare(&sql)\n .context(\"failed to prepare global recover query\")?;\n let iter = stmt.query_map(params![fetch_limit as i64], map_codex_recover_row)?;\n Ok(iter.collect::<rusqlite::Result<Vec<_>>>()?)\n })\n}\n\nfn read_codex_threads_by_session_hint(\n session_hint: &str,\n limit: usize,\n) -> Result<Vec<CodexRecoverRow>> {\n match codexd::query_session_hint(session_hint, limit) {\n Ok(rows) => Ok(rows),\n Err(err) => {\n debug!(\n error = %err,\n \"codexd session hint query failed; falling back to local query\"\n );\n read_codex_threads_by_session_hint_local(session_hint, limit)\n }\n }\n}\n\npub(crate) fn read_codex_threads_by_session_hint_local(\n session_hint: &str,\n limit: usize,\n) -> Result<Vec<CodexRecoverRow>> {\n let db_path = codex_state_db_path()?;\n let schema = load_codex_thread_schema(&db_path)?;\n let normalized_hint = session_hint.trim().to_ascii_lowercase();\n if normalized_hint.is_empty() {\n return Ok(vec![]);\n }\n let cache_key = format!(\"hint={normalized_hint}\\nlimit={}\", limit.max(1));\n\n let sql = format!(\n r#\"\n{}\nwhere archived = 0\n and (lower(id) = ?1 or lower(id) like ?2 escape '\\')\norder by\n case when lower(id) = ?1 then 0 else 1 end,\n updated_at desc\nlimit ?3\n\"#,\n codex_recover_select_sql(&schema)\n );\n\n let prefix_like = format!(\"{}%\", escape_like(&normalized_hint));\n with_codex_query_cache(&db_path, \"session-hint\", &cache_key, |conn| {\n let mut stmt = conn\n .prepare(&sql)\n .context(\"failed to prepare explicit session recover query\")?;\n let iter = stmt.query_map(\n params![normalized_hint, prefix_like, limit.max(1) as i64],\n map_codex_recover_row,\n )?;\n Ok(iter.collect::<rusqlite::Result<Vec<_>>>()?)\n })\n}\n\nfn search_codex_threads_for_find(\n target_path: Option<&Path>,\n exact_cwd: bool,\n query: &str,\n limit: usize,\n) -> Result<Vec<CodexRecoverRow>> {\n match codexd::query_find(target_path, exact_cwd, query, limit) {\n Ok(rows) => Ok(rows),\n Err(err) => {\n debug!(error = %err, \"codexd find query failed; falling back to local query\");\n search_codex_threads_for_find_local(target_path, exact_cwd, query, limit)\n }\n }\n}\n\npub(crate) fn search_codex_threads_for_find_local(\n target_path: Option<&Path>,\n exact_cwd: bool,\n query: &str,\n limit: usize,\n) -> Result<Vec<CodexRecoverRow>> {\n let normalized_query = query.trim().to_lowercase();\n if normalized_query.is_empty() {\n return Ok(vec![]);\n }\n\n if let Some(session_hint) = extract_codex_session_hint(&normalized_query) {\n let rows = read_codex_threads_by_session_hint_local(&session_hint, limit.max(1))?;\n if !rows.is_empty() {\n return Ok(rows);\n }\n }\n\n let db_path = codex_state_db_path()?;\n let schema = load_codex_thread_schema(&db_path)?;\n\n let mut sql = codex_recover_select_sql(&schema);\n sql.push_str(\"where archived = 0\\n\");\n let mut params_vec: Vec<Box<dyn rusqlite::ToSql>> = Vec::new();\n\n if let Some(target_path) = target_path {\n let target = target_path.to_string_lossy().to_string();\n if exact_cwd {\n sql.push_str(\" and cwd = ?\\n\");\n params_vec.push(Box::new(target));\n } else {\n sql.push_str(\" and (cwd = ? or cwd like ? escape '\\\\')\\n\");\n params_vec.push(Box::new(target.clone()));\n params_vec.push(Box::new(format!(\"{}/%\", escape_like(&target))));\n }\n }\n\n let search_terms = codex_find_search_terms(&normalized_query);\n let mut clauses = Vec::new();\n let mut search_columns = vec![\"id\", \"first_user_message\", \"title\", \"git_branch\", \"cwd\"];\n if schema.has_model {\n search_columns.push(\"model\");\n }\n if schema.has_reasoning_effort {\n search_columns.push(\"reasoning_effort\");\n }\n for term in search_terms {\n let pattern = format!(\"%{}%\", escape_like(&term));\n for column in &search_columns {\n clauses.push(format!(\"lower(coalesce({column}, '')) like ? escape '\\\\'\"));\n params_vec.push(Box::new(pattern.clone()));\n }\n }\n if !clauses.is_empty() {\n sql.push_str(\" and (\");\n sql.push_str(&clauses.join(\" or \"));\n sql.push_str(\")\\n\");\n }\n\n sql.push_str(\"order by updated_at desc\\nlimit ?\\n\");\n let fetch_limit = (limit.max(5) * 20).min(200);\n params_vec.push(Box::new(fetch_limit as i64));\n let scope_target = target_path\n .map(|path| path.display().to_string())\n .unwrap_or_default();\n let cache_key = format!(\n \"query={normalized_query}\\nexact={exact_cwd}\\ntarget={scope_target}\\nfetch_limit={fetch_limit}\"\n );\n let mut rows = with_codex_query_cache(&db_path, \"find\", &cache_key, |conn| {\n let params_refs: Vec<&dyn rusqlite::ToSql> =\n params_vec.iter().map(|p| p.as_ref()).collect();\n let mut stmt = conn\n .prepare(&sql)\n .context(\"failed to prepare Codex find query\")?;\n let iter = stmt.query_map(params_refs.as_slice(), map_codex_recover_row)?;\n Ok(iter.collect::<rusqlite::Result<Vec<_>>>()?)\n })?;\n rank_recover_rows(&mut rows, Some(&normalized_query));\n rows.truncate(limit.max(1));\n Ok(rows)\n}\n\nfn codex_find_search_terms(query: &str) -> Vec<String> {\n let normalized = query.trim().to_lowercase();\n if normalized.is_empty() {\n return vec![];\n }\n\n let mut terms = vec![normalized.clone()];\n let mut seen = BTreeSet::from([normalized]);\n for token in tokenize_recover_query(query) {\n if token.len() <= 2 {\n continue;\n }\n if seen.insert(token.clone()) {\n terms.push(token);\n }\n }\n terms\n}\n\nfn tokenize_recover_query(query: &str) -> Vec<String> {\n query\n .split(|ch: char| {\n !ch.is_ascii_alphanumeric() && ch != '/' && ch != '-' && ch != '_' && ch != '#'\n })\n .filter(|part| !part.is_empty())\n .map(|part| part.to_lowercase())\n .filter(|part| part.len() > 1)\n .collect()\n}\n\nfn rank_recover_rows(rows: &mut Vec<CodexRecoverRow>, query: Option<&str>) {\n let normalized_query = query.map(|q| q.to_lowercase()).unwrap_or_default();\n let tokens = tokenize_recover_query(&normalized_query);\n\n rows.sort_by(|a, b| {\n let score_a = recover_row_score(a, &normalized_query, &tokens);\n let score_b = recover_row_score(b, &normalized_query, &tokens);\n score_b\n .cmp(&score_a)\n .then_with(|| b.updated_at.cmp(&a.updated_at))\n .then_with(|| a.cwd.cmp(&b.cwd))\n });\n\n if !tokens.is_empty()\n && rows\n .iter()\n .all(|row| recover_row_score(row, &normalized_query, &tokens) == 0)\n {\n rows.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));\n }\n}\n\nfn recover_row_score(row: &CodexRecoverRow, normalized_query: &str, tokens: &[String]) -> i64 {\n if tokens.is_empty() && normalized_query.is_empty() {\n return 0;\n }\n\n let id = row.id.to_lowercase();\n let cwd = row.cwd.to_lowercase();\n let branch = row.git_branch.clone().unwrap_or_default().to_lowercase();\n let model = row.model.clone().unwrap_or_default().to_lowercase();\n let reasoning_effort = row\n .reasoning_effort\n .clone()\n .unwrap_or_default()\n .to_lowercase();\n let title = row.title.clone().unwrap_or_default().to_lowercase();\n let first = row\n .first_user_message\n .clone()\n .unwrap_or_default()\n .to_lowercase();\n\n let mut score = 0i64;\n\n if !normalized_query.is_empty() {\n if id == normalized_query {\n score += 600;\n } else if id.starts_with(normalized_query) {\n score += 500;\n } else if id.contains(normalized_query) {\n score += 300;\n }\n if first.contains(normalized_query) {\n score += 120;\n }\n if title.contains(normalized_query) {\n score += 90;\n }\n if branch.contains(normalized_query) {\n score += 70;\n }\n if model.contains(normalized_query) {\n score += 65;\n }\n if reasoning_effort.contains(normalized_query) {\n score += 30;\n }\n if cwd.contains(normalized_query) {\n score += 60;\n }\n }\n\n for token in tokens {\n if id.starts_with(token) {\n score += 90;\n } else if id.contains(token) {\n score += 60;\n }\n if first.contains(token) {\n score += 18;\n }\n if title.contains(token) {\n score += 14;\n }\n if branch.contains(token) {\n score += 12;\n }\n if model.contains(token) {\n score += 12;\n }\n if reasoning_effort.contains(token) {\n score += 6;\n }\n if cwd.contains(token) {\n score += 8;\n }\n }\n\n score\n}\n\nfn build_recover_output(\n target_path: &Path,\n exact_cwd: bool,\n query: Option<String>,\n rows: Vec<CodexRecoverRow>,\n) -> CodexRecoverOutput {\n let candidates: Vec<CodexRecoverCandidate> = rows\n .into_iter()\n .map(|row| CodexRecoverCandidate {\n id: row.id,\n updated_at: format_unix_ts(row.updated_at),\n updated_at_unix: row.updated_at,\n cwd: row.cwd,\n git_branch: row.git_branch.filter(|value| !value.trim().is_empty()),\n model: row.model.filter(|value| !value.trim().is_empty()),\n reasoning_effort: row\n .reasoning_effort\n .filter(|value| !value.trim().is_empty()),\n title: row.title.filter(|value| !value.trim().is_empty()),\n first_user_message: row\n .first_user_message\n .filter(|value| !value.trim().is_empty()),\n })\n .collect();\n\n let recommended_route = infer_recover_route(\n target_path,\n query.as_deref().unwrap_or_default(),\n &candidates,\n );\n let summary = build_recover_summary(target_path, exact_cwd, &recommended_route, &candidates);\n\n CodexRecoverOutput {\n target_path: target_path.to_string_lossy().to_string(),\n exact_cwd,\n query,\n recommended_route,\n summary,\n candidates,\n }\n}\n\nfn infer_recover_route(\n target_path: &Path,\n _query: &str,\n candidates: &[CodexRecoverCandidate],\n) -> String {\n if let Some(candidate) = candidates.first() {\n let candidate_cwd = Path::new(&candidate.cwd);\n if candidate_cwd != target_path {\n return format!(\n \"cd {} && f ai codex resume {}\",\n shell_escape_path(candidate_cwd),\n candidate.id\n );\n }\n return format!(\"f ai codex resume {}\", candidate.id);\n }\n\n \"f ai codex new\".to_string()\n}\n\nfn shell_escape_path(path: &Path) -> String {\n let display = path.to_string_lossy();\n if display\n .chars()\n .all(|ch| ch.is_ascii_alphanumeric() || \"/-._~\".contains(ch))\n {\n return display.to_string();\n }\n\n format!(\"'{}'\", display.replace('\\'', \"'\\\"'\\\"'\"))\n}\n\nfn build_recover_summary(\n target_path: &Path,\n exact_cwd: bool,\n recommended_route: &str,\n candidates: &[CodexRecoverCandidate],\n) -> String {\n let mut lines = Vec::new();\n let mode = if exact_cwd { \"exact cwd\" } else { \"repo-tree\" };\n lines.push(format!(\n \"Recovered recent Codex context for {} ({mode} lookup).\",\n target_path.display()\n ));\n\n if candidates.is_empty() {\n lines.push(\"No recent matching Codex sessions found.\".to_string());\n lines.push(format!(\"Recommended route: {}\", recommended_route));\n return lines.join(\"\\n\");\n }\n\n for candidate in candidates.iter().take(3) {\n let message = candidate\n .first_user_message\n .as_deref()\n .or(candidate.title.as_deref())\n .map(truncate_recover_text)\n .unwrap_or_else(|| \"(no stored prompt text)\".to_string());\n let branch = candidate\n .git_branch\n .as_deref()\n .map(|value| value.to_string())\n .unwrap_or_else(|| \"-\".to_string());\n lines.push(format!(\n \"- {} | {} | {} | {} | {}\",\n truncate_recover_id(&candidate.id),\n candidate.updated_at,\n branch,\n candidate.cwd,\n message\n ));\n }\n\n lines.push(format!(\"Recommended route: {}\", recommended_route));\n lines.join(\"\\n\")\n}\n\nfn truncate_recover_id(value: &str) -> String {\n value.chars().take(8).collect()\n}\n\nfn truncate_recover_text(value: &str) -> String {\n let clean = value.split_whitespace().collect::<Vec<_>>().join(\" \");\n if clean.chars().count() <= 110 {\n return clean;\n }\n let truncated: String = clean.chars().take(107).collect();\n format!(\"{truncated}...\")\n}\n\nfn format_unix_ts(ts: i64) -> String {\n DateTime::<Utc>::from_timestamp(ts, 0)\n .map(|value| value.format(\"%Y-%m-%d %H:%M\").to_string())\n .unwrap_or_else(|| ts.to_string())\n}\n\nfn codex_model_label(model: Option<&str>, reasoning_effort: Option<&str>) -> Option<String> {\n match (\n model.map(str::trim).filter(|value| !value.is_empty()),\n reasoning_effort\n .map(str::trim)\n .filter(|value| !value.is_empty()),\n ) {\n (Some(model), Some(reasoning_effort)) => Some(format!(\"{model} [{reasoning_effort}]\")),\n (Some(model), None) => Some(model.to_string()),\n (None, Some(reasoning_effort)) => Some(format!(\"reasoning {reasoning_effort}\")),\n (None, None) => None,\n }\n}\n\nfn print_recover_output(output: &CodexRecoverOutput) {\n println!(\"Target path: {}\", output.target_path);\n println!(\n \"Search mode: {}\",\n if output.exact_cwd {\n \"exact cwd\"\n } else {\n \"repo-tree\"\n }\n );\n if let Some(query) = output.query.as_deref() {\n println!(\"Query: {}\", query);\n }\n println!(\"Recommended route: {}\", output.recommended_route);\n println!();\n if output.candidates.is_empty() {\n println!(\"No recent matching Codex sessions found.\");\n return;\n }\n println!(\"Recent sessions:\");\n for candidate in &output.candidates {\n println!(\n \"- {} | {} | {}\",\n truncate_recover_id(&candidate.id),\n candidate.updated_at,\n candidate.cwd\n );\n if let Some(branch) = candidate.git_branch.as_deref() {\n println!(\" branch: {}\", branch);\n }\n if let Some(model) = codex_model_label(\n candidate.model.as_deref(),\n candidate.reasoning_effort.as_deref(),\n ) {\n println!(\" model: {}\", model);\n }\n if let Some(first) = candidate.first_user_message.as_deref() {\n println!(\" first: {}\", truncate_recover_text(first));\n } else if let Some(title) = candidate.title.as_deref() {\n println!(\" title: {}\", truncate_recover_text(title));\n }\n }\n println!();\n println!(\"Summary:\");\n println!(\"{}\", output.summary);\n}\n\nfn open_codex_session(\n path: Option<String>,\n query: Vec<String>,\n exact_cwd: bool,\n provider: Provider,\n) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"open is only supported for Codex sessions; use `f codex open ...`\");\n }\n ensure_provider_tty(Provider::Codex, \"open\")?;\n\n let plan = build_codex_open_plan(path, query, exact_cwd)?;\n record_codex_open_plan(&plan, \"open\");\n execute_codex_open_plan(&plan)\n}\n\nfn connect_codex_session(\n path: Option<String>,\n query: Vec<String>,\n exact_cwd: bool,\n json_output: bool,\n provider: Provider,\n) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"connect is only supported for Codex sessions; use `f codex connect ...`\");\n }\n\n let target_path = resolve_codex_connect_target_path(path)?;\n let query_text = query.join(\" \").trim().to_string();\n let normalized_query = query_text.to_ascii_lowercase();\n let resolved = if query_text.is_empty() {\n read_recent_codex_threads(&target_path, exact_cwd, 1, None)?\n .into_iter()\n .next()\n .map(|row| (row, \"latest recent session\".to_string()))\n } else {\n resolve_codex_session_lookup(&target_path, exact_cwd, &query_text, &normalized_query)?\n };\n\n let Some((row, reason)) = resolved else {\n if query_text.is_empty() {\n bail!(\"No Codex sessions found for {}\", target_path.display());\n }\n bail!(\n \"{}\",\n build_codex_open_no_match_message(&target_path, exact_cwd, &query_text)?\n );\n };\n\n if json_output {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&json!({\n \"id\": row.id,\n \"cwd\": row.cwd,\n \"updatedAtUnix\": row.updated_at,\n \"title\": row.title,\n \"firstUserMessage\": row.first_user_message,\n \"gitBranch\": row.git_branch,\n \"model\": row.model,\n \"reasoningEffort\": row.reasoning_effort,\n \"reason\": reason,\n \"targetPath\": target_path.display().to_string(),\n \"exactCwd\": exact_cwd,\n \"query\": if query_text.is_empty() { None::<String> } else { Some(query_text) },\n }))\n .context(\"failed to encode codex connect JSON\")?\n );\n return Ok(());\n }\n\n ensure_provider_tty(Provider::Codex, \"connect\")?;\n let connect_summary = if query_text.is_empty() {\n row.first_user_message\n .as_deref()\n .and_then(codex_text::sanitize_codex_query_text)\n .or_else(|| row.title.as_deref().map(str::trim).map(str::to_string))\n .unwrap_or_else(|| \"resume latest recent session\".to_string())\n } else {\n query_text.clone()\n };\n let mut connect_event = activity_log::ActivityEvent::done(\"codex.connect\", connect_summary);\n connect_event.route = Some(if query_text.is_empty() {\n \"latest\".to_string()\n } else {\n \"query\".to_string()\n });\n connect_event.target_path = Some(target_path.display().to_string());\n connect_event.launch_path = Some(row.cwd.clone());\n connect_event.session_id = Some(row.id.clone());\n connect_event.source = Some(\"codex-connect\".to_string());\n let _ = activity_log::append_daily_event(connect_event);\n\n let launch_path = PathBuf::from(&row.cwd);\n println!(\n \"Resuming session {} from {}...\",\n &row.id[..8.min(row.id.len())],\n launch_path.display()\n );\n if launch_session_for_target(\n &row.id,\n Provider::Codex,\n None,\n Some(&launch_path),\n None,\n None,\n )? {\n return Ok(());\n }\n\n bail!(\n \"failed to connect to codex session {} for {}\",\n row.id,\n launch_path.display()\n )\n}\n\nfn resolve_codex_input(\n path: Option<String>,\n query: Vec<String>,\n exact_cwd: bool,\n json_output: bool,\n provider: Provider,\n) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"resolve is only supported for Codex sessions; use `f codex resolve ...`\");\n }\n\n let (query, json_output) = normalize_codex_resolve_args(query, json_output);\n let plan = build_codex_open_plan(path, query, exact_cwd)?;\n record_codex_open_plan(&plan, \"resolve\");\n if json_output {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&plan).context(\"failed to encode Codex resolve JSON\")?\n );\n return Ok(());\n }\n\n print_codex_open_plan(&plan);\n Ok(())\n}\n\npub fn codex_resolve_inspector(\n path: Option<String>,\n query: String,\n exact_cwd: bool,\n) -> Result<CodexResolveInspectorResponse> {\n let plan = build_codex_open_plan(path, vec![query], exact_cwd)?;\n let runtime_skills = load_runtime_skills_from_plan(&plan)?;\n let workflow = build_codex_resolve_workflow_explanation(&plan, &runtime_skills);\n Ok(CodexResolveInspectorResponse {\n action: plan.action,\n route: plan.route,\n reason: plan.reason,\n target_path: plan.target_path,\n launch_path: plan.launch_path,\n query: plan.query,\n session_id: plan.session_id,\n prompt: plan.prompt,\n references: plan\n .references\n .into_iter()\n .map(|reference| CodexResolveReferenceSnapshot {\n name: reference.name,\n source: reference.source,\n matched: reference.matched,\n command: reference.command,\n output: reference.output,\n })\n .collect(),\n runtime_state_path: plan.runtime_state_path,\n runtime_skills,\n prompt_context_budget_chars: plan.prompt_context_budget_chars,\n max_resolved_references: plan.max_resolved_references,\n prompt_chars: plan.prompt_chars,\n injected_context_chars: plan.injected_context_chars,\n trace: plan.trace,\n workflow,\n })\n}\n\nfn build_codex_resolve_workflow_explanation(\n plan: &CodexOpenPlan,\n runtime_skills: &[CodexResolveRuntimeSkillSnapshot],\n) -> Option<CodexResolveWorkflowExplanation> {\n if let Some(reference) = plan.references.iter().find(|reference| reference.name == \"pr-feedback\")\n {\n return Some(build_pr_feedback_workflow_explanation(\n plan,\n reference,\n runtime_skills,\n ));\n }\n\n if let Some(reference) = plan\n .references\n .iter()\n .find(|reference| reference.name == \"commit-workflow\")\n {\n let repo_root = Path::new(&plan.target_path);\n let kit_gate = detect_commit_workflow_kit_gate(repo_root);\n return Some(CodexResolveWorkflowExplanation {\n id: \"commit-workflow\".to_string(),\n title: \"Commit workflow\".to_string(),\n summary: \"Flow recognized a high-confidence commit request and turned it into a guarded commit workflow instead of passing plain `commit` text through to Codex.\".to_string(),\n trigger: \"High-confidence commit language like `commit`, `commit and push`, or `review and commit`.\".to_string(),\n generated_by: \"flow backend route metadata\".to_string(),\n packet: CodexResolveWorkflowPacket {\n kind: \"commit_workflow\".to_string(),\n compact_summary: \"Compact commit packet seeded with repo status and diff stats instead of a full pasted diff.\".to_string(),\n default_view: \"Start with git status and compact diff stats. Open the full diff or long repo instructions only when the compact view does not explain the risk.\".to_string(),\n expansion_rules: vec![\n \"Read the compact repo snapshot first.\".to_string(),\n \"Inspect the exact local diff and adjacent call sites only after the compact view tells you where to look.\".to_string(),\n \"Use repo AGENTS/review instructions as binding constraints, but do not expand them into the prompt unless the change depends on them.\".to_string(),\n ],\n trace: plan.trace.clone(),\n validation_plan: {\n let mut plan = vec![\n CodexResolveWorkflowValidation {\n label: \"Diff inspection\".to_string(),\n tier: \"targeted\".to_string(),\n detail: \"Inspect the actual local diff and adjacent call sites before deciding on the final commit shape.\".to_string(),\n command: None,\n },\n CodexResolveWorkflowValidation {\n label: \"Smallest safety check\".to_string(),\n tier: \"targeted\".to_string(),\n detail: \"Run the smallest test, lint, or manual check that can falsify the change before committing.\".to_string(),\n command: None,\n },\n ];\n if let Some(command) = kit_gate {\n plan.push(CodexResolveWorkflowValidation {\n label: \"Deterministic repo gate\".to_string(),\n tier: \"targeted\".to_string(),\n detail: \"Run the repo's deterministic gate before the final commit when one is available.\".to_string(),\n command: Some(command),\n });\n }\n if let Some(command) = reference.command.clone() {\n plan.push(CodexResolveWorkflowValidation {\n label: \"Final guarded commit lane\".to_string(),\n tier: \"operator\".to_string(),\n detail: \"Use the slower Flow-assisted commit path for the final review and commit synthesis instead of a fast blind commit.\".to_string(),\n command: Some(command),\n });\n }\n plan\n },\n },\n commands: reference\n .command\n .as_deref()\n .map(|command| {\n vec![CodexResolveWorkflowCommand {\n label: \"Preferred command\".to_string(),\n command: command.to_string(),\n }]\n })\n .unwrap_or_default(),\n artifacts: Vec::new(),\n steps: vec![\n CodexResolveWorkflowStep {\n title: \"Inspect the real repo state\".to_string(),\n detail: \"Flow snapshots the repo status and diff context before Codex starts so the commit flow is grounded in actual local changes.\".to_string(),\n },\n CodexResolveWorkflowStep {\n title: \"Inject the commit contract\".to_string(),\n detail: \"The prompt includes a commit contract focused on correctness, regression risk, performance, robustness, and repo `AGENTS.md` compliance.\".to_string(),\n },\n CodexResolveWorkflowStep {\n title: \"Bias toward deterministic gates\".to_string(),\n detail: \"Repo-specific gates such as Kit lint/review are surfaced in the contract so the commit lane does not depend only on model judgment.\".to_string(),\n },\n ],\n notes: vec![\n format!(\"Route: {}\", plan.route),\n format!(\"Reason: {}\", plan.reason),\n ],\n });\n }\n\n if let Some(reference) = plan\n .references\n .iter()\n .find(|reference| reference.name == \"sync-workflow\")\n {\n return Some(CodexResolveWorkflowExplanation {\n id: \"sync-workflow\".to_string(),\n title: \"Sync workflow\".to_string(),\n summary: \"Flow recognized guarded sync language and routed it into the repo's safe sync workflow instead of leaving Codex to improvise branch sync behavior.\".to_string(),\n trigger: \"High-confidence sync language like `sync branch` in a supported repo/workspace.\".to_string(),\n generated_by: \"flow backend route metadata\".to_string(),\n packet: CodexResolveWorkflowPacket {\n kind: \"sync_workflow\".to_string(),\n compact_summary: \"Compact sync packet carrying the guarded repo sync command and repo workflow contract.\".to_string(),\n default_view: \"Start with the repo-specific sync contract. Only expand broader branch history or repo instructions if the guarded sync command reports a blocker.\".to_string(),\n expansion_rules: vec![\n \"Use the repo's guarded sync path first.\".to_string(),\n \"Inspect additional branch history only when sync reports a blocker.\".to_string(),\n \"Keep sync explanations branch-aware and compact instead of replaying full Git/JJ history.\".to_string(),\n ],\n trace: plan.trace.clone(),\n validation_plan: vec![\n CodexResolveWorkflowValidation {\n label: \"Guarded sync command\".to_string(),\n tier: \"targeted\".to_string(),\n detail: \"Use the repo sync contract rather than improvising Git/JJ steps.\".to_string(),\n command: reference.command.clone(),\n },\n CodexResolveWorkflowValidation {\n label: \"Post-sync status check\".to_string(),\n tier: \"targeted\".to_string(),\n detail: \"Confirm what changed, whether the branch is now synced, and whether any blocker remains.\".to_string(),\n command: None,\n },\n ],\n },\n commands: reference\n .command\n .as_deref()\n .map(|command| {\n vec![CodexResolveWorkflowCommand {\n label: \"Preferred command\".to_string(),\n command: command.to_string(),\n }]\n })\n .unwrap_or_default(),\n artifacts: Vec::new(),\n steps: vec![\n CodexResolveWorkflowStep {\n title: \"Map plain sync language to the repo workflow\".to_string(),\n detail: \"Flow chooses the repo-specific sync command so branch movement stays consistent with the local workflow instead of defaulting to raw git operations.\".to_string(),\n },\n CodexResolveWorkflowStep {\n title: \"Keep the main prompt compact\".to_string(),\n detail: \"Only the sync contract and relevant repo instructions are injected, which avoids bloating normal coding context.\".to_string(),\n },\n ],\n notes: vec![\n format!(\"Route: {}\", plan.route),\n format!(\"Reason: {}\", plan.reason),\n ],\n });\n }\n\n None\n}\n\nfn build_pr_feedback_workflow_explanation(\n plan: &CodexOpenPlan,\n reference: &CodexResolvedReference,\n runtime_skills: &[CodexResolveRuntimeSkillSnapshot],\n) -> CodexResolveWorkflowExplanation {\n let fields = parse_reference_fields(&reference.output);\n let mut commands = Vec::new();\n if let Some(command) = reference.command.as_deref() {\n commands.push(CodexResolveWorkflowCommand {\n label: \"Primary command\".to_string(),\n command: command.to_string(),\n });\n }\n if let Some(command) = fields.get(\"cursor reopen\") {\n commands.push(CodexResolveWorkflowCommand {\n label: \"Cursor reopen\".to_string(),\n command: command.clone(),\n });\n }\n\n let mut artifacts = Vec::new();\n push_workflow_artifact(&mut artifacts, \"Workspace\", fields.get(\"workspace\"), \"path\");\n push_workflow_artifact(\n &mut artifacts,\n \"Snapshot markdown\",\n fields.get(\"snapshot markdown\"),\n \"path\",\n );\n push_workflow_artifact(\n &mut artifacts,\n \"Snapshot json\",\n fields.get(\"snapshot json\"),\n \"path\",\n );\n push_workflow_artifact(&mut artifacts, \"Review plan\", fields.get(\"review plan\"), \"path\");\n push_workflow_artifact(\n &mut artifacts,\n \"Review rules\",\n fields.get(\"review rules\"),\n \"path\",\n );\n push_workflow_artifact(\n &mut artifacts,\n \"Kit system prompt\",\n fields.get(\"kit system prompt\"),\n \"path\",\n );\n push_workflow_artifact(&mut artifacts, \"Trace ID\", fields.get(\"trace id\"), \"text\");\n push_workflow_artifact(&mut artifacts, \"PR URL\", fields.get(\"url\"), \"url\");\n push_workflow_artifact(\n &mut artifacts,\n \"PR feedback\",\n fields.get(\"pr feedback\"),\n \"text\",\n );\n\n let skill_note = runtime_skills\n .iter()\n .find(|skill| {\n skill.name == \"github\"\n || skill.original_name.as_deref() == Some(\"github\")\n || skill.name.contains(\"github\")\n })\n .map(|skill| {\n let mut note = format!(\n \"Runtime skill: {}\",\n skill.original_name\n .as_deref()\n .unwrap_or(skill.name.as_str())\n );\n if let Some(reason) = skill.match_reason.as_deref() {\n note.push_str(\" — \");\n note.push_str(reason);\n }\n note\n });\n\n let mut notes = vec![\n format!(\"Route: {}\", plan.route),\n format!(\"Reason: {}\", plan.reason),\n \"This explanation is generated by Flow backend code, so myflow stays aligned with the current route behavior instead of duplicating docs in the UI.\".to_string(),\n ];\n if let Some(note) = skill_note {\n notes.push(note);\n }\n\n CodexResolveWorkflowExplanation {\n id: \"pr-feedback\".to_string(),\n title: \"GitHub PR review workflow\".to_string(),\n summary: \"Flow recognized the prompt as PR review intent, ran the PR feedback pipeline, generated a reusable review packet, injected compact review context into Codex, and loaded the GitHub runtime skill.\".to_string(),\n trigger: \"GitHub pull-request URL plus review language like `check`, `comments`, `review`, or `for comments`.\".to_string(),\n generated_by: \"flow backend route metadata\".to_string(),\n packet: CodexResolveWorkflowPacket {\n kind: \"pr_feedback\".to_string(),\n compact_summary: \"Compact PR review packet with artifact paths, top review items, and a review-plan handoff instead of the full GitHub page.\".to_string(),\n default_view: \"Start with the compact PR packet and the generated review plan. Expand snapshot markdown/json only when a review item needs more original context.\".to_string(),\n expansion_rules: vec![\n \"Read the compact packet first.\".to_string(),\n \"Use the generated review plan as the working ledger for item-by-item resolution.\".to_string(),\n \"Open snapshot markdown/json only when the packet or review plan is insufficient.\".to_string(),\n ],\n trace: plan.trace.clone(),\n validation_plan: {\n let mut plan = vec![CodexResolveWorkflowValidation {\n label: \"Per-item product validation\".to_string(),\n tier: \"targeted\".to_string(),\n detail: \"For each review item, run the smallest relevant test, lint, or manual repro in the product repo before marking it resolved.\".to_string(),\n command: None,\n }];\n if let Some(review_plan) = fields.get(\"review plan\") {\n plan.push(CodexResolveWorkflowValidation {\n label: \"Use the review ledger\".to_string(),\n tier: \"operator\".to_string(),\n detail: \"Keep the generated review plan up to date as the item-by-item source of truth instead of starting each item from an empty chat.\".to_string(),\n command: Some(review_plan.clone()),\n });\n }\n if let Some(command) = fields.get(\"cursor reopen\") {\n plan.push(CodexResolveWorkflowValidation {\n label: \"Reopen the full review surface\".to_string(),\n tier: \"operator\".to_string(),\n detail: \"Reopen the workspace and review artifacts together when you need the full human + Cursor review loop again.\".to_string(),\n command: Some(command.clone()),\n });\n }\n plan\n },\n },\n commands,\n artifacts,\n steps: vec![\n CodexResolveWorkflowStep {\n title: \"Route the URL as builtin `pr-feedback`\".to_string(),\n detail: \"Flow treats the prompt as review intent instead of a generic web URL, so the route is deterministic and review-specific.\".to_string(),\n },\n CodexResolveWorkflowStep {\n title: \"Run the PR feedback pipeline\".to_string(),\n detail: \"Flow effectively runs `f pr feedback <url>` and uses `gh` to fetch the PR title, reviews, review comments, and issue comments.\".to_string(),\n },\n CodexResolveWorkflowStep {\n title: \"Write the review packet\".to_string(),\n detail: \"Flow writes the markdown/json feedback snapshot, the human review plan, the review rules artifact, and the Kit system prompt.\".to_string(),\n },\n CodexResolveWorkflowStep {\n title: \"Inject compact review context\".to_string(),\n detail: \"Codex receives a compact PR-review block with the generated artifact paths and top feedback items instead of the full GitHub page.\".to_string(),\n },\n CodexResolveWorkflowStep {\n title: \"Load the GitHub runtime skill\".to_string(),\n detail: \"The runtime state activates the GitHub skill alongside the builtin route so follow-up GitHub CLI work has the right context.\".to_string(),\n },\n CodexResolveWorkflowStep {\n title: \"Drive the item-by-item review loop\".to_string(),\n detail: \"The generated review packet is what `forge review`, the Flow Review panel, and the Kit follow-up prompts use for the actual resolution workflow.\".to_string(),\n },\n ],\n notes,\n }\n}\n\nfn parse_reference_fields(output: &str) -> BTreeMap<String, String> {\n let mut fields = BTreeMap::new();\n for line in output.lines() {\n let trimmed = line.trim();\n if trimmed.is_empty() || trimmed.starts_with('[') {\n continue;\n }\n let Some((label, value)) = trimmed.split_once(\": \") else {\n continue;\n };\n if matches!(label, \"Summary\" | \"Top feedback items\" | \"Plan excerpt\") {\n continue;\n }\n let value = value.trim();\n if value.is_empty() {\n continue;\n }\n fields.insert(label.to_ascii_lowercase(), value.to_string());\n }\n fields\n}\n\nfn push_workflow_artifact(\n artifacts: &mut Vec<CodexResolveWorkflowArtifact>,\n label: &str,\n value: Option<&String>,\n kind: &str,\n) {\n if let Some(value) = value {\n artifacts.push(CodexResolveWorkflowArtifact {\n label: label.to_string(),\n value: value.clone(),\n kind: kind.to_string(),\n });\n }\n}\n\nfn load_runtime_skills_from_plan(\n plan: &CodexOpenPlan,\n) -> Result<Vec<CodexResolveRuntimeSkillSnapshot>> {\n let Some(path) = plan.runtime_state_path.as_deref() else {\n return Ok(Vec::new());\n };\n let raw =\n fs::read(path).with_context(|| format!(\"failed to read runtime state {}\", path))?;\n let state: codex_runtime::CodexRuntimeState = serde_json::from_slice(&raw)\n .with_context(|| format!(\"failed to decode runtime state {}\", path))?;\n Ok(state\n .skills\n .into_iter()\n .map(|skill| CodexResolveRuntimeSkillSnapshot {\n name: skill.name,\n kind: skill.kind,\n path: skill.path,\n trigger: skill.trigger,\n source: skill.source,\n original_name: skill.original_name,\n estimated_chars: skill.estimated_chars,\n match_reason: skill.match_reason,\n })\n .collect())\n}\n\nconst DEFAULT_GLOBAL_CODEX_WRAPPER_BIN: &str = \"~/code/flow/scripts/codex-flow-wrapper\";\nconst DEFAULT_GLOBAL_CODEX_HOME_SESSION_PATH: &str = \"~/repos/openai/codex\";\nconst DEFAULT_GLOBAL_CODEX_SKILL_SOURCE_NAME: &str = \"vercel-labs-skills\";\nconst DEFAULT_GLOBAL_CODEX_SKILL_SOURCE_PATH: &str = \"~/repos/vercel-labs/skills\";\nconst DEFAULT_GLOBAL_CODEX_PROMPT_BUDGET: usize = 1200;\nconst DEFAULT_GLOBAL_CODEX_MAX_REFERENCES: usize = 2;\nconst CODEX_SKILL_EVAL_LAUNCHD_LABEL: &str = \"dev.nikiv.flow-codex-skill-eval\";\n\n#[allow(dead_code)]\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nenum CodexSkillEvalScheduleStatus {\n Unsupported,\n NotInstalled,\n PlistOnly,\n Loaded,\n}\n\nimpl CodexSkillEvalScheduleStatus {\n fn as_str(self) -> &'static str {\n match self {\n Self::Unsupported => \"unsupported\",\n Self::NotInstalled => \"not-installed\",\n Self::PlistOnly => \"plist-only\",\n Self::Loaded => \"loaded\",\n }\n }\n\n fn ready(self) -> bool {\n matches!(self, Self::Loaded)\n }\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexDoctorSnapshot {\n target: String,\n codex_bin: String,\n codexd: String,\n codexd_socket: String,\n memory_state: String,\n memory_root: String,\n memory_db_path: String,\n memory_events_indexed: usize,\n memory_facts_indexed: usize,\n runtime_transport: String,\n runtime_skills: String,\n auto_resolve_references: bool,\n home_session_path: String,\n prompt_context_budget_chars: usize,\n max_resolved_references: usize,\n reference_resolvers: usize,\n query_cache: String,\n query_cache_entries_on_disk: usize,\n skill_eval_events_on_disk: usize,\n skill_eval_outcomes_on_disk: usize,\n skill_scorecard_samples: usize,\n skill_scorecard_entries: usize,\n skill_scorecard_top: Option<String>,\n external_skill_candidates: usize,\n runtime_state_files: usize,\n runtime_state_files_for_target: usize,\n skill_eval_schedule: String,\n learning_state: String,\n runtime_ready: bool,\n schedule_ready: bool,\n learning_ready: bool,\n warnings: Vec<String>,\n}\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexSkillsDashboardResponse {\n pub doctor: CodexDoctorSnapshot,\n pub skills: codex_runtime::CodexSkillsDashboardSnapshot,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexEvalRouteSnapshot {\n pub route: String,\n pub count: usize,\n pub share: f64,\n pub avg_context_chars: f64,\n pub avg_reference_count: f64,\n pub runtime_activation_rate: f64,\n pub last_recorded_at_unix: u64,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexEvalSkillSnapshot {\n pub name: String,\n pub score: f64,\n pub sample_size: usize,\n pub outcome_samples: usize,\n pub pass_rate: f64,\n pub normalized_gain: f64,\n pub avg_context_chars: f64,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexEvalOpportunity {\n pub severity: String,\n pub title: String,\n pub detail: String,\n pub next_step: String,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexEvalCommand {\n pub label: String,\n pub command: String,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexEvalSnapshot {\n pub generated_at_unix: u64,\n pub target_path: String,\n pub sample_limit: usize,\n pub recent_events: usize,\n pub recent_outcomes: usize,\n pub summary: String,\n pub quality: CodexEvalQualitySnapshot,\n pub doctor: CodexDoctorSnapshot,\n pub top_routes: Vec<CodexEvalRouteSnapshot>,\n pub top_skills: Vec<CodexEvalSkillSnapshot>,\n pub opportunities: Vec<CodexEvalOpportunity>,\n pub commands: Vec<CodexEvalCommand>,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexEvalQualitySnapshot {\n pub status: String,\n pub summary: String,\n pub failure_modes: Vec<String>,\n pub grounded: bool,\n}\n\nfn codex_skill_eval_launchd_plist_path() -> PathBuf {\n config::expand_path(&format!(\n \"~/Library/LaunchAgents/{}.plist\",\n CODEX_SKILL_EVAL_LAUNCHD_LABEL\n ))\n}\n\nfn codex_skill_eval_launchd_status() -> CodexSkillEvalScheduleStatus {\n #[cfg(not(target_os = \"macos\"))]\n {\n CodexSkillEvalScheduleStatus::Unsupported\n }\n\n #[cfg(target_os = \"macos\")]\n {\n let plist = codex_skill_eval_launchd_plist_path();\n if !plist.exists() {\n return CodexSkillEvalScheduleStatus::NotInstalled;\n }\n\n let uid = unsafe { libc::geteuid() };\n let domain = format!(\"gui/{uid}/{CODEX_SKILL_EVAL_LAUNCHD_LABEL}\");\n match Command::new(\"launchctl\").arg(\"print\").arg(&domain).output() {\n Ok(output) if output.status.success() => CodexSkillEvalScheduleStatus::Loaded,\n _ => CodexSkillEvalScheduleStatus::PlistOnly,\n }\n }\n}\n\nfn collect_codex_doctor_snapshot(target_path: &Path) -> Result<CodexDoctorSnapshot> {\n let codex_cfg = load_codex_config_for_path(target_path);\n let runtime_transport_enabled = codex_runtime_transport_enabled(target_path);\n let runtime_states = codex_runtime::load_runtime_states()?;\n let active_runtime_states = runtime_states\n .iter()\n .filter(|state| state.target_path == target_path.display().to_string())\n .count();\n let codex_bin = configured_codex_bin_for_workdir(target_path);\n let codexd_socket = codexd::socket_path()?;\n let codexd_running = codexd::is_running();\n let memory_stats = codex_memory::stats().ok();\n let skill_eval_events = codex_skill_eval::event_count();\n let skill_eval_outcomes = codex_skill_eval::outcome_count();\n let schedule_status = codex_skill_eval_launchd_status();\n let scorecard = codex_skill_eval::load_scorecard(target_path)?;\n let (skill_scorecard_samples, skill_scorecard_entries, skill_scorecard_top) = scorecard\n .as_ref()\n .map(|value| {\n (\n value.samples,\n value.skills.len(),\n value\n .skills\n .first()\n .map(|top| format!(\"{} ({:.2})\", top.name, top.score)),\n )\n })\n .unwrap_or((0, 0, None));\n let discovered_skills = codex_runtime::discover_external_skills(target_path, &codex_cfg)?;\n\n let runtime_skills_state =\n if codex_cfg.runtime_skills.unwrap_or(false) && runtime_transport_enabled {\n \"enabled\"\n } else if codex_cfg.runtime_skills.unwrap_or(false) {\n \"configured-but-inactive\"\n } else {\n \"disabled\"\n };\n let runtime_ready = runtime_transport_enabled\n && runtime_skills_state == \"enabled\"\n && codex_cfg.auto_resolve_references.unwrap_or(true);\n let learning_state = if skill_scorecard_entries > 0 && skill_eval_outcomes > 0 {\n \"grounded\"\n } else if skill_scorecard_entries > 0 {\n \"affinity-only\"\n } else if skill_eval_events > 0 || skill_eval_outcomes > 0 {\n \"warming-up\"\n } else {\n \"dormant\"\n };\n let learning_ready =\n skill_eval_events > 0 && skill_eval_outcomes > 0 && skill_scorecard_entries > 0;\n\n let mut warnings = Vec::new();\n if !runtime_transport_enabled {\n warnings.push(\n \"wrapper transport is disabled; Flow is launching plain `codex`, so runtime skills never activate\"\n .to_string(),\n );\n }\n if runtime_skills_state == \"disabled\" {\n warnings.push(\"runtime skills are disabled in config\".to_string());\n }\n if !schedule_status.ready() {\n warnings.push(\n \"scheduled skill-eval refresh is not loaded; scorecards will only update when you run cron manually\"\n .to_string(),\n );\n }\n if skill_eval_events == 0 {\n warnings.push(\"no Codex route events recorded yet\".to_string());\n }\n if skill_eval_outcomes == 0 {\n warnings.push(\n \"no grounded outcome events recorded yet; scorecards are still affinity-only\"\n .to_string(),\n );\n }\n if memory_stats.is_none() {\n warnings.push(\n \"codex memory mirror is unavailable; recent memory and durable sync will stay local-only\"\n .to_string(),\n );\n }\n\n let (memory_state, memory_root, memory_db_path, memory_events_indexed, memory_facts_indexed) =\n if let Some(stats) = memory_stats {\n (\n \"ready\".to_string(),\n stats.root_dir,\n stats.db_path,\n stats.total_events,\n stats.total_facts,\n )\n } else {\n (\n \"unavailable\".to_string(),\n codex_memory::root_dir().display().to_string(),\n codex_memory::db_path().display().to_string(),\n 0,\n 0,\n )\n };\n\n Ok(CodexDoctorSnapshot {\n target: target_path.display().to_string(),\n codex_bin,\n codexd: if codexd_running {\n \"running\".to_string()\n } else {\n \"stopped\".to_string()\n },\n codexd_socket: codexd_socket.display().to_string(),\n memory_state,\n memory_root,\n memory_db_path,\n memory_events_indexed,\n memory_facts_indexed,\n runtime_transport: if runtime_transport_enabled {\n \"enabled\".to_string()\n } else {\n \"disabled\".to_string()\n },\n runtime_skills: runtime_skills_state.to_string(),\n auto_resolve_references: codex_cfg.auto_resolve_references.unwrap_or(true),\n home_session_path: codex_cfg\n .home_session_path\n .as_deref()\n .map(config::expand_path)\n .unwrap_or_else(default_codex_connect_path)\n .display()\n .to_string(),\n prompt_context_budget_chars: effective_prompt_context_budget_chars(&codex_cfg, false),\n max_resolved_references: effective_max_resolved_references(&codex_cfg),\n reference_resolvers: codex_cfg.reference_resolvers.len(),\n query_cache: if codex_query_cache_disabled() {\n \"disabled\".to_string()\n } else {\n \"enabled\".to_string()\n },\n query_cache_entries_on_disk: codex_query_cache_entry_count(),\n skill_eval_events_on_disk: skill_eval_events,\n skill_eval_outcomes_on_disk: skill_eval_outcomes,\n skill_scorecard_samples,\n skill_scorecard_entries,\n skill_scorecard_top,\n external_skill_candidates: discovered_skills.len(),\n runtime_state_files: runtime_states.len(),\n runtime_state_files_for_target: active_runtime_states,\n skill_eval_schedule: schedule_status.as_str().to_string(),\n learning_state: learning_state.to_string(),\n runtime_ready,\n schedule_ready: schedule_status.ready(),\n learning_ready,\n warnings,\n })\n}\n\npub fn codex_skills_dashboard_snapshot(\n target_path: &Path,\n recent_limit: usize,\n) -> Result<CodexSkillsDashboardResponse> {\n let codex_cfg = load_codex_config_for_path(target_path);\n Ok(CodexSkillsDashboardResponse {\n doctor: collect_codex_doctor_snapshot(target_path)?,\n skills: codex_runtime::dashboard_snapshot(target_path, &codex_cfg, recent_limit)?,\n })\n}\n\npub fn codex_skill_source_sync(\n target_path: &Path,\n selected_skills: &[String],\n force: bool,\n) -> Result<usize> {\n let codex_cfg = load_codex_config_for_path(target_path);\n codex_runtime::sync_external_skills(target_path, &codex_cfg, selected_skills, force)\n}\n\nfn print_codex_doctor(snapshot: &CodexDoctorSnapshot) {\n println!(\"# codex doctor\");\n println!(\"target: {}\", snapshot.target);\n println!(\"codex_bin: {}\", snapshot.codex_bin);\n println!(\"codexd: {}\", snapshot.codexd);\n println!(\"codexd_socket: {}\", snapshot.codexd_socket);\n println!(\"memory_state: {}\", snapshot.memory_state);\n println!(\"memory_root: {}\", snapshot.memory_root);\n println!(\"memory_db_path: {}\", snapshot.memory_db_path);\n println!(\"memory_events_indexed: {}\", snapshot.memory_events_indexed);\n println!(\"memory_facts_indexed: {}\", snapshot.memory_facts_indexed);\n println!(\"runtime_transport: {}\", snapshot.runtime_transport);\n println!(\"runtime_skills: {}\", snapshot.runtime_skills);\n println!(\n \"auto_resolve_references: {}\",\n snapshot.auto_resolve_references\n );\n println!(\"home_session_path: {}\", snapshot.home_session_path);\n println!(\n \"prompt_context_budget_chars: {}\",\n snapshot.prompt_context_budget_chars\n );\n println!(\n \"max_resolved_references: {}\",\n snapshot.max_resolved_references\n );\n println!(\"reference_resolvers: {}\", snapshot.reference_resolvers);\n println!(\"query_cache: {}\", snapshot.query_cache);\n println!(\n \"query_cache_entries_on_disk: {}\",\n snapshot.query_cache_entries_on_disk\n );\n println!(\n \"skill_eval_events_on_disk: {}\",\n snapshot.skill_eval_events_on_disk\n );\n println!(\n \"skill_eval_outcomes_on_disk: {}\",\n snapshot.skill_eval_outcomes_on_disk\n );\n println!(\n \"skill_scorecard_samples: {}\",\n snapshot.skill_scorecard_samples\n );\n println!(\n \"skill_scorecard_entries: {}\",\n snapshot.skill_scorecard_entries\n );\n if let Some(top) = &snapshot.skill_scorecard_top {\n println!(\"skill_scorecard_top: {}\", top);\n }\n println!(\n \"external_skill_candidates: {}\",\n snapshot.external_skill_candidates\n );\n println!(\"runtime_state_files: {}\", snapshot.runtime_state_files);\n println!(\n \"runtime_state_files_for_target: {}\",\n snapshot.runtime_state_files_for_target\n );\n println!(\"skill_eval_schedule: {}\", snapshot.skill_eval_schedule);\n println!(\"learning_state: {}\", snapshot.learning_state);\n println!(\"runtime_ready: {}\", snapshot.runtime_ready);\n println!(\"schedule_ready: {}\", snapshot.schedule_ready);\n println!(\"learning_ready: {}\", snapshot.learning_ready);\n if !snapshot.warnings.is_empty() {\n println!(\"warnings: {}\", snapshot.warnings.len());\n for warning in &snapshot.warnings {\n println!(\"- {}\", warning);\n }\n }\n}\n\nfn assert_codex_doctor(\n snapshot: &CodexDoctorSnapshot,\n assert_runtime: bool,\n assert_schedule: bool,\n assert_learning: bool,\n assert_autonomous: bool,\n) -> Result<()> {\n let mut failures = Vec::new();\n let require_runtime = assert_runtime || assert_autonomous;\n let require_schedule = assert_schedule || assert_autonomous;\n let require_learning = assert_learning || assert_autonomous;\n\n if require_runtime {\n if snapshot.runtime_transport != \"enabled\" {\n failures.push(\n \"runtime transport is disabled; set [options].codex_bin to the Flow wrapper\"\n .to_string(),\n );\n }\n if snapshot.runtime_skills != \"enabled\" {\n failures.push(\n \"runtime skills are not active; enable [codex].runtime_skills and use the Flow wrapper\"\n .to_string(),\n );\n }\n if !snapshot.auto_resolve_references {\n failures.push(\"auto_resolve_references is disabled\".to_string());\n }\n }\n\n if require_schedule && !snapshot.schedule_ready {\n failures.push(format!(\n \"scheduled skill-eval refresh is {}; install/load the launchd agent\",\n snapshot.skill_eval_schedule\n ));\n }\n\n if require_learning {\n if snapshot.skill_eval_events_on_disk == 0 {\n failures.push(\"no Codex route events recorded yet\".to_string());\n }\n if snapshot.skill_scorecard_entries == 0 {\n failures.push(\"no skill scorecard entries built yet\".to_string());\n }\n if snapshot.skill_eval_outcomes_on_disk == 0 {\n failures.push(\n \"no grounded skill outcome events recorded yet; the system is still affinity-only\"\n .to_string(),\n );\n }\n }\n\n if failures.is_empty() {\n return Ok(());\n }\n\n bail!(\n \"codex doctor assertion failed:\\n- {}\\nnext: run `f codex enable-global --full`, then exercise `f codex open ...` or `f ai codex new` through Flow until outcomes appear\",\n failures.join(\"\\n- \")\n )\n}\n\nfn codexd_learning_refresh_interval_secs() -> u64 {\n std::env::var(\"FLOW_CODEXD_LEARNING_REFRESH_SECS\")\n .ok()\n .and_then(|value| value.parse::<u64>().ok())\n .map(|value| value.clamp(60, 3600))\n .unwrap_or(900)\n}\n\nfn codexd_learning_refresh_state() -> &'static Mutex<u64> {\n static STATE: OnceLock<Mutex<u64>> = OnceLock::new();\n STATE.get_or_init(|| Mutex::new(0))\n}\n\npub(crate) fn maybe_run_codex_learning_refresh() -> Result<usize> {\n let interval_secs = codexd_learning_refresh_interval_secs();\n let now = unix_now_secs();\n {\n let mut guard = codexd_learning_refresh_state()\n .lock()\n .expect(\"codexd learning refresh mutex poisoned\");\n if now.saturating_sub(*guard) < interval_secs {\n return Ok(0);\n }\n *guard = now;\n }\n\n let _ = codex_memory::sync_from_skill_eval_logs(400);\n let targets = codex_skill_eval::recent_targets(400, 10, 168)?;\n let mut refreshed = 0usize;\n for target in targets {\n if !target.exists() {\n continue;\n }\n codex_skill_eval::rebuild_scorecard(&target, 200)?;\n refreshed += 1;\n }\n Ok(refreshed)\n}\n\nfn codex_eval_commands(target_path: &Path) -> Vec<CodexEvalCommand> {\n let target = target_path.display().to_string();\n vec![\n CodexEvalCommand {\n label: \"Doctor\".to_string(),\n command: format!(\"f codex doctor --path {}\", target),\n },\n CodexEvalCommand {\n label: \"Autonomous readiness\".to_string(),\n command: format!(\"f codex doctor --path {} --assert-autonomous\", target),\n },\n CodexEvalCommand {\n label: \"Skill scorecard\".to_string(),\n command: format!(\"f codex skill-eval show --path {}\", target),\n },\n CodexEvalCommand {\n label: \"Recent memory\".to_string(),\n command: format!(\"f codex memory recent --path {} --limit 12\", target),\n },\n CodexEvalCommand {\n label: \"Daemon status\".to_string(),\n command: \"f codex daemon status\".to_string(),\n },\n ]\n}\n\nfn codex_eval_failure_modes(doctor: &CodexDoctorSnapshot) -> Vec<String> {\n let mut failure_modes = Vec::new();\n if doctor.runtime_transport != \"enabled\" {\n failure_modes.push(\"wrapper transport disabled\".to_string());\n }\n if doctor.runtime_skills != \"enabled\" {\n failure_modes.push(format!(\"runtime skills {}\", doctor.runtime_skills));\n }\n if doctor.memory_state != \"ready\" {\n failure_modes.push(\"codex memory unavailable\".to_string());\n }\n failure_modes\n}\n\nfn build_codex_eval_quality(\n doctor: &CodexDoctorSnapshot,\n recent_events: usize,\n recent_outcomes: usize,\n) -> CodexEvalQualitySnapshot {\n let failure_modes = codex_eval_failure_modes(doctor);\n let status = if failure_modes.is_empty() {\n \"valid\"\n } else {\n \"erroneous\"\n };\n let grounded = recent_outcomes > 0 && doctor.learning_ready;\n let summary = if status == \"erroneous\" {\n format!(\n \"Current target health is erroneous for workflow measurement because Flow is not fully controlling Codex here: {}.\",\n failure_modes.join(\", \")\n )\n } else if grounded {\n \"Current target health is valid and grounded outcome samples are available.\".to_string()\n } else if recent_events == 0 {\n \"Current target health is valid, but there are no recorded Flow-routed Codex events here yet.\".to_string()\n } else {\n \"Current target health is valid, but measurements are still warming up because there are no grounded outcome samples yet.\".to_string()\n };\n\n CodexEvalQualitySnapshot {\n status: status.to_string(),\n summary,\n failure_modes,\n grounded,\n }\n}\n\nfn build_codex_eval_summary(\n doctor: &CodexDoctorSnapshot,\n events: usize,\n outcomes: usize,\n top_route: Option<&CodexEvalRouteSnapshot>,\n top_skill: Option<&CodexEvalSkillSnapshot>,\n) -> String {\n if events == 0 {\n return \"No Flow-routed Codex events recorded yet for this target.\".to_string();\n }\n if !doctor.runtime_ready {\n return format!(\n \"Flow is recording usage, but the Codex wrapper/runtime path is not fully active yet. Recent launches: {}.\",\n events\n );\n }\n if outcomes == 0 {\n return format!(\n \"Flow is recording {} recent Codex launches here, but there are no grounded outcome samples yet, so learning is still affinity-only.\",\n events\n );\n }\n\n let route = top_route\n .map(|value| value.route.as_str())\n .unwrap_or(\"unknown\");\n let skill = top_skill\n .map(|value| value.name.as_str())\n .unwrap_or(\"none\");\n format!(\n \"Runtime is ready and grounded learning is active. Recent launches: {}, grounded outcomes: {}, top route: {}, top skill: {}.\",\n events, outcomes, route, skill\n )\n}\n\nfn build_codex_eval_opportunities(\n doctor: &CodexDoctorSnapshot,\n recent_events: usize,\n recent_outcomes: usize,\n routes: &[CodexEvalRouteSnapshot],\n skills: &[CodexEvalSkillSnapshot],\n) -> Vec<CodexEvalOpportunity> {\n let mut opportunities = Vec::new();\n\n if doctor.runtime_transport != \"enabled\" || doctor.runtime_skills != \"enabled\" {\n opportunities.push(CodexEvalOpportunity {\n severity: \"high\".to_string(),\n title: \"Wrapper/runtime path is not fully active\".to_string(),\n detail: \"Flow cannot reliably improve Codex usage until prompts enter through the Flow wrapper and runtime skills are active.\".to_string(),\n next_step: \"Run `f codex enable-global --full`, then start Codex through `j`, `L`, or `f codex open ...`.\".to_string(),\n });\n }\n\n if doctor.codexd != \"running\" {\n opportunities.push(CodexEvalOpportunity {\n severity: \"medium\".to_string(),\n title: \"codexd is not running\".to_string(),\n detail: \"Recent-session hydration and background completion reconciliation stay cold when the Flow Codex daemon is stopped.\".to_string(),\n next_step: \"Run `f codex daemon start` to keep session recovery and eval maintenance warm.\".to_string(),\n });\n }\n\n if recent_events > 0 && recent_outcomes == 0 {\n opportunities.push(CodexEvalOpportunity {\n severity: \"high\".to_string(),\n title: \"No grounded outcome samples for this target yet\".to_string(),\n detail: \"Flow is learning from route history here, but it does not yet have target-scoped success/failure outcomes to tell whether runtime skills are actually helping.\".to_string(),\n next_step: \"Exercise workflows that emit outcomes through Flow for this repo/path, then rerun `f codex eval --path ...` or `f codex skill-eval show --path ...`.\".to_string(),\n });\n } else if recent_outcomes > 0 && doctor.skill_scorecard_entries == 0 {\n opportunities.push(CodexEvalOpportunity {\n severity: \"medium\".to_string(),\n title: \"Scorecard has not been built yet\".to_string(),\n detail: \"Outcome data exists, but there is no repo-scoped scorecard summarizing which runtime skills are helping.\".to_string(),\n next_step: \"Run `f codex skill-eval run --path ...` once, or let codexd refresh it in the background.\".to_string(),\n });\n }\n\n if let Some(skill) = skills.first()\n && skill.outcome_samples == 0\n {\n opportunities.push(CodexEvalOpportunity {\n severity: \"medium\".to_string(),\n title: format!(\"Top skill `{}` is still affinity-only\", skill.name),\n detail: \"This skill is triggering often enough to score highly, but Flow has not seen grounded success outcomes for it yet.\".to_string(),\n next_step: \"Add or reuse a deterministic success marker for the workflow that uses this skill, so outcomes get logged.\".to_string(),\n });\n }\n\n if let Some(skill) = skills\n .iter()\n .find(|skill| skill.sample_size >= 3 && skill.outcome_samples >= 2 && skill.pass_rate < 0.55)\n {\n opportunities.push(CodexEvalOpportunity {\n severity: \"medium\".to_string(),\n title: format!(\"Skill `{}` is underperforming\", skill.name),\n detail: format!(\n \"It has {} grounded outcome sample(s) with pass rate {:.2}.\",\n skill.outcome_samples, skill.pass_rate\n ),\n next_step: \"Inspect the skill trigger, gotchas, and injected context. Trim or sharpen it before adding more automation.\".to_string(),\n });\n }\n\n if let Some(route) = routes\n .iter()\n .find(|route| route.count >= 3 && route.avg_context_chars > 1800.0)\n {\n opportunities.push(CodexEvalOpportunity {\n severity: \"low\".to_string(),\n title: format!(\"Route `{}` is context-heavy\", route.route),\n detail: format!(\n \"Average injected context is {:.0} chars across {} recent launch(es).\",\n route.avg_context_chars, route.count\n ),\n next_step: \"Trim the workflow packet or sharpen the reference unrolling so the route stays compact.\".to_string(),\n });\n }\n\n if let Some(route) = routes.first()\n && route.route == \"new-plain\"\n && route.share >= 0.7\n && doctor.external_skill_candidates > 0\n {\n opportunities.push(CodexEvalOpportunity {\n severity: \"low\".to_string(),\n title: \"Most launches are still plain prompts\".to_string(),\n detail: \"That is not necessarily bad, but it suggests the repo has more opportunity for explicit workflow routes or sharper runtime skill triggers.\".to_string(),\n next_step: \"Inspect common prompts in the recent events and decide whether one should become a first-class workflow or skill trigger.\".to_string(),\n });\n }\n\n if !doctor.schedule_ready && doctor.codexd != \"running\" {\n opportunities.push(CodexEvalOpportunity {\n severity: \"low\".to_string(),\n title: \"No background refresh is active\".to_string(),\n detail: \"Scorecards only refresh when you run commands manually if neither launchd nor codexd is keeping the learning data warm.\".to_string(),\n next_step: \"Install the launchd refresher with `f codex enable-global --full` or keep `codexd` running.\".to_string(),\n });\n }\n\n if opportunities.is_empty() {\n opportunities.push(CodexEvalOpportunity {\n severity: \"info\".to_string(),\n title: \"No immediate weaknesses detected\".to_string(),\n detail: \"Flow runtime, grounding, and recent skill usage look healthy for this repo/path.\".to_string(),\n next_step: \"Keep using `f codex eval --path ...` after workflow changes to catch regressions early.\".to_string(),\n });\n }\n\n opportunities\n}\n\npub fn codex_eval_snapshot(target_path: &Path, limit: usize) -> Result<CodexEvalSnapshot> {\n let _ = reconcile_pending_codex_quick_launches(limit.max(64));\n let doctor = collect_codex_doctor_snapshot(target_path)?;\n let events = codex_skill_eval::load_events(Some(target_path), limit)?;\n let outcomes = codex_skill_eval::load_outcomes(Some(target_path), limit)?;\n let latest_event_at = events.first().map(|event| event.recorded_at_unix).unwrap_or(0);\n let scorecard = match codex_skill_eval::load_scorecard(target_path)? {\n Some(scorecard) if scorecard.generated_at_unix >= latest_event_at => scorecard,\n _ => codex_skill_eval::rebuild_scorecard(target_path, limit.max(200))?,\n };\n\n #[derive(Default)]\n struct RouteAggregate {\n count: usize,\n total_context_chars: usize,\n total_reference_count: usize,\n runtime_activations: usize,\n last_recorded_at_unix: u64,\n }\n\n let mut route_aggregates: BTreeMap<String, RouteAggregate> = BTreeMap::new();\n for event in &events {\n let entry = route_aggregates.entry(event.route.clone()).or_default();\n entry.count += 1;\n entry.total_context_chars += event.injected_context_chars;\n entry.total_reference_count += event.reference_count;\n if !event.runtime_skills.is_empty() {\n entry.runtime_activations += 1;\n }\n entry.last_recorded_at_unix = entry.last_recorded_at_unix.max(event.recorded_at_unix);\n }\n\n let event_count = events.len().max(1) as f64;\n let mut top_routes = route_aggregates\n .into_iter()\n .map(|(route, agg)| CodexEvalRouteSnapshot {\n route,\n count: agg.count,\n share: agg.count as f64 / event_count,\n avg_context_chars: agg.total_context_chars as f64 / agg.count as f64,\n avg_reference_count: agg.total_reference_count as f64 / agg.count as f64,\n runtime_activation_rate: agg.runtime_activations as f64 / agg.count as f64,\n last_recorded_at_unix: agg.last_recorded_at_unix,\n })\n .collect::<Vec<_>>();\n top_routes.sort_by(|a, b| {\n b.count\n .cmp(&a.count)\n .then_with(|| b.last_recorded_at_unix.cmp(&a.last_recorded_at_unix))\n });\n top_routes.truncate(6);\n\n let mut top_skills = scorecard\n .skills\n .iter()\n .map(|skill| CodexEvalSkillSnapshot {\n name: skill.name.clone(),\n score: skill.score,\n sample_size: skill.sample_size,\n outcome_samples: skill.outcome_samples,\n pass_rate: skill.pass_rate,\n normalized_gain: skill.normalized_gain,\n avg_context_chars: skill.avg_context_chars,\n })\n .collect::<Vec<_>>();\n top_skills.truncate(6);\n\n let summary = build_codex_eval_summary(\n &doctor,\n events.len(),\n outcomes.len(),\n top_routes.first(),\n top_skills.first(),\n );\n let quality = build_codex_eval_quality(&doctor, events.len(), outcomes.len());\n let opportunities = build_codex_eval_opportunities(\n &doctor,\n events.len(),\n outcomes.len(),\n &top_routes,\n &top_skills,\n );\n\n Ok(CodexEvalSnapshot {\n generated_at_unix: unix_now_secs(),\n target_path: target_path.display().to_string(),\n sample_limit: limit,\n recent_events: events.len(),\n recent_outcomes: outcomes.len(),\n summary,\n quality,\n doctor,\n top_routes,\n top_skills,\n opportunities,\n commands: codex_eval_commands(target_path),\n })\n}\n\nfn print_codex_eval(snapshot: &CodexEvalSnapshot) {\n println!(\"# codex eval\");\n println!(\"target: {}\", snapshot.target_path);\n println!(\"summary: {}\", snapshot.summary);\n println!(\"quality: {}\", snapshot.quality.status);\n println!(\"quality_summary: {}\", snapshot.quality.summary);\n println!(\"sample_limit: {}\", snapshot.sample_limit);\n println!(\"recent_events: {}\", snapshot.recent_events);\n println!(\"recent_outcomes: {}\", snapshot.recent_outcomes);\n println!(\"runtime_ready: {}\", snapshot.doctor.runtime_ready);\n println!(\"learning_ready: {}\", snapshot.doctor.learning_ready);\n println!(\"codexd: {}\", snapshot.doctor.codexd);\n if !snapshot.quality.failure_modes.is_empty() {\n println!(\"failure_modes:\");\n for mode in &snapshot.quality.failure_modes {\n println!(\"- {}\", mode);\n }\n }\n if !snapshot.top_routes.is_empty() {\n println!(\"routes:\");\n for route in &snapshot.top_routes {\n println!(\n \"- {} | count {} | share {:.0}% | ctx {:.0} chars | refs {:.1} | runtime {:.0}%\",\n route.route,\n route.count,\n route.share * 100.0,\n route.avg_context_chars,\n route.avg_reference_count,\n route.runtime_activation_rate * 100.0\n );\n }\n }\n if !snapshot.top_skills.is_empty() {\n println!(\"skills:\");\n for skill in &snapshot.top_skills {\n println!(\n \"- {} | score {:.2} | samples {} | outcomes {} | pass {:.2} | gain {:.3} | ctx {:.0} chars\",\n skill.name,\n skill.score,\n skill.sample_size,\n skill.outcome_samples,\n skill.pass_rate,\n skill.normalized_gain,\n skill.avg_context_chars\n );\n }\n }\n if !snapshot.opportunities.is_empty() {\n println!(\"opportunities:\");\n for item in &snapshot.opportunities {\n println!(\"- [{}] {} — {}\", item.severity, item.title, item.detail);\n println!(\" next: {}\", item.next_step);\n }\n }\n if !snapshot.commands.is_empty() {\n println!(\"commands:\");\n for command in &snapshot.commands {\n println!(\"- {}: {}\", command.label, command.command);\n }\n }\n}\n\nfn codex_eval(\n path: Option<String>,\n limit: usize,\n json: bool,\n provider: Provider,\n) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"eval is only supported for Codex sessions; use `f codex eval`\");\n }\n\n let target_path = resolve_session_target_path(path.as_deref())?;\n let snapshot = codex_eval_snapshot(&target_path, limit.clamp(20, 1000))?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&snapshot)\n .context(\"failed to encode codex eval JSON\")?\n );\n } else {\n print_codex_eval(&snapshot);\n }\n Ok(())\n}\n\nfn parse_global_flow_toml(path: &Path) -> Result<toml::value::Table> {\n if !path.exists() {\n return Ok(toml::value::Table::new());\n }\n\n let content =\n fs::read_to_string(path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n if content.trim().is_empty() {\n return Ok(toml::value::Table::new());\n }\n\n let value: TomlValue =\n toml::from_str(&content).with_context(|| format!(\"failed to parse {}\", path.display()))?;\n value\n .as_table()\n .cloned()\n .ok_or_else(|| anyhow::anyhow!(\"global flow config must be a TOML table\"))\n}\n\nfn ensure_toml_table<'a>(\n root: &'a mut toml::value::Table,\n key: &str,\n) -> Result<&'a mut toml::value::Table> {\n let needs_insert = !matches!(root.get(key), Some(TomlValue::Table(_)));\n if needs_insert {\n if root.contains_key(key) {\n bail!(\"expected [{}] to be a table in global flow config\", key);\n }\n root.insert(key.to_string(), TomlValue::Table(toml::value::Table::new()));\n }\n root.get_mut(key)\n .and_then(TomlValue::as_table_mut)\n .ok_or_else(|| anyhow::anyhow!(\"expected [{}] to be a table in global flow config\", key))\n}\n\nfn write_string_atomically(path: &Path, content: &str) -> Result<()> {\n let parent = path\n .parent()\n .ok_or_else(|| anyhow::anyhow!(\"missing parent for {}\", path.display()))?;\n fs::create_dir_all(parent)?;\n let temp = parent.join(format!(\n \".{}.tmp-{}-{}\",\n path.file_name()\n .and_then(|value| value.to_str())\n .unwrap_or(\"flow.toml\"),\n std::process::id(),\n unix_now_secs()\n ));\n fs::write(&temp, content).with_context(|| format!(\"failed to write {}\", temp.display()))?;\n fs::rename(&temp, path).with_context(|| format!(\"failed to replace {}\", path.display()))?;\n Ok(())\n}\n\nfn upsert_global_codex_config(path: &Path) -> Result<(String, bool, bool, bool)> {\n let mut root = parse_global_flow_toml(path)?;\n let created = !path.exists();\n let wrapper_path = config::expand_path(DEFAULT_GLOBAL_CODEX_WRAPPER_BIN);\n if !wrapper_path.exists() {\n bail!(\n \"Flow Codex wrapper is missing at {}; build or sync Flow first\",\n wrapper_path.display()\n );\n }\n\n let codex = ensure_toml_table(&mut root, \"codex\")?;\n codex.insert(\"runtime_skills\".to_string(), TomlValue::Boolean(true));\n codex.insert(\n \"auto_resolve_references\".to_string(),\n TomlValue::Boolean(true),\n );\n codex\n .entry(\"home_session_path\".to_string())\n .or_insert_with(|| TomlValue::String(DEFAULT_GLOBAL_CODEX_HOME_SESSION_PATH.to_string()));\n codex\n .entry(\"prompt_context_budget_chars\".to_string())\n .or_insert_with(|| TomlValue::Integer(DEFAULT_GLOBAL_CODEX_PROMPT_BUDGET as i64));\n codex\n .entry(\"max_resolved_references\".to_string())\n .or_insert_with(|| TomlValue::Integer(DEFAULT_GLOBAL_CODEX_MAX_REFERENCES as i64));\n\n let skill_source_root = config::expand_path(DEFAULT_GLOBAL_CODEX_SKILL_SOURCE_PATH);\n let skill_source_available = skill_source_root.exists();\n let mut skill_source_added = false;\n if skill_source_available {\n let entry = codex\n .entry(\"skill_source\".to_string())\n .or_insert_with(|| TomlValue::Array(Vec::new()));\n let array = entry\n .as_array_mut()\n .ok_or_else(|| anyhow::anyhow!(\"[codex].skill_source must be an array\"))?;\n let exists = array.iter().any(|value| {\n let Some(table) = value.as_table() else {\n return false;\n };\n table\n .get(\"name\")\n .and_then(TomlValue::as_str)\n .map(|name| name == DEFAULT_GLOBAL_CODEX_SKILL_SOURCE_NAME)\n .unwrap_or(false)\n || table\n .get(\"path\")\n .and_then(TomlValue::as_str)\n .map(|value| config::expand_path(value) == skill_source_root)\n .unwrap_or(false)\n });\n if !exists {\n let mut source = toml::value::Table::new();\n source.insert(\n \"name\".to_string(),\n TomlValue::String(DEFAULT_GLOBAL_CODEX_SKILL_SOURCE_NAME.to_string()),\n );\n source.insert(\n \"path\".to_string(),\n TomlValue::String(DEFAULT_GLOBAL_CODEX_SKILL_SOURCE_PATH.to_string()),\n );\n source.insert(\"enabled\".to_string(), TomlValue::Boolean(true));\n array.push(TomlValue::Table(source));\n skill_source_added = true;\n }\n }\n\n let options = ensure_toml_table(&mut root, \"options\")?;\n options.insert(\n \"codex_bin\".to_string(),\n TomlValue::String(DEFAULT_GLOBAL_CODEX_WRAPPER_BIN.to_string()),\n );\n\n let rendered = toml::to_string_pretty(&TomlValue::Table(root))\n .context(\"failed to render global flow config\")?;\n Ok((\n rendered,\n created,\n skill_source_added,\n skill_source_available,\n ))\n}\n\nfn install_codex_skill_eval_launchd(\n current_exe: &Path,\n minutes: usize,\n limit: usize,\n max_targets: usize,\n within_hours: u64,\n dry_run: bool,\n) -> Result<String> {\n let script = PathBuf::from(env!(\"CARGO_MANIFEST_DIR\"))\n .join(\"scripts\")\n .join(\"codex-skill-eval-launchd.py\");\n let mut command = Command::new(\"python3\");\n command\n .arg(script)\n .arg(\"install\")\n .arg(\"--minutes\")\n .arg(minutes.to_string())\n .arg(\"--limit\")\n .arg(limit.to_string())\n .arg(\"--max-targets\")\n .arg(max_targets.to_string())\n .arg(\"--within-hours\")\n .arg(within_hours.to_string());\n if dry_run {\n command.arg(\"--dry-run\");\n }\n command.env(\"FLOW_CODEX_SKILL_EVAL_F_BIN\", current_exe);\n let output = command\n .output()\n .context(\"failed to run codex skill-eval launchd installer\")?;\n if !output.status.success() {\n bail!(\n \"codex skill-eval launchd install failed: {}\",\n String::from_utf8_lossy(&output.stderr).trim()\n );\n }\n Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())\n}\n\nfn codex_enable_global(\n dry_run: bool,\n install_launchd: bool,\n start_daemon: bool,\n sync_skills: bool,\n full: bool,\n minutes: usize,\n limit: usize,\n max_targets: usize,\n within_hours: u64,\n provider: Provider,\n) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"enable-global is only supported for Codex sessions; use `f codex enable-global`\");\n }\n\n let install_launchd = install_launchd || full;\n let start_daemon = start_daemon || full;\n let sync_skills = sync_skills || full;\n let config_path = config::default_config_path();\n let (rendered, created, skill_source_added, skill_source_available) =\n upsert_global_codex_config(&config_path)?;\n\n if dry_run {\n println!(\"# codex enable-global\");\n println!(\"config_path: {}\", config_path.display());\n println!(\"config_created: {}\", created);\n println!(\"skill_source_available: {}\", skill_source_available);\n println!(\"skill_source_added: {}\", skill_source_added);\n if install_launchd {\n let preview = install_codex_skill_eval_launchd(\n &env::current_exe().context(\"failed to resolve current flow executable\")?,\n minutes,\n limit,\n max_targets,\n within_hours,\n true,\n )?;\n println!();\n println!(\"{}\", preview);\n }\n println!();\n print!(\"{}\", rendered);\n return Ok(());\n }\n\n let global_dir = config::ensure_global_config_dir()?;\n write_string_atomically(&config_path, &rendered)?;\n println!(\"Updated global Flow config: {}\", config_path.display());\n if created {\n println!(\"Created {}\", global_dir.display());\n }\n println!(\n \"Enabled global Codex wrapper/runtime transport via {}\",\n DEFAULT_GLOBAL_CODEX_WRAPPER_BIN\n );\n if skill_source_available {\n if skill_source_added {\n println!(\n \"Registered external skill source: {}\",\n DEFAULT_GLOBAL_CODEX_SKILL_SOURCE_PATH\n );\n } else {\n println!(\n \"External skill source already configured: {}\",\n DEFAULT_GLOBAL_CODEX_SKILL_SOURCE_PATH\n );\n }\n }\n\n if install_launchd {\n let launchd_output = install_codex_skill_eval_launchd(\n &env::current_exe().context(\"failed to resolve current flow executable\")?,\n minutes,\n limit,\n max_targets,\n within_hours,\n false,\n )?;\n if !launchd_output.is_empty() {\n println!(\"{}\", launchd_output);\n }\n }\n\n if start_daemon {\n codexd::start()?;\n }\n\n if sync_skills {\n let target_path = env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\"));\n let codex_cfg = load_codex_config_for_path(&target_path);\n let installed = codex_runtime::sync_external_skills(&target_path, &codex_cfg, &[], false)?;\n println!(\n \"Synced {} external Codex skill(s) into ~/.codex/skills.\",\n installed\n );\n }\n\n let verify_target = env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\"));\n let snapshot = collect_codex_doctor_snapshot(&verify_target)?;\n assert_codex_doctor(&snapshot, true, install_launchd, false, false)?;\n println!();\n print_codex_doctor(&snapshot);\n Ok(())\n}\n\nfn codex_doctor(\n path: Option<String>,\n assert_runtime: bool,\n assert_schedule: bool,\n assert_learning: bool,\n assert_autonomous: bool,\n json_output: bool,\n provider: Provider,\n) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"doctor is only supported for Codex sessions; use `f codex doctor`\");\n }\n\n let target_path = resolve_session_target_path(path.as_deref())?;\n let snapshot = collect_codex_doctor_snapshot(&target_path)?;\n if json_output {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&snapshot)\n .context(\"failed to encode codex doctor JSON\")?\n );\n } else {\n print_codex_doctor(&snapshot);\n }\n assert_codex_doctor(\n &snapshot,\n assert_runtime,\n assert_schedule,\n assert_learning,\n assert_autonomous,\n )?;\n Ok(())\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct CodexQuickLaunchEvent {\n version: u8,\n launch_id: String,\n recorded_at_unix: u64,\n mode: String,\n cwd: String,\n daemon: String,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct CodexQuickLaunchHydration {\n version: u8,\n launch_id: String,\n hydrated_at_unix: u64,\n target_path: String,\n session_id: String,\n query: String,\n prompt_recorded_at_unix: u64,\n}\n\nfn codex_quick_launch_log_path() -> Result<PathBuf> {\n Ok(config::ensure_global_state_dir()?\n .join(\"codex\")\n .join(\"quick-launches.jsonl\"))\n}\n\nfn codex_quick_launch_hydrations_path() -> Result<PathBuf> {\n Ok(config::ensure_global_state_dir()?\n .join(\"codex\")\n .join(\"quick-launches-hydrated.jsonl\"))\n}\n\nfn log_codex_quick_launch_event(event: &CodexQuickLaunchEvent) -> Result<()> {\n let path = codex_quick_launch_log_path()?;\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n let mut file = OpenOptions::new()\n .create(true)\n .append(true)\n .open(&path)\n .with_context(|| format!(\"failed to open {}\", path.display()))?;\n serde_json::to_writer(&mut file, event).context(\"failed to encode quick launch event\")?;\n file.write_all(b\"\\n\")\n .context(\"failed to terminate quick launch event\")?;\n Ok(())\n}\n\nfn log_codex_quick_launch_hydration(hydration: &CodexQuickLaunchHydration) -> Result<()> {\n let path = codex_quick_launch_hydrations_path()?;\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n let mut file = OpenOptions::new()\n .create(true)\n .append(true)\n .open(&path)\n .with_context(|| format!(\"failed to open {}\", path.display()))?;\n serde_json::to_writer(&mut file, hydration)\n .context(\"failed to encode quick launch hydration\")?;\n file.write_all(b\"\\n\")\n .context(\"failed to terminate quick launch hydration\")?;\n Ok(())\n}\n\nfn load_recent_codex_quick_launches(limit: usize) -> Result<Vec<CodexQuickLaunchEvent>> {\n let path = codex_quick_launch_log_path()?;\n if !path.exists() || limit == 0 {\n return Ok(Vec::new());\n }\n let raw =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let mut launches = raw\n .lines()\n .rev()\n .filter_map(|line| {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n return None;\n }\n serde_json::from_str::<CodexQuickLaunchEvent>(trimmed).ok()\n })\n .take(limit)\n .collect::<Vec<_>>();\n launches.sort_by_key(|launch| launch.recorded_at_unix);\n Ok(launches)\n}\n\nfn load_hydrated_codex_quick_launch_ids() -> Result<BTreeSet<String>> {\n let path = codex_quick_launch_hydrations_path()?;\n if !path.exists() {\n return Ok(BTreeSet::new());\n }\n let raw =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n Ok(raw\n .lines()\n .filter_map(|line| serde_json::from_str::<CodexQuickLaunchHydration>(line.trim()).ok())\n .map(|hydration| hydration.launch_id)\n .collect())\n}\n\nfn parse_rfc3339_to_unix(value: &str) -> Option<u64> {\n chrono::DateTime::parse_from_rfc3339(value)\n .ok()\n .and_then(|dt| u64::try_from(dt.timestamp()).ok())\n}\n\nfn read_codex_first_user_message_since(\n session_file: &PathBuf,\n since_unix: u64,\n) -> Result<Option<(String, u64)>> {\n let mut first: Option<(String, u64)> = None;\n for_each_nonempty_jsonl_line(session_file, |line| {\n let entry: CodexEntry = match crate::json_parse::parse_json_line(line) {\n Ok(v) => v,\n Err(_) => return,\n };\n let Some((role, text)) = extract_codex_message(&entry) else {\n return;\n };\n if role != \"user\" || text.trim().is_empty() {\n return;\n }\n let Some(cleaned) = codex_text::sanitize_codex_query_text(&text) else {\n return;\n };\n let Some(ts) =\n extract_codex_timestamp(&entry).and_then(|value| parse_rfc3339_to_unix(&value))\n else {\n return;\n };\n if ts < since_unix {\n return;\n }\n if first\n .as_ref()\n .map(|(_, current)| ts < *current)\n .unwrap_or(true)\n {\n first = Some((cleaned, ts));\n }\n })?;\n Ok(first)\n}\n\nfn file_modified_unix(path: &Path) -> Option<u64> {\n fs::metadata(path)\n .ok()?\n .modified()\n .ok()?\n .duration_since(UNIX_EPOCH)\n .ok()\n .map(|value| value.as_secs())\n}\n\nfn read_codex_session_completion_snapshot(\n session_file: &Path,\n) -> Result<Option<CodexSessionCompletionSnapshot>> {\n let file_modified_unix = file_modified_unix(session_file).unwrap_or(0);\n let mut snapshot = CodexSessionCompletionSnapshot {\n last_role: None,\n last_user_message: None,\n last_user_at_unix: None,\n last_assistant_message: None,\n last_assistant_at_unix: None,\n file_modified_unix,\n };\n\n for_each_nonempty_jsonl_line(session_file, |line| {\n let entry: CodexEntry = match crate::json_parse::parse_json_line(line) {\n Ok(v) => v,\n Err(_) => return,\n };\n let Some((role, text)) = extract_codex_message(&entry) else {\n return;\n };\n let Some(ts) =\n extract_codex_timestamp(&entry).and_then(|value| parse_rfc3339_to_unix(&value))\n else {\n return;\n };\n\n snapshot.last_role = Some(role.clone());\n match role.as_str() {\n \"user\" => {\n snapshot.last_user_message = Some(text);\n snapshot.last_user_at_unix = Some(ts);\n }\n \"assistant\" => {\n snapshot.last_assistant_message = Some(text);\n snapshot.last_assistant_at_unix = Some(ts);\n }\n _ => {}\n }\n })?;\n\n if snapshot.last_role.is_none() {\n return Ok(None);\n }\n Ok(Some(snapshot))\n}\n\nfn assistant_completion_summary(text: &str) -> Option<String> {\n let cleaned = codex_text::sanitize_codex_memory_rollout_text(text)?;\n let first_line = cleaned\n .lines()\n .map(str::trim)\n .find(|line| !line.is_empty())?;\n let summary = first_line\n .trim_start_matches(|ch: char| matches!(ch, '-' | '*' | ' '))\n .trim();\n if summary.is_empty() {\n return None;\n }\n\n let lower = summary.to_ascii_lowercase();\n if matches!(\n lower.as_str(),\n \"done\"\n | \"done.\"\n | \"completed\"\n | \"completed.\"\n | \"implemented\"\n | \"implemented.\"\n | \"fixed\"\n | \"fixed.\"\n | \"it's in.\"\n | \"it’s in.\"\n | \"all set.\"\n ) {\n return None;\n }\n\n Some(summary.to_string())\n}\n\nfn select_codex_session_completion_summary(\n row: &CodexRecoverRow,\n snapshot: &CodexSessionCompletionSnapshot,\n) -> String {\n snapshot\n .last_assistant_message\n .as_deref()\n .and_then(assistant_completion_summary)\n .or_else(|| {\n snapshot\n .last_user_message\n .as_deref()\n .and_then(codex_text::sanitize_codex_query_text)\n })\n .or_else(|| {\n row.first_user_message\n .as_deref()\n .and_then(codex_text::sanitize_codex_query_text)\n })\n .or_else(|| row.title.as_deref().map(str::trim).map(str::to_string))\n .unwrap_or_else(|| \"completed session turn\".to_string())\n}\n\nfn build_codex_session_completion_event(\n row: &CodexRecoverRow,\n snapshot: &CodexSessionCompletionSnapshot,\n) -> activity_log::ActivityEvent {\n let mut event = activity_log::ActivityEvent::done(\n \"codex.done\",\n truncate_recover_text(&select_codex_session_completion_summary(row, snapshot)),\n );\n event.target_path = Some(row.cwd.clone());\n event.launch_path = Some(row.cwd.clone());\n event.session_id = Some(row.id.clone());\n event.source = Some(\"codex-session-completion\".to_string());\n event.dedupe_key = snapshot\n .last_assistant_at_unix\n .map(|value| format!(\"codex:done:{}:{value}\", row.id));\n event\n}\n\nfn read_codex_turn_patch_changes(\n session_file: &Path,\n since_unix: u64,\n until_unix: u64,\n session_cwd: &str,\n) -> Result<Vec<CodexTurnPatchChange>> {\n let mut changes: Vec<CodexTurnPatchChange> = Vec::new();\n for_each_nonempty_jsonl_line(session_file, |line| {\n let entry: CodexEntry = match crate::json_parse::parse_json_line(line) {\n Ok(value) => value,\n Err(_) => return,\n };\n let Some(ts) =\n extract_codex_timestamp(&entry).and_then(|value| parse_rfc3339_to_unix(&value))\n else {\n return;\n };\n if ts < since_unix || ts > until_unix {\n return;\n }\n\n let Some(payload) = entry.payload.as_ref() else {\n return;\n };\n if entry.entry_type.as_deref() != Some(\"response_item\") {\n return;\n }\n if payload.get(\"type\").and_then(|value| value.as_str()) != Some(\"custom_tool_call\") {\n return;\n }\n if payload.get(\"status\").and_then(|value| value.as_str()) != Some(\"completed\") {\n return;\n }\n if payload.get(\"name\").and_then(|value| value.as_str()) != Some(\"apply_patch\") {\n return;\n }\n let Some(input) = payload.get(\"input\").and_then(|value| value.as_str()) else {\n return;\n };\n\n for change in parse_apply_patch_changes(input, session_cwd) {\n if let Some(existing) = changes.iter_mut().find(|item| item.path == change.path) {\n if !existing.patch.is_empty() && !change.patch.is_empty() {\n existing.patch.push('\\n');\n }\n existing.patch.push_str(&change.patch);\n if existing.action != change.action {\n existing.action = \"update\".to_string();\n }\n } else {\n changes.push(change);\n }\n }\n })?;\n Ok(changes)\n}\n\nfn parse_apply_patch_changes(input: &str, session_cwd: &str) -> Vec<CodexTurnPatchChange> {\n let mut changes = Vec::new();\n let mut current_path: Option<String> = None;\n let mut current_action = String::new();\n let mut current_patch = String::new();\n\n let flush_current = |changes: &mut Vec<CodexTurnPatchChange>,\n current_path: &mut Option<String>,\n current_action: &mut String,\n current_patch: &mut String| {\n let Some(path) = current_path.take() else {\n return;\n };\n changes.push(CodexTurnPatchChange {\n path,\n action: std::mem::take(current_action),\n patch: current_patch.trim().to_string(),\n });\n current_patch.clear();\n };\n\n for line in input.lines() {\n let header = if let Some(path) = line.strip_prefix(\"*** Update File: \") {\n Some((\"update\", path))\n } else if let Some(path) = line.strip_prefix(\"*** Add File: \") {\n Some((\"add\", path))\n } else if let Some(path) = line.strip_prefix(\"*** Delete File: \") {\n Some((\"delete\", path))\n } else {\n None\n };\n\n if let Some((action, path)) = header {\n flush_current(\n &mut changes,\n &mut current_path,\n &mut current_action,\n &mut current_patch,\n );\n current_action = action.to_string();\n current_path = Some(resolve_patch_path(path, session_cwd));\n continue;\n }\n\n if let Some(path) = line.strip_prefix(\"*** Move to: \") {\n current_path = Some(resolve_patch_path(path, session_cwd));\n continue;\n }\n\n if current_path.is_some() {\n current_patch.push_str(line);\n current_patch.push('\\n');\n }\n }\n\n flush_current(\n &mut changes,\n &mut current_path,\n &mut current_action,\n &mut current_patch,\n );\n changes\n}\n\nfn resolve_patch_path(path: &str, session_cwd: &str) -> String {\n let raw = Path::new(path);\n if raw.is_absolute() {\n return raw.display().to_string();\n }\n Path::new(session_cwd).join(raw).display().to_string()\n}\n\nfn fish_fn_path() -> String {\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"config\")\n .join(\"fish\")\n .join(\"fn.fish\")\n .display()\n .to_string()\n}\n\nfn is_fish_fn_path(path: &str) -> bool {\n path.ends_with(\"/config/fish/fn.fish\") || path == fish_fn_path()\n}\n\nfn summarize_fish_fn_change(text: &str) -> Option<String> {\n let normalized = text.to_ascii_lowercase();\n let mut remaps = Vec::new();\n if normalized.contains(\"j is now the fresh codex entrypoint\")\n || normalized.contains(\"j runs f codex open\")\n || normalized.contains(\"__flow_codex open --path\")\n {\n remaps.push(\"j->codex.open\");\n }\n if normalized.contains(\"k is now the current-folder codex continue entrypoint\")\n || normalized.contains(\"k uses f codex connect\")\n || normalized.contains(\"__flow_codex connect --path\")\n {\n remaps.push(\"k->codex.connect\");\n }\n if normalized.contains(\"l is now kit\")\n || normalized.contains(\"kit --continue --no-exit\")\n || normalized.contains(\"exec \\\"$kit_bin\\\" --continue\")\n {\n remaps.push(\"l->kit\");\n }\n if normalized.contains(\"l now delegates to j\")\n || text.contains(\"function L\") && text.contains(\"j $argv\")\n {\n remaps.push(\"L->j\");\n }\n\n if remaps.is_empty() {\n if normalized.contains(\"fn.fish\") {\n return Some(\"updated fn.fish\".to_string());\n }\n return None;\n }\n\n let keep_fallbacks = normalized.contains(\"old k moved to cl\")\n || normalized.contains(\"function cl\")\n || normalized.contains(\"function cf\")\n || text.contains(\"function cF\");\n let mut summary = format!(\"remap {}\", remaps.join(\", \"));\n if keep_fallbacks {\n summary.push_str(\"; keep cl/cf/cF fallbacks\");\n }\n Some(summary)\n}\n\nfn build_fish_fn_changed_event(\n row: &CodexRecoverRow,\n snapshot: &CodexSessionCompletionSnapshot,\n summary: String,\n) -> activity_log::ActivityEvent {\n let mut event = activity_log::ActivityEvent::changed(\"fish.fn\", summary);\n event.target_path = Some(fish_fn_path());\n event.session_id = Some(row.id.clone());\n event.source = Some(\"codex-session-change\".to_string());\n event.dedupe_key = snapshot\n .last_assistant_at_unix\n .map(|value| format!(\"codex:changed:{}:{value}:fish.fn\", row.id));\n event\n}\n\nfn changed_file_label(path: &str) -> String {\n let path_ref = Path::new(path);\n if is_fish_fn_path(path) {\n return \"fn.fish\".to_string();\n }\n path_ref\n .file_name()\n .and_then(|value| value.to_str())\n .map(|value| value.to_string())\n .unwrap_or_else(|| path.to_string())\n}\n\nfn summarize_generic_changed_files(changes: &[CodexTurnPatchChange]) -> String {\n let labels = changes\n .iter()\n .map(|change| changed_file_label(&change.path))\n .collect::<Vec<_>>();\n match labels.len() {\n 0 => \"updated files\".to_string(),\n 1 => format!(\"updated {}\", labels[0]),\n 2 => format!(\"updated {}, {}\", labels[0], labels[1]),\n _ => format!(\n \"updated {}, {} + {} more\",\n labels[0],\n labels[1],\n labels.len() - 2\n ),\n }\n}\n\nfn build_codex_session_changed_events(\n row: &CodexRecoverRow,\n snapshot: &CodexSessionCompletionSnapshot,\n session_file: &Path,\n) -> Result<Vec<activity_log::ActivityEvent>> {\n let mut events = Vec::new();\n let Some(last_assistant_at_unix) = snapshot.last_assistant_at_unix else {\n return Ok(events);\n };\n\n let patch_changes = snapshot\n .last_user_at_unix\n .map(|last_user_at_unix| {\n read_codex_turn_patch_changes(\n session_file,\n last_user_at_unix,\n last_assistant_at_unix,\n &row.cwd,\n )\n })\n .transpose()?\n .unwrap_or_default();\n\n let fish_summary = patch_changes\n .iter()\n .find(|change| is_fish_fn_path(&change.path))\n .and_then(|change| summarize_fish_fn_change(&change.patch))\n .or_else(|| {\n snapshot\n .last_assistant_message\n .as_deref()\n .and_then(summarize_fish_fn_change)\n })\n .or_else(|| {\n snapshot\n .last_user_message\n .as_deref()\n .and_then(summarize_fish_fn_change)\n });\n\n let mut remaining_changes = Vec::new();\n for change in patch_changes {\n if is_fish_fn_path(&change.path) {\n continue;\n }\n remaining_changes.push(change);\n }\n\n if let Some(summary) = fish_summary {\n events.push(build_fish_fn_changed_event(row, snapshot, summary));\n }\n\n if !remaining_changes.is_empty() {\n let mut event = activity_log::ActivityEvent::changed(\n \"files.changed\",\n summarize_generic_changed_files(&remaining_changes),\n );\n event.target_path = Some(row.cwd.clone());\n event.launch_path = Some(row.cwd.clone());\n event.session_id = Some(row.id.clone());\n event.source = Some(\"codex-session-change\".to_string());\n event.dedupe_key = Some(format!(\n \"codex:changed:{}:{}:aggregate\",\n row.id, last_assistant_at_unix\n ));\n events.push(event);\n }\n\n Ok(events)\n}\n\nfn hydrate_codex_quick_launch(\n launch: &CodexQuickLaunchEvent,\n) -> Result<Option<CodexQuickLaunchHydration>> {\n let target_path = PathBuf::from(&launch.cwd);\n if !target_path.exists() {\n return Ok(None);\n }\n\n let mut candidates = read_recent_codex_threads_local(&target_path, true, 8, None)?;\n if candidates.is_empty() {\n candidates = read_recent_codex_threads_local(&target_path, false, 8, None)?;\n }\n if candidates.is_empty() {\n return Ok(None);\n }\n\n let since_unix = launch.recorded_at_unix.saturating_sub(1);\n let mut best: Option<(u64, String, String)> = None;\n for candidate in candidates {\n let Some(session_file) = find_codex_session_file(&candidate.id) else {\n continue;\n };\n let Some((query, prompt_recorded_at_unix)) =\n read_codex_first_user_message_since(&session_file, since_unix)?\n else {\n continue;\n };\n let replace = best\n .as_ref()\n .map(|(best_ts, _, _)| prompt_recorded_at_unix < *best_ts)\n .unwrap_or(true);\n if replace {\n best = Some((prompt_recorded_at_unix, candidate.id, query));\n }\n }\n\n let Some((prompt_recorded_at_unix, session_id, query)) = best else {\n return Ok(None);\n };\n\n Ok(Some(CodexQuickLaunchHydration {\n version: 1,\n launch_id: launch.launch_id.clone(),\n hydrated_at_unix: SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0),\n target_path: target_path.display().to_string(),\n session_id,\n query,\n prompt_recorded_at_unix,\n }))\n}\n\nfn reconcile_pending_codex_quick_launches(limit: usize) -> Result<usize> {\n let launches = load_recent_codex_quick_launches(limit)?;\n if launches.is_empty() {\n return Ok(0);\n }\n\n let hydrated_ids = load_hydrated_codex_quick_launch_ids()?;\n let now = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0);\n let mut reconciled = 0usize;\n\n for launch in launches {\n if hydrated_ids.contains(&launch.launch_id) {\n continue;\n }\n if now.saturating_sub(launch.recorded_at_unix) < 2 {\n continue;\n }\n let Some(hydration) = hydrate_codex_quick_launch(&launch)? else {\n continue;\n };\n\n let event = codex_skill_eval::CodexSkillEvalEvent {\n version: 1,\n recorded_at_unix: hydration.prompt_recorded_at_unix,\n mode: \"quick-launch\".to_string(),\n action: if launch.mode == \"new\" {\n \"new\".to_string()\n } else {\n \"resume\".to_string()\n },\n route: \"quick-launch-hydrated\".to_string(),\n target_path: hydration.target_path.clone(),\n launch_path: hydration.target_path.clone(),\n query: hydration.query.clone(),\n session_id: Some(hydration.session_id.clone()),\n runtime_token: None,\n runtime_skills: Vec::new(),\n prompt_context_budget_chars: 0,\n prompt_chars: hydration.query.chars().count(),\n injected_context_chars: 0,\n reference_count: 0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n workflow_kind: None,\n service_name: None,\n };\n let _ = codex_skill_eval::log_event(&event);\n let _ = log_codex_quick_launch_hydration(&hydration);\n let mut activity_event =\n activity_log::ActivityEvent::done(\"codex.quick-launch\", hydration.query.clone());\n activity_event.route = Some(format!(\"{}-hydrated\", launch.mode));\n activity_event.target_path = Some(hydration.target_path.clone());\n activity_event.launch_path = Some(hydration.target_path.clone());\n activity_event.session_id = Some(hydration.session_id.clone());\n activity_event.source = Some(\"codex-quick-launch\".to_string());\n activity_event.dedupe_key = Some(format!(\"codex:quick-launch:{}\", launch.launch_id));\n let _ = activity_log::append_daily_event(activity_event);\n reconciled += 1;\n }\n\n Ok(reconciled)\n}\n\npub(crate) fn reconcile_codex_session_completions(limit: usize) -> Result<usize> {\n if limit == 0 {\n return Ok(0);\n }\n\n let rows = read_recent_codex_threads_global_local(limit)?;\n if rows.is_empty() {\n return Ok(0);\n }\n\n let now = unix_now_secs();\n let idle_secs = codex_session_completion_idle_secs();\n let _ = prune_codex_session_completion_markers(now);\n let mut reconciled = 0usize;\n\n for row in rows {\n let Some(session_file) = find_codex_session_file(&row.id) else {\n continue;\n };\n let Some(snapshot) = read_codex_session_completion_snapshot(&session_file)? else {\n continue;\n };\n if snapshot.last_role.as_deref() != Some(\"assistant\") {\n continue;\n }\n let Some(last_assistant_at_unix) = snapshot.last_assistant_at_unix else {\n continue;\n };\n let idle_anchor = snapshot.file_modified_unix.max(last_assistant_at_unix);\n if now.saturating_sub(idle_anchor) < idle_secs {\n continue;\n }\n if !claim_codex_session_completion_marker(&row.id, last_assistant_at_unix)? {\n continue;\n }\n\n let _ =\n activity_log::append_daily_event(build_codex_session_completion_event(&row, &snapshot));\n for event in build_codex_session_changed_events(&row, &snapshot, &session_file)? {\n let _ = activity_log::append_daily_event(event);\n }\n reconciled += 1;\n }\n\n Ok(reconciled)\n}\n\npub(crate) fn run_codex_background_maintenance() -> Result<(usize, usize)> {\n let hydrated = reconcile_pending_codex_quick_launches(48)?;\n let completed = reconcile_codex_session_completions(codex_session_completion_scan_limit())?;\n Ok((hydrated, completed))\n}\n\npub(crate) fn maybe_run_codex_telemetry_export(limit: usize) -> Result<usize> {\n codex_telemetry::maybe_flush(limit)\n}\n\nfn codex_touch_launch(mode: String, cwd: Option<String>, provider: Provider) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"touch-launch is only supported for Codex sessions; use `f codex touch-launch`\");\n }\n\n let cwd_path = resolve_session_target_path(cwd.as_deref())?;\n let daemon = if codexd::ensure_running().is_ok() {\n \"running\"\n } else {\n \"unavailable\"\n };\n let recorded_at_unix = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0);\n let mut hasher = std::collections::hash_map::DefaultHasher::new();\n mode.hash(&mut hasher);\n cwd_path.hash(&mut hasher);\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_nanos())\n .unwrap_or(0)\n .hash(&mut hasher);\n let event = CodexQuickLaunchEvent {\n version: 1,\n launch_id: format!(\"{:016x}\", hasher.finish()),\n recorded_at_unix,\n mode,\n cwd: cwd_path.display().to_string(),\n daemon: daemon.to_string(),\n };\n let _ = log_codex_quick_launch_event(&event);\n let _ = run_codex_background_maintenance();\n Ok(())\n}\n\nfn codex_daemon_command(action: Option<CodexDaemonAction>, provider: Provider) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"daemon is only supported for Codex sessions; use `f codex daemon ...`\");\n }\n\n match action.unwrap_or(CodexDaemonAction::Status) {\n CodexDaemonAction::Start => codexd::start(),\n CodexDaemonAction::Stop => codexd::stop(),\n CodexDaemonAction::Restart => {\n codexd::stop().ok();\n std::thread::sleep(Duration::from_millis(300));\n codexd::start()\n }\n CodexDaemonAction::Status => codexd::status(),\n CodexDaemonAction::Serve { socket } => codexd::serve(socket.as_deref()),\n CodexDaemonAction::Ping => codexd::ping(),\n }\n}\n\nfn codex_memory_command(action: Option<CodexMemoryAction>, provider: Provider) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"memory is only supported for Codex sessions; use `f codex memory ...`\");\n }\n\n match action.unwrap_or(CodexMemoryAction::Status { json: false }) {\n CodexMemoryAction::Status { json } => {\n let stats = codex_memory::stats()?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&stats)\n .context(\"failed to encode codex memory status JSON\")?\n );\n } else {\n println!(\"# codex memory\");\n println!(\"root: {}\", stats.root_dir);\n println!(\"db_path: {}\", stats.db_path);\n println!(\"events_indexed: {}\", stats.total_events);\n println!(\"facts_indexed: {}\", stats.total_facts);\n println!(\"skill_eval_events: {}\", stats.skill_eval_events);\n println!(\"skill_eval_outcomes: {}\", stats.skill_eval_outcomes);\n if let Some(latest) = stats.latest_recorded_at_unix {\n println!(\"latest_recorded_at_unix: {}\", latest);\n }\n }\n Ok(())\n }\n CodexMemoryAction::Sync { limit, json } => {\n let _ = reconcile_pending_codex_quick_launches(limit.max(64));\n let summary = codex_memory::sync_from_skill_eval_logs(limit)?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&summary)\n .context(\"failed to encode codex memory sync JSON\")?\n );\n } else {\n println!(\"# codex memory sync\");\n println!(\"total_considered: {}\", summary.total_considered);\n println!(\"inserted: {}\", summary.inserted);\n println!(\"skipped: {}\", summary.skipped);\n }\n Ok(())\n }\n CodexMemoryAction::Query {\n path,\n limit,\n json,\n query,\n } => {\n let query_text = query.join(\" \").trim().to_string();\n if query_text.is_empty() {\n bail!(\"codex memory query requires a search string\");\n }\n let target_path = resolve_session_target_path(path.as_deref())?;\n let result = codex_memory::query_repo_facts(&target_path, &query_text, limit)?\n .ok_or_else(|| anyhow::anyhow!(\"no codex memory facts matched {:?}\", query_text))?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&result)\n .context(\"failed to encode codex memory query JSON\")?\n );\n } else {\n println!(\"{}\", result.rendered);\n }\n Ok(())\n }\n CodexMemoryAction::Recent { path, limit, json } => {\n let _ = reconcile_pending_codex_quick_launches(limit.max(64));\n let _ = codex_memory::sync_from_skill_eval_logs(limit.max(200));\n let target_path = path\n .as_deref()\n .map(|value| resolve_session_target_path(Some(value)))\n .transpose()?;\n let rows = codex_memory::recent(target_path.as_deref(), limit)?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&rows)\n .context(\"failed to encode codex memory recent JSON\")?\n );\n } else if rows.is_empty() {\n println!(\"No codex memory rows recorded.\");\n } else {\n println!(\"# codex memory recent\");\n for row in rows {\n let subject = row\n .query\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n .map(|value| truncate_message(value, 96))\n .or_else(|| row.route.clone())\n .unwrap_or_else(|| \"(no query)\".to_string());\n println!(\n \"- {} | {} | {}\",\n row.event_kind, row.recorded_at_unix, subject\n );\n }\n }\n Ok(())\n }\n }\n}\n\nfn codex_telemetry_command(\n action: Option<CodexTelemetryAction>,\n provider: Provider,\n) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"telemetry is only supported for Codex sessions; use `f codex telemetry ...`\");\n }\n\n match action.unwrap_or(CodexTelemetryAction::Status { json: false }) {\n CodexTelemetryAction::Status { json } => {\n let status = codex_telemetry::status()?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&status)\n .context(\"failed to encode codex telemetry status JSON\")?\n );\n } else {\n println!(\"# codex telemetry\");\n println!(\"enabled: {}\", status.enabled);\n println!(\"configured_targets: {}\", status.configured_targets);\n println!(\"service_name: {}\", status.service_name);\n println!(\"scope_name: {}\", status.scope_name);\n println!(\"state_path: {}\", status.state_path);\n println!(\"events_path: {}\", status.events_path);\n println!(\"outcomes_path: {}\", status.outcomes_path);\n println!(\"events_offset: {}\", status.events_offset);\n println!(\"outcomes_offset: {}\", status.outcomes_offset);\n println!(\"events_exported: {}\", status.events_exported);\n println!(\"outcomes_exported: {}\", status.outcomes_exported);\n if let Some(last) = status.last_exported_at_unix {\n println!(\"last_exported_at_unix: {}\", last);\n }\n }\n Ok(())\n }\n CodexTelemetryAction::Flush { limit, json } => {\n let summary = codex_telemetry::flush(limit)?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&summary)\n .context(\"failed to encode codex telemetry flush JSON\")?\n );\n } else {\n println!(\"# codex telemetry flush\");\n println!(\"enabled: {}\", summary.enabled);\n println!(\"configured_targets: {}\", summary.configured_targets);\n println!(\"events_seen: {}\", summary.events_seen);\n println!(\"outcomes_seen: {}\", summary.outcomes_seen);\n println!(\"events_exported: {}\", summary.events_exported);\n println!(\"outcomes_exported: {}\", summary.outcomes_exported);\n println!(\"state_path: {}\", summary.state_path);\n if let Some(last) = summary.last_exported_at_unix {\n println!(\"last_exported_at_unix: {}\", last);\n }\n }\n Ok(())\n }\n }\n}\n\nfn codex_trace_command(action: Option<CodexTraceAction>, provider: Provider) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"trace is only supported for Codex sessions; use `f codex trace ...`\");\n }\n\n match action.unwrap_or(CodexTraceAction::CurrentSession {\n flush: true,\n json: false,\n }) {\n CodexTraceAction::Status { json } => {\n let status = codex_telemetry::trace_status()?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&status)\n .context(\"failed to encode codex trace status JSON\")?\n );\n } else {\n println!(\"# codex trace\");\n println!(\"enabled: {}\", status.enabled);\n println!(\"endpoint: {}\", status.endpoint);\n println!(\"token_source: {}\", status.token_source);\n println!(\"tools_list_ok: {}\", status.tools_list_ok);\n println!(\"tools_count: {}\", status.tools_count);\n println!(\"read_probe_ok: {}\", status.read_probe_ok);\n if let Some(error) = status.read_probe_error.as_deref() {\n println!(\"read_probe_error: {}\", error);\n }\n }\n Ok(())\n }\n CodexTraceAction::CurrentSession { flush, json } => {\n let current = codex_telemetry::inspect_current_session_trace(flush)?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(¤t)\n .context(\"failed to encode current codex trace JSON\")?\n );\n } else {\n println!(\"# codex current-session trace\");\n println!(\"trace_id: {}\", current.trace_id);\n if let Some(span_id) = current.span_id.as_deref() {\n println!(\"span_id: {}\", span_id);\n }\n if let Some(parent_span_id) = current.parent_span_id.as_deref() {\n println!(\"parent_span_id: {}\", parent_span_id);\n }\n if let Some(workflow_kind) = current.workflow_kind.as_deref() {\n println!(\"workflow_kind: {}\", workflow_kind);\n }\n if let Some(service_name) = current.service_name.as_deref() {\n println!(\"service_name: {}\", service_name);\n }\n println!(\"flushed: {}\", current.flushed);\n println!(\"endpoint: {}\", current.endpoint);\n println!(\"token_source: {}\", current.token_source);\n if let Some(error) = current.read_error.as_deref() {\n println!(\"read_error: {}\", error);\n }\n if let Some(result) = current.result.as_ref() {\n println!(\n \"{}\",\n serde_json::to_string_pretty(result)\n .context(\"failed to encode current codex trace result\")?\n );\n }\n }\n Ok(())\n }\n CodexTraceAction::Inspect {\n trace_id,\n flush,\n json,\n } => {\n let inspected = codex_telemetry::inspect_trace(&trace_id, flush)?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&inspected)\n .context(\"failed to encode codex trace inspect JSON\")?\n );\n } else {\n println!(\"# codex trace inspect\");\n println!(\"trace_id: {}\", inspected.trace_id);\n println!(\"flushed: {}\", inspected.flushed);\n println!(\"endpoint: {}\", inspected.endpoint);\n println!(\"token_source: {}\", inspected.token_source);\n if let Some(error) = inspected.read_error.as_deref() {\n println!(\"read_error: {}\", error);\n }\n if let Some(result) = inspected.result.as_ref() {\n println!(\n \"{}\",\n serde_json::to_string_pretty(result)\n .context(\"failed to encode codex trace inspect result\")?\n );\n }\n }\n Ok(())\n }\n }\n}\n\nfn codex_skill_eval_command(\n action: Option<CodexSkillEvalAction>,\n provider: Provider,\n) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"skill-eval is only supported for Codex sessions; use `f codex skill-eval ...`\");\n }\n\n match action.unwrap_or(CodexSkillEvalAction::Show {\n path: None,\n json: false,\n }) {\n CodexSkillEvalAction::Run { path, limit, json } => {\n let _ = reconcile_pending_codex_quick_launches(limit.max(48));\n let target_path = resolve_session_target_path(path.as_deref())?;\n let scorecard = codex_skill_eval::rebuild_scorecard(&target_path, limit)?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&scorecard)\n .context(\"failed to encode codex skill-eval JSON\")?\n );\n } else {\n println!(\"{}\", codex_skill_eval::format_scorecard(&scorecard));\n }\n Ok(())\n }\n CodexSkillEvalAction::Show { path, json } => {\n let _ = reconcile_pending_codex_quick_launches(64);\n let target_path = resolve_session_target_path(path.as_deref())?;\n let scorecard = codex_skill_eval::load_scorecard(&target_path)?\n .unwrap_or(codex_skill_eval::rebuild_scorecard(&target_path, 200)?);\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&scorecard)\n .context(\"failed to encode codex skill-eval JSON\")?\n );\n } else {\n println!(\"{}\", codex_skill_eval::format_scorecard(&scorecard));\n }\n Ok(())\n }\n CodexSkillEvalAction::Events { path, limit, json } => {\n let _ = reconcile_pending_codex_quick_launches(limit.max(48));\n let target_path = path\n .as_deref()\n .map(|value| resolve_session_target_path(Some(value)))\n .transpose()?;\n let events = codex_skill_eval::load_events(target_path.as_deref(), limit)?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&events)\n .context(\"failed to encode codex skill-eval events JSON\")?\n );\n } else if events.is_empty() {\n println!(\"No codex skill-eval events recorded.\");\n } else {\n println!(\"# codex skill-eval events\");\n for event in events {\n println!(\n \"- {} | {} | {} | skills {}\",\n event.mode,\n event.route,\n event.target_path,\n if event.runtime_skills.is_empty() {\n \"(none)\".to_string()\n } else {\n event.runtime_skills.join(\", \")\n }\n );\n }\n }\n Ok(())\n }\n CodexSkillEvalAction::Cron {\n limit,\n max_targets,\n within_hours,\n json,\n } => {\n let reconciled = reconcile_pending_codex_quick_launches(limit.max(64))?;\n let memory_sync = codex_memory::sync_from_skill_eval_logs(limit.max(200))?;\n let targets = codex_skill_eval::recent_targets(limit, max_targets, within_hours)?;\n let mut capsule_sync_count = 0usize;\n let mut scorecards = Vec::new();\n for target in targets {\n if codex_memory::sync_repo_capsule_for_path(&target).is_ok() {\n capsule_sync_count += 1;\n }\n scorecards.push(codex_skill_eval::rebuild_scorecard(&target, limit)?);\n }\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&json!({\n \"reconciledQuickLaunches\": reconciled,\n \"memorySync\": memory_sync,\n \"capsulesSynced\": capsule_sync_count,\n \"scorecards\": scorecards,\n }))\n .context(\"failed to encode codex skill-eval cron JSON\")?\n );\n } else if scorecards.is_empty() {\n println!(\n \"No recent Codex skill-eval targets found. Reconciled {} fast launch(es), indexed {} memory event(s), synced {} repo capsule(s).\",\n reconciled, memory_sync.inserted, capsule_sync_count\n );\n } else {\n println!(\"# codex skill-eval cron\");\n println!(\"reconciled fast launches: {}\", reconciled);\n println!(\"memory inserted: {}\", memory_sync.inserted);\n println!(\"repo capsules synced: {}\", capsule_sync_count);\n for scorecard in scorecards {\n let top = scorecard\n .skills\n .first()\n .map(|skill| format!(\"{} ({:.2})\", skill.name, skill.score))\n .unwrap_or_else(|| \"none\".to_string());\n println!(\n \"- {} | samples {} | top {}\",\n scorecard.target_path, scorecard.samples, top\n );\n }\n }\n Ok(())\n }\n }\n}\n\nfn codex_skill_source_command(\n action: Option<CodexSkillSourceAction>,\n provider: Provider,\n) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"skill-source is only supported for Codex sessions; use `f codex skill-source ...`\");\n }\n\n match action.unwrap_or(CodexSkillSourceAction::List {\n path: None,\n json: false,\n }) {\n CodexSkillSourceAction::List { path, json } => {\n let target_path = resolve_session_target_path(path.as_deref())?;\n let codex_cfg = load_codex_config_for_path(&target_path);\n let skills = codex_runtime::discover_external_skills(&target_path, &codex_cfg)?;\n if json {\n println!(\n \"{}\",\n serde_json::to_string_pretty(&skills)\n .context(\"failed to encode codex skill-source JSON\")?\n );\n } else {\n println!(\"{}\", codex_runtime::format_external_skills(&skills));\n }\n Ok(())\n }\n CodexSkillSourceAction::Sync {\n path,\n skills,\n force,\n } => {\n let target_path = resolve_session_target_path(path.as_deref())?;\n let codex_cfg = load_codex_config_for_path(&target_path);\n let installed =\n codex_runtime::sync_external_skills(&target_path, &codex_cfg, &skills, force)?;\n println!(\n \"Synced {} external Codex skill(s) into ~/.codex/skills.\",\n installed\n );\n Ok(())\n }\n }\n}\n\nfn codex_runtime_command(action: Option<CodexRuntimeAction>, provider: Provider) -> Result<()> {\n if provider != Provider::Codex {\n bail!(\"runtime helpers are only supported for Codex sessions; use `f codex runtime ...`\");\n }\n\n match action.unwrap_or(CodexRuntimeAction::Show) {\n CodexRuntimeAction::Show => {\n let states = codex_runtime::load_runtime_states()?;\n println!(\"{}\", codex_runtime::format_runtime_states(&states));\n }\n CodexRuntimeAction::Clear => {\n let removed = codex_runtime::clear_runtime_states()?;\n println!(\n \"Cleared {} Flow-managed Codex runtime state file(s).\",\n removed\n );\n }\n CodexRuntimeAction::WritePlan {\n title,\n stem,\n dir,\n source_session,\n } => {\n let path = codex_runtime::write_plan_from_stdin(\n title.as_deref(),\n stem.as_deref(),\n dir.as_deref(),\n source_session.as_deref(),\n )?;\n println!(\"{}\", path.display());\n }\n }\n\n Ok(())\n}\n\nfn normalize_codex_resolve_args(query: Vec<String>, json_output: bool) -> (Vec<String>, bool) {\n if json_output {\n return (query, true);\n }\n\n let mut normalized = query;\n let mut resolved_json = false;\n while matches!(normalized.last().map(String::as_str), Some(\"--json\")) {\n normalized.pop();\n resolved_json = true;\n }\n\n (normalized, resolved_json)\n}\n\nfn build_codex_open_plan(\n path: Option<String>,\n query: Vec<String>,\n exact_cwd: bool,\n) -> Result<CodexOpenPlan> {\n let target_path = resolve_session_target_path(path.as_deref())?;\n let query_text = normalize_recover_query(&query);\n let codex_cfg = load_codex_config_for_path(&target_path);\n let auto_resolve_references = codex_cfg.auto_resolve_references.unwrap_or(true);\n let max_resolved_references = effective_max_resolved_references(&codex_cfg);\n let runtime_skills_enabled =\n codex_cfg.runtime_skills.unwrap_or(false) && codex_runtime_transport_enabled(&target_path);\n let default_prompt_budget = effective_prompt_context_budget_chars(&codex_cfg, false);\n\n let Some(query_text) = query_text else {\n let prompt = None;\n return Ok(finalize_codex_open_plan(CodexOpenPlan {\n action: \"new\".to_string(),\n route: \"new-empty\".to_string(),\n reason: \"no query provided\".to_string(),\n target_path: target_path.display().to_string(),\n launch_path: target_path.display().to_string(),\n query: None,\n session_id: None,\n prompt,\n references: Vec::new(),\n runtime_state_path: None,\n runtime_skills: Vec::new(),\n prompt_context_budget_chars: default_prompt_budget,\n max_resolved_references,\n prompt_chars: 0,\n injected_context_chars: 0,\n trace: None,\n }));\n };\n\n let normalized_query = query_text.to_ascii_lowercase();\n\n if let Some(request) = extract_codex_session_reference_request(&query_text, &normalized_query) {\n let mut references = Vec::new();\n for session_hint in &request.session_hints {\n let reference = resolve_builtin_codex_session_reference(session_hint, request.count)?;\n if !references\n .iter()\n .any(|existing: &CodexResolvedReference| existing.matched == reference.matched)\n {\n references.push(reference);\n }\n }\n if auto_resolve_references {\n let extra_references = resolve_codex_references(\n &target_path,\n &request.user_request,\n &codex_cfg.reference_resolvers,\n )?;\n for reference in extra_references {\n if !references\n .iter()\n .any(|existing| existing.matched == reference.matched)\n {\n references.push(reference);\n }\n }\n }\n let runtime = codex_runtime::prepare_runtime_activation(\n &target_path,\n &request.user_request,\n runtime_skills_enabled,\n &codex_cfg,\n )?;\n let prompt_budget = effective_prompt_context_budget_chars(&codex_cfg, true);\n let prompt = build_codex_prompt_with_runtime(\n &request.user_request,\n &references,\n runtime.as_ref(),\n max_resolved_references,\n prompt_budget,\n );\n let route = if request.session_hints.len() > 1 {\n \"multi-session-reference-new\"\n } else {\n \"session-reference-new\"\n };\n let reason = if request.session_hints.len() > 1 {\n format!(\n \"start a new session with {} resolved Codex session contexts\",\n request.session_hints.len()\n )\n } else {\n \"start a new session with resolved Codex session context\".to_string()\n };\n return Ok(finalize_codex_open_plan(CodexOpenPlan {\n action: \"new\".to_string(),\n route: route.to_string(),\n reason,\n target_path: target_path.display().to_string(),\n launch_path: target_path.display().to_string(),\n query: Some(query_text),\n session_id: None,\n prompt,\n references,\n runtime_state_path: runtime\n .as_ref()\n .map(|value| value.state_path.display().to_string()),\n runtime_skills: runtime_skill_names(runtime.as_ref()),\n prompt_context_budget_chars: prompt_budget,\n max_resolved_references,\n prompt_chars: 0,\n injected_context_chars: 0,\n trace: None,\n }));\n }\n\n if let Some(plan) = build_codex_commit_workflow_plan(\n &target_path,\n &query_text,\n &normalized_query,\n runtime_skills_enabled,\n auto_resolve_references,\n max_resolved_references,\n default_prompt_budget,\n &codex_cfg,\n )? {\n return Ok(plan);\n }\n\n if let Some(plan) = build_codex_sync_workflow_plan(\n &target_path,\n &query_text,\n &normalized_query,\n max_resolved_references,\n default_prompt_budget,\n )? {\n return Ok(plan);\n }\n\n if looks_like_recovery_prompt(&normalized_query) {\n return build_codex_recovery_plan(\n &target_path,\n exact_cwd,\n &query_text,\n runtime_skills_enabled,\n default_prompt_budget,\n max_resolved_references,\n );\n }\n\n if let Some((session, reason)) =\n resolve_codex_session_lookup(&target_path, exact_cwd, &query_text, &normalized_query)?\n {\n return Ok(finalize_codex_open_plan(CodexOpenPlan {\n action: \"resume\".to_string(),\n route: \"resume-existing\".to_string(),\n reason,\n target_path: target_path.display().to_string(),\n launch_path: session.cwd.clone(),\n query: Some(query_text),\n session_id: Some(session.id),\n prompt: None,\n references: Vec::new(),\n runtime_state_path: None,\n runtime_skills: Vec::new(),\n prompt_context_budget_chars: default_prompt_budget,\n max_resolved_references,\n prompt_chars: 0,\n injected_context_chars: 0,\n trace: None,\n }));\n }\n\n if looks_like_session_lookup_query(&normalized_query) {\n bail!(\n \"{}\",\n build_codex_open_no_match_message(&target_path, exact_cwd, &query_text)?\n );\n }\n\n let references = if auto_resolve_references {\n resolve_codex_references(&target_path, &query_text, &codex_cfg.reference_resolvers)?\n } else {\n Vec::new()\n };\n let runtime = codex_runtime::prepare_runtime_activation(\n &target_path,\n &query_text,\n runtime_skills_enabled,\n &codex_cfg,\n )?;\n let prompt_budget =\n effective_prompt_context_budget_chars(&codex_cfg, has_session_reference(&references));\n let prompt = build_codex_prompt_with_runtime(\n &query_text,\n &references,\n runtime.as_ref(),\n max_resolved_references,\n prompt_budget,\n );\n\n Ok(finalize_codex_open_plan(CodexOpenPlan {\n action: \"new\".to_string(),\n route: if references.is_empty() {\n \"new-plain\".to_string()\n } else {\n \"new-with-context\".to_string()\n },\n reason: if references.is_empty() {\n \"start a new session from the current query\".to_string()\n } else {\n \"start a new session with compact resolved context\".to_string()\n },\n target_path: target_path.display().to_string(),\n launch_path: target_path.display().to_string(),\n query: Some(query_text),\n session_id: None,\n prompt,\n references,\n runtime_state_path: runtime\n .as_ref()\n .map(|value| value.state_path.display().to_string()),\n runtime_skills: runtime_skill_names(runtime.as_ref()),\n prompt_context_budget_chars: prompt_budget,\n max_resolved_references,\n prompt_chars: 0,\n injected_context_chars: 0,\n trace: None,\n }))\n}\n\nfn build_codex_commit_workflow_plan(\n target_path: &Path,\n query_text: &str,\n normalized_query: &str,\n runtime_skills_enabled: bool,\n auto_resolve_references: bool,\n max_resolved_references: usize,\n default_prompt_budget: usize,\n codex_cfg: &config::CodexConfig,\n) -> Result<Option<CodexOpenPlan>> {\n if !looks_like_commit_workflow_query(normalized_query) {\n return Ok(None);\n }\n\n let Some(repo_root) = detect_git_root(target_path) else {\n return Ok(None);\n };\n\n let mut references = vec![resolve_builtin_commit_workflow_reference(&repo_root)?];\n if auto_resolve_references {\n for reference in resolve_codex_references(&repo_root, query_text, &codex_cfg.reference_resolvers)? {\n if !references\n .iter()\n .any(|existing| existing.matched == reference.matched)\n {\n references.push(reference);\n }\n }\n }\n\n let runtime = codex_runtime::prepare_runtime_activation(\n &repo_root,\n query_text,\n runtime_skills_enabled,\n codex_cfg,\n )?;\n let prompt_budget =\n effective_prompt_context_budget_chars(codex_cfg, has_session_reference(&references))\n .max(2200);\n let prompt = build_codex_prompt_with_runtime(\n query_text,\n &references,\n runtime.as_ref(),\n max_resolved_references,\n prompt_budget,\n );\n\n Ok(Some(finalize_codex_open_plan(CodexOpenPlan {\n action: \"new\".to_string(),\n route: \"commit-workflow-new\".to_string(),\n reason: \"start a new session with enforced deep-review commit workflow\".to_string(),\n target_path: repo_root.display().to_string(),\n launch_path: repo_root.display().to_string(),\n query: Some(query_text.to_string()),\n session_id: None,\n prompt,\n references,\n runtime_state_path: runtime\n .as_ref()\n .map(|value| value.state_path.display().to_string()),\n runtime_skills: runtime_skill_names(runtime.as_ref()),\n prompt_context_budget_chars: prompt_budget.max(default_prompt_budget),\n max_resolved_references,\n prompt_chars: 0,\n injected_context_chars: 0,\n trace: None,\n })))\n}\n\nfn build_codex_sync_workflow_plan(\n target_path: &Path,\n query_text: &str,\n normalized_query: &str,\n max_resolved_references: usize,\n default_prompt_budget: usize,\n) -> Result<Option<CodexOpenPlan>> {\n if !looks_like_prom_sync_workflow_query(normalized_query) {\n return Ok(None);\n }\n\n let Some(repo_root) = detect_git_root(target_path) else {\n return Ok(None);\n };\n if !is_prom_workspace_path(&repo_root) {\n return Ok(None);\n }\n\n let references = vec![resolve_builtin_sync_workflow_reference(&repo_root)?];\n let prompt_budget = default_prompt_budget.max(1600);\n let prompt = build_codex_prompt(query_text, &references, max_resolved_references, prompt_budget);\n\n Ok(Some(finalize_codex_open_plan(CodexOpenPlan {\n action: \"new\".to_string(),\n route: \"sync-workflow-new\".to_string(),\n reason: \"start a new session with enforced guarded sync workflow\".to_string(),\n target_path: repo_root.display().to_string(),\n launch_path: repo_root.display().to_string(),\n query: Some(query_text.to_string()),\n session_id: None,\n prompt,\n references,\n runtime_state_path: None,\n runtime_skills: Vec::new(),\n prompt_context_budget_chars: prompt_budget,\n max_resolved_references,\n prompt_chars: 0,\n injected_context_chars: 0,\n trace: None,\n })))\n}\n\nfn execute_codex_open_plan(plan: &CodexOpenPlan) -> Result<()> {\n let launch_path = PathBuf::from(&plan.launch_path);\n match plan.action.as_str() {\n \"resume\" => {\n let session_id = plan\n .session_id\n .as_deref()\n .ok_or_else(|| anyhow::anyhow!(\"missing session id for resume plan\"))?;\n println!(\n \"Opening Codex session {} in {}...\",\n truncate_recover_id(session_id),\n launch_path.display()\n );\n if launch_session_for_target(\n session_id,\n Provider::Codex,\n plan.prompt.as_deref(),\n Some(&launch_path),\n plan.runtime_state_path.as_deref(),\n plan.trace.as_ref(),\n )? {\n Ok(())\n } else {\n bail!(\"failed to resume codex session {}\", session_id);\n }\n }\n \"new\" | \"recover-new\" => {\n maybe_open_cursor_for_pr_feedback_check(plan);\n new_session_for_target(\n Provider::Codex,\n plan.prompt.as_deref(),\n Some(&launch_path),\n plan.runtime_state_path.as_deref(),\n plan.trace.as_ref(),\n )\n }\n other => bail!(\"unsupported codex open action: {}\", other),\n }\n}\n\nfn maybe_open_cursor_for_pr_feedback_check(plan: &CodexOpenPlan) {\n let Some(query) = plan\n .query\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n else {\n return;\n };\n if !looks_like_pr_feedback_query(query) {\n return;\n }\n if env_flag_is_false(\"FLOW_OPEN_CURSOR_ON_PR_CHECK\") {\n return;\n }\n let Some(handoff) = plan\n .references\n .iter()\n .find(|reference| reference.name == \"pr-feedback\")\n .and_then(|reference| parse_pr_feedback_cursor_handoff(&reference.output))\n else {\n return;\n };\n let _ = open_cursor_review_handoff(&handoff);\n}\n\nfn env_flag_is_false(name: &str) -> bool {\n let Ok(value) = env::var(name) else {\n return false;\n };\n matches!(\n value.trim().to_ascii_lowercase().as_str(),\n \"0\" | \"false\" | \"no\" | \"off\"\n )\n}\n\nfn parse_pr_feedback_cursor_handoff(value: &str) -> Option<PrFeedbackCursorHandoff> {\n let mut workspace_path = None;\n let mut review_plan_path = None;\n let mut review_rules_path = None;\n let mut kit_system_path = None;\n for line in value.lines().map(str::trim) {\n if let Some(path) = line.strip_prefix(\"Workspace:\") {\n workspace_path = Some(PathBuf::from(path.trim()));\n } else if let Some(path) = line.strip_prefix(\"Review plan:\") {\n review_plan_path = Some(PathBuf::from(path.trim()));\n } else if let Some(path) = line.strip_prefix(\"Review rules:\") {\n review_rules_path = Some(PathBuf::from(path.trim()));\n } else if let Some(path) = line.strip_prefix(\"Kit system prompt:\") {\n kit_system_path = Some(PathBuf::from(path.trim()));\n }\n }\n Some(PrFeedbackCursorHandoff {\n workspace_path: workspace_path?,\n review_plan_path: review_plan_path?,\n review_rules_path,\n kit_system_path: kit_system_path?,\n })\n}\n\nfn command_on_path(command: &str) -> bool {\n let Some(path_os) = env::var_os(\"PATH\") else {\n return false;\n };\n env::split_paths(&path_os).any(|dir| dir.join(command).is_file())\n}\n\nfn open_cursor_review_handoff(handoff: &PrFeedbackCursorHandoff) -> Result<()> {\n let mut command = if cfg!(target_os = \"macos\") || !command_on_path(\"cursor\") {\n let mut command = Command::new(\"open\");\n command.arg(\"-g\").arg(\"-a\").arg(\"Cursor\");\n command\n } else {\n Command::new(\"cursor\")\n };\n command\n .arg(&handoff.workspace_path)\n .arg(&handoff.review_plan_path)\n .args(handoff.review_rules_path.iter())\n .arg(&handoff.kit_system_path)\n .stdout(Stdio::null())\n .stderr(Stdio::null());\n let _status = command.status()?;\n Ok(())\n}\n\nfn print_codex_open_plan(plan: &CodexOpenPlan) {\n println!(\"# codex resolve\");\n println!(\"action: {}\", plan.action);\n println!(\"route: {}\", plan.route);\n println!(\"reason: {}\", plan.reason);\n println!(\"target: {}\", plan.target_path);\n println!(\"launch: {}\", plan.launch_path);\n println!(\n \"budget: {} chars, up to {} reference(s)\",\n plan.prompt_context_budget_chars, plan.max_resolved_references\n );\n if let Some(session_id) = plan.session_id.as_deref() {\n println!(\"session: {}\", truncate_recover_id(session_id));\n }\n if !plan.references.is_empty() {\n println!(\"references:\");\n for reference in &plan.references {\n println!(\n \"- {} [{}] {}\",\n reference.name, reference.source, reference.matched\n );\n }\n }\n if !plan.runtime_skills.is_empty() {\n println!(\"runtime:\");\n for skill in &plan.runtime_skills {\n println!(\"- {}\", skill);\n }\n if let Some(path) = plan.runtime_state_path.as_deref() {\n println!(\"runtime_state: {}\", path);\n }\n }\n if let Some(prompt) = plan.prompt.as_deref() {\n println!(\"prompt_chars: {}\", plan.prompt_chars);\n println!(\"injected_context_chars: {}\", plan.injected_context_chars);\n println!(\"prompt:\");\n println!(\"{}\", compact_codex_context_block(prompt, 12, 900));\n }\n}\n\nfn record_codex_open_plan(plan: &CodexOpenPlan, mode: &str) {\n let Some(query) = plan\n .query\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n else {\n return;\n };\n\n let event = codex_skill_eval::CodexSkillEvalEvent {\n version: 1,\n recorded_at_unix: SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0),\n mode: mode.to_string(),\n action: plan.action.clone(),\n route: plan.route.clone(),\n target_path: plan.target_path.clone(),\n launch_path: plan.launch_path.clone(),\n query: query.to_string(),\n session_id: plan.session_id.clone(),\n runtime_token: plan.runtime_state_path.as_deref().and_then(|path| {\n Path::new(path)\n .file_stem()\n .and_then(|value| value.to_str())\n .map(|value| value.to_string())\n }),\n runtime_skills: plan.runtime_skills.clone(),\n prompt_context_budget_chars: plan.prompt_context_budget_chars,\n prompt_chars: plan.prompt_chars,\n injected_context_chars: plan.injected_context_chars,\n reference_count: plan.references.len(),\n trace_id: plan.trace.as_ref().map(|trace| trace.trace_id.clone()),\n span_id: plan.trace.as_ref().map(|trace| trace.span_id.clone()),\n parent_span_id: plan\n .trace\n .as_ref()\n .and_then(|trace| trace.parent_span_id.clone()),\n workflow_kind: plan.trace.as_ref().map(|trace| trace.workflow_kind.clone()),\n service_name: plan.trace.as_ref().map(|trace| trace.service_name.clone()),\n };\n\n let _ = codex_skill_eval::log_event(&event);\n let mut activity_event =\n activity_log::ActivityEvent::done(format!(\"codex.{mode}\"), query.to_string());\n activity_event.route = Some(plan.route.clone());\n activity_event.target_path = Some(plan.target_path.clone());\n activity_event.launch_path = Some(plan.launch_path.clone());\n activity_event.session_id = plan.session_id.clone();\n activity_event.runtime_token = plan.runtime_state_path.as_deref().and_then(|path| {\n Path::new(path)\n .file_stem()\n .and_then(|value| value.to_str())\n .map(|value| value.to_string())\n });\n activity_event.source = Some(\"codex-open-plan\".to_string());\n let _ = activity_log::append_daily_event(activity_event);\n}\n\nfn load_codex_config_for_path(target_path: &Path) -> config::CodexConfig {\n let mut resolved = config::CodexConfig::default();\n\n let global_path = config::default_config_path();\n if global_path.exists()\n && let Ok(cfg) = config::load(&global_path)\n && let Some(codex_cfg) = cfg.codex\n {\n resolved.merge(codex_cfg);\n }\n\n if let Some(local_path) = project_snapshot::find_flow_toml_upwards(target_path)\n && local_path != global_path\n && let Ok(cfg) = config::load(&local_path)\n && let Some(codex_cfg) = cfg.codex\n {\n resolved.merge(codex_cfg);\n }\n\n resolved\n}\n\nfn default_codex_connect_path() -> PathBuf {\n let seed = env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\"));\n let cfg = load_codex_config_for_path(&seed);\n if let Some(path) = cfg\n .home_session_path\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n {\n return config::expand_path(path);\n }\n\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\"~\"))\n .join(\"repos\")\n .join(\"openai\")\n .join(\"codex\")\n}\n\nfn resolve_codex_connect_target_path(path: Option<String>) -> Result<PathBuf> {\n match path\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n {\n Some(value) => resolve_session_target_path(Some(value)),\n None => Ok(default_codex_connect_path()),\n }\n}\n\nfn looks_like_recovery_prompt(normalized_query: &str) -> bool {\n normalized_query.contains(\"see this convo\")\n || normalized_query.contains(\"what was i doing\")\n || normalized_query.contains(\"recover recent context\")\n || normalized_query.contains(\"recover context\")\n || (normalized_query.contains(\"continue the\")\n && (normalized_query.contains(\" work\")\n || normalized_query.contains(\" session\")\n || normalized_query.contains(\" convo\")\n || normalized_query.contains(\" conversation\")))\n}\n\nfn looks_like_commit_workflow_query(normalized_query: &str) -> bool {\n let collapsed = normalized_query\n .split_whitespace()\n .collect::<Vec<_>>()\n .join(\" \");\n matches!(\n collapsed.as_str(),\n \"commit\"\n | \"commit this\"\n | \"commit these\"\n | \"commit it\"\n | \"commit now\"\n | \"commit please\"\n | \"commit and push\"\n | \"commit & push\"\n | \"commit/push\"\n | \"review and commit\"\n | \"review commit\"\n | \"review, commit, and push\"\n )\n}\n\nfn looks_like_prom_sync_workflow_query(normalized_query: &str) -> bool {\n let collapsed = normalized_query\n .split_whitespace()\n .collect::<Vec<_>>()\n .join(\" \");\n matches!(\n collapsed.as_str(),\n \"sync branch\"\n | \"sync this branch\"\n | \"sync with origin/main\"\n | \"sync with origin main\"\n )\n}\n\nfn looks_like_session_lookup_query(normalized_query: &str) -> bool {\n extract_codex_session_hint(normalized_query).is_some()\n || looks_like_directional_session_query(normalized_query)\n || parse_ordinal_index(normalized_query).is_some()\n || looks_like_latest_query(normalized_query)\n || (contains_lookup_subject(normalized_query)\n && starts_with_session_control_phrase(normalized_query))\n}\n\nfn looks_like_directional_session_query(query: &str) -> bool {\n let has_direction = find_word_boundary(query, \"after\").is_some()\n || find_word_boundary(query, \"before\").is_some();\n has_direction && (contains_lookup_subject(query) || starts_with_session_control_phrase(query))\n}\n\nfn contains_lookup_subject(query: &str) -> bool {\n [\n \"session\",\n \"sessions\",\n \"conversation\",\n \"conversations\",\n \"convo\",\n \"convos\",\n ]\n .iter()\n .any(|value| query.split_whitespace().any(|word| word == *value))\n}\n\nfn starts_with_session_control_phrase(query: &str) -> bool {\n [\n \"open \",\n \"resume \",\n \"continue \",\n \"connect \",\n \"find \",\n \"recover \",\n \"show \",\n \"see \",\n \"copy \",\n \"summarize \",\n \"what was i doing\",\n ]\n .iter()\n .any(|prefix| query.starts_with(prefix))\n}\n\nfn resolve_codex_session_lookup(\n target_path: &Path,\n exact_cwd: bool,\n query_text: &str,\n normalized_query: &str,\n) -> Result<Option<(CodexRecoverRow, String)>> {\n if let Some(session_hint) = extract_codex_session_hint(normalized_query) {\n let rows = read_codex_threads_by_session_hint(&session_hint, 1)?;\n if let Some(row) = rows.into_iter().next() {\n return Ok(Some((\n row,\n format!(\"explicit session id/prefix `{}`\", session_hint),\n )));\n }\n }\n\n if let Some((row, reason)) =\n resolve_directional_session_lookup(target_path, exact_cwd, normalized_query)?\n {\n return Ok(Some((row, reason)));\n }\n\n if let Some(index) = parse_ordinal_index(normalized_query) {\n let rows = read_recent_codex_threads(target_path, exact_cwd, index + 1, None)?;\n if let Some(row) = rows.into_iter().nth(index) {\n return Ok(Some((row, format!(\"ordinal session match #{}\", index + 1))));\n }\n }\n\n if looks_like_latest_query(normalized_query) {\n let rows = read_recent_codex_threads(target_path, exact_cwd, 1, None)?;\n if let Some(row) = rows.into_iter().next() {\n return Ok(Some((row, \"latest recent session\".to_string())));\n }\n }\n\n if looks_like_session_lookup_query(normalized_query) {\n let rows = search_codex_threads_for_find(Some(target_path), exact_cwd, query_text, 1)?;\n if let Some(row) = rows.into_iter().next() {\n return Ok(Some((row, \"matched session search query\".to_string())));\n }\n }\n\n Ok(None)\n}\n\nfn resolve_directional_session_lookup(\n target_path: &Path,\n exact_cwd: bool,\n normalized_query: &str,\n) -> Result<Option<(CodexRecoverRow, String)>> {\n if !looks_like_directional_session_query(normalized_query) {\n return Ok(None);\n }\n let Some((direction, anchor_text)) = split_directional_query(normalized_query) else {\n return Ok(None);\n };\n let recent_rows = read_recent_codex_threads(target_path, exact_cwd, 50, None)?;\n if recent_rows.is_empty() {\n return Ok(None);\n }\n\n let anchor = if let Some(index) = parse_ordinal_index(&anchor_text) {\n recent_rows.get(index).cloned()\n } else if anchor_text.is_empty() || looks_like_latest_query(&anchor_text) {\n recent_rows.first().cloned()\n } else if let Some(session_hint) = extract_codex_session_hint(&anchor_text) {\n read_codex_threads_by_session_hint(&session_hint, 1)?\n .into_iter()\n .next()\n } else {\n search_codex_threads_for_find(Some(target_path), exact_cwd, &anchor_text, 1)?\n .into_iter()\n .next()\n };\n\n let Some(anchor) = anchor else {\n return Ok(None);\n };\n let Some(anchor_index) = recent_rows.iter().position(|row| row.id == anchor.id) else {\n return Ok(None);\n };\n let selected = if direction == \"after\" {\n recent_rows.get(anchor_index + 1).cloned()\n } else {\n anchor_index\n .checked_sub(1)\n .and_then(|index| recent_rows.get(index).cloned())\n };\n\n Ok(selected.map(|row| {\n (\n row,\n format!(\"{} session relative to `{}`\", direction, anchor_text.trim()),\n )\n }))\n}\n\nfn split_directional_query(query: &str) -> Option<(String, String)> {\n for direction in [\"after\", \"before\"] {\n if let Some(index) = find_word_boundary(query, direction) {\n let anchor = query[index + direction.len()..].trim().to_string();\n return Some((direction.to_string(), anchor));\n }\n }\n None\n}\n\nfn find_word_boundary(text: &str, needle: &str) -> Option<usize> {\n let haystack = text.as_bytes();\n let needle_bytes = needle.as_bytes();\n let last = haystack.len().checked_sub(needle_bytes.len())?;\n for start in 0..=last {\n if &haystack[start..start + needle_bytes.len()] != needle_bytes {\n continue;\n }\n let before_ok = start == 0 || !haystack[start - 1].is_ascii_alphanumeric();\n let after_index = start + needle_bytes.len();\n let after_ok =\n after_index >= haystack.len() || !haystack[after_index].is_ascii_alphanumeric();\n if before_ok && after_ok {\n return Some(start);\n }\n }\n None\n}\n\nfn parse_ordinal_index(query: &str) -> Option<usize> {\n let filtered = strip_codex_control_words(query);\n if filtered.len() == 1 {\n if let Ok(value) = filtered[0].parse::<usize>() {\n if value > 0 {\n return Some(value - 1);\n }\n }\n let ordinal = match filtered[0].as_str() {\n \"1st\" | \"first\" | \"one\" => Some(0),\n \"2nd\" | \"second\" | \"two\" => Some(1),\n \"3rd\" | \"third\" | \"three\" => Some(2),\n \"4th\" | \"fourth\" | \"four\" => Some(3),\n \"5th\" | \"fifth\" | \"five\" => Some(4),\n \"6th\" | \"sixth\" | \"six\" => Some(5),\n \"7th\" | \"seventh\" | \"seven\" => Some(6),\n \"8th\" | \"eighth\" | \"eight\" => Some(7),\n \"9th\" | \"ninth\" | \"nine\" => Some(8),\n \"10th\" | \"tenth\" | \"ten\" => Some(9),\n _ => None,\n };\n if ordinal.is_some() {\n return ordinal;\n }\n }\n None\n}\n\nfn looks_like_latest_query(query: &str) -> bool {\n let filtered = strip_codex_control_words(query);\n filtered.is_empty()\n && (query.contains(\"most recent\")\n || query.contains(\"latest\")\n || query.contains(\"newest\")\n || query.contains(\"last\"))\n}\n\nfn strip_codex_control_words(query: &str) -> Vec<String> {\n query\n .split(|ch: char| !ch.is_ascii_alphanumeric())\n .filter(|part| !part.is_empty())\n .map(|part| part.to_ascii_lowercase())\n .filter(|part| {\n !matches!(\n part.as_str(),\n \"connect\"\n | \"open\"\n | \"resume\"\n | \"continue\"\n | \"session\"\n | \"sessions\"\n | \"conversation\"\n | \"conversations\"\n | \"convo\"\n | \"convos\"\n | \"after\"\n | \"before\"\n | \"most\"\n | \"recent\"\n | \"latest\"\n | \"newest\"\n | \"last\"\n | \"active\"\n | \"the\"\n | \"a\"\n | \"an\"\n | \"to\"\n | \"from\"\n | \"for\"\n | \"please\"\n )\n })\n .collect()\n}\n\nfn build_codex_recovery_plan(\n target_path: &Path,\n exact_cwd: bool,\n query_text: &str,\n runtime_skills_enabled: bool,\n prompt_context_budget_chars: usize,\n max_resolved_references: usize,\n) -> Result<CodexOpenPlan> {\n let rows = read_recent_codex_threads(target_path, exact_cwd, 3, Some(query_text))?;\n let output = build_recover_output(target_path, exact_cwd, Some(query_text.to_string()), rows);\n let launch_path = output\n .candidates\n .first()\n .map(|value| value.cwd.clone())\n .unwrap_or_else(|| target_path.display().to_string());\n\n if output.candidates.is_empty() {\n bail!(\"{}\", output.summary);\n }\n\n let recovery_prompt = build_recovery_prompt(query_text, &output, prompt_context_budget_chars);\n let codex_cfg = load_codex_config_for_path(target_path);\n let runtime = codex_runtime::prepare_runtime_activation(\n target_path,\n query_text,\n runtime_skills_enabled,\n &codex_cfg,\n )?;\n let prompt = runtime\n .as_ref()\n .map(|value| value.inject_into_prompt(&recovery_prompt))\n .or(Some(recovery_prompt));\n Ok(finalize_codex_open_plan(CodexOpenPlan {\n action: \"recover-new\".to_string(),\n route: \"recover-new\".to_string(),\n reason: \"explicit recovery prompt\".to_string(),\n target_path: target_path.display().to_string(),\n launch_path,\n query: Some(query_text.to_string()),\n session_id: None,\n prompt,\n references: Vec::new(),\n runtime_state_path: runtime\n .as_ref()\n .map(|value| value.state_path.display().to_string()),\n runtime_skills: runtime_skill_names(runtime.as_ref()),\n prompt_context_budget_chars,\n max_resolved_references,\n prompt_chars: 0,\n injected_context_chars: 0,\n trace: None,\n }))\n}\n\nfn build_recovery_prompt(\n query_text: &str,\n output: &CodexRecoverOutput,\n max_chars: usize,\n) -> String {\n let mut lines = vec![\"Recovered recent Codex context:\".to_string()];\n for candidate in output.candidates.iter().take(2) {\n let preview = candidate\n .first_user_message\n .as_deref()\n .or(candidate.title.as_deref())\n .map(truncate_recover_text)\n .unwrap_or_else(|| \"(no stored prompt text)\".to_string());\n let model = codex_model_label(\n candidate.model.as_deref(),\n candidate.reasoning_effort.as_deref(),\n );\n let line = if let Some(model) = model {\n format!(\n \"- {} | {} | {} | {} | {}\",\n truncate_recover_id(&candidate.id),\n candidate.updated_at,\n model,\n candidate.cwd,\n preview\n )\n } else {\n format!(\n \"- {} | {} | {} | {}\",\n truncate_recover_id(&candidate.id),\n candidate.updated_at,\n candidate.cwd,\n preview\n )\n };\n lines.push(line);\n }\n lines.push(String::new());\n lines.push(\"User request:\".to_string());\n lines.push(query_text.trim().to_string());\n compact_codex_context_block(&lines.join(\"\\n\"), 10, max_chars)\n}\n\nfn build_codex_open_no_match_message(\n target_path: &Path,\n exact_cwd: bool,\n query_text: &str,\n) -> Result<String> {\n let output = build_recover_output(\n target_path,\n exact_cwd,\n Some(query_text.to_string()),\n read_recent_codex_threads(target_path, exact_cwd, 5, None)?,\n );\n Ok(format!(\n \"No Codex session matched {:?}.\\n{}\",\n query_text, output.summary\n ))\n}\n\nfn resolve_codex_references(\n target_path: &Path,\n query_text: &str,\n resolvers: &[config::CodexReferenceResolverConfig],\n) -> Result<Vec<CodexResolvedReference>> {\n let candidates = extract_reference_candidates(query_text);\n let mut matches = Vec::new();\n\n for resolver in resolvers {\n if let Some(reference) =\n resolve_external_reference(target_path, query_text, &candidates, resolver)?\n {\n matches.push(reference);\n }\n if matches.len() >= 2 {\n return Ok(matches);\n }\n }\n\n let remaining = 2usize.saturating_sub(matches.len());\n if remaining > 0 {\n for reference in\n resolve_builtin_repo_references(target_path, query_text, &candidates, remaining)?\n {\n if !matches\n .iter()\n .any(|value| value.matched == reference.matched)\n {\n matches.push(reference);\n }\n if matches.len() >= 2 {\n return Ok(matches);\n }\n }\n }\n\n if let Some(reference) = resolve_builtin_linear_reference(query_text, &candidates)\n && !matches\n .iter()\n .any(|value| value.matched == reference.matched)\n {\n matches.push(reference);\n }\n\n if let Some(reference) =\n resolve_builtin_url_reference(target_path, query_text, &candidates, &matches)\n && !matches\n .iter()\n .any(|value| value.matched == reference.matched)\n {\n matches.push(reference);\n }\n\n Ok(matches)\n}\n\nfn resolve_builtin_repo_references(\n target_path: &Path,\n query_text: &str,\n candidates: &[String],\n limit: usize,\n) -> Result<Vec<CodexResolvedReference>> {\n let references =\n repo_capsule::resolve_reference_candidates(target_path, query_text, candidates, limit)?;\n Ok(references\n .into_iter()\n .map(|reference| {\n let memory_context =\n codex_memory::query_repo_facts(Path::new(&reference.repo_root), query_text, 4)\n .ok()\n .flatten()\n .map(|result| compact_codex_context_block(&result.rendered, 8, 700));\n let output = if let Some(memory) = memory_context {\n format!(\"{}\\n{}\", reference.output, memory)\n } else {\n reference.output\n };\n CodexResolvedReference {\n name: \"repo\".to_string(),\n source: \"repo\".to_string(),\n matched: reference.matched,\n command: None,\n output,\n }\n })\n .collect())\n}\n\nfn resolve_external_reference(\n target_path: &Path,\n query_text: &str,\n candidates: &[String],\n resolver: &config::CodexReferenceResolverConfig,\n) -> Result<Option<CodexResolvedReference>> {\n for candidate in candidates {\n if !resolver\n .matches\n .iter()\n .any(|pattern| wildcard_match(pattern, candidate))\n {\n continue;\n }\n\n let command_text = render_reference_resolver_command(\n &resolver.command,\n candidate,\n query_text,\n target_path,\n );\n let args = shell_words::split(&command_text)\n .with_context(|| format!(\"invalid resolver command: {}\", command_text))?;\n let Some((program, rest)) = args.split_first() else {\n bail!(\"empty resolver command for {}\", resolver.name);\n };\n let output = Command::new(program)\n .args(rest)\n .current_dir(target_path)\n .output()\n .with_context(|| format!(\"failed to run resolver {}\", resolver.name))?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();\n bail!(\n \"resolver {} failed for {}: {}\",\n resolver.name,\n candidate,\n if stderr.is_empty() {\n format!(\"exit status {}\", output.status)\n } else {\n stderr\n }\n );\n }\n let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if stdout.is_empty() {\n bail!(\n \"resolver {} returned empty output for {}\",\n resolver.name,\n candidate\n );\n }\n\n return Ok(Some(CodexResolvedReference {\n name: resolver\n .inject_as\n .clone()\n .unwrap_or_else(|| resolver.name.clone()),\n source: \"resolver\".to_string(),\n matched: candidate.clone(),\n command: Some(command_text),\n output: compact_codex_context_block(&stdout, 12, 1200),\n }));\n }\n\n Ok(None)\n}\n\nfn render_reference_resolver_command(\n template: &str,\n matched: &str,\n query_text: &str,\n target_path: &Path,\n) -> String {\n template\n .replace(\"{{ref}}\", &shell_words::quote(matched))\n .replace(\"{{query}}\", &shell_words::quote(query_text))\n .replace(\n \"{{cwd}}\",\n &shell_words::quote(&target_path.display().to_string()),\n )\n}\n\nfn resolve_builtin_linear_reference(\n query_text: &str,\n candidates: &[String],\n) -> Option<CodexResolvedReference> {\n for candidate in candidates {\n if let Some(reference) = parse_linear_url_reference(candidate) {\n return Some(CodexResolvedReference {\n name: \"linear\".to_string(),\n source: \"builtin\".to_string(),\n matched: candidate.clone(),\n command: None,\n output: render_linear_url_reference(&reference),\n });\n }\n }\n let _ = query_text;\n None\n}\n\nfn resolve_builtin_url_reference(\n target_path: &Path,\n query_text: &str,\n candidates: &[String],\n existing: &[CodexResolvedReference],\n) -> Option<CodexResolvedReference> {\n for candidate in candidates {\n if !looks_like_http_url(candidate) {\n continue;\n }\n if existing.iter().any(|value| value.matched == *candidate) {\n continue;\n }\n if looks_like_github_pr_url(candidate) && looks_like_pr_feedback_query(query_text) {\n let Ok(output) = crate::commit::resolve_pr_feedback_reference(target_path, candidate)\n else {\n continue;\n };\n return Some(CodexResolvedReference {\n name: \"pr-feedback\".to_string(),\n source: \"builtin\".to_string(),\n matched: candidate.clone(),\n command: Some(format!(\"f pr feedback {}\", shell_words::quote(candidate))),\n output: compact_codex_context_block(&output, 16, 2400),\n });\n }\n let Ok(output) = url_inspect::inspect_compact(candidate, target_path) else {\n continue;\n };\n return Some(CodexResolvedReference {\n name: \"url\".to_string(),\n source: \"builtin\".to_string(),\n matched: candidate.clone(),\n command: None,\n output: compact_codex_context_block(&output, 10, 900),\n });\n }\n None\n}\n\nfn resolve_builtin_commit_workflow_reference(repo_root: &Path) -> Result<CodexResolvedReference> {\n let status = capture_git_stdout(repo_root, &[\"status\", \"--short\"]).unwrap_or_default();\n let staged_diff = capture_git_stdout(repo_root, &[\"diff\", \"--cached\", \"--stat\", \"--compact-summary\"])\n .unwrap_or_default();\n let working_diff = if staged_diff.trim().is_empty() {\n capture_git_stdout(repo_root, &[\"diff\", \"--stat\", \"--compact-summary\"]).unwrap_or_default()\n } else {\n String::new()\n };\n let review_instructions = crate::commit::get_review_instructions(repo_root).unwrap_or_default();\n let agents_instructions = read_repo_agents_instructions(repo_root).unwrap_or_default();\n let kit_gate = detect_commit_workflow_kit_gate(repo_root);\n let output = render_commit_workflow_reference(\n repo_root,\n &status,\n &staged_diff,\n &working_diff,\n &review_instructions,\n &agents_instructions,\n kit_gate.as_deref(),\n );\n\n Ok(CodexResolvedReference {\n name: \"commit-workflow\".to_string(),\n source: \"builtin\".to_string(),\n matched: \"commit\".to_string(),\n command: Some(\"f commit --slow --context\".to_string()),\n output: compact_codex_context_block(&output, 20, 2200),\n })\n}\n\nfn resolve_builtin_sync_workflow_reference(repo_root: &Path) -> Result<CodexResolvedReference> {\n let agents_instructions = read_repo_agents_instructions(repo_root).unwrap_or_default();\n let command = detect_sync_workflow_command(repo_root);\n let output = render_sync_workflow_reference(\n repo_root,\n &agents_instructions,\n command.as_deref().unwrap_or(\"forge sync\"),\n );\n\n Ok(CodexResolvedReference {\n name: \"sync-workflow\".to_string(),\n source: \"builtin\".to_string(),\n matched: \"sync branch\".to_string(),\n command,\n output: compact_codex_context_block(&output, 18, 1600),\n })\n}\n\nfn capture_git_stdout(repo_root: &Path, args: &[&str]) -> Option<String> {\n let output = Command::new(\"git\")\n .args(args)\n .current_dir(repo_root)\n .output()\n .ok()?;\n if !output.status.success() {\n return None;\n }\n let stdout = String::from_utf8(output.stdout).ok()?;\n let trimmed = stdout.trim();\n if trimmed.is_empty() {\n return None;\n }\n Some(trimmed.to_string())\n}\n\nfn render_commit_workflow_reference(\n repo_root: &Path,\n status: &str,\n staged_diff: &str,\n working_diff: &str,\n review_instructions: &str,\n agents_instructions: &str,\n kit_gate: Option<&str>,\n) -> String {\n let mut lines = vec![\n \"Commit workflow contract:\".to_string(),\n format!(\"Workspace: {}\", repo_root.display()),\n \"Interpret plain `commit` as deep-review-then-commit, not the fast lane.\".to_string(),\n \"If you use Flow CLI for the final commit, prefer `f commit --slow --context` over plain `f commit`.\".to_string(),\n \"Default focus: correctness, regression risk, performance, robustness, and clear intent.\".to_string(),\n \"Preferred execution shape: keep the main thread lean and, if available, use a detached Codex review lane or subagent to inspect the diff in parallel and only surface blocking issues back to the main thread.\".to_string(),\n \"Treat repo AGENTS.md and repo review instructions as binding commit constraints.\".to_string(),\n ];\n\n if let Some(kit_gate) = kit_gate {\n lines.push(format!(\"Deterministic gate: {}\", kit_gate));\n }\n\n lines.extend([\n \"Required operating order:\".to_string(),\n \"1. Inspect the actual local diff and adjacent call sites before deciding anything.\".to_string(),\n \"2. Run deterministic local gates before the final commit when they are available.\".to_string(),\n \"3. Explain the intent behind the change and the main risks.\".to_string(),\n \"4. Name the smallest validation that proves the change is safe.\".to_string(),\n \"5. Draft a commit title/body that explains why the change was made, not just what changed.\".to_string(),\n \"6. Only commit/push once the review is clean and the change is scoped.\".to_string(),\n ]);\n\n if !status.trim().is_empty() {\n lines.push(String::new());\n lines.push(\"Git status:\".to_string());\n lines.push(render_compact_bullet_block(status, 10));\n }\n\n if !staged_diff.trim().is_empty() {\n lines.push(String::new());\n lines.push(\"Staged diff stat:\".to_string());\n lines.push(render_compact_bullet_block(staged_diff, 12));\n } else if !working_diff.trim().is_empty() {\n lines.push(String::new());\n lines.push(\"Working tree diff stat (nothing staged yet):\".to_string());\n lines.push(render_compact_bullet_block(working_diff, 12));\n } else {\n lines.push(String::new());\n lines.push(\"Diff state: working tree is clean right now.\".to_string());\n }\n\n if !review_instructions.trim().is_empty() {\n lines.push(String::new());\n lines.push(\"Repo commit review instructions:\".to_string());\n lines.push(compact_codex_context_block(review_instructions.trim(), 5, 500));\n }\n\n lines.push(String::new());\n lines.push(\"Final deliverable contract:\".to_string());\n lines.push(\"- provide one short review summary covering correctness, perf, robustness, and regression risk\".to_string());\n lines.push(\"- provide exact validation commands or manual checks\".to_string());\n lines.push(\"- provide the final commit title and body with explicit intent, not only file-level changes\".to_string());\n\n let _ = agents_instructions;\n lines.join(\"\\n\")\n}\n\nfn render_sync_workflow_reference(repo_root: &Path, agents_instructions: &str, command: &str) -> String {\n let mut lines = vec![\n \"Sync workflow contract:\".to_string(),\n format!(\"Workspace: {}\", repo_root.display()),\n \"Interpret plain `sync branch` as the guarded repo sync workflow, not raw `git pull`, generic rebase steps, or improvised JJ commands.\".to_string(),\n format!(\"Preferred command: {}\", command),\n \"Required operating order:\".to_string(),\n \"1. Read ./AGENTS.md if it exists and treat repo workflow instructions as binding.\".to_string(),\n \"2. Use the guarded sync path for this repo instead of ad hoc Git/JJ commands.\".to_string(),\n \"3. Preserve branch-aware behavior and explain what changed.\".to_string(),\n \"4. If sync fails, report the blocker and next safe step instead of improvising.\".to_string(),\n \"Final deliverable contract:\".to_string(),\n \"- state whether sync succeeded\".to_string(),\n \"- summarize the main changes pulled in\".to_string(),\n \"- name any remaining blocker or follow-up\".to_string(),\n ];\n\n if !agents_instructions.trim().is_empty() {\n lines.push(String::new());\n lines.push(\"Repo workflow instructions:\".to_string());\n lines.push(compact_codex_context_block(agents_instructions.trim(), 5, 400));\n }\n\n lines.join(\"\\n\")\n}\n\nfn render_compact_bullet_block(value: &str, max_lines: usize) -> String {\n let mut lines = Vec::new();\n for line in value.lines().map(str::trim).filter(|line| !line.is_empty()) {\n lines.push(format!(\"- {}\", truncate_message(line, 140)));\n if lines.len() >= max_lines {\n break;\n }\n }\n if lines.is_empty() {\n \"- none\".to_string()\n } else {\n lines.join(\"\\n\")\n }\n}\n\nfn read_repo_agents_instructions(repo_root: &Path) -> Option<String> {\n let path = repo_root.join(\"AGENTS.md\");\n let content = fs::read_to_string(path).ok()?;\n let trimmed = content.trim();\n if trimmed.is_empty() {\n return None;\n }\n Some(trimmed.to_string())\n}\n\nfn detect_commit_workflow_kit_gate(repo_root: &Path) -> Option<String> {\n if !command_on_path(\"kit\") {\n return None;\n }\n Some(format!(\n \"cd {} && kit lint --setup never && kit review --dir . --json\",\n shell_words::quote(&repo_root.display().to_string())\n ))\n}\n\nfn is_prom_workspace_path(path: &Path) -> bool {\n let display = path.display().to_string();\n display.contains(\"/code/prom\") || display.contains(\"/.jj/workspaces/prom/\")\n}\n\nfn detect_sync_workflow_command(repo_root: &Path) -> Option<String> {\n if !is_prom_workspace_path(repo_root) {\n return None;\n }\n Some(\"forge sync\".to_string())\n}\n\nfn extract_reference_candidates(query_text: &str) -> Vec<String> {\n let mut seen = BTreeSet::new();\n let mut candidates = Vec::new();\n\n let trimmed = trim_reference_token(query_text);\n if !trimmed.is_empty() && seen.insert(trimmed.to_string()) {\n candidates.push(trimmed.to_string());\n }\n\n for token in query_text.split_whitespace() {\n let trimmed = trim_reference_token(token);\n if trimmed.is_empty() {\n continue;\n }\n if seen.insert(trimmed.to_string()) {\n candidates.push(trimmed.to_string());\n }\n }\n\n candidates\n}\n\nfn trim_reference_token(value: &str) -> &str {\n value.trim_matches(|ch: char| {\n matches!(\n ch,\n '\"' | '\\'' | '(' | ')' | '[' | ']' | '{' | '}' | '<' | '>' | ',' | '.' | ';'\n )\n })\n}\n\nfn looks_like_http_url(value: &str) -> bool {\n let trimmed = trim_reference_token(value);\n trimmed.starts_with(\"https://\") || trimmed.starts_with(\"http://\")\n}\n\nfn looks_like_github_pr_url(value: &str) -> bool {\n let trimmed = trim_reference_token(value).trim_end_matches('/');\n let Some(rest) = trimmed.strip_prefix(\"https://github.com/\") else {\n return false;\n };\n let mut parts = rest.split('/');\n let owner = parts.next().unwrap_or_default().trim();\n let repo = parts.next().unwrap_or_default().trim();\n let kind = parts.next().unwrap_or_default().trim();\n let number = parts.next().unwrap_or_default().trim();\n !owner.is_empty() && !repo.is_empty() && kind == \"pull\" && number.parse::<u64>().is_ok()\n}\n\nfn looks_like_pr_feedback_query(query_text: &str) -> bool {\n let lowered = query_text.to_ascii_lowercase();\n lowered.contains(\"check \")\n || lowered.starts_with(\"check\")\n || lowered.contains(\"feedback\")\n || lowered.contains(\"comments\")\n || lowered.contains(\"review\")\n || lowered.contains(\"lint\")\n}\n\nfn wildcard_match(pattern: &str, candidate: &str) -> bool {\n let pattern = pattern.to_ascii_lowercase();\n let candidate = candidate.to_ascii_lowercase();\n if !pattern.contains('*') {\n return pattern == candidate;\n }\n\n let mut remainder = candidate.as_str();\n let mut anchored = true;\n for segment in pattern.split('*') {\n if segment.is_empty() {\n anchored = false;\n continue;\n }\n if anchored {\n let Some(stripped) = remainder.strip_prefix(segment) else {\n return false;\n };\n remainder = stripped;\n } else if let Some(index) = remainder.find(segment) {\n remainder = &remainder[index + segment.len()..];\n } else {\n return false;\n }\n anchored = false;\n }\n\n pattern.ends_with('*') || remainder.is_empty()\n}\n\nfn parse_linear_url_reference(value: &str) -> Option<LinearUrlReference> {\n let trimmed = trim_reference_token(value);\n let relative = trimmed.strip_prefix(\"https://linear.app/\")?;\n let relative = relative\n .split(['?', '#'])\n .next()\n .unwrap_or(relative)\n .trim_matches('/');\n let segments: Vec<_> = relative\n .split('/')\n .filter(|segment| !segment.is_empty())\n .collect();\n if segments.len() < 3 {\n return None;\n }\n\n let workspace_slug = segments[0].to_string();\n match segments[1] {\n \"issue\" => Some(LinearUrlReference {\n url: trimmed.to_string(),\n workspace_slug,\n resource_kind: LinearUrlKind::Issue,\n resource_value: segments[2].to_string(),\n view: None,\n title_hint: segments[2].to_string(),\n }),\n \"project\" => {\n let project_slug = segments[2].to_string();\n let title_hint = humanize_linear_slug(&project_slug);\n Some(LinearUrlReference {\n url: trimmed.to_string(),\n workspace_slug,\n resource_kind: LinearUrlKind::Project,\n resource_value: project_slug,\n view: segments.get(3).map(|value| (*value).to_string()),\n title_hint,\n })\n }\n _ => None,\n }\n}\n\nfn humanize_linear_slug(value: &str) -> String {\n let mut parts: Vec<_> = value.split('-').filter(|part| !part.is_empty()).collect();\n if parts\n .last()\n .is_some_and(|part| part.len() >= 8 && part.chars().all(|ch| ch.is_ascii_hexdigit()))\n {\n parts.pop();\n }\n if parts.is_empty() {\n value.to_string()\n } else {\n parts.join(\" \")\n }\n}\n\nfn render_linear_url_reference(reference: &LinearUrlReference) -> String {\n let mut lines = vec![format!(\"- Linear URL: {}\", reference.url)];\n lines.push(format!(\"- Linear workspace: {}\", reference.workspace_slug));\n match reference.resource_kind {\n LinearUrlKind::Issue => {\n lines.push(format!(\"- Linear issue: {}\", reference.resource_value));\n }\n LinearUrlKind::Project => {\n lines.push(format!(\n \"- Linear project slug: {}\",\n reference.resource_value\n ));\n lines.push(format!(\"- Linear project hint: {}\", reference.title_hint));\n if let Some(view) = reference.view.as_deref() {\n lines.push(format!(\"- Linear project view: {}\", view));\n }\n }\n }\n compact_codex_context_block(&lines.join(\"\\n\"), 8, 700)\n}\n\nfn build_codex_prompt(\n query_text: &str,\n references: &[CodexResolvedReference],\n max_resolved_references: usize,\n max_chars: usize,\n) -> Option<String> {\n let trimmed_query = query_text.trim();\n if references.is_empty() {\n if trimmed_query.is_empty() {\n return None;\n }\n return Some(trimmed_query.to_string());\n }\n\n let mut lines = vec![\"Resolved context:\".to_string()];\n let selected: Vec<_> = references.iter().take(max_resolved_references).collect();\n for (index, reference) in selected.iter().enumerate() {\n let current_chars = lines.iter().map(|line| line.chars().count()).sum::<usize>();\n let query_reserve = if trimmed_query.is_empty() {\n 0\n } else {\n trimmed_query.chars().count() + \"User request:\".chars().count() + 8\n };\n let remaining = max_chars.saturating_sub(current_chars + query_reserve);\n if remaining < 80 {\n break;\n }\n let refs_left = selected.len().saturating_sub(index).max(1);\n let per_ref_budget = (remaining / refs_left).clamp(120, max_chars.max(120));\n let header = format!(\"[{}]\", reference.name);\n if !reference.output.trim_start().starts_with(&header) {\n lines.push(header);\n }\n lines.push(compact_codex_context_block(\n &reference.output,\n 8,\n per_ref_budget,\n ));\n }\n if !trimmed_query.is_empty() {\n lines.push(String::new());\n lines.push(\"User request:\".to_string());\n lines.push(trimmed_query.to_string());\n }\n let (max_lines, max_chars) = if has_session_reference(references) {\n (24, max_chars)\n } else {\n (14, max_chars)\n };\n Some(compact_codex_context_block(\n &lines.join(\"\\n\"),\n max_lines,\n max_chars,\n ))\n}\n\nfn build_codex_prompt_with_runtime(\n query_text: &str,\n references: &[CodexResolvedReference],\n runtime: Option<&codex_runtime::CodexRuntimeActivation>,\n max_resolved_references: usize,\n max_chars: usize,\n) -> Option<String> {\n let prompt = build_codex_prompt(query_text, references, max_resolved_references, max_chars)?;\n Some(\n runtime\n .map(|value| value.inject_into_prompt(&prompt))\n .unwrap_or(prompt),\n )\n}\n\nfn has_session_reference(references: &[CodexResolvedReference]) -> bool {\n references\n .iter()\n .any(|reference| reference.source == \"session\")\n}\n\nfn effective_max_resolved_references(codex_cfg: &config::CodexConfig) -> usize {\n codex_cfg.max_resolved_references.unwrap_or(2).clamp(1, 6)\n}\n\nfn effective_prompt_context_budget_chars(\n codex_cfg: &config::CodexConfig,\n has_session_reference: bool,\n) -> usize {\n codex_cfg\n .prompt_context_budget_chars\n .unwrap_or(if has_session_reference { 2200 } else { 1200 })\n .clamp(300, 12_000)\n}\n\nfn new_workflow_trace_id() -> String {\n Uuid::new_v4().simple().to_string()\n}\n\nfn new_workflow_span_id() -> String {\n Uuid::new_v4().simple().to_string()[..16].to_string()\n}\n\nfn workflow_kind_from_route(route: &str) -> String {\n route\n .trim()\n .trim_matches(|ch: char| !ch.is_ascii_alphanumeric() && ch != '-')\n .replace('-', \"_\")\n}\n\nfn trace_context_from_reference(\n reference: &CodexResolvedReference,\n workflow_kind: String,\n) -> Option<CodexResolveWorkflowTrace> {\n let fields = parse_reference_fields(&reference.output);\n let trace_id = fields.get(\"trace id\")?.trim();\n if trace_id.is_empty() {\n return None;\n }\n Some(CodexResolveWorkflowTrace {\n trace_id: trace_id.to_string(),\n span_id: new_workflow_span_id(),\n parent_span_id: None,\n workflow_kind,\n service_name: FLOW_CODEX_TRACE_SERVICE_NAME.to_string(),\n })\n}\n\nfn derive_codex_open_plan_trace(plan: &CodexOpenPlan) -> Option<CodexResolveWorkflowTrace> {\n if let Some(reference) = plan\n .references\n .iter()\n .find(|reference| reference.name == \"pr-feedback\")\n .and_then(|reference| trace_context_from_reference(reference, \"pr_feedback\".to_string()))\n {\n return Some(reference);\n }\n\n Some(CodexResolveWorkflowTrace {\n trace_id: new_workflow_trace_id(),\n span_id: new_workflow_span_id(),\n parent_span_id: None,\n workflow_kind: workflow_kind_from_route(&plan.route),\n service_name: FLOW_CODEX_TRACE_SERVICE_NAME.to_string(),\n })\n}\n\nfn finalize_codex_open_plan(mut plan: CodexOpenPlan) -> CodexOpenPlan {\n if plan.trace.is_none() {\n plan.trace = derive_codex_open_plan_trace(&plan);\n }\n plan.prompt_chars = plan\n .prompt\n .as_deref()\n .map(|value| value.chars().count())\n .unwrap_or(0);\n let query_chars = plan\n .query\n .as_deref()\n .map(str::trim)\n .map(|value| value.chars().count())\n .unwrap_or(0);\n plan.injected_context_chars = plan.prompt_chars.saturating_sub(query_chars);\n plan\n}\n\nfn runtime_skill_names(runtime: Option<&codex_runtime::CodexRuntimeActivation>) -> Vec<String> {\n runtime\n .map(|value| {\n value\n .skills\n .iter()\n .map(|skill| {\n skill\n .original_name\n .clone()\n .unwrap_or_else(|| skill.name.clone())\n })\n .collect()\n })\n .unwrap_or_default()\n}\n\nfn compact_codex_context_block(value: &str, max_lines: usize, max_chars: usize) -> String {\n let mut lines = Vec::new();\n let mut chars = 0usize;\n for line in value\n .lines()\n .map(str::trim_end)\n .filter(|line| !line.is_empty())\n {\n let line_chars = line.chars().count();\n if lines.len() >= max_lines || chars + line_chars > max_chars {\n break;\n }\n lines.push(line.to_string());\n chars += line_chars;\n }\n let mut out = lines.join(\"\\n\");\n if out.chars().count() > max_chars {\n out = out\n .chars()\n .take(max_chars.saturating_sub(1))\n .collect::<String>()\n + \"…\";\n }\n out\n}\n\n/// Copy session history to clipboard.\nfn copy_session(session: Option<String>, provider: Provider) -> Result<()> {\n // Auto-import any new sessions silently\n auto_import_sessions()?;\n\n if session.is_none() && provider != Provider::All {\n return copy_last_session(provider, None);\n }\n\n // Handle provider shortcuts: \"claude\" or \"codex\" -> copy last session for that provider\n if let Some(ref query) = session {\n let q = query.to_lowercase();\n if q == \"claude\" || q == \"c\" {\n return copy_last_session(Provider::Claude, None);\n }\n if q == \"codex\" || q == \"x\" {\n return copy_last_session(Provider::Codex, None);\n }\n if q == \"cursor\" || q == \"u\" {\n return copy_last_session(Provider::Cursor, None);\n }\n }\n\n let index = load_index()?;\n let sessions = read_sessions_for_project(provider)?;\n\n if sessions.is_empty() && session.is_none() {\n let provider_name = match provider {\n Provider::Claude => \"Claude\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n };\n println!(\"No {} sessions found for this project.\", provider_name);\n return Ok(());\n }\n\n if session.is_none() && !io::stdin().is_terminal() {\n bail!(\"no session specified (interactive selection requires a TTY)\");\n }\n\n // Find the session ID and provider\n let (session_id, session_provider) = if let Some(ref query) = session {\n resolve_session_selection(query, &sessions, &index, provider)?\n } else {\n // Show fzf selection\n let mut entries: Vec<FzfSessionEntry> = Vec::new();\n\n for session in &sessions {\n if session.timestamp.is_none()\n && session.last_message_at.is_none()\n && session.last_message.is_none()\n && session.first_message.is_none()\n && session.error_summary.is_none()\n {\n continue;\n }\n\n let relative_time = session\n .last_message_at\n .as_deref()\n .or(session.timestamp.as_deref())\n .map(format_relative_time)\n .unwrap_or_else(|| \"\".to_string());\n\n let saved_name = index\n .sessions\n .iter()\n .find(|(_, s)| s.id == session.session_id)\n .map(|(name, _)| name.as_str())\n .filter(|name| !is_auto_generated_name(name));\n\n let summary = session\n .last_message\n .as_deref()\n .or(session.first_message.as_deref())\n .or(session.error_summary.as_deref())\n .unwrap_or(\"\");\n let summary_clean = clean_summary(summary);\n let id_short = &session.session_id[..8.min(session.session_id.len())];\n\n // Add provider indicator when showing all\n let provider_tag = if provider == Provider::All {\n match session.provider {\n Provider::Claude => \"claude | \",\n Provider::Codex => \"codex | \",\n Provider::Cursor => \"cursor | \",\n Provider::All => \"\",\n }\n } else {\n \"\"\n };\n\n let display = if let Some(name) = saved_name {\n format!(\n \"{}{} | {} | {}\",\n provider_tag,\n name,\n relative_time,\n truncate_str(&summary_clean, 40)\n )\n } else {\n format!(\n \"{}{} | {} | {}\",\n provider_tag,\n relative_time,\n truncate_str(&summary_clean, 60),\n id_short\n )\n };\n\n entries.push(FzfSessionEntry {\n display,\n session_id: session.session_id.clone(),\n provider: session.provider,\n });\n }\n\n if entries.is_empty() {\n println!(\"No sessions available.\");\n return Ok(());\n }\n\n if which::which(\"fzf\").is_err() {\n bail!(\"fzf not found – install it for fuzzy selection\");\n }\n\n let Some(selected) = run_session_fzf(&entries)? else {\n return Ok(());\n };\n\n (selected.session_id.clone(), selected.provider)\n };\n\n // Read and format the session history\n let history = read_session_history(&session_id, session_provider)?;\n\n // Copy to clipboard\n copy_to_clipboard(&history)?;\n\n let line_count = history.lines().count();\n println!(\"Copied session history ({} lines) to clipboard\", line_count);\n\n Ok(())\n}\n\nfn copy_session_history_to_clipboard(session_id: &str, provider: Provider) -> Result<usize> {\n let history = read_session_history(session_id, provider)?;\n copy_to_clipboard(&history)?;\n Ok(history.lines().count())\n}\n\n/// Copy the most recent session for a provider directly (no fzf selection).\n/// If search query is provided, searches ALL sessions globally for matching content.\nfn copy_last_session(provider: Provider, search: Option<String>) -> Result<()> {\n // Auto-import any new sessions silently\n auto_import_sessions()?;\n\n // If search query provided, search all sessions globally\n if let Some(query) = search {\n return copy_session_by_search(provider, &query);\n }\n\n let sessions = read_sessions_for_project(provider)?;\n\n if sessions.is_empty() {\n let provider_name = match provider {\n Provider::Claude => \"Claude\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n };\n println!(\"No {} sessions found for this project.\", provider_name);\n return Ok(());\n }\n\n // sessions are already sorted by most recent first\n let session = &sessions[0];\n\n // Read and format the session history\n let history = read_session_history(&session.session_id, session.provider)?;\n\n // Copy to clipboard\n copy_to_clipboard(&history)?;\n\n let line_count = history.lines().count();\n let id_short = &session.session_id[..8.min(session.session_id.len())];\n println!(\n \"Copied session {} ({} lines) to clipboard\",\n id_short, line_count\n );\n\n Ok(())\n}\n\n/// Search all sessions globally for content matching the query.\nfn copy_session_by_search(provider: Provider, query: &str) -> Result<()> {\n let query_lower = query.to_lowercase();\n\n // Search Codex sessions\n if provider == Provider::Codex || provider == Provider::All {\n let sessions_dir = get_codex_sessions_dir();\n if sessions_dir.exists() {\n for file_path in collect_codex_session_files(&sessions_dir) {\n // Read raw content and check for query\n if let Ok(content) = fs::read_to_string(&file_path) {\n if content.to_lowercase().contains(&query_lower) {\n // Found a match - get session ID and read formatted history\n let filename = file_path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n let session_id = filename.split('_').next().unwrap_or(filename);\n\n let history = read_session_history(session_id, Provider::Codex)?;\n copy_to_clipboard(&history)?;\n\n let line_count = history.lines().count();\n let id_short = &session_id[..8.min(session_id.len())];\n\n // Try to get project path from session\n if let Some((_, cwd)) = parse_codex_session_file(&file_path, filename) {\n if let Some(project_path) = cwd {\n println!(\n \"Copied session {} from {} ({} lines) to clipboard\",\n id_short,\n project_path.display(),\n line_count\n );\n return Ok(());\n }\n }\n\n println!(\n \"Copied session {} ({} lines) to clipboard\",\n id_short, line_count\n );\n return Ok(());\n }\n }\n }\n }\n }\n\n // Search Cursor sessions\n if provider == Provider::Cursor || provider == Provider::All {\n let projects_dir = get_cursor_projects_dir();\n if projects_dir.exists() {\n if let Ok(entries) = fs::read_dir(&projects_dir) {\n for entry in entries.flatten() {\n let project_dir = entry.path();\n if !project_dir.is_dir() {\n continue;\n }\n for file_path in collect_cursor_project_session_files(&project_dir) {\n if let Ok(content) = fs::read_to_string(&file_path) {\n if content.to_lowercase().contains(&query_lower) {\n let session_id =\n file_path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n\n let history = read_session_history(session_id, Provider::Cursor)?;\n copy_to_clipboard(&history)?;\n\n let line_count = history.lines().count();\n let id_short = &session_id[..8.min(session_id.len())];\n let project_name = project_dir\n .file_name()\n .and_then(|s| s.to_str())\n .and_then(decode_cursor_project_path)\n .and_then(|path| {\n path.file_name()\n .and_then(|name| name.to_str())\n .map(str::to_string)\n })\n .unwrap_or_else(|| {\n project_dir\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(\"unknown\")\n .to_string()\n });\n\n println!(\n \"Copied session {} from {} ({} lines) to clipboard\",\n id_short, project_name, line_count\n );\n return Ok(());\n }\n }\n }\n }\n }\n }\n }\n\n // Search Claude sessions\n if provider == Provider::Claude || provider == Provider::All {\n let projects_dir = get_claude_projects_dir();\n if projects_dir.exists() {\n if let Ok(entries) = fs::read_dir(&projects_dir) {\n for entry in entries.flatten() {\n let project_dir = entry.path();\n if !project_dir.is_dir() {\n continue;\n }\n if let Ok(files) = fs::read_dir(&project_dir) {\n for file in files.flatten() {\n let file_path = file.path();\n if file_path.extension().map(|e| e == \"jsonl\").unwrap_or(false) {\n if let Ok(content) = fs::read_to_string(&file_path) {\n if content.to_lowercase().contains(&query_lower) {\n let session_id = file_path\n .file_stem()\n .and_then(|s| s.to_str())\n .unwrap_or(\"\");\n\n let history =\n read_session_history(session_id, Provider::Claude)?;\n copy_to_clipboard(&history)?;\n\n let line_count = history.lines().count();\n let id_short = &session_id[..8.min(session_id.len())];\n let project_name = project_dir\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(\"unknown\");\n\n println!(\n \"Copied session {} from {} ({} lines) to clipboard\",\n id_short, project_name, line_count\n );\n return Ok(());\n }\n }\n }\n }\n }\n }\n }\n }\n }\n\n println!(\"No session found containing: {}\", query);\n Ok(())\n}\n\nfn append_history_message(\n history: &mut String,\n last_entry: &mut Option<(String, String)>,\n role: &str,\n content: &str,\n) {\n let trimmed = content.trim();\n if trimmed.is_empty() {\n return;\n }\n\n let role_label = match role {\n \"user\" => \"Human\",\n \"assistant\" => \"Assistant\",\n _ => return,\n };\n\n let content_key = trimmed.to_string();\n if let Some((last_role, last_content)) = last_entry.as_ref() {\n if last_role == role_label && last_content == &content_key {\n return;\n }\n }\n\n history.push_str(role_label);\n history.push_str(\": \");\n history.push_str(trimmed);\n history.push_str(\"\\n\\n\");\n *last_entry = Some((role_label.to_string(), content_key));\n}\n\n/// Read full session history from JSONL file and format as conversation.\nfn read_session_history(session_id: &str, provider: Provider) -> Result<String> {\n let session_file = if provider == Provider::Codex {\n // Codex stores sessions in ~/.codex/sessions/ with different structure\n find_codex_session_file(session_id)\n .ok_or_else(|| anyhow::anyhow!(\"Codex session file not found: {}\", session_id))?\n } else if provider == Provider::Cursor {\n find_cursor_session_file(session_id)\n .ok_or_else(|| anyhow::anyhow!(\"Cursor session file not found: {}\", session_id))?\n } else {\n let cwd = std::env::current_dir()?;\n let cwd_str = cwd.to_string_lossy().to_string();\n let project_folder = path_to_project_name(&cwd_str);\n let projects_dir = get_claude_projects_dir();\n projects_dir\n .join(&project_folder)\n .join(format!(\"{}.jsonl\", session_id))\n };\n\n if !session_file.exists() {\n bail!(\"Session file not found: {}\", session_file.display());\n }\n\n let mut history = String::new();\n let mut last_entry: Option<(String, String)> = None;\n\n for_each_nonempty_jsonl_line(&session_file, |line| {\n let Ok(entry) = serde_json::from_str::<serde_json::Value>(line) else {\n return;\n };\n\n // Cursor format (top-level role + nested message.content)\n if let Some(role) = entry\n .get(\"role\")\n .and_then(|r| r.as_str())\n .map(normalize_cursor_role)\n {\n let content_text = extract_content_text(\n entry\n .get(\"message\")\n .and_then(|message| message.get(\"content\")),\n );\n if let Some(cleaned) = normalize_session_message(role, &content_text) {\n append_history_message(&mut history, &mut last_entry, role, &cleaned);\n }\n return;\n }\n\n // Try Claude format first (entry.message.role + entry.message.content)\n if let Some(msg) = entry.get(\"message\") {\n let role = msg\n .get(\"role\")\n .and_then(|r| r.as_str())\n .unwrap_or(\"unknown\");\n let content_text = extract_content_text(msg.get(\"content\"));\n if let Some(cleaned) = normalize_session_message(role, &content_text) {\n append_history_message(&mut history, &mut last_entry, role, &cleaned);\n }\n return;\n }\n\n // Try Codex format (type: response_item, payload.type: message)\n if entry.get(\"type\").and_then(|t| t.as_str()) == Some(\"response_item\") {\n if let Some(payload) = entry.get(\"payload\") {\n if payload.get(\"type\").and_then(|t| t.as_str()) == Some(\"message\") {\n let role = payload\n .get(\"role\")\n .and_then(|r| r.as_str())\n .unwrap_or(\"unknown\");\n let content_text = payload\n .get(\"content\")\n .and_then(extract_codex_content_text)\n .unwrap_or_default();\n if let Some(cleaned) = normalize_session_message(role, &content_text) {\n append_history_message(&mut history, &mut last_entry, role, &cleaned);\n }\n }\n }\n }\n })?;\n\n Ok(history)\n}\n\n/// Extract text content from various content formats.\nfn extract_content_text(content: Option<&serde_json::Value>) -> String {\n let Some(content) = content else {\n return String::new();\n };\n\n match content {\n serde_json::Value::String(s) => s.clone(),\n serde_json::Value::Array(arr) => {\n arr.iter()\n .filter_map(|v| {\n // Handle text blocks (Claude uses \"text\", Codex uses \"text\" in input_text type)\n v.get(\"text\")\n .and_then(|t| t.as_str())\n .map(|s| s.to_string())\n })\n .collect::<Vec<_>>()\n .join(\"\\n\")\n }\n _ => String::new(),\n }\n}\n\n/// Strip <system-reminder>...</system-reminder> blocks from text.\nfn strip_system_reminders(text: &str) -> String {\n let mut result = text.to_string();\n while let Some(start) = result.find(\"<system-reminder>\") {\n if let Some(end) = result[start..].find(\"</system-reminder>\") {\n let end_pos = start + end + \"</system-reminder>\".len();\n result = format!(\"{}{}\", &result[..start], &result[end_pos..]);\n } else {\n // Unclosed tag - remove from start to end\n result = result[..start].to_string();\n break;\n }\n }\n result.trim().to_string()\n}\n\n/// Check if content is boilerplate that should be skipped.\nfn is_session_boilerplate(text: &str) -> bool {\n let trimmed = text.trim();\n\n // === Codex boilerplate ===\n // Skip agents.md instructions\n if trimmed.starts_with(\"# AGENTS.md instructions\")\n || trimmed.starts_with(\"# agents.md instructions\")\n {\n return true;\n }\n // Skip environment context\n if trimmed.starts_with(\"<environment_context>\") {\n return true;\n }\n // Skip instructions blocks\n if trimmed.starts_with(\"<INSTRUCTIONS>\") {\n return true;\n }\n // Skip permissions instructions (Codex system context)\n if trimmed.contains(\"<permissions instructions>\") {\n return true;\n }\n // Skip developer role messages with system instructions\n if trimmed.starts_with(\"developer:\") {\n return true;\n }\n // Skip skill usage announcements\n if trimmed.starts_with(\"Using \") && trimmed.contains(\"skill\") {\n return true;\n }\n\n // === Claude boilerplate ===\n // Skip system reminders\n if trimmed.starts_with(\"<system-reminder>\") {\n return true;\n }\n // Skip messages that are only system reminders\n if trimmed.contains(\"<system-reminder>\")\n && !trimmed.contains(\"Human:\")\n && !trimmed.contains(\"Assistant:\")\n {\n // Check if the non-reminder content is minimal\n let without_reminders = trimmed\n .split(\"<system-reminder>\")\n .next()\n .unwrap_or(\"\")\n .trim();\n if without_reminders.is_empty() {\n return true;\n }\n }\n\n false\n}\n\n/// Copy last prompt and response from a session to clipboard.\nfn copy_context(\n session: Option<String>,\n provider: Provider,\n count: usize,\n path: Option<String>,\n) -> Result<()> {\n // Auto-import any new sessions silently\n auto_import_sessions()?;\n\n // Treat \"-\" as None (trigger fuzzy search)\n let mut session = session.filter(|s| s != \"-\");\n let mut path = path;\n\n // Allow `f ai context .` to mean \"use current path\" instead of a session ID.\n if path.is_none() {\n if let Some(ref candidate) = session {\n let candidate_path = PathBuf::from(candidate);\n if candidate == \".\" || candidate == \"..\" || candidate_path.exists() {\n path = Some(candidate.clone());\n session = None;\n }\n }\n }\n\n // Determine project path\n let project_path = if let Some(ref p) = path {\n PathBuf::from(p)\n } else {\n std::env::current_dir()?\n };\n\n let index = load_index()?;\n let sessions = read_sessions_for_path(provider, &project_path)?;\n\n if sessions.is_empty() && session.is_none() {\n let provider_name = match provider {\n Provider::Claude => \"Claude\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n };\n println!(\"No {} sessions found for this project.\", provider_name);\n return Ok(());\n }\n\n // Find the session ID and provider\n let (session_id, session_provider) = if let Some(ref query) = session {\n resolve_session_selection(query, &sessions, &index, provider)?\n } else {\n // Show fzf selection\n let mut entries: Vec<FzfSessionEntry> = Vec::new();\n\n for session in &sessions {\n if session.timestamp.is_none()\n && session.last_message_at.is_none()\n && session.last_message.is_none()\n && session.first_message.is_none()\n && session.error_summary.is_none()\n {\n continue;\n }\n\n let relative_time = session\n .last_message_at\n .as_deref()\n .or(session.timestamp.as_deref())\n .map(format_relative_time)\n .unwrap_or_else(|| \"\".to_string());\n\n let saved_name = index\n .sessions\n .iter()\n .find(|(_, s)| s.id == session.session_id)\n .map(|(name, _)| name.as_str())\n .filter(|name| !is_auto_generated_name(name));\n\n let summary = session\n .last_message\n .as_deref()\n .or(session.first_message.as_deref())\n .or(session.error_summary.as_deref())\n .unwrap_or(\"\");\n let summary_clean = clean_summary(summary);\n let id_short = &session.session_id[..8.min(session.session_id.len())];\n\n let provider_tag = if provider == Provider::All {\n match session.provider {\n Provider::Claude => \"claude | \",\n Provider::Codex => \"codex | \",\n Provider::Cursor => \"cursor | \",\n Provider::All => \"\",\n }\n } else {\n \"\"\n };\n\n let display = if let Some(name) = saved_name {\n format!(\n \"{}{} | {} | {}\",\n provider_tag,\n name,\n relative_time,\n truncate_str(&summary_clean, 40)\n )\n } else {\n format!(\n \"{}{} | {} | {}\",\n provider_tag,\n relative_time,\n truncate_str(&summary_clean, 60),\n id_short\n )\n };\n\n entries.push(FzfSessionEntry {\n display,\n session_id: session.session_id.clone(),\n provider: session.provider,\n });\n }\n\n if entries.is_empty() {\n println!(\"No sessions available.\");\n return Ok(());\n }\n\n if which::which(\"fzf\").is_err() {\n bail!(\"fzf not found – install it for fuzzy selection\");\n }\n\n let Some(selected) = run_session_fzf(&entries)? else {\n return Ok(());\n };\n\n (selected.session_id.clone(), selected.provider)\n };\n\n // Read the last N exchanges\n let context = read_last_context(&session_id, session_provider, count, &project_path)?;\n\n // Copy to clipboard\n copy_to_clipboard(&context)?;\n\n let exchange_word = if count == 1 { \"exchange\" } else { \"exchanges\" };\n let line_count = context.lines().count();\n println!(\n \"Copied last {} {} ({} lines) to clipboard\",\n count, exchange_word, line_count\n );\n\n Ok(())\n}\n\n/// Print a cleaned session excerpt to stdout.\nfn show_session(\n session: Option<String>,\n provider: Provider,\n count: usize,\n path: Option<String>,\n full: bool,\n) -> Result<()> {\n auto_import_sessions()?;\n\n let mut session = session.filter(|value| value != \"-\");\n let mut path = path;\n\n if path.is_none() {\n if let Some(ref candidate) = session {\n let candidate_path = PathBuf::from(candidate);\n if candidate == \".\" || candidate == \"..\" || candidate_path.exists() {\n path = Some(candidate.clone());\n session = None;\n }\n }\n }\n\n let project_path = if let Some(ref p) = path {\n PathBuf::from(p)\n } else {\n std::env::current_dir()?\n };\n\n let index = load_index()?;\n let sessions = read_sessions_for_path(provider, &project_path)?;\n\n let (session_id, session_provider) = if let Some(ref query) = session {\n resolve_session_selection(query, &sessions, &index, provider)?\n } else {\n let latest = sessions.first().ok_or_else(|| {\n let provider_name = match provider {\n Provider::Claude => \"Claude\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n };\n anyhow::anyhow!(\n \"No {provider_name} sessions found for {}\",\n project_path.display()\n )\n })?;\n (latest.session_id.clone(), latest.provider)\n };\n\n let output = if full {\n read_session_history(&session_id, session_provider)?\n } else {\n read_last_context(&session_id, session_provider, count.max(1), &project_path)?\n };\n\n print!(\"{}\", output);\n Ok(())\n}\n\n/// Read last N user prompts and assistant responses from a session.\nfn read_last_context(\n session_id: &str,\n provider: Provider,\n count: usize,\n project_path: &PathBuf,\n) -> Result<String> {\n if provider == Provider::Codex {\n let session_file = find_codex_session_file(session_id).ok_or_else(|| {\n anyhow::anyhow!(\"Session file not found for Codex session {}\", session_id)\n })?;\n return read_codex_last_context(&session_file, count);\n }\n if provider == Provider::Cursor {\n let session_file = find_cursor_session_file(session_id).ok_or_else(|| {\n anyhow::anyhow!(\"Session file not found for Cursor session {}\", session_id)\n })?;\n return read_cursor_last_context(&session_file, count);\n }\n\n let path_str = project_path.to_string_lossy().to_string();\n let project_folder = path_to_project_name(&path_str);\n\n let projects_dir = match provider {\n Provider::Claude | Provider::All => get_claude_projects_dir(),\n Provider::Codex => get_codex_projects_dir(),\n Provider::Cursor => get_cursor_projects_dir(),\n };\n\n let session_file = projects_dir\n .join(&project_folder)\n .join(format!(\"{}.jsonl\", session_id));\n\n if !session_file.exists() {\n bail!(\"Session file not found: {}\", session_file.display());\n }\n\n // Collect only the trailing `count` exchanges to bound memory usage for large sessions.\n let keep = count.max(1);\n let mut exchanges: VecDeque<(String, String)> = VecDeque::with_capacity(keep.min(64));\n let mut current_user: Option<String> = None;\n\n for_each_nonempty_jsonl_line(&session_file, |line| {\n if let Ok(entry) = crate::json_parse::parse_json_line::<JsonlEntry>(line) {\n if let Some(ref msg) = entry.message {\n let role = msg.role.as_deref().unwrap_or(\"unknown\");\n\n let Some(content_text) = msg.content.as_ref().and_then(extract_message_text) else {\n return;\n };\n let Some(clean_text) = normalize_session_message(role, &content_text) else {\n return;\n };\n\n match role {\n \"user\" => {\n current_user = Some(clean_text);\n }\n \"assistant\" => {\n if let Some(user_msg) = current_user.take() {\n if exchanges.len() == keep {\n exchanges.pop_front();\n }\n exchanges.push_back((user_msg, clean_text));\n }\n }\n _ => {}\n }\n }\n }\n })?;\n\n if exchanges.is_empty() {\n bail!(\"No exchanges found in session\");\n }\n\n // Format the context\n let mut context = String::new();\n\n for (user_msg, assistant_msg) in exchanges {\n context.push_str(\"Human: \");\n context.push_str(&user_msg);\n context.push_str(\"\\n\\n\");\n context.push_str(\"Assistant: \");\n context.push_str(&assistant_msg);\n context.push_str(\"\\n\\n\");\n }\n\n // Remove trailing newlines\n while context.ends_with('\\n') {\n context.pop();\n }\n context.push('\\n');\n\n Ok(context)\n}\n\n/// Copy text to system clipboard.\nfn copy_to_clipboard(text: &str) -> Result<()> {\n if std::env::var(\"FLOW_NO_CLIPBOARD\").is_ok() {\n return Ok(());\n }\n #[cfg(target_os = \"macos\")]\n {\n let mut child = Command::new(\"pbcopy\")\n .stdin(Stdio::piped())\n .spawn()\n .context(\"failed to spawn pbcopy\")?;\n\n if let Some(stdin) = child.stdin.as_mut() {\n stdin.write_all(text.as_bytes())?;\n }\n\n let status = child.wait()?;\n if !status.success() {\n bail!(\"pbcopy exited with status {}\", status);\n }\n }\n\n #[cfg(target_os = \"linux\")]\n {\n // Try xclip first, then xsel\n let result = Command::new(\"xclip\")\n .arg(\"-selection\")\n .arg(\"clipboard\")\n .stdin(Stdio::piped())\n .spawn();\n\n let mut child = match result {\n Ok(c) => c,\n Err(_) => Command::new(\"xsel\")\n .arg(\"--clipboard\")\n .arg(\"--input\")\n .stdin(Stdio::piped())\n .spawn()\n .context(\"failed to spawn xclip or xsel\")?,\n };\n\n if let Some(stdin) = child.stdin.as_mut() {\n stdin.write_all(text.as_bytes())?;\n }\n\n let status = child.wait()?;\n if !status.success() {\n bail!(\"clipboard command exited with status {}\", status);\n }\n }\n\n #[cfg(not(any(target_os = \"macos\", target_os = \"linux\")))]\n {\n bail!(\"clipboard not supported on this platform\");\n }\n\n Ok(())\n}\n\n/// Strip <thinking> blocks from content (internal Claude processing).\nfn strip_thinking_blocks(s: &str) -> String {\n let mut remaining = s;\n let mut out = String::new();\n\n loop {\n let Some(start) = remaining.find(\"<thinking>\") else {\n out.push_str(remaining);\n break;\n };\n\n out.push_str(&remaining[..start]);\n let after_start = &remaining[start + \"<thinking>\".len()..];\n\n let Some(end) = after_start.find(\"</thinking>\") else {\n break;\n };\n\n remaining = &after_start[end + \"</thinking>\".len()..];\n }\n\n out\n}\n\nfn truncate_str(s: &str, max: usize) -> String {\n let first_line = s.lines().next().unwrap_or(s);\n\n if first_line.chars().count() <= max {\n first_line.to_string()\n } else {\n let take_len = max.saturating_sub(3);\n let truncated: String = first_line.chars().take(take_len).collect();\n format!(\"{}...\", truncated)\n }\n}\n\n/// Format timestamp as relative time (e.g., \"3 days ago\", \"2 hours ago\").\nfn format_relative_time(ts: &str) -> String {\n // Parse ISO 8601 timestamp: \"2025-12-09T19:21:15.562Z\"\n let parsed = chrono::DateTime::parse_from_rfc3339(ts).or_else(|_| {\n // Try without timezone\n chrono::NaiveDateTime::parse_from_str(ts, \"%Y-%m-%dT%H:%M:%S%.fZ\")\n .map(|dt| dt.and_utc().fixed_offset())\n });\n\n let Ok(dt) = parsed else {\n return \"unknown\".to_string();\n };\n\n let now = chrono::Utc::now();\n let duration = now.signed_duration_since(dt);\n\n let seconds = duration.num_seconds();\n if seconds < 0 {\n return \"just now\".to_string();\n }\n\n let minutes = duration.num_minutes();\n let hours = duration.num_hours();\n let days = duration.num_days();\n let weeks = days / 7;\n\n if seconds < 60 {\n \"just now\".to_string()\n } else if minutes < 60 {\n format!(\"{}m ago\", minutes)\n } else if hours < 24 {\n format!(\"{}h ago\", hours)\n } else if days == 1 {\n \"yesterday\".to_string()\n } else if days < 7 {\n format!(\"{}d ago\", days)\n } else if weeks < 4 {\n format!(\"{}w ago\", weeks)\n } else {\n // Show date for older sessions\n dt.format(\"%b %d\").to_string()\n }\n}\n\n/// Check if a session name looks auto-generated (from import).\nfn is_auto_generated_name(name: &str) -> bool {\n // Auto-generated names start with date like \"20251215-\" or \"unknown-session\"\n name.starts_with(\"202\") && name.chars().nth(8) == Some('-')\n || name.starts_with(\"unknown-session\")\n}\n\nfn extract_error_summary(entry: &JsonlEntry) -> Option<String> {\n let entry_type = entry.entry_type.as_deref();\n let subtype = entry.subtype.as_deref();\n let level = entry.level.as_deref();\n\n let is_error = level == Some(\"error\")\n || entry_type == Some(\"error\")\n || subtype.map(|s| s.contains(\"error\")).unwrap_or(false)\n || entry.error.is_some();\n\n if !is_error {\n return None;\n }\n\n let mut summary = if let Some(sub) = subtype {\n format!(\"error: {}\", sub)\n } else if let Some(kind) = entry_type {\n format!(\"error: {}\", kind)\n } else {\n \"error\".to_string()\n };\n\n if let Some(err) = &entry.error {\n let msg = err\n .get(\"message\")\n .and_then(|v| v.as_str())\n .or_else(|| err.get(\"error\").and_then(|v| v.as_str()));\n if let Some(msg) = msg {\n summary = format!(\"{}: {}\", summary, msg);\n }\n }\n\n Some(summary)\n}\n\nfn extract_codex_user_message(entry: &CodexEntry) -> Option<String> {\n let entry_type = entry.entry_type.as_deref();\n\n if entry_type == Some(\"response_item\") {\n let payload = entry.payload.as_ref()?;\n if payload.get(\"type\").and_then(|v| v.as_str()) != Some(\"message\") {\n return None;\n }\n if payload.get(\"role\").and_then(|v| v.as_str()) != Some(\"user\") {\n return None;\n }\n let text = extract_codex_content_text(payload.get(\"content\")?)?;\n return normalize_session_message(\"user\", &text);\n }\n\n if entry_type == Some(\"event_msg\") {\n let payload = entry.payload.as_ref()?;\n let payload_type = payload.get(\"type\").and_then(|v| v.as_str());\n if payload_type == Some(\"user_message\") {\n return payload\n .get(\"message\")\n .and_then(|v| v.as_str())\n .and_then(|s| normalize_session_message(\"user\", s));\n }\n }\n\n if entry_type == Some(\"message\") && entry.role.as_deref() == Some(\"user\") {\n if let Some(content) = entry.content.as_ref() {\n let text = extract_codex_content_text(content)?;\n return normalize_session_message(\"user\", &text);\n }\n }\n\n None\n}\n\nfn extract_codex_error_summary(entry: &CodexEntry) -> Option<String> {\n let entry_type = entry.entry_type.as_deref();\n let payload = entry.payload.as_ref();\n\n let is_error = entry_type == Some(\"error\")\n || payload\n .and_then(|p| p.get(\"type\").and_then(|v| v.as_str()))\n .map(|t| t.contains(\"error\"))\n .unwrap_or(false);\n\n if !is_error {\n return None;\n }\n\n let mut summary = if let Some(t) = entry_type {\n format!(\"error: {}\", t)\n } else {\n \"error\".to_string()\n };\n\n if let Some(p) = payload {\n if let Some(msg) = p.get(\"message\").and_then(|v| v.as_str()) {\n summary = format!(\"{}: {}\", summary, msg);\n }\n }\n\n Some(summary)\n}\n\nfn extract_codex_content_text(value: &serde_json::Value) -> Option<String> {\n match value {\n serde_json::Value::String(s) => Some(s.clone()),\n serde_json::Value::Array(arr) => {\n let mut parts = Vec::new();\n for item in arr {\n if let Some(text) = item.get(\"text\").and_then(|v| v.as_str()) {\n parts.push(text.to_string());\n continue;\n }\n if let Some(text) = item.get(\"input_text\").and_then(|v| v.as_str()) {\n parts.push(text.to_string());\n continue;\n }\n if let Some(text) = item.get(\"output_text\").and_then(|v| v.as_str()) {\n parts.push(text.to_string());\n continue;\n }\n }\n if parts.is_empty() {\n None\n } else {\n Some(parts.join(\"\\n\"))\n }\n }\n _ => None,\n }\n}\n\n/// Clean up a summary string - remove noise, paths, special chars.\nfn clean_summary(s: &str) -> String {\n // Take first meaningful line (skip empty lines and lines starting with special chars)\n let meaningful_line = s\n .lines()\n .map(|l| l.trim())\n .find(|l| {\n !l.is_empty()\n && !l.starts_with('~')\n && !l.starts_with('/')\n && !l.starts_with('>')\n && !l.starts_with('❯')\n && !l.starts_with('$')\n && !l.starts_with('#')\n && !l.starts_with(\"Error:\")\n && !l.starts_with(\"<INSTRUCTIONS>\")\n && !l.starts_with(\"## Skills\")\n })\n .or_else(|| s.lines().find(|l| !l.trim().is_empty()))\n .unwrap_or(s);\n\n // Clean up the line\n meaningful_line.trim().replace('\\t', \" \").replace(\" \", \" \")\n}\n\nconst GEMINI_API_URL: &str = \"https://generativelanguage.googleapis.com/v1beta/models\";\nconst DEFAULT_GEMINI_MODEL: &str = \"gemini-1.5-flash\";\nconst DEFAULT_SUMMARY_AGE_MINUTES: i64 = 45;\nconst DEFAULT_SUMMARY_MAX_CHARS: usize = 12_000;\nconst DEFAULT_HANDOFF_MAX_CHARS: usize = 6_000;\n\nfn get_session_summaries_path(project_path: &PathBuf) -> PathBuf {\n project_path\n .join(\".ai\")\n .join(\"internal\")\n .join(\"session-summaries.json\")\n}\n\nfn load_session_summaries(project_path: &PathBuf) -> Result<SessionSummaries> {\n let path = get_session_summaries_path(project_path);\n if !path.exists() {\n return Ok(SessionSummaries::default());\n }\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n serde_json::from_str(&content).context(\"failed to parse session-summaries.json\")\n}\n\nfn save_session_summaries(project_path: &PathBuf, summaries: &SessionSummaries) -> Result<()> {\n let path = get_session_summaries_path(project_path);\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n let content = serde_json::to_string_pretty(summaries)?;\n fs::write(&path, content)?;\n Ok(())\n}\n\nfn summary_key(session: &CrossProjectSession) -> String {\n let provider = match session.provider {\n Provider::Claude => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n Provider::All => \"ai\",\n };\n format!(\"{}:{}\", provider, session.session_id)\n}\n\nfn get_summary_cache_entry<'a>(\n cache: &'a mut HashMap<PathBuf, SummaryCacheEntry>,\n project_path: &PathBuf,\n) -> Result<&'a mut SummaryCacheEntry> {\n if !cache.contains_key(project_path) {\n let store = load_session_summaries(project_path)?;\n cache.insert(\n project_path.clone(),\n SummaryCacheEntry {\n store,\n dirty: false,\n },\n );\n }\n Ok(cache.get_mut(project_path).expect(\"cache entry must exist\"))\n}\n\nfn summary_age_minutes() -> i64 {\n std::env::var(\"FLOW_SESSIONS_SUMMARY_AGE_MINUTES\")\n .ok()\n .and_then(|v| v.parse::<i64>().ok())\n .unwrap_or(DEFAULT_SUMMARY_AGE_MINUTES)\n}\n\nfn summary_max_chars() -> usize {\n std::env::var(\"FLOW_SESSIONS_SUMMARY_MAX_CHARS\")\n .ok()\n .and_then(|v| v.parse::<usize>().ok())\n .unwrap_or(DEFAULT_SUMMARY_MAX_CHARS)\n}\n\nfn handoff_max_chars() -> usize {\n std::env::var(\"FLOW_SESSIONS_HANDOFF_MAX_CHARS\")\n .ok()\n .and_then(|v| v.parse::<usize>().ok())\n .unwrap_or(DEFAULT_HANDOFF_MAX_CHARS)\n}\n\nfn gemini_model() -> String {\n std::env::var(\"GEMINI_MODEL\").unwrap_or_else(|_| DEFAULT_GEMINI_MODEL.to_string())\n}\n\nfn get_gemini_api_key() -> Result<String> {\n if let Ok(key) = std::env::var(\"GEMINI_API_KEY\") {\n if !key.trim().is_empty() {\n return Ok(key);\n }\n }\n if let Ok(key) = std::env::var(\"GOOGLE_API_KEY\") {\n if !key.trim().is_empty() {\n return Ok(key);\n }\n }\n\n if let Ok(Some(key)) = crate::env::get_personal_env_var(\"GEMINI_API_KEY\") {\n if !key.trim().is_empty() {\n return Ok(key);\n }\n }\n if let Ok(Some(key)) = crate::env::get_personal_env_var(\"GOOGLE_API_KEY\") {\n if !key.trim().is_empty() {\n return Ok(key);\n }\n }\n\n bail!(\"Missing GEMINI_API_KEY/GOOGLE_API_KEY (set env var or add to personal env)\")\n}\n\nfn truncate_for_summary(context: &str) -> String {\n let max_chars = summary_max_chars();\n if context.chars().count() <= max_chars {\n return context.to_string();\n }\n let start = context.chars().count().saturating_sub(max_chars);\n context.chars().skip(start).collect()\n}\n\nfn truncate_for_handoff(context: &str) -> String {\n let max_chars = handoff_max_chars();\n if context.chars().count() <= max_chars {\n return context.to_string();\n }\n let start = context.chars().count().saturating_sub(max_chars);\n context.chars().skip(start).collect()\n}\n\nfn should_summarize(last_ts: &str) -> bool {\n let Ok(ts) = chrono::DateTime::parse_from_rfc3339(last_ts) else {\n return false;\n };\n let age = chrono::Utc::now().signed_duration_since(ts);\n age.num_minutes() >= summary_age_minutes()\n}\n\nfn summarize_session_with_gemini(context: &str) -> Result<SessionSummary> {\n let api_key = get_gemini_api_key()?;\n let model = gemini_model();\n\n let prompt = format!(\n \"Summarize this coding session. Return JSON only with fields:\\n\\\nsummary: short 1-2 sentence summary (<= 220 chars), no boilerplate\\n\\\nchapters: array of 3-8 items, each with title (3-8 words) and summary (1-2 sentences)\\n\\\n\\nSession:\\n{}\",\n truncate_for_summary(context)\n );\n\n let client = crate::http_client::blocking_with_timeout(Duration::from_secs(30))\n .context(\"failed to create HTTP client\")?;\n\n let url = format!(\n \"{}/{}:generateContent?key={}\",\n GEMINI_API_URL, model, api_key\n );\n let payload = json!({\n \"contents\": [\n {\n \"role\": \"user\",\n \"parts\": [\n { \"text\": prompt }\n ]\n }\n ],\n \"generationConfig\": {\n \"temperature\": 0.2,\n \"maxOutputTokens\": 700,\n \"responseMimeType\": \"application/json\"\n }\n });\n\n let resp = client\n .post(&url)\n .json(&payload)\n .send()\n .context(\"failed to call Gemini API\")?;\n\n if !resp.status().is_success() {\n let status = resp.status();\n let text = resp.text().unwrap_or_default();\n bail!(\"Gemini API error {}: {}\", status, text);\n }\n\n let parsed: GeminiResponse = resp.json().context(\"failed to parse Gemini response\")?;\n let content = parsed\n .candidates\n .get(0)\n .and_then(|c| c.content.parts.get(0))\n .and_then(|p| p.text.as_deref())\n .unwrap_or(\"\")\n .trim();\n\n if content.is_empty() {\n bail!(\"Gemini returned empty summary\");\n }\n\n let summary_payload = parse_summary_response(content)?;\n\n Ok(SessionSummary {\n summary: summary_payload.summary,\n chapters: summary_payload.chapters,\n session_last_timestamp: None,\n model,\n updated_at: chrono::Utc::now().to_rfc3339(),\n })\n}\n\nfn summarize_handoff_with_gemini(context: &str) -> Result<String> {\n let api_key = get_gemini_api_key()?;\n let model = gemini_model();\n\n let prompt = format!(\n \"Create a concise handoff for another coding agent. Plain text only.\\n\\\nInclude these sections:\\n\\\n- Goal\\n\\\n- Current state\\n\\\n- Key files/paths\\n\\\n- Pending tasks / next steps\\n\\\n- Gotchas / blockers\\n\\\nKeep it brief (<= 12 lines). No preamble.\\n\\\n\\nSession:\\n{}\",\n truncate_for_handoff(context)\n );\n\n let client = crate::http_client::blocking_with_timeout(Duration::from_secs(30))\n .context(\"failed to create HTTP client\")?;\n\n let url = format!(\n \"{}/{}:generateContent?key={}\",\n GEMINI_API_URL, model, api_key\n );\n let payload = json!({\n \"contents\": [\n {\n \"role\": \"user\",\n \"parts\": [\n { \"text\": prompt }\n ]\n }\n ],\n \"generationConfig\": {\n \"temperature\": 0.2,\n \"maxOutputTokens\": 600,\n \"responseMimeType\": \"text/plain\"\n }\n });\n\n let resp = client\n .post(&url)\n .json(&payload)\n .send()\n .context(\"failed to call Gemini API\")?;\n\n if !resp.status().is_success() {\n let status = resp.status();\n let text = resp.text().unwrap_or_default();\n bail!(\"Gemini API error {}: {}\", status, text);\n }\n\n let parsed: GeminiResponse = resp.json().context(\"failed to parse Gemini response\")?;\n let content = parsed\n .candidates\n .get(0)\n .and_then(|c| c.content.parts.get(0))\n .and_then(|p| p.text.as_deref())\n .unwrap_or(\"\")\n .trim();\n\n if content.is_empty() {\n bail!(\"Gemini returned empty handoff\");\n }\n\n Ok(content.to_string())\n}\n\nfn parse_summary_response(content: &str) -> Result<SessionSummaryResponse> {\n if let Ok(parsed) = serde_json::from_str::<SessionSummaryResponse>(content) {\n return Ok(parsed);\n }\n\n let json_blob = extract_json_object(content)\n .ok_or_else(|| anyhow::anyhow!(\"summary response was not valid JSON\"))?;\n serde_json::from_str(&json_blob).context(\"failed to parse summary JSON\")\n}\n\nfn extract_json_object(s: &str) -> Option<String> {\n let start = s.find('{')?;\n let end = s.rfind('}')?;\n if end <= start {\n return None;\n }\n Some(s[start..=end].to_string())\n}\n\n#[derive(Debug, Deserialize)]\nstruct GeminiResponse {\n candidates: Vec<GeminiCandidate>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GeminiCandidate {\n content: GeminiContent,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GeminiContent {\n parts: Vec<GeminiPart>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GeminiPart {\n text: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct SessionSummaryResponse {\n summary: String,\n chapters: Vec<SessionChapter>,\n}\n\nfn get_display_summary(\n session: &CrossProjectSession,\n cache: &mut HashMap<PathBuf, SummaryCacheEntry>,\n) -> Result<Option<String>> {\n let key = summary_key(session);\n let entry = get_summary_cache_entry(cache, &session.project_path)?;\n if let Some(summary) = entry.store.summaries.get(&key) {\n if !summary.summary.trim().is_empty() {\n return Ok(Some(summary.summary.clone()));\n }\n }\n Ok(None)\n}\n\n/// Return provider:session_id for the most recent session in the project.\npub fn get_latest_session_ref_for_path(project_path: &PathBuf) -> Result<Option<String>> {\n let sessions = read_sessions_for_path(Provider::All, project_path)?;\n Ok(sessions\n .first()\n .map(|session| format_session_ref(session, true)))\n}\n\n/// Return full message history for the latest session matching a path.\npub fn get_latest_session_history_for_path(\n project_path: &PathBuf,\n) -> Result<Option<SessionHistory>> {\n let sessions = read_sessions_for_path(Provider::All, project_path)?;\n let Some(session) = sessions.first() else {\n return Ok(None);\n };\n let session_messages =\n read_session_messages_for_path(project_path, &session.session_id, session.provider)?;\n let provider = match session.provider {\n Provider::Claude => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n Provider::All => \"unknown\",\n };\n\n let started_at = session_messages\n .started_at\n .clone()\n .or_else(|| session.timestamp.clone());\n let last_message_at = session_messages\n .last_message_at\n .clone()\n .or_else(|| session.last_message_at.clone())\n .or_else(|| started_at.clone());\n\n Ok(Some(SessionHistory {\n session_id: session.session_id.clone(),\n provider: provider.to_string(),\n started_at,\n last_message_at,\n messages: session_messages.messages,\n }))\n}\n\nfn maybe_update_summary(\n session: &CrossProjectSession,\n cache: &mut HashMap<PathBuf, SummaryCacheEntry>,\n) -> Result<()> {\n let Some(last_ts) = get_session_last_timestamp_for_session(session)? else {\n return Ok(());\n };\n\n if !should_summarize(&last_ts) {\n return Ok(());\n }\n\n let key = summary_key(session);\n let entry = get_summary_cache_entry(cache, &session.project_path)?;\n if let Some(existing) = entry.store.summaries.get(&key) {\n if existing.session_last_timestamp.as_deref() == Some(last_ts.as_str()) {\n return Ok(());\n }\n }\n\n let (context, context_last_ts) = read_cross_project_context(session, None, None)?;\n if context.trim().is_empty() {\n return Ok(());\n }\n\n let mut summary = summarize_session_with_gemini(&context)?;\n summary.session_last_timestamp = Some(context_last_ts.unwrap_or(last_ts));\n\n entry.store.summaries.insert(key, summary);\n entry.dirty = true;\n\n Ok(())\n}\n\nfn save_summary_cache(cache: &mut HashMap<PathBuf, SummaryCacheEntry>) -> Result<()> {\n for (project_path, entry) in cache.iter_mut() {\n if entry.dirty {\n save_session_summaries(project_path, &entry.store)?;\n entry.dirty = false;\n }\n }\n Ok(())\n}\n\nfn get_session_last_timestamp_for_session(session: &CrossProjectSession) -> Result<Option<String>> {\n if session.provider == Provider::Codex {\n let session_file = session\n .session_path\n .clone()\n .or_else(|| find_codex_session_file(&session.session_id));\n let Some(session_file) = session_file else {\n return Ok(None);\n };\n return get_codex_last_timestamp(&session_file);\n }\n\n get_session_last_timestamp_for_path(\n &session.session_id,\n session.provider,\n &session.project_path,\n )\n}\n\n/// Resume a session by name or ID.\nfn resume_session(session: Option<String>, path: Option<String>, provider: Provider) -> Result<()> {\n let index = load_index()?;\n let sessions = read_sessions_for_target(provider, path.as_deref())?;\n let explicit_session_requested = session.is_some();\n let default_provider = if provider == Provider::All {\n Provider::Claude\n } else {\n provider\n };\n\n let (session_id, session_provider) = match session {\n Some(s) => {\n // Check if it's a saved name\n if let Some(saved) = index.sessions.get(&s) {\n // Find the provider for this session\n let prov = sessions\n .iter()\n .find(|sess| sess.session_id == saved.id)\n .map(|sess| sess.provider)\n .unwrap_or(default_provider);\n (saved.id.clone(), prov)\n } else if s.len() >= 8 {\n // Might be a session ID or prefix\n if let Some(sess) = sessions.iter().find(|sess| sess.session_id.starts_with(&s)) {\n (sess.session_id.clone(), sess.provider)\n } else {\n // Assume it's a full ID for requested provider.\n (s, default_provider)\n }\n } else {\n // Try numeric index (1-based)\n if let Ok(idx) = s.parse::<usize>() {\n if idx > 0 && idx <= sessions.len() {\n let sess = &sessions[idx - 1];\n (sess.session_id.clone(), sess.provider)\n } else {\n bail!(\"Session index {} out of range\", idx);\n }\n } else {\n bail!(\"Session '{}' not found\", s);\n }\n }\n }\n None => {\n // Resume most recent\n let sess = sessions\n .first()\n .ok_or_else(|| anyhow::anyhow!(\"No sessions found for this project\"))?;\n (sess.session_id.clone(), sess.provider)\n }\n };\n\n let has_tty = io::stdin().is_terminal() && io::stdout().is_terminal();\n if !has_tty {\n match session_provider {\n Provider::Codex => {\n bail!(\n \"codex resume requires an interactive terminal (TTY); run this in a terminal tab (e.g. Zed/Ghostty)\"\n );\n }\n Provider::Claude => {\n bail!(\n \"claude resume requires an interactive terminal (TTY); run this in a terminal tab (e.g. Zed/Ghostty)\"\n );\n }\n Provider::Cursor => {\n bail!(\n \"cursor transcripts are readable only; use `f cursor list`, `f cursor copy`, or `f cursor context`\"\n );\n }\n Provider::All => {}\n }\n }\n\n if session_provider == Provider::Cursor {\n bail!(\n \"cursor transcripts are readable only; use `f cursor list`, `f cursor copy`, or `f cursor context`\"\n );\n }\n\n println!(\n \"Resuming session {}...\",\n &session_id[..8.min(session_id.len())]\n );\n let launched = launch_session(&session_id, session_provider)?;\n if launched {\n return Ok(());\n }\n\n // Claude occasionally cannot reopen older local transcript IDs.\n // For explicit IDs, do not auto-fallback to --continue because that can\n // open a different conversation and hide the failure.\n if session_provider == Provider::Claude {\n eprintln!(\n \"Claude could not resume session {}.\",\n &session_id[..8.min(session_id.len())]\n );\n if explicit_session_requested {\n bail!(\n \"failed to resume exact claude session {}. refusing fallback to `claude --continue` to avoid opening the wrong session\",\n session_id\n );\n }\n if !has_tty {\n bail!(\n \"failed to resume claude session {} (non-interactive shell; fallback continue unavailable)\",\n session_id\n );\n }\n eprintln!(\"Falling back to `claude --continue` in this directory...\");\n let continued = launch_claude_continue()?;\n if continued {\n return Ok(());\n }\n bail!(\n \"failed to resume claude session {} and fallback `claude --continue` also failed\",\n session_id\n );\n }\n\n bail!(\n \"failed to resume {} session {}\",\n provider_name(session_provider),\n session_id\n );\n}\n\n/// Save a session with a name.\nfn save_session(name: &str, id: Option<String>) -> Result<()> {\n let session_id = match id {\n Some(id) => id,\n None => get_most_recent_session_id()?\n .ok_or_else(|| anyhow::anyhow!(\"No sessions found. Start an AI session first.\"))?,\n };\n\n let mut index = load_index()?;\n\n // Check if name already exists\n if index.sessions.contains_key(name) {\n bail!(\n \"Session name '{}' already exists. Use a different name or remove it first.\",\n name\n );\n }\n\n let session_provider = read_sessions_for_project(Provider::All)?\n .into_iter()\n .find(|session| session.session_id == session_id)\n .map(|session| session.provider)\n .unwrap_or(Provider::Claude);\n\n let saved = SavedSession {\n id: session_id.clone(),\n provider: provider_name(session_provider).to_string(),\n description: None,\n saved_at: chrono::Utc::now().to_rfc3339(),\n last_resumed: None,\n };\n\n index.sessions.insert(name.to_string(), saved);\n save_index(&index)?;\n\n println!(\"Saved session as '{}'\", name);\n println!(\" ID: {}\", &session_id[..8.min(session_id.len())]);\n println!(\"\\nResume with: f ai resume {}\", name);\n\n Ok(())\n}\n\n/// Open or create notes for a session.\nfn open_notes(session: &str) -> Result<()> {\n let index = load_index()?;\n\n // Find the session ID\n let session_id = if let Some(saved) = index.sessions.get(session) {\n saved.id.clone()\n } else {\n // Might be a direct ID\n session.to_string()\n };\n\n let notes_dir = get_notes_dir()?;\n fs::create_dir_all(¬es_dir)?;\n\n let note_file = notes_dir.join(format!(\"{}.md\", session));\n\n // Create the file if it doesn't exist\n if !note_file.exists() {\n let template = format!(\n \"# Session: {}\\n\\nSession ID: {}\\n\\n## Notes\\n\\n\",\n session,\n &session_id[..8.min(session_id.len())]\n );\n fs::write(¬e_file, template)?;\n }\n\n // Open in $EDITOR\n let editor = std::env::var(\"EDITOR\").unwrap_or_else(|_| \"vim\".to_string());\n let status = Command::new(&editor)\n .arg(¬e_file)\n .status()\n .with_context(|| format!(\"failed to open editor: {}\", editor))?;\n\n if !status.success() {\n bail!(\"editor exited with status {}\", status);\n }\n\n Ok(())\n}\n\n/// Remove a saved session from tracking.\nfn remove_session(session: &str) -> Result<()> {\n let mut index = load_index()?;\n\n if index.sessions.remove(session).is_some() {\n save_index(&index)?;\n println!(\"Removed session '{}'\", session);\n\n // Also remove notes if they exist\n let notes_dir = get_notes_dir()?;\n let note_file = notes_dir.join(format!(\"{}.md\", session));\n if note_file.exists() {\n fs::remove_file(¬e_file)?;\n println!(\"Removed notes file\");\n }\n } else {\n bail!(\"Session '{}' not found in saved sessions\", session);\n }\n\n Ok(())\n}\n\n/// Initialize the .ai folder structure.\nfn init_ai_folder() -> Result<()> {\n let ai_dir = std::env::current_dir()?.join(\".ai\");\n let internal_dir = ai_dir.join(\"internal\");\n let sessions_dir = internal_dir.join(\"sessions\").join(\"claude\");\n let notes_dir = sessions_dir.join(\"notes\");\n\n fs::create_dir_all(¬es_dir)?;\n\n // Create empty index.json if it doesn't exist\n let index_path = sessions_dir.join(\"index.json\");\n if !index_path.exists() {\n let index = SessionIndex::default();\n let content = serde_json::to_string_pretty(&index)?;\n fs::write(&index_path, content)?;\n }\n\n println!(\"Initialized .ai folder structure:\");\n println!(\" .ai/internal/sessions/claude/index.json\");\n println!(\" .ai/internal/sessions/claude/notes/\");\n\n Ok(())\n}\n\n/// Ensure .ai/internal is in the project's .gitignore to prevent session leaks.\nfn ensure_gitignore() -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n let gitignore_path = cwd.join(\".gitignore\");\n\n if gitignore_path.exists() {\n let content = fs::read_to_string(&gitignore_path).unwrap_or_default();\n // Check if .ai/internal is already ignored\n let already_ignored = content.lines().any(|line| {\n let trimmed = line.trim();\n trimmed == \".ai/internal\"\n || trimmed == \".ai/internal/\"\n || trimmed == \"/.ai/internal\"\n || trimmed == \"/.ai/internal/\"\n });\n\n if !already_ignored {\n // Append .ai/internal to gitignore\n let mut file = fs::OpenOptions::new().append(true).open(&gitignore_path)?;\n // Add newline if file doesn't end with one\n if !content.ends_with('\\n') && !content.is_empty() {\n writeln!(file)?;\n }\n writeln!(file, \".ai/internal/\")?;\n }\n } else {\n // Create .gitignore with .ai/internal\n fs::write(&gitignore_path, \".ai/internal/\\n\")?;\n }\n\n Ok(())\n}\n\n/// Silently auto-import any new Claude sessions (called by list_sessions).\nfn auto_import_sessions() -> Result<()> {\n // Ensure .ai is in .gitignore to prevent session leaks\n let _ = ensure_gitignore();\n\n // Silently ensure .ai folder exists\n let sessions_dir = get_ai_sessions_dir()?;\n if !sessions_dir.exists() {\n fs::create_dir_all(&sessions_dir)?;\n let index_path = sessions_dir.join(\"index.json\");\n fs::write(&index_path, \"{\\\"sessions\\\":{}}\")?;\n }\n\n let sessions = read_sessions_for_project(Provider::Claude)?;\n if sessions.is_empty() {\n return Ok(());\n }\n\n let mut index = load_index()?;\n let mut changed = false;\n\n for session in &sessions {\n // Skip if already imported\n if index.sessions.values().any(|s| s.id == session.session_id) {\n continue;\n }\n\n let name = generate_session_name(session, &index);\n let provider_str = match session.provider {\n Provider::Claude => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n Provider::All => \"claude\",\n };\n let saved = SavedSession {\n id: session.session_id.clone(),\n provider: provider_str.to_string(),\n description: session\n .first_message\n .as_ref()\n .or(session.error_summary.as_ref())\n .map(|m| {\n if m.len() > 100 {\n let end = floor_char_boundary(m, 97);\n format!(\"{}...\", &m[..end])\n } else {\n m.clone()\n }\n }),\n saved_at: chrono::Utc::now().to_rfc3339(),\n last_resumed: None,\n };\n\n index.sessions.insert(name, saved);\n changed = true;\n }\n\n if changed {\n save_index(&index)?;\n }\n\n Ok(())\n}\n\n/// Import all existing Claude sessions for this project.\nfn import_sessions() -> Result<()> {\n // Ensure .ai folder exists\n init_ai_folder()?;\n println!();\n\n let sessions = read_sessions_for_project(Provider::Claude)?;\n\n if sessions.is_empty() {\n println!(\"No Claude sessions found for this project.\");\n return Ok(());\n }\n\n let mut index = load_index()?;\n let mut imported = 0;\n let mut skipped = 0;\n\n for session in &sessions {\n // Check if already imported\n if index.sessions.values().any(|s| s.id == session.session_id) {\n skipped += 1;\n continue;\n }\n\n // Generate a name from timestamp and first few words of first message\n let name = generate_session_name(session, &index);\n\n let provider_str = match session.provider {\n Provider::Claude => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n Provider::All => \"claude\",\n };\n let saved = SavedSession {\n id: session.session_id.clone(),\n provider: provider_str.to_string(),\n description: session\n .first_message\n .as_ref()\n .or(session.error_summary.as_ref())\n .map(|m| {\n if m.len() > 100 {\n let end = floor_char_boundary(m, 97);\n format!(\"{}...\", &m[..end])\n } else {\n m.clone()\n }\n }),\n saved_at: chrono::Utc::now().to_rfc3339(),\n last_resumed: None,\n };\n\n index.sessions.insert(name.clone(), saved);\n imported += 1;\n\n let id_short = &session.session_id[..8.min(session.session_id.len())];\n println!(\" Imported: {} ({})\", name, id_short);\n }\n\n save_index(&index)?;\n\n println!();\n println!(\n \"Imported {} sessions, skipped {} (already exists)\",\n imported, skipped\n );\n\n Ok(())\n}\n\n/// Generate a unique name for a session based on its content.\nfn generate_session_name(session: &AiSession, index: &SessionIndex) -> String {\n // Try to create a name from date + first words of message\n let date_part = session\n .timestamp\n .as_deref()\n .map(|ts| ts[..10].replace('-', \"\")) // \"20251209\"\n .unwrap_or_else(|| \"unknown\".to_string());\n\n let words_part = session\n .first_message\n .as_deref()\n .or(session.error_summary.as_deref())\n .map(|msg| {\n // Extract first few meaningful words\n let words: Vec<&str> = msg\n .split_whitespace()\n .filter(|w| w.len() > 2 && !w.starts_with('/') && !w.starts_with('~'))\n .take(3)\n .collect();\n\n if words.is_empty() {\n \"session\".to_string()\n } else {\n words\n .join(\"-\")\n .to_lowercase()\n .chars()\n .filter(|c| c.is_alphanumeric() || *c == '-')\n .take(20)\n .collect()\n }\n })\n .unwrap_or_else(|| \"session\".to_string());\n\n let base_name = format!(\"{}-{}\", date_part, words_part);\n\n // Ensure uniqueness\n if !index.sessions.contains_key(&base_name) {\n return base_name;\n }\n\n // Add suffix if name exists\n for i in 2..100 {\n let name = format!(\"{}-{}\", base_name, i);\n if !index.sessions.contains_key(&name) {\n return name;\n }\n }\n\n // Fallback to UUID prefix\n format!(\"{}-{}\", base_name, &session.session_id[..8])\n}\n\n// ============================================================================\n// Cross-project session search (f sessions)\n// ============================================================================\n\nuse crate::cli::SessionsOpts;\n\n/// Session with project info for cross-project display.\n#[derive(Debug, Clone)]\nstruct CrossProjectSession {\n session_id: String,\n provider: Provider,\n project_path: PathBuf,\n project_name: String,\n timestamp: Option<String>,\n first_message: Option<String>,\n error_summary: Option<String>,\n session_path: Option<PathBuf>,\n}\n\n#[derive(Debug, Serialize, Deserialize, Default)]\nstruct SessionSummaries {\n summaries: HashMap<String, SessionSummary>,\n}\n\n#[derive(Debug, Serialize, Deserialize, Clone)]\nstruct SessionSummary {\n summary: String,\n chapters: Vec<SessionChapter>,\n session_last_timestamp: Option<String>,\n model: String,\n updated_at: String,\n}\n\n#[derive(Debug, Serialize, Deserialize, Clone)]\nstruct SessionChapter {\n title: String,\n summary: String,\n}\n\nstruct SummaryCacheEntry {\n store: SessionSummaries,\n dirty: bool,\n}\n\n/// Consumed checkpoint tracking - stored in target project's .ai folder.\n#[derive(Debug, Serialize, Deserialize, Default)]\nstruct ConsumedCheckpoints {\n /// Map of source project path -> last consumed timestamp\n consumed: HashMap<String, ConsumedEntry>,\n}\n\n#[derive(Debug, Serialize, Deserialize, Clone)]\nstruct ConsumedEntry {\n /// Last consumed timestamp from that project\n last_timestamp: String,\n /// When we consumed it\n consumed_at: String,\n /// Session ID we consumed from\n session_id: String,\n}\n\n/// Run cross-project session search.\npub fn run_sessions(opts: &SessionsOpts) -> Result<()> {\n let provider = match opts.provider.to_lowercase().as_str() {\n \"claude\" => Provider::Claude,\n \"codex\" => Provider::Codex,\n \"cursor\" => Provider::Cursor,\n _ => Provider::All,\n };\n\n let sessions = scan_all_project_sessions(provider)?;\n let mut summary_cache: HashMap<PathBuf, SummaryCacheEntry> = HashMap::new();\n let summarize_enabled = opts.summarize && get_gemini_api_key().is_ok();\n\n if sessions.is_empty() {\n println!(\"No AI sessions found across projects.\");\n return Ok(());\n }\n\n if opts.summarize && !summarize_enabled {\n println!(\"GEMINI_API_KEY/GOOGLE_API_KEY not set; skipping session summaries.\");\n }\n\n if summarize_enabled {\n for session in &sessions {\n let _ = maybe_update_summary(session, &mut summary_cache);\n }\n let _ = save_summary_cache(&mut summary_cache);\n }\n\n if opts.list {\n // Just list, don't fuzzy search\n println!(\"AI Sessions across projects:\\n\");\n for session in &sessions {\n let relative_time = session\n .timestamp\n .as_deref()\n .map(format_relative_time)\n .unwrap_or_else(|| \"unknown\".to_string());\n let summary = get_display_summary(session, &mut summary_cache)?\n .or_else(|| {\n session\n .first_message\n .as_deref()\n .or(session.error_summary.as_deref())\n .map(|s| s.to_string())\n })\n .map(|s| truncate_str(&clean_summary(&s), 50))\n .unwrap_or_default();\n let provider_tag = match session.provider {\n Provider::Claude => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n Provider::All => \"ai\",\n };\n println!(\n \"{} | {} | {} | {}\",\n session.project_name, provider_tag, relative_time, summary\n );\n }\n return Ok(());\n }\n\n // Build fzf entries\n let entries: Vec<(String, &CrossProjectSession)> = sessions\n .iter()\n .filter(|s| s.timestamp.is_some() || s.first_message.is_some() || s.error_summary.is_some())\n .map(|session| {\n let relative_time = session\n .timestamp\n .as_deref()\n .map(format_relative_time)\n .unwrap_or_else(|| \"\".to_string());\n let summary = get_display_summary(session, &mut summary_cache)\n .unwrap_or(None)\n .or_else(|| {\n session\n .first_message\n .as_deref()\n .or(session.error_summary.as_deref())\n .map(|s| s.to_string())\n })\n .map(|s| truncate_str(&clean_summary(&s), 40))\n .unwrap_or_default();\n let provider_tag = match session.provider {\n Provider::Claude => \"claude\",\n Provider::Codex => \"codex\",\n Provider::Cursor => \"cursor\",\n Provider::All => \"\",\n };\n let display = format!(\n \"{} | {} | {} | {}\",\n session.project_name, provider_tag, relative_time, summary\n );\n (display, session)\n })\n .collect();\n\n if entries.is_empty() {\n println!(\"No sessions with content found.\");\n return Ok(());\n }\n\n // Check for fzf\n if which::which(\"fzf\").is_err() {\n println!(\"fzf not found – install it for fuzzy selection.\");\n println!(\"\\nSessions:\");\n for (display, _) in &entries {\n println!(\"{}\", display);\n }\n return Ok(());\n }\n\n // Run fzf\n let mut child = Command::new(\"fzf\")\n .arg(\"--prompt\")\n .arg(\"sessions> \")\n .arg(\"--ansi\")\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n {\n let stdin = child.stdin.as_mut().context(\"failed to open fzf stdin\")?;\n for (display, _) in &entries {\n writeln!(stdin, \"{}\", display)?;\n }\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(());\n }\n\n let selection = String::from_utf8(output.stdout).context(\"fzf output was not valid UTF-8\")?;\n let selection = selection.trim();\n\n if selection.is_empty() {\n return Ok(());\n }\n\n // Find selected session\n let Some((_, session)) = entries.iter().find(|(d, _)| d == selection) else {\n bail!(\"Session not found\");\n };\n\n // Get context since last consumed checkpoint (or full if --full)\n let context = get_cross_project_context(session, opts.count, opts.full)?;\n\n if context.is_empty() {\n if opts.full {\n println!(\"No context found in session.\");\n } else {\n println!(\"No new context since last consumption. Use --full for entire session.\");\n }\n return Ok(());\n }\n\n let output = if opts.handoff {\n summarize_handoff_with_gemini(&context)?\n } else {\n context\n };\n\n // Copy to clipboard\n copy_to_clipboard(&output)?;\n\n let explains = if opts.handoff {\n \"handoff summary\"\n } else {\n \"context\"\n };\n\n let line_count = output.lines().count();\n println!(\n \"Copied {} from {} ({} lines) to clipboard\",\n explains, session.project_name, line_count\n );\n\n // Save consumed checkpoint\n save_consumed_checkpoint(session)?;\n\n Ok(())\n}\n\n/// Scan all projects for AI sessions.\nfn scan_all_project_sessions(provider: Provider) -> Result<Vec<CrossProjectSession>> {\n let mut all_sessions = Vec::new();\n\n // Scan Claude projects\n if provider == Provider::Claude || provider == Provider::All {\n let claude_dir = get_claude_projects_dir();\n if claude_dir.exists() {\n if let Ok(entries) = fs::read_dir(&claude_dir) {\n for entry in entries.flatten() {\n let project_folder = entry.path();\n if project_folder.is_dir() {\n let project_name = extract_project_name(&project_folder);\n let project_path = folder_to_path(&project_folder);\n\n if let Ok(sessions) =\n scan_project_sessions(&project_folder, Provider::Claude)\n {\n for session in sessions {\n all_sessions.push(CrossProjectSession {\n session_id: session.session_id,\n provider: Provider::Claude,\n project_path: project_path.clone(),\n project_name: project_name.clone(),\n timestamp: session.timestamp,\n first_message: session.first_message,\n error_summary: session.error_summary,\n session_path: None,\n });\n }\n }\n }\n }\n }\n }\n }\n\n // Scan Codex sessions (new format)\n if provider == Provider::Codex || provider == Provider::All {\n let codex_dir = get_codex_sessions_dir();\n if codex_dir.exists() {\n for file_path in collect_codex_session_files(&codex_dir) {\n let filename = file_path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n let Some((session, cwd)) = parse_codex_session_file(&file_path, filename) else {\n continue;\n };\n let Some(project_path) = cwd else {\n continue;\n };\n let project_name = project_path\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(\"unknown\")\n .to_string();\n\n all_sessions.push(CrossProjectSession {\n session_id: session.session_id,\n provider: Provider::Codex,\n project_path,\n project_name,\n timestamp: session.timestamp,\n first_message: session.first_message,\n error_summary: session.error_summary,\n session_path: Some(file_path),\n });\n }\n } else {\n // Fallback to legacy Codex projects layout\n let codex_dir = get_codex_projects_dir();\n if codex_dir.exists() {\n if let Ok(entries) = fs::read_dir(&codex_dir) {\n for entry in entries.flatten() {\n let project_folder = entry.path();\n if project_folder.is_dir() {\n let project_name = extract_project_name(&project_folder);\n let project_path = folder_to_path(&project_folder);\n\n if let Ok(sessions) =\n scan_project_sessions(&project_folder, Provider::Codex)\n {\n for session in sessions {\n all_sessions.push(CrossProjectSession {\n session_id: session.session_id,\n provider: Provider::Codex,\n project_path: project_path.clone(),\n project_name: project_name.clone(),\n timestamp: session.timestamp,\n first_message: session.first_message,\n error_summary: session.error_summary,\n session_path: None,\n });\n }\n }\n }\n }\n }\n }\n }\n }\n\n // Scan Cursor agent transcripts.\n if provider == Provider::Cursor || provider == Provider::All {\n let cursor_dir = get_cursor_projects_dir();\n if cursor_dir.exists() {\n if let Ok(entries) = fs::read_dir(&cursor_dir) {\n for entry in entries.flatten() {\n let project_dir = entry.path();\n if !project_dir.is_dir() {\n continue;\n }\n\n let Some(project_key) = project_dir.file_name().and_then(|name| name.to_str())\n else {\n continue;\n };\n let Some(project_path) = decode_cursor_project_path(project_key) else {\n continue;\n };\n let project_name = project_path\n .file_name()\n .and_then(|name| name.to_str())\n .unwrap_or(project_key)\n .to_string();\n\n for file_path in collect_cursor_project_session_files(&project_dir) {\n let filename = file_path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n let Some(session) = parse_cursor_session_file(&file_path, filename) else {\n continue;\n };\n\n all_sessions.push(CrossProjectSession {\n session_id: session.session_id,\n provider: Provider::Cursor,\n project_path: project_path.clone(),\n project_name: project_name.clone(),\n timestamp: session.timestamp,\n first_message: session.first_message,\n error_summary: session.error_summary,\n session_path: Some(file_path),\n });\n }\n }\n }\n }\n }\n\n // Sort by timestamp descending (most recent first)\n all_sessions.sort_by(|a, b| {\n let ts_a = a.timestamp.as_deref().unwrap_or(\"\");\n let ts_b = b.timestamp.as_deref().unwrap_or(\"\");\n ts_b.cmp(ts_a)\n });\n\n Ok(all_sessions)\n}\n\n/// Scan a project folder for sessions.\nfn scan_project_sessions(project_folder: &PathBuf, provider: Provider) -> Result<Vec<AiSession>> {\n let mut sessions = Vec::new();\n\n let entries = fs::read_dir(project_folder)\n .with_context(|| format!(\"failed to read {}\", project_folder.display()))?;\n\n for entry in entries.flatten() {\n let path = entry.path();\n if path.extension().map(|e| e == \"jsonl\").unwrap_or(false) {\n let filename = path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n\n if filename.starts_with(\"agent-\") {\n continue;\n }\n\n if let Some(session) = parse_session_file(&path, filename, provider) {\n sessions.push(session);\n }\n }\n }\n\n // Sort by timestamp descending\n sessions.sort_by(|a, b| {\n let ts_a = a.timestamp.as_deref().unwrap_or(\"\");\n let ts_b = b.timestamp.as_deref().unwrap_or(\"\");\n ts_b.cmp(ts_a)\n });\n\n Ok(sessions)\n}\n\n/// Extract a friendly project name from the folder name.\nfn extract_project_name(folder: &PathBuf) -> String {\n folder\n .file_name()\n .and_then(|s| s.to_str())\n .map(|s| {\n // The folder name is path with / replaced by -\n // Extract just the last component as project name\n s.rsplit('-').next().unwrap_or(s).to_string()\n })\n .unwrap_or_else(|| \"unknown\".to_string())\n}\n\n/// Convert folder name back to approximate path.\nfn folder_to_path(folder: &PathBuf) -> PathBuf {\n let name = folder.file_name().and_then(|s| s.to_str()).unwrap_or(\"\");\n // Folder name is path with / replaced by -\n // This is a heuristic - convert leading - to /\n PathBuf::from(name.replacen('-', \"/\", name.matches('-').count()))\n}\n\n/// Get context from a cross-project session since last consumed checkpoint.\nfn get_cross_project_context(\n session: &CrossProjectSession,\n count: Option<usize>,\n full: bool,\n) -> Result<String> {\n // If full mode, ignore checkpoints\n let since_ts = if full {\n None\n } else {\n // Load consumed checkpoints for current project\n let cwd = std::env::current_dir()?;\n let consumed = load_consumed_checkpoints(&cwd)?;\n let source_key = session.project_path.to_string_lossy().to_string();\n consumed\n .consumed\n .get(&source_key)\n .map(|e| e.last_timestamp.clone())\n };\n\n // Read context since checkpoint (or full if since_ts is None)\n let (context, _last_ts) = read_cross_project_context(session, since_ts.as_deref(), count)?;\n\n Ok(context)\n}\n\n/// Read context from a cross-project session.\nfn read_cross_project_context(\n session: &CrossProjectSession,\n since_ts: Option<&str>,\n max_count: Option<usize>,\n) -> Result<(String, Option<String>)> {\n if session.provider == Provider::Codex {\n let session_file = session\n .session_path\n .clone()\n .or_else(|| find_codex_session_file(&session.session_id));\n let Some(session_file) = session_file else {\n bail!(\n \"Session file not found for Codex session {}\",\n session.session_id\n );\n };\n return read_codex_cross_project_context(session, &session_file, since_ts, max_count);\n }\n if session.provider == Provider::Cursor {\n let session_file = session\n .session_path\n .clone()\n .or_else(|| find_cursor_session_file(&session.session_id));\n let Some(session_file) = session_file else {\n bail!(\n \"Session file not found for Cursor session {}\",\n session.session_id\n );\n };\n return read_cursor_cross_project_context(session, &session_file, since_ts, max_count);\n }\n\n let projects_dir = match session.provider {\n Provider::Claude | Provider::All => get_claude_projects_dir(),\n Provider::Codex => get_codex_projects_dir(),\n Provider::Cursor => get_cursor_projects_dir(),\n };\n\n let project_folder = session.project_path.to_string_lossy().replace('/', \"-\");\n let session_file = projects_dir\n .join(&project_folder)\n .join(format!(\"{}.jsonl\", session.session_id));\n\n if !session_file.exists() {\n bail!(\"Session file not found: {}\", session_file.display());\n }\n\n // Collect exchanges after the checkpoint timestamp\n let mut exchanges: Vec<(String, String, String)> = Vec::new();\n let mut current_user: Option<String> = None;\n let mut current_ts: Option<String> = None;\n let mut last_ts: Option<String> = None;\n\n for_each_nonempty_jsonl_line(&session_file, |line| {\n if let Ok(entry) = crate::json_parse::parse_json_line::<JsonlEntry>(line) {\n let entry_ts = entry.timestamp.clone();\n\n // Skip entries before checkpoint\n if let (Some(since), Some(ts)) = (since_ts, &entry_ts) {\n if ts.as_str() <= since {\n return;\n }\n }\n\n if let Some(ref msg) = entry.message {\n let role = msg.role.as_deref().unwrap_or(\"unknown\");\n\n let Some(content_text) = msg.content.as_ref().and_then(extract_message_text) else {\n return;\n };\n let Some(clean_text) = normalize_session_message(role, &content_text) else {\n return;\n };\n\n match role {\n \"user\" => {\n current_user = Some(clean_text);\n current_ts = entry_ts.clone();\n }\n \"assistant\" => {\n if let Some(user_msg) = current_user.take() {\n let ts = current_ts.take().or(entry_ts.clone()).unwrap_or_default();\n exchanges.push((user_msg, clean_text, ts.clone()));\n last_ts = Some(ts);\n }\n }\n _ => {}\n }\n }\n\n if entry_ts.is_some() {\n last_ts = entry_ts;\n }\n }\n })?;\n\n if exchanges.is_empty() {\n return Ok((String::new(), last_ts));\n }\n\n // Limit exchanges if count specified\n let exchanges_to_use = if let Some(count) = max_count {\n let start = exchanges.len().saturating_sub(count);\n &exchanges[start..]\n } else {\n &exchanges[..]\n };\n\n // Format the context with project info\n let mut context = format!(\n \"=== Context from {} ({}) ===\\n\\n\",\n session.project_name,\n match session.provider {\n Provider::Claude => \"Claude Code\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n }\n );\n\n for (user_msg, assistant_msg, _ts) in exchanges_to_use {\n context.push_str(\"H: \");\n context.push_str(user_msg);\n context.push_str(\"\\n\\n\");\n context.push_str(\"A: \");\n context.push_str(assistant_msg);\n context.push_str(\"\\n\\n\");\n }\n\n context.push_str(\"=== End Context ===\\n\");\n\n Ok((context, last_ts))\n}\n\nfn find_codex_session_file(session_id: &str) -> Option<PathBuf> {\n let root = get_codex_sessions_dir();\n if !root.exists() {\n return None;\n }\n\n let mut stack = vec![root];\n while let Some(dir) = stack.pop() {\n let entries = match fs::read_dir(&dir) {\n Ok(v) => v,\n Err(_) => continue,\n };\n\n for entry in entries.flatten() {\n let path = entry.path();\n if path.is_dir() {\n stack.push(path);\n } else if path.extension().map(|e| e == \"jsonl\").unwrap_or(false) {\n let filename = path.file_name().and_then(|s| s.to_str()).unwrap_or(\"\");\n if filename.contains(session_id) {\n return Some(path);\n }\n }\n }\n }\n\n None\n}\n\nfn find_cursor_session_file(session_id: &str) -> Option<PathBuf> {\n let root = get_cursor_projects_dir();\n if !root.exists() {\n return None;\n }\n\n let entries = fs::read_dir(&root).ok()?;\n for entry in entries.flatten() {\n let project_dir = entry.path();\n if !project_dir.is_dir() {\n continue;\n }\n\n for file_path in collect_cursor_project_session_files(&project_dir) {\n let filename = file_path.file_name().and_then(|s| s.to_str()).unwrap_or(\"\");\n if filename.contains(session_id) {\n return Some(file_path);\n }\n }\n }\n\n None\n}\n\nfn read_codex_cross_project_context(\n session: &CrossProjectSession,\n session_file: &PathBuf,\n since_ts: Option<&str>,\n max_count: Option<usize>,\n) -> Result<(String, Option<String>)> {\n let (exchanges, last_ts) = read_codex_exchanges(session_file, since_ts, None)?;\n\n if exchanges.is_empty() {\n return Ok((String::new(), last_ts));\n }\n\n let exchanges_to_use = if let Some(count) = max_count {\n let start = exchanges.len().saturating_sub(count);\n &exchanges[start..]\n } else {\n &exchanges[..]\n };\n\n let mut context = format!(\n \"=== Context from {} ({}) ===\\n\\n\",\n session.project_name,\n match session.provider {\n Provider::Claude => \"Claude Code\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n }\n );\n\n for (user_msg, assistant_msg, _ts) in exchanges_to_use {\n context.push_str(\"H: \");\n context.push_str(user_msg);\n context.push_str(\"\\n\\n\");\n context.push_str(\"A: \");\n context.push_str(assistant_msg);\n context.push_str(\"\\n\\n\");\n }\n\n context.push_str(\"=== End Context ===\\n\");\n\n Ok((context, last_ts))\n}\n\nfn read_cursor_cross_project_context(\n session: &CrossProjectSession,\n session_file: &PathBuf,\n since_ts: Option<&str>,\n max_count: Option<usize>,\n) -> Result<(String, Option<String>)> {\n let (exchanges, last_ts) = read_cursor_exchanges(session_file, since_ts, None)?;\n\n if exchanges.is_empty() {\n return Ok((String::new(), last_ts));\n }\n\n let exchanges_to_use = if let Some(count) = max_count {\n let start = exchanges.len().saturating_sub(count);\n &exchanges[start..]\n } else {\n &exchanges[..]\n };\n\n let mut context = format!(\n \"=== Context from {} ({}) ===\\n\\n\",\n session.project_name,\n match session.provider {\n Provider::Claude => \"Claude Code\",\n Provider::Codex => \"Codex\",\n Provider::Cursor => \"Cursor\",\n Provider::All => \"AI\",\n }\n );\n\n for (user_msg, assistant_msg, _ts) in exchanges_to_use {\n context.push_str(\"H: \");\n context.push_str(user_msg);\n context.push_str(\"\\n\\n\");\n context.push_str(\"A: \");\n context.push_str(assistant_msg);\n context.push_str(\"\\n\\n\");\n }\n\n context.push_str(\"=== End Context ===\\n\");\n\n Ok((context, last_ts))\n}\n\n/// Get consumed checkpoints file path.\nfn get_consumed_checkpoints_path(project_path: &PathBuf) -> PathBuf {\n project_path\n .join(\".ai\")\n .join(\"internal\")\n .join(\"consumed-checkpoints.json\")\n}\n\n/// Load consumed checkpoints for a project.\nfn load_consumed_checkpoints(project_path: &PathBuf) -> Result<ConsumedCheckpoints> {\n let path = get_consumed_checkpoints_path(project_path);\n if !path.exists() {\n return Ok(ConsumedCheckpoints::default());\n }\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n serde_json::from_str(&content).context(\"failed to parse consumed-checkpoints.json\")\n}\n\n/// Save consumed checkpoint after copying context.\nfn save_consumed_checkpoint(session: &CrossProjectSession) -> Result<()> {\n let cwd = std::env::current_dir()?;\n let path = get_consumed_checkpoints_path(&cwd);\n\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n\n let mut checkpoints = load_consumed_checkpoints(&cwd).unwrap_or_default();\n\n // Get the last timestamp from this session\n let last_ts = get_session_last_timestamp_for_path(\n &session.session_id,\n session.provider,\n &session.project_path,\n )?\n .unwrap_or_else(|| chrono::Utc::now().to_rfc3339());\n\n let source_key = session.project_path.to_string_lossy().to_string();\n checkpoints.consumed.insert(\n source_key,\n ConsumedEntry {\n last_timestamp: last_ts,\n consumed_at: chrono::Utc::now().to_rfc3339(),\n session_id: session.session_id.clone(),\n },\n );\n\n let content = serde_json::to_string_pretty(&checkpoints)?;\n fs::write(&path, content)?;\n\n Ok(())\n}\n\n/// Get the last timestamp from a session file (for a specific project path).\nfn get_session_last_timestamp_for_path(\n session_id: &str,\n provider: Provider,\n project_path: &PathBuf,\n) -> Result<Option<String>> {\n if provider == Provider::Codex {\n let session_file = find_codex_session_file(session_id);\n let Some(session_file) = session_file else {\n return Ok(None);\n };\n return get_codex_last_timestamp(&session_file);\n }\n if provider == Provider::Cursor {\n let session_file = find_cursor_session_file(session_id);\n let Some(session_file) = session_file else {\n return Ok(None);\n };\n return get_cursor_last_timestamp(&session_file);\n }\n\n let projects_dir = match provider {\n Provider::Claude | Provider::All => get_claude_projects_dir(),\n Provider::Codex => get_codex_projects_dir(),\n Provider::Cursor => get_cursor_projects_dir(),\n };\n\n let project_folder = project_path.to_string_lossy().replace('/', \"-\");\n let session_file = projects_dir\n .join(&project_folder)\n .join(format!(\"{}.jsonl\", session_id));\n\n if !session_file.exists() {\n return Ok(None);\n }\n\n let mut last_ts: Option<String> = None;\n for_each_nonempty_jsonl_line(&session_file, |line| {\n if let Ok(entry) = crate::json_parse::parse_json_line::<JsonlEntry>(line) {\n if let Some(ts) = entry.timestamp {\n last_ts = Some(ts);\n }\n }\n })?;\n\n Ok(last_ts)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use std::fs;\n use std::process::Command;\n use tempfile::tempdir;\n\n fn init_temp_git_repo() -> tempfile::TempDir {\n let root = tempdir().expect(\"tempdir\");\n let status = Command::new(\"git\")\n .args([\"init\"])\n .current_dir(root.path())\n .status()\n .expect(\"git init\");\n assert!(status.success());\n root\n }\n\n #[test]\n fn decode_cursor_project_path_handles_hyphenated_components() {\n let root = tempfile::Builder::new()\n .prefix(\"cursorproject\")\n .tempdir_in(\"/tmp\")\n .expect(\"tempdir\");\n let repo_path = root\n .path()\n .join(\"review\")\n .join(\"nikiv-designer-dev-deploy\")\n .join(\"ide\")\n .join(\"designer\");\n fs::create_dir_all(&repo_path).expect(\"create repo path\");\n\n let project_key = format!(\n \"tmp-{}-review-nikiv-designer-dev-deploy-ide-designer\",\n root.path()\n .file_name()\n .and_then(|name| name.to_str())\n .expect(\"tempdir name\")\n );\n\n let decoded = decode_cursor_project_path(&project_key).expect(\"decoded path\");\n assert_eq!(decoded, repo_path);\n }\n\n #[test]\n fn parse_cursor_session_file_extracts_messages() {\n let root = tempdir().expect(\"tempdir\");\n let session_file = root.path().join(\"cursor-session.jsonl\");\n fs::write(\n &session_file,\n concat!(\n \"{\\\"role\\\":\\\"user\\\",\\\"message\\\":{\\\"content\\\":[{\\\"type\\\":\\\"text\\\",\\\"text\\\":\\\"hello cursor\\\"}]}}\\n\",\n \"{\\\"role\\\":\\\"assistant\\\",\\\"message\\\":{\\\"content\\\":[{\\\"type\\\":\\\"text\\\",\\\"text\\\":\\\"world\\\"}]}}\\n\"\n ),\n )\n .expect(\"write session file\");\n\n let session =\n parse_cursor_session_file(&session_file, \"cursor-session\").expect(\"parsed session\");\n assert_eq!(session.session_id, \"cursor-session\");\n assert_eq!(session.provider, Provider::Cursor);\n assert_eq!(session.first_message.as_deref(), Some(\"hello cursor\"));\n assert_eq!(session.last_message.as_deref(), Some(\"world\"));\n assert!(session.timestamp.is_some());\n assert_eq!(session.last_message_at, session.timestamp);\n }\n\n #[test]\n fn normalize_session_message_strips_setup_scaffolding() {\n let workflow_text = concat!(\n \"ai sidebar improvements\\n\\n\",\n \"Workflow context:\\n\",\n \"- Repo: ~/code/example-project\\n\",\n \"- Review branch: review/example-feature\\n\",\n \"\\nStart by checking:\\n1. flow status\\n\"\n );\n assert_eq!(\n normalize_session_message(\"user\", workflow_text).as_deref(),\n Some(\"ai sidebar improvements\")\n );\n\n let agents_text = concat!(\n \"# AGENTS.md instructions for /tmp/repo\\n\\n\",\n \"<INSTRUCTIONS>\\n\",\n \"Do important things.\\n\",\n \"</INSTRUCTIONS>\"\n );\n assert_eq!(normalize_session_message(\"user\", agents_text), None);\n\n let assistant_setup = \"Using `example-dispatch`, then `example-workflow` because this is a stacked review workspace.\";\n assert_eq!(\n normalize_session_message(\"assistant\", assistant_setup),\n None\n );\n }\n\n #[test]\n fn normalize_codex_resolve_args_accepts_trailing_json_flag() {\n let (query, json_output) = normalize_codex_resolve_args(\n vec![\n \"https://developers.cloudflare.com/changelog/post/2026-03-10-br-crawl-endpoint/\"\n .to_string(),\n \"--json\".to_string(),\n ],\n false,\n );\n\n assert!(json_output);\n assert_eq!(\n query,\n vec![\n \"https://developers.cloudflare.com/changelog/post/2026-03-10-br-crawl-endpoint/\"\n .to_string()\n ]\n );\n }\n\n #[test]\n fn select_codex_state_db_path_prefers_highest_version() {\n let root = tempdir().expect(\"tempdir\");\n fs::write(root.path().join(\"state_3.sqlite\"), \"\").expect(\"write state_3\");\n fs::write(root.path().join(\"state_5.sqlite\"), \"\").expect(\"write state_5\");\n fs::write(root.path().join(\"state_4.sqlite\"), \"\").expect(\"write state_4\");\n\n let selected = select_codex_state_db_path(root.path()).expect(\"select state db\");\n assert_eq!(selected, root.path().join(\"state_5.sqlite\"));\n }\n\n #[test]\n fn read_codex_thread_schema_detects_optional_columns() {\n let conn = Connection::open_in_memory().expect(\"open in-memory sqlite\");\n conn.execute_batch(\n r#\"\ncreate table threads (\n id text primary key,\n updated_at integer not null,\n cwd text not null,\n title text,\n first_user_message text,\n git_branch text\n);\n\"#,\n )\n .expect(\"create threads table\");\n\n let initial = read_codex_thread_schema(&conn).expect(\"read initial schema\");\n assert_eq!(\n initial,\n CodexThreadSchema {\n has_model: false,\n has_reasoning_effort: false,\n }\n );\n\n conn.execute_batch(\n r#\"\nalter table threads add column model text;\nalter table threads add column reasoning_effort text;\n\"#,\n )\n .expect(\"alter threads table\");\n\n let updated = read_codex_thread_schema(&conn).expect(\"read updated schema\");\n assert_eq!(\n updated,\n CodexThreadSchema {\n has_model: true,\n has_reasoning_effort: true,\n }\n );\n }\n\n #[test]\n fn read_codex_first_user_message_since_prefers_first_post_launch_turn() {\n let root = tempdir().expect(\"tempdir\");\n let session_file = root.path().join(\"codex.jsonl\");\n fs::write(\n &session_file,\n concat!(\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-16T10:00:00Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"input_text\\\",\\\"text\\\":\\\"old prompt\\\"}]}}\\n\",\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-16T10:00:01Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"assistant\\\",\\\"content\\\":[{\\\"type\\\":\\\"output_text\\\",\\\"text\\\":\\\"old answer\\\"}]}}\\n\",\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-16T10:05:00Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"input_text\\\",\\\"text\\\":\\\"new prompt after launch\\\"}]}}\\n\",\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-16T10:05:02Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"assistant\\\",\\\"content\\\":[{\\\"type\\\":\\\"output_text\\\",\\\"text\\\":\\\"new answer\\\"}]}}\\n\"\n ),\n )\n .expect(\"write session file\");\n\n let since_unix = parse_rfc3339_to_unix(\"2026-03-16T10:05:00Z\").expect(\"parse timestamp\");\n let first = read_codex_first_user_message_since(&session_file, since_unix)\n .expect(\"read\")\n .expect(\"first post-launch prompt\");\n assert_eq!(first.0, \"new prompt after launch\");\n assert_eq!(first.1, since_unix);\n }\n\n #[test]\n fn read_codex_first_user_message_since_skips_contextual_scaffolding() {\n let root = tempdir().expect(\"tempdir\");\n let session_file = root.path().join(\"codex.jsonl\");\n fs::write(\n &session_file,\n concat!(\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-16T10:05:00Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"input_text\\\",\\\"text\\\":\\\"# AGENTS.md instructions for /tmp\\\\n\\\\n<INSTRUCTIONS>\\\\nbody\\\\n</INSTRUCTIONS>\\\"}]}}\\n\",\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-16T10:05:01Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"input_text\\\",\\\"text\\\":\\\"<environment_context>\\\\n<cwd>/tmp</cwd>\\\\n</environment_context>\\\"}]}}\\n\",\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-16T10:05:02Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"input_text\\\",\\\"text\\\":\\\"write plan for rollout\\\"}]}}\\n\"\n ),\n )\n .expect(\"write session file\");\n\n let since_unix = parse_rfc3339_to_unix(\"2026-03-16T10:05:00Z\").expect(\"parse timestamp\");\n let first = read_codex_first_user_message_since(&session_file, since_unix)\n .expect(\"read\")\n .expect(\"first real prompt\");\n assert_eq!(first.0, \"write plan for rollout\");\n assert_eq!(first.1, since_unix + 2);\n }\n\n #[test]\n fn append_history_message_skips_consecutive_duplicates() {\n let mut history = String::new();\n let mut last_entry = None;\n\n append_history_message(&mut history, &mut last_entry, \"user\", \"same\");\n append_history_message(&mut history, &mut last_entry, \"user\", \"same\");\n append_history_message(&mut history, &mut last_entry, \"assistant\", \"reply\");\n append_history_message(&mut history, &mut last_entry, \"assistant\", \"reply\");\n\n assert_eq!(history, \"Human: same\\n\\nAssistant: reply\\n\\n\");\n }\n\n #[test]\n fn codex_find_search_terms_keep_phrase_and_meaningful_tokens() {\n assert_eq!(\n codex_find_search_terms(\"make plan to get designer\"),\n vec![\n \"make plan to get designer\".to_string(),\n \"make\".to_string(),\n \"plan\".to_string(),\n \"get\".to_string(),\n \"designer\".to_string(),\n ]\n );\n }\n\n #[test]\n fn rank_recover_rows_prefers_matching_session_id_prefix() {\n let mut rows = vec![\n CodexRecoverRow {\n id: \"019caaaa-0000-7000-8000-aaaaaaaaaaaa\".to_string(),\n updated_at: 10,\n cwd: \"/tmp/repo\".to_string(),\n title: Some(\"one remaining unrelated issue\".to_string()),\n first_user_message: Some(\"npm run lint still fails\".to_string()),\n git_branch: Some(\"main\".to_string()),\n model: None,\n reasoning_effort: None,\n },\n CodexRecoverRow {\n id: \"019cdcff-0b3a-7a80-b22b-5ac4ff076eff\".to_string(),\n updated_at: 5,\n cwd: \"/tmp/other\".to_string(),\n title: Some(\"something else\".to_string()),\n first_user_message: Some(\"different prompt\".to_string()),\n git_branch: Some(\"feature\".to_string()),\n model: None,\n reasoning_effort: None,\n },\n ];\n\n rank_recover_rows(&mut rows, Some(\"019cdcff\"));\n\n assert_eq!(rows[0].id, \"019cdcff-0b3a-7a80-b22b-5ac4ff076eff\");\n }\n\n #[test]\n fn extract_codex_session_hint_prefers_uuid_like_token() {\n assert_eq!(\n extract_codex_session_hint(\n \"see 019cdcff-0b3a-7a80-b22b-5ac4ff076eff for work done on that\"\n ),\n Some(\"019cdcff-0b3a-7a80-b22b-5ac4ff076eff\".to_string())\n );\n }\n\n #[test]\n fn extract_codex_session_hint_ignores_git_sha_like_token() {\n assert_eq!(\n extract_codex_session_hint(\"see 3a4c62bfd29335a0170397b028a440c49858f1f5 for that\"),\n None\n );\n }\n\n #[test]\n fn extract_codex_session_reference_request_parses_count_and_followup() {\n let request = extract_codex_session_reference_request(\n \"see 019ce6ce-c77a-7d52-838e-c01f8820f6b8 last 20 messages, research react hot reload\",\n \"see 019ce6ce-c77a-7d52-838e-c01f8820f6b8 last 20 messages, research react hot reload\",\n )\n .expect(\"expected session reference request\");\n\n assert_eq!(\n request.session_hints,\n vec![\"019ce6ce-c77a-7d52-838e-c01f8820f6b8\".to_string()]\n );\n assert_eq!(request.count, 20);\n assert_eq!(request.user_request, \"research react hot reload\");\n }\n\n #[test]\n fn extract_codex_session_reference_request_supports_two_session_hints() {\n let request = extract_codex_session_reference_request(\n \"see 019cf695-d1d8-7e32-a572-f05e1d03d24f and 019cf983-79c3-7ad0-a870-05e308daa032 codex lets make dedicated plan for /tmp/review.md\",\n \"see 019cf695-d1d8-7e32-a572-f05e1d03d24f and 019cf983-79c3-7ad0-a870-05e308daa032 codex lets make dedicated plan for /tmp/review.md\",\n )\n .expect(\"expected session reference request\");\n\n assert_eq!(\n request.session_hints,\n vec![\n \"019cf695-d1d8-7e32-a572-f05e1d03d24f\".to_string(),\n \"019cf983-79c3-7ad0-a870-05e308daa032\".to_string()\n ]\n );\n assert_eq!(\n request.user_request,\n \"lets make dedicated plan for /tmp/review.md\"\n );\n }\n\n #[test]\n fn extract_codex_session_reference_request_requires_followup_work() {\n assert!(\n extract_codex_session_reference_request(\n \"see 019ce6ce-c77a-7d52-838e-c01f8820f6b8 last 20 messages\",\n \"see 019ce6ce-c77a-7d52-838e-c01f8820f6b8 last 20 messages\",\n )\n .is_none()\n );\n }\n\n #[test]\n fn extract_codex_session_reference_request_does_not_steal_resume_queries() {\n assert!(\n extract_codex_session_reference_request(\n \"resume 019ce6ce-c77a-7d52-838e-c01f8820f6b8\",\n \"resume 019ce6ce-c77a-7d52-838e-c01f8820f6b8\",\n )\n .is_none()\n );\n }\n\n #[test]\n fn infer_recover_route_changes_directory_for_cross_repo_candidate() {\n let output = build_recover_output(\n Path::new(\"/tmp/current\"),\n false,\n Some(\"019cdcff-0b3a-7a80-b22b-5ac4ff076eff\".to_string()),\n vec![CodexRecoverRow {\n id: \"019cdcff-0b3a-7a80-b22b-5ac4ff076eff\".to_string(),\n updated_at: 5,\n cwd: \"/tmp/other\".to_string(),\n title: Some(\"something else\".to_string()),\n first_user_message: Some(\"different prompt\".to_string()),\n git_branch: Some(\"feature\".to_string()),\n model: None,\n reasoning_effort: None,\n }],\n );\n\n assert_eq!(\n output.recommended_route,\n \"cd /tmp/other && f ai codex resume 019cdcff-0b3a-7a80-b22b-5ac4ff076eff\"\n );\n }\n\n #[test]\n fn session_lookup_detection_stays_conservative_for_general_session_work() {\n assert!(!looks_like_session_lookup_query(\n \"improve session support in flow\"\n ));\n assert!(!looks_like_session_lookup_query(\n \"conversation summary pipeline cleanup\"\n ));\n assert!(!looks_like_session_lookup_query(\n \"write plan after reading https://github.com/openai/codex\"\n ));\n }\n\n #[test]\n fn session_lookup_detection_accepts_explicit_control_prompts() {\n assert!(looks_like_session_lookup_query(\"resume session\"));\n assert!(looks_like_session_lookup_query(\"show conversation\"));\n assert!(looks_like_session_lookup_query(\"latest\"));\n assert!(looks_like_session_lookup_query(\"after latest\"));\n }\n\n #[test]\n fn wildcard_match_handles_linear_style_patterns() {\n assert!(wildcard_match(\n \"https://linear.app/*/project/*\",\n \"https://linear.app/fl2024008/project/llm-proxy-v1-6cd0a041bd76/overview\"\n ));\n assert!(wildcard_match(\n \"https://linear.app/*/issue/*\",\n \"https://linear.app/fl2024008/issue/IDE-331/test-title\"\n ));\n assert!(!wildcard_match(\n \"https://linear.app/*/issue/*\",\n \"https://github.com/openai/codex\"\n ));\n }\n\n fn sample_codex_doctor_snapshot() -> CodexDoctorSnapshot {\n CodexDoctorSnapshot {\n target: \"/tmp/repo\".to_string(),\n codex_bin: \"codex-flow-wrapper\".to_string(),\n codexd: \"running\".to_string(),\n codexd_socket: \"/tmp/codexd.sock\".to_string(),\n memory_state: \"ready\".to_string(),\n memory_root: \"/tmp/jazz2/codex-memory\".to_string(),\n memory_db_path: \"/tmp/jazz2/codex-memory/memory.sqlite\".to_string(),\n memory_events_indexed: 9,\n memory_facts_indexed: 12,\n runtime_transport: \"enabled\".to_string(),\n runtime_skills: \"enabled\".to_string(),\n auto_resolve_references: true,\n home_session_path: \"/tmp/home\".to_string(),\n prompt_context_budget_chars: 1200,\n max_resolved_references: 2,\n reference_resolvers: 0,\n query_cache: \"enabled\".to_string(),\n query_cache_entries_on_disk: 4,\n skill_eval_events_on_disk: 6,\n skill_eval_outcomes_on_disk: 3,\n skill_scorecard_samples: 6,\n skill_scorecard_entries: 2,\n skill_scorecard_top: Some(\"plan_write (0.91)\".to_string()),\n external_skill_candidates: 1,\n runtime_state_files: 2,\n runtime_state_files_for_target: 1,\n skill_eval_schedule: \"loaded\".to_string(),\n learning_state: \"grounded\".to_string(),\n runtime_ready: true,\n schedule_ready: true,\n learning_ready: true,\n warnings: Vec::new(),\n }\n }\n\n #[test]\n fn codex_doctor_assert_autonomous_accepts_grounded_snapshot() {\n let snapshot = sample_codex_doctor_snapshot();\n assert!(assert_codex_doctor(&snapshot, false, false, false, true).is_ok());\n }\n\n #[test]\n fn codex_doctor_assert_learning_requires_grounded_outcomes() {\n let mut snapshot = sample_codex_doctor_snapshot();\n snapshot.skill_eval_outcomes_on_disk = 0;\n snapshot.learning_ready = false;\n snapshot.learning_state = \"affinity-only\".to_string();\n\n let err = assert_codex_doctor(&snapshot, false, false, true, false)\n .expect_err(\"learning assertion should fail without outcomes\");\n let message = format!(\"{err:#}\");\n assert!(message.contains(\"no grounded skill outcome events recorded yet\"));\n }\n\n #[test]\n fn codex_eval_opportunities_flag_missing_runtime_and_daemon() {\n let mut snapshot = sample_codex_doctor_snapshot();\n snapshot.runtime_transport = \"disabled\".to_string();\n snapshot.runtime_skills = \"disabled\".to_string();\n snapshot.runtime_ready = false;\n snapshot.codexd = \"stopped\".to_string();\n snapshot.skill_eval_outcomes_on_disk = 0;\n snapshot.learning_ready = false;\n\n let opportunities = build_codex_eval_opportunities(&snapshot, 4, 0, &[], &[]);\n assert!(opportunities\n .iter()\n .any(|item| item.title.contains(\"Wrapper/runtime path\")));\n assert!(opportunities\n .iter()\n .any(|item| item.title.contains(\"codexd is not running\")));\n assert!(opportunities\n .iter()\n .any(|item| item.title.contains(\"No grounded outcome samples for this target yet\")));\n }\n\n #[test]\n fn codex_eval_summary_prefers_grounded_signal_when_ready() {\n let snapshot = sample_codex_doctor_snapshot();\n let route = CodexEvalRouteSnapshot {\n route: \"new-with-context\".to_string(),\n count: 4,\n share: 0.5,\n avg_context_chars: 420.0,\n avg_reference_count: 1.0,\n runtime_activation_rate: 0.75,\n last_recorded_at_unix: 10,\n };\n let skill = CodexEvalSkillSnapshot {\n name: \"github\".to_string(),\n score: 12.0,\n sample_size: 4,\n outcome_samples: 3,\n pass_rate: 1.0,\n normalized_gain: 0.4,\n avg_context_chars: 300.0,\n };\n\n let summary =\n build_codex_eval_summary(&snapshot, 8, 3, Some(&route), Some(&skill));\n assert!(summary.contains(\"grounded learning is active\"));\n assert!(summary.contains(\"top route: new-with-context\"));\n assert!(summary.contains(\"top skill: github\"));\n }\n\n #[test]\n fn codex_eval_quality_marks_blocking_runtime_failures_erroneous() {\n let mut snapshot = sample_codex_doctor_snapshot();\n snapshot.runtime_transport = \"disabled\".to_string();\n snapshot.runtime_skills = \"configured-but-inactive\".to_string();\n snapshot.runtime_ready = false;\n snapshot.memory_state = \"unavailable\".to_string();\n\n let quality = build_codex_eval_quality(&snapshot, 5, 0);\n assert_eq!(quality.status, \"erroneous\");\n assert!(!quality.grounded);\n assert!(quality\n .failure_modes\n .iter()\n .any(|mode| mode.contains(\"wrapper transport disabled\")));\n assert!(quality\n .failure_modes\n .iter()\n .any(|mode| mode.contains(\"runtime skills\")));\n assert!(quality\n .failure_modes\n .iter()\n .any(|mode| mode.contains(\"codex memory unavailable\")));\n }\n\n #[test]\n fn codex_eval_quality_stays_valid_while_warming_up() {\n let snapshot = sample_codex_doctor_snapshot();\n let quality = build_codex_eval_quality(&snapshot, 3, 0);\n assert_eq!(quality.status, \"valid\");\n assert!(!quality.grounded);\n assert!(quality.failure_modes.is_empty());\n assert!(quality.summary.contains(\"warming up\"));\n }\n\n #[test]\n fn parse_linear_url_reference_extracts_project_shape() {\n let reference = parse_linear_url_reference(\n \"https://linear.app/fl2024008/project/llm-proxy-v1-6cd0a041bd76/overview\",\n )\n .expect(\"linear project url should parse\");\n\n assert_eq!(reference.workspace_slug, \"fl2024008\");\n assert_eq!(reference.resource_kind, LinearUrlKind::Project);\n assert_eq!(reference.resource_value, \"llm-proxy-v1-6cd0a041bd76\");\n assert_eq!(reference.view.as_deref(), Some(\"overview\"));\n assert_eq!(reference.title_hint, \"llm proxy v1\");\n }\n\n #[test]\n fn github_pr_url_detection_is_specific() {\n assert!(looks_like_github_pr_url(\n \"https://github.com/fl2024008/prometheus/pull/2922\"\n ));\n assert!(!looks_like_github_pr_url(\n \"https://github.com/fl2024008/prometheus/issues/2922\"\n ));\n }\n\n #[test]\n fn pr_feedback_query_detection_matches_check_and_comments() {\n assert!(looks_like_pr_feedback_query(\n \"check https://github.com/fl2024008/prometheus/pull/2922\"\n ));\n assert!(looks_like_pr_feedback_query(\n \"see https://github.com/fl2024008/prometheus/pull/2922 for comments\"\n ));\n assert!(!looks_like_pr_feedback_query(\n \"open https://github.com/fl2024008/prometheus/pull/2922 in browser\"\n ));\n }\n\n #[test]\n fn commit_workflow_query_detection_matches_high_confidence_phrases() {\n assert!(looks_like_commit_workflow_query(\"commit\"));\n assert!(looks_like_commit_workflow_query(\"commit and push\"));\n assert!(looks_like_commit_workflow_query(\"review and commit\"));\n }\n\n #[test]\n fn commit_workflow_query_detection_stays_conservative() {\n assert!(!looks_like_commit_workflow_query(\n \"improve commit queue throughput\"\n ));\n assert!(!looks_like_commit_workflow_query(\n \"explain commit routing in flow\"\n ));\n }\n\n #[test]\n fn prom_sync_workflow_query_detection_matches_high_confidence_phrases() {\n assert!(looks_like_prom_sync_workflow_query(\"sync branch\"));\n assert!(looks_like_prom_sync_workflow_query(\"sync this branch\"));\n assert!(looks_like_prom_sync_workflow_query(\"sync with origin/main\"));\n }\n\n #[test]\n fn prom_sync_workflow_query_detection_stays_conservative() {\n assert!(!looks_like_prom_sync_workflow_query(\n \"explain sync branch semantics\"\n ));\n assert!(!looks_like_prom_sync_workflow_query(\n \"sync branch protection settings\"\n ));\n }\n\n #[test]\n fn build_codex_open_plan_routes_plain_commit_into_commit_workflow() {\n let root = init_temp_git_repo();\n fs::write(root.path().join(\"README.md\"), \"hello\\n\").expect(\"write readme\");\n\n let plan = build_codex_open_plan(\n Some(root.path().display().to_string()),\n vec![\"commit\".to_string()],\n false,\n )\n .expect(\"commit plan\");\n\n assert_eq!(plan.route, \"commit-workflow-new\");\n assert_eq!(plan.action, \"new\");\n assert_eq!(plan.references[0].name, \"commit-workflow\");\n assert_eq!(\n plan.references[0].command.as_deref(),\n Some(\"f commit --slow --context\")\n );\n let prompt = plan.prompt.expect(\"prompt\");\n assert!(prompt.contains(\"Commit workflow contract:\"));\n assert!(prompt.contains(\"deep-review-then-commit\"));\n }\n\n #[test]\n fn build_codex_open_plan_routes_prom_sync_branch_into_sync_workflow() {\n let temp = tempdir().expect(\"tempdir\");\n let root = temp.path().join(\"code\").join(\"prom\").join(\"review-workspace\");\n fs::create_dir_all(&root).expect(\"create root\");\n Command::new(\"git\")\n .arg(\"init\")\n .arg(\"-q\")\n .current_dir(&root)\n .status()\n .expect(\"git init\");\n\n let plan = build_codex_open_plan(\n Some(root.display().to_string()),\n vec![\"sync branch\".to_string()],\n false,\n )\n .expect(\"sync plan\");\n\n assert_eq!(plan.route, \"sync-workflow-new\");\n assert_eq!(plan.action, \"new\");\n assert_eq!(plan.references[0].name, \"sync-workflow\");\n assert_eq!(plan.references[0].command.as_deref(), Some(\"forge sync\"));\n let prompt = plan.prompt.expect(\"prompt\");\n assert!(prompt.contains(\"Sync workflow contract:\"));\n assert!(prompt.contains(\"guarded repo sync workflow\"));\n }\n\n #[test]\n fn parse_pr_feedback_cursor_handoff_extracts_paths() {\n let handoff = parse_pr_feedback_cursor_handoff(\n \"[pr-feedback]\\n\\\n Workspace: /tmp/repo\\n\\\n PR feedback: owner/repo#1\\n\\\n Review plan: /tmp/plan.md\\n\\\n Review rules: /tmp/review-rules.md\\n\\\n Kit system prompt: /tmp/kit.md\\n\",\n )\n .expect(\"handoff\");\n\n assert_eq!(handoff.workspace_path, PathBuf::from(\"/tmp/repo\"));\n assert_eq!(handoff.review_plan_path, PathBuf::from(\"/tmp/plan.md\"));\n assert_eq!(\n handoff.review_rules_path,\n Some(PathBuf::from(\"/tmp/review-rules.md\"))\n );\n assert_eq!(handoff.kit_system_path, PathBuf::from(\"/tmp/kit.md\"));\n }\n\n #[test]\n fn build_codex_prompt_keeps_plain_query_plain() {\n assert_eq!(\n build_codex_prompt(\"improve codex open perf\", &[], 2, 1200).as_deref(),\n Some(\"improve codex open perf\")\n );\n }\n\n #[test]\n fn build_codex_prompt_avoids_duplicate_reference_header() {\n let references = vec![CodexResolvedReference {\n name: \"pr-feedback\".to_string(),\n source: \"builtin\".to_string(),\n matched: \"https://github.com/example/repo/pull/1\".to_string(),\n command: None,\n output: \"[pr-feedback]\\nReview plan: /tmp/plan.md\".to_string(),\n }];\n\n let prompt = build_codex_prompt(\"check pr\", &references, 2, 600).expect(\"prompt\");\n assert_eq!(prompt.matches(\"[pr-feedback]\").count(), 1);\n }\n\n #[test]\n fn parse_reference_fields_extracts_pr_feedback_artifacts() {\n let fields = parse_reference_fields(\n \"[pr-feedback]\\n\\\n Workspace: /tmp/repo\\n\\\n PR feedback: owner/repo#1\\n\\\n Trace ID: trace-1\\n\\\n URL: https://github.com/owner/repo/pull/1\\n\\\n Snapshot markdown: /tmp/repo/.ai/reviews/pr-feedback-1.md\\n\\\n Snapshot json: /tmp/repo/.ai/reviews/pr-feedback-1.json\\n\\\n Review plan: /tmp/plan.md\\n\\\n Review rules: /tmp/review-rules.md\\n\\\n Kit system prompt: /tmp/kit.md\\n\\\n Cursor reopen: f pr feedback https://github.com/owner/repo/pull/1 --compact --cursor\\n\\\n Summary:\\n\\\n - Actionable items: 6\\n\",\n );\n\n assert_eq!(fields.get(\"workspace\").map(String::as_str), Some(\"/tmp/repo\"));\n assert_eq!(\n fields.get(\"snapshot markdown\").map(String::as_str),\n Some(\"/tmp/repo/.ai/reviews/pr-feedback-1.md\")\n );\n assert_eq!(\n fields.get(\"review plan\").map(String::as_str),\n Some(\"/tmp/plan.md\")\n );\n assert_eq!(fields.get(\"trace id\").map(String::as_str), Some(\"trace-1\"));\n assert_eq!(\n fields.get(\"cursor reopen\").map(String::as_str),\n Some(\"f pr feedback https://github.com/owner/repo/pull/1 --compact --cursor\")\n );\n }\n\n #[test]\n fn derive_codex_open_plan_trace_assigns_plain_routes() {\n let plan = CodexOpenPlan {\n action: \"new\".to_string(),\n route: \"new-plain\".to_string(),\n reason: \"start a new session from the current query\".to_string(),\n target_path: \"/tmp/repo\".to_string(),\n launch_path: \"/tmp/repo\".to_string(),\n query: Some(\"summarize this repo\".to_string()),\n session_id: None,\n prompt: Some(\"summarize this repo\".to_string()),\n references: Vec::new(),\n runtime_state_path: None,\n runtime_skills: Vec::new(),\n prompt_context_budget_chars: 1200,\n max_resolved_references: 3,\n prompt_chars: 19,\n injected_context_chars: 0,\n trace: None,\n };\n\n let trace = derive_codex_open_plan_trace(&plan).expect(\"trace\");\n assert_eq!(trace.workflow_kind, \"new_plain\");\n assert_eq!(trace.service_name, FLOW_CODEX_TRACE_SERVICE_NAME);\n assert_eq!(trace.trace_id.len(), 32);\n assert_eq!(trace.span_id.len(), 16);\n }\n\n #[test]\n fn build_pr_feedback_workflow_explanation_surfaces_packet_and_command() {\n let plan = CodexOpenPlan {\n action: \"new\".to_string(),\n route: \"new-with-context\".to_string(),\n reason: \"builtin pr feedback route\".to_string(),\n target_path: \"/tmp/repo\".to_string(),\n launch_path: \"/tmp/repo\".to_string(),\n query: Some(\"check https://github.com/owner/repo/pull/1\".to_string()),\n session_id: None,\n prompt: Some(\"prompt\".to_string()),\n references: vec![CodexResolvedReference {\n name: \"pr-feedback\".to_string(),\n source: \"builtin\".to_string(),\n matched: \"https://github.com/owner/repo/pull/1\".to_string(),\n command: Some(\"f pr feedback https://github.com/owner/repo/pull/1\".to_string()),\n output: \"[pr-feedback]\\n\\\n Workspace: /tmp/repo\\n\\\n PR feedback: owner/repo#1\\n\\\n Trace ID: trace-1\\n\\\n URL: https://github.com/owner/repo/pull/1\\n\\\n Snapshot markdown: /tmp/repo/.ai/reviews/pr-feedback-1.md\\n\\\n Snapshot json: /tmp/repo/.ai/reviews/pr-feedback-1.json\\n\\\n Review plan: /tmp/plan.md\\n\\\n Review rules: /tmp/review-rules.md\\n\\\n Kit system prompt: /tmp/kit.md\\n\\\n Cursor reopen: f pr feedback https://github.com/owner/repo/pull/1 --compact --cursor\\n\"\n .to_string(),\n }],\n runtime_state_path: None,\n runtime_skills: vec![],\n prompt_context_budget_chars: 2400,\n max_resolved_references: 2,\n prompt_chars: 100,\n injected_context_chars: 80,\n trace: Some(CodexResolveWorkflowTrace {\n trace_id: \"trace-1\".to_string(),\n span_id: \"span-1\".to_string(),\n parent_span_id: None,\n workflow_kind: \"pr_feedback\".to_string(),\n service_name: FLOW_CODEX_TRACE_SERVICE_NAME.to_string(),\n }),\n };\n let runtime_skills = vec![CodexResolveRuntimeSkillSnapshot {\n name: \"flow-runtime-ext-dimillian-skills-github\".to_string(),\n kind: \"external\".to_string(),\n path: \"/tmp/github\".to_string(),\n trigger: \"github\".to_string(),\n source: Some(\"dimillian\".to_string()),\n original_name: Some(\"github\".to_string()),\n estimated_chars: Some(1200),\n match_reason: Some(\"matched skill name phrase `github`\".to_string()),\n }];\n\n let workflow = build_codex_resolve_workflow_explanation(&plan, &runtime_skills)\n .expect(\"workflow explanation\");\n assert_eq!(workflow.id, \"pr-feedback\");\n assert_eq!(workflow.packet.kind, \"pr_feedback\");\n assert!(workflow\n .packet\n .expansion_rules\n .iter()\n .any(|rule| rule.contains(\"Read the compact packet first\")));\n assert!(workflow\n .packet\n .validation_plan\n .iter()\n .any(|item| item.label == \"Per-item product validation\"));\n assert_eq!(workflow.commands.first().map(|c| c.command.as_str()), Some(\"f pr feedback https://github.com/owner/repo/pull/1\"));\n assert!(workflow\n .artifacts\n .iter()\n .any(|artifact| artifact.label == \"Review plan\" && artifact.value == \"/tmp/plan.md\"));\n assert!(workflow\n .artifacts\n .iter()\n .any(|artifact| artifact.label == \"Trace ID\" && artifact.value == \"trace-1\"));\n assert_eq!(\n workflow\n .packet\n .trace\n .as_ref()\n .map(|trace| trace.trace_id.as_str()),\n Some(\"trace-1\")\n );\n assert!(workflow\n .notes\n .iter()\n .any(|note| note.contains(\"Runtime skill: github\")));\n }\n\n #[test]\n fn build_codex_prompt_respects_shared_context_budget() {\n let references = vec![\n CodexResolvedReference {\n name: \"docs\".to_string(),\n source: \"resolver\".to_string(),\n matched: \"one\".to_string(),\n command: None,\n output: \"A\".repeat(500),\n },\n CodexResolvedReference {\n name: \"issue\".to_string(),\n source: \"resolver\".to_string(),\n matched: \"two\".to_string(),\n command: None,\n output: \"B\".repeat(500),\n },\n ];\n\n let prompt =\n build_codex_prompt(\"summarize\", &references, 2, 260).expect(\"prompt should exist\");\n\n assert!(prompt.chars().count() <= 260);\n assert!(prompt.contains(\"User request:\"));\n }\n\n #[test]\n fn read_codex_session_completion_snapshot_tracks_latest_completed_turn() {\n let root = tempdir().expect(\"tempdir\");\n let session_file = root.path().join(\"codex.jsonl\");\n fs::write(\n &session_file,\n concat!(\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-17T10:00:00Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"input_text\\\",\\\"text\\\":\\\"first prompt\\\"}]}}\\n\",\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-17T10:00:01Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"assistant\\\",\\\"content\\\":[{\\\"type\\\":\\\"output_text\\\",\\\"text\\\":\\\"first answer\\\"}]}}\\n\",\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-17T10:01:00Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"user\\\",\\\"content\\\":[{\\\"type\\\":\\\"input_text\\\",\\\"text\\\":\\\"second prompt\\\"}]}}\\n\",\n \"{\\\"type\\\":\\\"response_item\\\",\\\"timestamp\\\":\\\"2026-03-17T10:01:03Z\\\",\\\"payload\\\":{\\\"type\\\":\\\"message\\\",\\\"role\\\":\\\"assistant\\\",\\\"content\\\":[{\\\"type\\\":\\\"output_text\\\",\\\"text\\\":\\\"second answer\\\"}]}}\\n\"\n ),\n )\n .expect(\"write session file\");\n\n let snapshot = read_codex_session_completion_snapshot(&session_file)\n .expect(\"snapshot\")\n .expect(\"completion snapshot\");\n assert_eq!(snapshot.last_role.as_deref(), Some(\"assistant\"));\n assert_eq!(snapshot.last_user_message.as_deref(), Some(\"second prompt\"));\n assert_eq!(\n snapshot.last_assistant_message.as_deref(),\n Some(\"second answer\")\n );\n assert_eq!(\n snapshot.last_assistant_at_unix,\n parse_rfc3339_to_unix(\"2026-03-17T10:01:03Z\")\n );\n }\n\n #[test]\n fn select_codex_session_completion_summary_prefers_last_user_message() {\n let row = CodexRecoverRow {\n id: \"019ce791-7e05-7e51-b2b7-610dc7172e5c\".to_string(),\n updated_at: 0,\n cwd: \"/tmp/repo\".to_string(),\n title: Some(\"fallback title\".to_string()),\n first_user_message: Some(\"older intent\".to_string()),\n git_branch: None,\n model: None,\n reasoning_effort: None,\n };\n let snapshot = CodexSessionCompletionSnapshot {\n last_role: Some(\"assistant\".to_string()),\n last_user_message: Some(\"implement codex session logging\".to_string()),\n last_user_at_unix: Some(1),\n last_assistant_message: Some(\"done\".to_string()),\n last_assistant_at_unix: Some(2),\n file_modified_unix: 2,\n };\n\n let summary = select_codex_session_completion_summary(&row, &snapshot);\n assert_eq!(summary, \"implement codex session logging\");\n }\n\n #[test]\n fn parse_apply_patch_changes_extracts_absolute_paths() {\n let changes = parse_apply_patch_changes(\n concat!(\n \"*** Begin Patch\\n\",\n \"*** Update File: /tmp/config/fish/fn.fish\\n\",\n \"@@\\n\",\n \"+function j\\n\",\n \"*** Add File: relative/new-file.rs\\n\",\n \"+fn main() {}\\n\",\n \"*** End Patch\\n\",\n ),\n \"/tmp/code/flow\",\n );\n assert_eq!(changes.len(), 2);\n assert_eq!(changes[0].path, \"/tmp/config/fish/fn.fish\");\n assert_eq!(changes[0].action, \"update\");\n assert!(changes[0].patch.contains(\"function j\"));\n assert_eq!(changes[1].path, \"/tmp/code/flow/relative/new-file.rs\");\n assert_eq!(changes[1].action, \"add\");\n }\n\n #[test]\n fn summarize_fish_fn_change_detects_shortcut_remap() {\n let summary = summarize_fish_fn_change(\n \"j runs f codex open --path (pwd -P) --exact-cwd. \\\nk uses f codex connect --path (pwd -P) --exact-cwd. \\\nl is now Kit for ~/repos/mark3labs/kit. \\\nL now delegates to j. old k moved to cl. old l moved to cf. old L moved to cF.\",\n )\n .expect(\"summary\");\n assert!(summary.contains(\"j->codex.open\"));\n assert!(summary.contains(\"k->codex.connect\"));\n assert!(summary.contains(\"l->kit\"));\n assert!(summary.contains(\"L->j\"));\n assert!(summary.contains(\"cl/cf/cF\"));\n }\n\n #[test]\n fn build_codex_session_changed_events_uses_fish_summary_fallback() {\n let root = tempdir().expect(\"tempdir\");\n let session_file = root.path().join(\"codex.jsonl\");\n fs::write(&session_file, \"\").expect(\"write empty session file\");\n\n let row = CodexRecoverRow {\n id: \"019ce791-7e05-7e51-b2b7-610dc7172e5c\".to_string(),\n updated_at: 0,\n cwd: \"/tmp/code/flow\".to_string(),\n title: None,\n first_user_message: None,\n git_branch: None,\n model: None,\n reasoning_effort: None,\n };\n let snapshot = CodexSessionCompletionSnapshot {\n last_role: Some(\"assistant\".to_string()),\n last_user_message: Some(\n \"The remap is in fn.fish. j runs f codex open --path (pwd -P) --exact-cwd. \\\nk uses f codex connect --path (pwd -P) --exact-cwd. \\\nl is now Kit. L now delegates to j. old k moved to cl. old l moved to cf. old L moved to cF.\"\n .to_string(),\n ),\n last_user_at_unix: Some(1),\n last_assistant_message: Some(\"logged\".to_string()),\n last_assistant_at_unix: Some(2),\n file_modified_unix: 2,\n };\n\n let events =\n build_codex_session_changed_events(&row, &snapshot, &session_file).expect(\"events\");\n assert_eq!(events.len(), 1);\n assert_eq!(events[0].kind, \"fish.fn\");\n assert!(events[0].summary.contains(\"j->codex.open\"));\n assert!(events[0].summary.contains(\"k->codex.connect\"));\n }\n\n #[test]\n fn format_session_ref_respects_provider_prefix_flag() {\n let session = AiSession {\n session_id: \"019ce791-7e05-7e51-b2b7-610dc7172e5c\".to_string(),\n provider: Provider::Codex,\n timestamp: None,\n last_message_at: None,\n last_message: None,\n first_message: None,\n error_summary: None,\n };\n\n assert_eq!(\n format_session_ref(&session, false),\n \"019ce791-7e05-7e51-b2b7-610dc7172e5c\"\n );\n assert_eq!(\n format_session_ref(&session, true),\n \"codex:019ce791-7e05-7e51-b2b7-610dc7172e5c\"\n );\n }\n\n #[test]\n fn ai_session_from_codex_recover_row_prefers_title_for_preview() {\n let session = ai_session_from_codex_recover_row(CodexRecoverRow {\n id: \"019ce791-7e05-7e51-b2b7-610dc7172e5c\".to_string(),\n updated_at: 1_773_776_290,\n cwd: \"/tmp/repo\".to_string(),\n title: Some(\"review github integration\".to_string()),\n first_user_message: Some(\"older prompt\".to_string()),\n git_branch: None,\n model: None,\n reasoning_effort: None,\n });\n\n assert_eq!(\n session.last_message.as_deref(),\n Some(\"review github integration\")\n );\n assert_eq!(session.first_message.as_deref(), Some(\"older prompt\"));\n assert_eq!(session.provider, Provider::Codex);\n assert!(session.last_message_at.is_some());\n }\n\n #[test]\n fn ai_session_from_codex_recover_row_falls_back_to_first_user_message() {\n let session = ai_session_from_codex_recover_row(CodexRecoverRow {\n id: \"019ce791-7e05-7e51-b2b7-610dc7172e5c\".to_string(),\n updated_at: 1_773_776_290,\n cwd: \"/tmp/repo\".to_string(),\n title: None,\n first_user_message: Some(\"inspect the current diff\".to_string()),\n git_branch: None,\n model: None,\n reasoning_effort: None,\n });\n\n assert_eq!(\n session.last_message.as_deref(),\n Some(\"inspect the current diff\")\n );\n assert_eq!(\n session.first_message.as_deref(),\n Some(\"inspect the current diff\")\n );\n }\n}\n" }, { "path": "src/ai_context.rs", "content": "//! AI context loading from `.ai/context/` directories.\n//!\n//! This module provides functionality to load contextual AI instructions\n//! from `.ai/context/` directories in the project root.\n//!\n//! ## Directory Structure\n//!\n//! ```\n//! .ai/\n//! context/\n//! commands/ # Command-specific context\n//! sync.md # Context for `f sync`\n//! deploy.md # Context for `f deploy`\n//! ...\n//! tasks/ # Task-specific context (by task name)\n//! build.md\n//! test.md\n//! ...\n//! project.md # General project context\n//! ```\n//!\n//! ## Usage\n//!\n//! Context files are markdown with rules, patterns, and instructions\n//! that get included in AI prompts for better conflict resolution,\n//! code generation, and task execution.\n\nuse std::fs;\nuse std::path::{Path, PathBuf};\n\n/// Find the project root by looking for common markers.\npub fn find_project_root() -> Option<PathBuf> {\n let cwd = std::env::current_dir().ok()?;\n let mut current = cwd.as_path();\n\n loop {\n // Check for .ai/context directory\n if current.join(\".ai/context\").exists() {\n return Some(current.to_path_buf());\n }\n // Check for other common project markers\n if current.join(\".git\").exists()\n || current.join(\"flow.toml\").exists()\n || current.join(\"Cargo.toml\").exists()\n || current.join(\"package.json\").exists()\n {\n return Some(current.to_path_buf());\n }\n current = current.parent()?;\n }\n}\n\n/// Load context for a specific flow command (e.g., \"sync\", \"deploy\").\npub fn load_command_context(command: &str) -> Option<String> {\n let root = find_project_root()?;\n let context_path = root\n .join(\".ai/context/commands\")\n .join(format!(\"{}.md\", command));\n load_context_file(&context_path)\n}\n\n/// Load context for a specific task name.\npub fn load_task_context(task_name: &str) -> Option<String> {\n let root = find_project_root()?;\n let context_path = root\n .join(\".ai/context/tasks\")\n .join(format!(\"{}.md\", task_name));\n load_context_file(&context_path)\n}\n\n/// Load the general project context.\npub fn load_project_context() -> Option<String> {\n let root = find_project_root()?;\n let context_path = root.join(\".ai/context/project.md\");\n load_context_file(&context_path)\n}\n\n/// Load all relevant context for a command, combining project + command context.\npub fn load_full_command_context(command: &str) -> String {\n let mut context = String::new();\n\n if let Some(project_ctx) = load_project_context() {\n context.push_str(\"## Project Context\\n\\n\");\n context.push_str(&project_ctx);\n context.push_str(\"\\n\\n\");\n }\n\n if let Some(cmd_ctx) = load_command_context(command) {\n context.push_str(&format!(\"## {} Command Context\\n\\n\", command));\n context.push_str(&cmd_ctx);\n context.push_str(\"\\n\\n\");\n }\n\n context\n}\n\n/// Load a context file if it exists.\nfn load_context_file(path: &Path) -> Option<String> {\n if path.exists() {\n fs::read_to_string(path).ok()\n } else {\n None\n }\n}\n\n/// Check if any AI context exists for the current project.\npub fn has_ai_context() -> bool {\n find_project_root()\n .map(|root| root.join(\".ai/context\").exists())\n .unwrap_or(false)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn test_find_project_root_returns_some_in_git_repo() {\n // This test assumes we're running from within a git repo\n let root = find_project_root();\n assert!(root.is_some() || std::env::var(\"CI\").is_ok());\n }\n}\n" }, { "path": "src/ai_everruns.rs", "content": "use std::collections::HashSet;\nuse std::io::{self, BufRead, BufReader, IsTerminal, Read};\nuse std::path::{Path, PathBuf};\nuse std::thread;\nuse std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result, bail};\nuse reqwest::blocking::{Client, RequestBuilder};\nuse seq_everruns_bridge::{\n ToolCall as BridgeToolCall, build_request as bridge_build_request,\n client_side_tool_definitions as bridge_tool_definitions,\n maple::{MapleSpan, MapleTraceExporter},\n parse_tool_call_requested,\n};\nuse serde::{Deserialize, Serialize};\nuse serde_json::{Map, Value, json};\n\nuse crate::cli::AiEverrunsOpts;\nuse crate::config::{self, EverrunsConfig};\nuse crate::rl_signals;\nuse crate::seq_client::{RpcRequest, SeqClient};\n\nconst DEFAULT_EVERRUNS_BASE_URL: &str = \"http://127.0.0.1:9300/api\";\nconst DEFAULT_EVERRUNS_API_KEY_ENV: &str = \"EVERRUNS_API_KEY\";\nconst DEFAULT_SEQ_SOCKET: &str = \"/tmp/seqd.sock\";\n\npub fn run(opts: AiEverrunsOpts) -> Result<()> {\n let prompt = resolve_prompt(&opts)?;\n let resolved = ResolvedSettings::from_opts(&opts)?;\n let api = EverrunsApi::new(resolved.base_url.clone(), resolved.api_key.clone())?;\n\n let session_id = resolve_session_id(&api, &resolved)?;\n let seq_bridge = SeqBridge::connect(&resolved)?;\n\n eprintln!(\"everruns session: {}\", session_id);\n\n let message_id = api.post_message(&session_id, &prompt)?;\n eprintln!(\"message_id: {}\", message_id);\n\n rl_signals::emit(json!({\n \"event_type\": \"everruns.run_started\",\n \"runtime\": \"everruns\",\n \"session_id\": session_id,\n \"input_message_id\": message_id,\n \"prompt_chars\": prompt.chars().count(),\n \"prompt_text\": text_signal_payload(&prompt),\n \"poll_interval_ms\": resolved.poll_ms,\n \"timeout_secs\": resolved.wait_timeout_secs,\n \"seq_socket\": resolved.seq_socket.display().to_string(),\n \"no_seq_tools\": resolved.no_seq_tools,\n }));\n\n let run_started = Instant::now();\n let result = wait_for_completion(\n &api,\n &seq_bridge,\n &session_id,\n &message_id,\n &prompt,\n resolved.poll_ms,\n resolved.wait_timeout_secs,\n );\n\n let runtime_ms = run_started.elapsed().as_millis() as u64;\n match &result {\n Ok(_) => rl_signals::emit(json!({\n \"event_type\": \"everruns.run_completed\",\n \"runtime\": \"everruns\",\n \"session_id\": session_id,\n \"input_message_id\": message_id,\n \"ok\": true,\n \"runtime_ms\": runtime_ms,\n })),\n Err(err) => rl_signals::emit(json!({\n \"event_type\": \"everruns.run_failed\",\n \"runtime\": \"everruns\",\n \"session_id\": session_id,\n \"input_message_id\": message_id,\n \"ok\": false,\n \"runtime_ms\": runtime_ms,\n \"error\": err.to_string(),\n \"error_class\": classify_error_text(&err.to_string()),\n })),\n }\n result\n}\n\nfn resolve_prompt(opts: &AiEverrunsOpts) -> Result<String> {\n if !opts.prompt.is_empty() {\n let joined = opts.prompt.join(\" \").trim().to_string();\n if joined.is_empty() {\n bail!(\"prompt is empty\");\n };\n return Ok(joined);\n }\n\n if io::stdin().is_terminal() {\n bail!(\"missing prompt. Usage: f ai everruns \\\"your prompt\\\"\");\n }\n\n let mut buf = String::new();\n io::stdin()\n .read_to_string(&mut buf)\n .context(\"failed to read prompt from stdin\")?;\n let prompt = buf.trim().to_string();\n if prompt.is_empty() {\n bail!(\"prompt from stdin is empty\");\n }\n Ok(prompt)\n}\n\nfn wait_for_completion(\n api: &EverrunsApi,\n seq_bridge: &SeqBridge,\n session_id: &str,\n input_message_id: &str,\n prompt: &str,\n poll_ms: u64,\n wait_timeout_secs: u64,\n) -> Result<()> {\n match wait_for_completion_sse(\n api,\n seq_bridge,\n session_id,\n input_message_id,\n prompt,\n poll_ms,\n wait_timeout_secs,\n ) {\n Ok(()) => Ok(()),\n Err(err) => {\n if is_sse_unavailable_error(&err) {\n eprintln!(\n \"note: Everruns SSE endpoint unavailable, falling back to /events polling\"\n );\n rl_signals::emit(json!({\n \"event_type\": \"everruns.transport_fallback\",\n \"runtime\": \"everruns\",\n \"session_id\": session_id,\n \"input_message_id\": input_message_id,\n \"from\": \"sse\",\n \"to\": \"poll\",\n \"reason\": err.to_string(),\n }));\n return wait_for_completion_poll(\n api,\n seq_bridge,\n session_id,\n input_message_id,\n prompt,\n poll_ms,\n wait_timeout_secs,\n );\n }\n Err(err)\n }\n }\n}\n\nfn wait_for_completion_sse(\n api: &EverrunsApi,\n seq_bridge: &SeqBridge,\n session_id: &str,\n input_message_id: &str,\n prompt: &str,\n poll_ms: u64,\n wait_timeout_secs: u64,\n) -> Result<()> {\n let started = Instant::now();\n let timeout = Duration::from_secs(wait_timeout_secs.max(1));\n let mut since_id: Option<String> = None;\n let mut handled_tool_calls = HashSet::new();\n let mut saw_stream = false;\n\n loop {\n if started.elapsed() > timeout {\n bail!(\n \"timed out waiting for Everruns output after {}s\",\n wait_timeout_secs\n );\n }\n\n let remaining = timeout.saturating_sub(started.elapsed());\n let stream_timeout = remaining\n .min(Duration::from_secs(70))\n .max(Duration::from_secs(1));\n\n let batch = match api.read_sse_batch(session_id, since_id.as_deref(), stream_timeout) {\n Ok(batch) => {\n saw_stream = true;\n batch\n }\n Err(err) => {\n if !saw_stream && is_sse_unavailable_error(&err) {\n return Err(err);\n }\n thread::sleep(Duration::from_millis(poll_ms.max(25)));\n continue;\n }\n };\n\n let mut did_work = false;\n for event in batch.events {\n let event_started = Instant::now();\n let event_start_ns = unix_time_nanos_now();\n since_id = Some(event.id.clone());\n\n if let Some(ref event_input_id) = event.context.input_message_id\n && event_input_id != input_message_id\n {\n continue;\n }\n\n match event.event_type.as_str() {\n \"tool.call_requested\" => {\n let requested_calls =\n parse_tool_call_requested(&event.data).with_context(|| {\n format!(\n \"failed to parse tool.call_requested payload for event {}\",\n event.id\n )\n })?;\n\n let requested_count = requested_calls.len();\n let mut tool_results = Vec::new();\n for call in requested_calls {\n if !handled_tool_calls.insert(call.id.clone()) {\n continue;\n }\n tool_results\n .push(seq_bridge.execute_tool_call(session_id, &event.id, call));\n }\n let unique_count = tool_results.len();\n let duplicate_count = requested_count.saturating_sub(unique_count);\n\n if !tool_results.is_empty() {\n api.submit_tool_results(session_id, tool_results)?;\n did_work = true;\n }\n seq_bridge.emit_runtime_event(\n session_id,\n &event.id,\n \"tool_call_requested\",\n true,\n None,\n event_start_ns,\n end_unix_nanos(event_start_ns, event_started),\n vec![\n (\n \"tool_calls.requested\".to_string(),\n requested_count.to_string(),\n ),\n (\"tool_calls.unique\".to_string(), unique_count.to_string()),\n (\n \"tool_calls.duplicates_filtered\".to_string(),\n duplicate_count.to_string(),\n ),\n ],\n );\n }\n \"output.message.completed\" => {\n let output_text = extract_output_text(&event.data);\n if let Some(text) = output_text.as_ref() {\n println!(\"{}\", text);\n } else {\n println!(\"{}\", serde_json::to_string_pretty(&event.data)?);\n }\n let output_chars = output_text.as_ref().map(|t| t.chars().count()).unwrap_or(0);\n seq_bridge.emit_runtime_event(\n session_id,\n &event.id,\n \"output_message_completed\",\n true,\n None,\n event_start_ns,\n end_unix_nanos(event_start_ns, event_started),\n vec![(\"output_chars\".to_string(), output_chars.to_string())],\n );\n emit_qa_pair_signal(\n session_id,\n input_message_id,\n &event.id,\n prompt,\n output_text.as_deref().unwrap_or(\"\"),\n );\n return Ok(());\n }\n \"turn.failed\" => {\n let error = event\n .data\n .get(\"error\")\n .and_then(Value::as_str)\n .unwrap_or(\"unknown turn failure\");\n seq_bridge.emit_runtime_event(\n session_id,\n &event.id,\n \"turn_failed\",\n false,\n Some(error),\n event_start_ns,\n end_unix_nanos(event_start_ns, event_started),\n vec![(\n \"error_class\".to_string(),\n classify_error_text(error).to_string(),\n )],\n );\n bail!(\"everruns turn failed: {}\", error);\n }\n _ => {\n seq_bridge.emit_runtime_event(\n session_id,\n &event.id,\n &format!(\"event_{}\", event.event_type.replace(['.', '-', ' '], \"_\")),\n true,\n None,\n event_start_ns,\n end_unix_nanos(event_start_ns, event_started),\n vec![],\n );\n }\n }\n }\n\n if !did_work && !batch.saw_disconnect {\n thread::sleep(Duration::from_millis(poll_ms.max(25)));\n }\n }\n}\n\nfn wait_for_completion_poll(\n api: &EverrunsApi,\n seq_bridge: &SeqBridge,\n session_id: &str,\n input_message_id: &str,\n prompt: &str,\n poll_ms: u64,\n wait_timeout_secs: u64,\n) -> Result<()> {\n let started = Instant::now();\n let mut since_id: Option<String> = None;\n let mut handled_tool_calls = HashSet::new();\n\n loop {\n if started.elapsed() > Duration::from_secs(wait_timeout_secs.max(1)) {\n bail!(\n \"timed out waiting for Everruns output after {}s\",\n wait_timeout_secs\n );\n }\n\n let events = api.list_events(session_id, since_id.as_deref())?;\n if let Some(last) = events.last() {\n since_id = Some(last.id.clone());\n }\n\n let mut did_work = false;\n for event in events {\n let event_started = Instant::now();\n let event_start_ns = unix_time_nanos_now();\n if let Some(ref event_input_id) = event.context.input_message_id\n && event_input_id != input_message_id\n {\n continue;\n }\n\n match event.event_type.as_str() {\n \"tool.call_requested\" => {\n let requested_calls =\n parse_tool_call_requested(&event.data).with_context(|| {\n format!(\n \"failed to parse tool.call_requested payload for event {}\",\n event.id\n )\n })?;\n\n let requested_count = requested_calls.len();\n let mut tool_results = Vec::new();\n for call in requested_calls {\n if !handled_tool_calls.insert(call.id.clone()) {\n continue;\n }\n tool_results\n .push(seq_bridge.execute_tool_call(session_id, &event.id, call));\n }\n let unique_count = tool_results.len();\n let duplicate_count = requested_count.saturating_sub(unique_count);\n\n if !tool_results.is_empty() {\n api.submit_tool_results(session_id, tool_results)?;\n did_work = true;\n }\n seq_bridge.emit_runtime_event(\n session_id,\n &event.id,\n \"tool_call_requested\",\n true,\n None,\n event_start_ns,\n end_unix_nanos(event_start_ns, event_started),\n vec![\n (\n \"tool_calls.requested\".to_string(),\n requested_count.to_string(),\n ),\n (\"tool_calls.unique\".to_string(), unique_count.to_string()),\n (\n \"tool_calls.duplicates_filtered\".to_string(),\n duplicate_count.to_string(),\n ),\n ],\n );\n }\n \"output.message.completed\" => {\n let output_text = extract_output_text(&event.data);\n if let Some(text) = output_text.as_ref() {\n println!(\"{}\", text);\n } else {\n println!(\"{}\", serde_json::to_string_pretty(&event.data)?);\n }\n let output_chars = output_text.as_ref().map(|t| t.chars().count()).unwrap_or(0);\n seq_bridge.emit_runtime_event(\n session_id,\n &event.id,\n \"output_message_completed\",\n true,\n None,\n event_start_ns,\n end_unix_nanos(event_start_ns, event_started),\n vec![(\"output_chars\".to_string(), output_chars.to_string())],\n );\n emit_qa_pair_signal(\n session_id,\n input_message_id,\n &event.id,\n prompt,\n output_text.as_deref().unwrap_or(\"\"),\n );\n return Ok(());\n }\n \"turn.failed\" => {\n let error = event\n .data\n .get(\"error\")\n .and_then(Value::as_str)\n .unwrap_or(\"unknown turn failure\");\n seq_bridge.emit_runtime_event(\n session_id,\n &event.id,\n \"turn_failed\",\n false,\n Some(error),\n event_start_ns,\n end_unix_nanos(event_start_ns, event_started),\n vec![(\n \"error_class\".to_string(),\n classify_error_text(error).to_string(),\n )],\n );\n bail!(\"everruns turn failed: {}\", error);\n }\n _ => {\n seq_bridge.emit_runtime_event(\n session_id,\n &event.id,\n &format!(\"event_{}\", event.event_type.replace(['.', '-', ' '], \"_\")),\n true,\n None,\n event_start_ns,\n end_unix_nanos(event_start_ns, event_started),\n vec![],\n );\n }\n }\n }\n\n if !did_work {\n thread::sleep(Duration::from_millis(poll_ms.max(25)));\n }\n }\n}\n\nfn is_sse_unavailable_error(err: &anyhow::Error) -> bool {\n let text = err.to_string().to_ascii_lowercase();\n text.contains(\"sse endpoint unavailable\")\n}\n\nfn classify_error_text(err: &str) -> &'static str {\n let lower = err.to_ascii_lowercase();\n if lower.contains(\"timed out\") || lower.contains(\"timeout\") {\n return \"timeout\";\n }\n if lower.contains(\"failed to connect\") || lower.contains(\"unreachable\") {\n return \"connectivity\";\n }\n if lower.contains(\"mutex poisoned\") {\n return \"concurrency\";\n }\n if lower.contains(\"failed to parse\") || lower.contains(\"invalid json\") {\n return \"parse\";\n }\n if lower.contains(\"unsupported\") {\n return \"unsupported\";\n }\n if lower.contains(\"turn failed\") {\n return \"turn_failed\";\n }\n \"runtime_error\"\n}\n\nfn emit_qa_pair_signal(\n session_id: &str,\n input_message_id: &str,\n event_id: &str,\n prompt: &str,\n output: &str,\n) {\n rl_signals::emit(json!({\n \"event_type\": \"everruns.qa_pair\",\n \"runtime\": \"everruns\",\n \"session_id\": session_id,\n \"input_message_id\": input_message_id,\n \"event_id\": event_id,\n \"ok\": !output.trim().is_empty(),\n \"prompt_text\": text_signal_payload(prompt),\n \"response_text\": text_signal_payload(output),\n }));\n}\n\n#[derive(Clone, Copy, Debug)]\nenum SignalTextMode {\n Off,\n Snippet,\n Full,\n}\n\nfn signal_text_mode() -> SignalTextMode {\n let raw = std::env::var(\"FLOW_RL_SIGNAL_TEXT\")\n .unwrap_or_else(|_| \"snippet\".to_string())\n .to_ascii_lowercase();\n match raw.as_str() {\n \"0\" | \"off\" | \"none\" | \"false\" => SignalTextMode::Off,\n \"full\" | \"all\" => SignalTextMode::Full,\n _ => SignalTextMode::Snippet,\n }\n}\n\nfn signal_text_max_chars() -> usize {\n std::env::var(\"FLOW_RL_SIGNAL_MAX_CHARS\")\n .ok()\n .and_then(|raw| raw.parse::<usize>().ok())\n .unwrap_or(4000)\n .clamp(256, 100_000)\n}\n\nfn text_signal_payload(text: &str) -> Value {\n let trimmed = text.trim();\n let chars = trimmed.chars().count();\n let max_chars = signal_text_max_chars();\n match signal_text_mode() {\n SignalTextMode::Off => json!({\n \"chars\": chars,\n \"captured\": false,\n }),\n SignalTextMode::Snippet => {\n let snippet: String = trimmed.chars().take(max_chars).collect();\n json!({\n \"chars\": chars,\n \"captured\": true,\n \"truncated\": chars > max_chars,\n \"text\": snippet,\n })\n }\n SignalTextMode::Full => json!({\n \"chars\": chars,\n \"captured\": true,\n \"truncated\": false,\n \"text\": trimmed,\n }),\n }\n}\n\nfn extract_output_text(data: &Value) -> Option<String> {\n let content = data\n .get(\"message\")\n .and_then(|m| m.get(\"content\"))\n .and_then(Value::as_array)?;\n let mut out = Vec::new();\n for part in content {\n if let Some(text) = part.get(\"text\").and_then(Value::as_str)\n && !text.trim().is_empty()\n {\n out.push(text.to_string());\n }\n }\n if out.is_empty() {\n None\n } else {\n Some(out.join(\"\\n\"))\n }\n}\n\nfn resolve_session_id(api: &EverrunsApi, resolved: &ResolvedSettings) -> Result<String> {\n if let Some(session_id) = resolved.session_id.as_ref() {\n if !resolved.no_seq_tools {\n eprintln!(\n \"note: reusing session {} (seq tools are not injected for existing sessions)\",\n session_id\n );\n }\n return Ok(session_id.clone());\n }\n\n let harness_id = if let Some(id) = resolved.harness_id.clone() {\n id\n } else {\n api.pick_first_harness_id()?\n };\n\n let agent_id = resolved\n .agent_id\n .clone()\n .or_else(|| api.pick_first_agent_id().ok());\n\n let mut body = Map::new();\n body.insert(\"harness_id\".to_string(), Value::String(harness_id.clone()));\n if let Some(agent_id) = agent_id {\n body.insert(\"agent_id\".to_string(), Value::String(agent_id));\n }\n if let Some(model_id) = resolved.model_id.clone() {\n body.insert(\"model_id\".to_string(), Value::String(model_id));\n }\n if !resolved.no_seq_tools {\n body.insert(\"tools\".to_string(), Value::Array(bridge_tool_definitions()));\n }\n\n let session_id = api.create_session(Value::Object(body))?;\n eprintln!(\"created session {} (harness_id={})\", session_id, harness_id);\n Ok(session_id)\n}\n\n#[derive(Debug, Clone)]\nstruct ResolvedSettings {\n base_url: String,\n api_key: Option<String>,\n session_id: Option<String>,\n agent_id: Option<String>,\n harness_id: Option<String>,\n model_id: Option<String>,\n poll_ms: u64,\n wait_timeout_secs: u64,\n seq_socket: PathBuf,\n seq_timeout_ms: u64,\n no_seq_tools: bool,\n}\n\nimpl ResolvedSettings {\n fn from_opts(opts: &AiEverrunsOpts) -> Result<Self> {\n let cfg = load_project_everruns_config();\n\n let api_key_env = env_non_empty(\"FLOW_EVERRUNS_API_KEY_ENV\")\n .or_else(|| cfg.as_ref().and_then(|c| c.api_key_env.clone()))\n .unwrap_or_else(|| DEFAULT_EVERRUNS_API_KEY_ENV.to_string());\n\n let base_url = first_non_empty(\n opts.base_url.clone(),\n env_non_empty(\"FLOW_EVERRUNS_BASE_URL\")\n .or_else(|| env_non_empty(\"EVERRUNS_BASE_URL\"))\n .or_else(|| cfg.as_ref().and_then(|c| c.base_url.clone()))\n .or_else(|| Some(DEFAULT_EVERRUNS_BASE_URL.to_string())),\n )\n .unwrap_or_else(|| DEFAULT_EVERRUNS_BASE_URL.to_string());\n let base_url = normalize_base_url(&base_url)?;\n\n let api_key = first_non_empty(\n opts.api_key.clone(),\n env_non_empty(\"FLOW_EVERRUNS_API_KEY\")\n .or_else(|| env_non_empty(&api_key_env))\n .or_else(|| env_non_empty(\"EVERRUNS_API_KEY\")),\n );\n\n let session_id = first_non_empty(\n opts.session_id.clone(),\n env_non_empty(\"FLOW_EVERRUNS_SESSION_ID\")\n .or_else(|| env_non_empty(\"EVERRUNS_SESSION_ID\"))\n .or_else(|| cfg.as_ref().and_then(|c| c.session_id.clone())),\n );\n let agent_id = first_non_empty(\n opts.agent_id.clone(),\n env_non_empty(\"FLOW_EVERRUNS_AGENT_ID\")\n .or_else(|| env_non_empty(\"EVERRUNS_AGENT_ID\"))\n .or_else(|| cfg.as_ref().and_then(|c| c.agent_id.clone())),\n );\n let harness_id = first_non_empty(\n opts.harness_id.clone(),\n env_non_empty(\"FLOW_EVERRUNS_HARNESS_ID\")\n .or_else(|| env_non_empty(\"EVERRUNS_HARNESS_ID\"))\n .or_else(|| cfg.as_ref().and_then(|c| c.harness_id.clone())),\n );\n let model_id = first_non_empty(\n opts.model_id.clone(),\n env_non_empty(\"FLOW_EVERRUNS_MODEL_ID\")\n .or_else(|| env_non_empty(\"EVERRUNS_MODEL_ID\"))\n .or_else(|| cfg.as_ref().and_then(|c| c.model_id.clone())),\n );\n\n let seq_socket = resolve_seq_socket_path(opts.seq_socket.clone());\n\n Ok(Self {\n base_url,\n api_key,\n session_id,\n agent_id,\n harness_id,\n model_id,\n poll_ms: opts.poll_ms.max(25),\n wait_timeout_secs: opts.wait_timeout_secs.max(1),\n seq_socket,\n seq_timeout_ms: opts.seq_timeout_ms.max(1),\n no_seq_tools: opts.no_seq_tools,\n })\n }\n}\n\nfn normalize_base_url(raw: &str) -> Result<String> {\n let mut url = raw.trim().to_string();\n if url.is_empty() {\n bail!(\"Everruns base URL is empty\");\n }\n while url.ends_with('/') {\n url.pop();\n }\n if !url.starts_with(\"http://\") && !url.starts_with(\"https://\") {\n bail!(\n \"invalid Everruns base URL '{}': must start with http:// or https://\",\n raw\n );\n }\n Ok(url)\n}\n\nfn resolve_seq_socket_path(cli_socket: Option<PathBuf>) -> PathBuf {\n if let Some(path) = cli_socket {\n return path;\n }\n if let Some(path) = env_non_empty(\"SEQ_SOCKET_PATH\") {\n return PathBuf::from(path);\n }\n if let Some(path) = env_non_empty(\"SEQD_SOCKET\") {\n return PathBuf::from(path);\n }\n PathBuf::from(DEFAULT_SEQ_SOCKET)\n}\n\nfn load_project_everruns_config() -> Option<EverrunsConfig> {\n let cwd = std::env::current_dir().ok()?;\n let flow_toml = find_flow_toml_upwards(&cwd)?;\n let cfg = config::load(flow_toml).ok()?;\n cfg.everruns\n}\n\nfn find_flow_toml_upwards(start: &Path) -> Option<PathBuf> {\n let mut current = Some(start.to_path_buf());\n while let Some(dir) = current {\n let candidate = dir.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n current = dir.parent().map(Path::to_path_buf);\n }\n None\n}\n\nfn first_non_empty(a: Option<String>, b: Option<String>) -> Option<String> {\n for candidate in [a, b].into_iter().flatten() {\n let trimmed = candidate.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n }\n }\n None\n}\n\nfn env_non_empty(name: &str) -> Option<String> {\n let value = std::env::var(name).ok()?;\n let trimmed = value.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n }\n}\n\n#[derive(Clone)]\nstruct EverrunsApi {\n client: Client,\n sse_client: Client,\n base_url: String,\n api_key: Option<String>,\n}\n\nimpl EverrunsApi {\n fn new(base_url: String, api_key: Option<String>) -> Result<Self> {\n let client = Client::builder()\n .timeout(Duration::from_secs(30))\n .build()\n .context(\"failed to build Everruns HTTP client\")?;\n let sse_client = Client::builder()\n .connect_timeout(Duration::from_secs(5))\n .build()\n .context(\"failed to build Everruns SSE HTTP client\")?;\n Ok(Self {\n client,\n sse_client,\n base_url,\n api_key,\n })\n }\n\n fn pick_first_harness_id(&self) -> Result<String> {\n let value = self.get_json(\"/v1/harnesses\", &[])?;\n let resp: ListResponse<ResourceStub> =\n serde_json::from_value(value).context(\"failed to decode harness list response\")?;\n resp.data\n .into_iter()\n .find(|h| h.status.as_deref() != Some(\"disabled\"))\n .map(|h| h.id)\n .ok_or_else(|| anyhow::anyhow!(\"no harnesses found in Everruns\"))\n }\n\n fn pick_first_agent_id(&self) -> Result<String> {\n let value = self.get_json(\"/v1/agents\", &[])?;\n let resp: ListResponse<ResourceStub> =\n serde_json::from_value(value).context(\"failed to decode agent list response\")?;\n resp.data\n .into_iter()\n .find(|a| a.status.as_deref() != Some(\"archived\"))\n .map(|a| a.id)\n .ok_or_else(|| anyhow::anyhow!(\"no agents found in Everruns\"))\n }\n\n fn create_session(&self, body: Value) -> Result<String> {\n let value = self.post_json(\"/v1/sessions\", body)?;\n value\n .get(\"id\")\n .and_then(Value::as_str)\n .map(|s| s.to_string())\n .ok_or_else(|| anyhow::anyhow!(\"Everruns create session response missing id\"))\n }\n\n fn post_message(&self, session_id: &str, prompt: &str) -> Result<String> {\n let path = format!(\"/v1/sessions/{}/messages\", session_id);\n let payload = json!({\n \"message\": {\n \"content\": [\n { \"type\": \"text\", \"text\": prompt }\n ]\n }\n });\n let value = self.post_json(&path, payload)?;\n value\n .get(\"id\")\n .and_then(Value::as_str)\n .map(|s| s.to_string())\n .ok_or_else(|| anyhow::anyhow!(\"Everruns create message response missing id\"))\n }\n\n fn list_events(&self, session_id: &str, since_id: Option<&str>) -> Result<Vec<EverrunsEvent>> {\n let path = format!(\"/v1/sessions/{}/events\", session_id);\n let mut query: Vec<(&str, String)> = vec![\n (\"exclude\", \"output.message.delta\".to_string()),\n (\"exclude\", \"reason.thinking.delta\".to_string()),\n ];\n if let Some(since_id) = since_id {\n query.push((\"since_id\", since_id.to_string()));\n }\n\n let value = self.get_json(&path, &query)?;\n let resp: ListResponse<EverrunsEvent> =\n serde_json::from_value(value).context(\"failed to decode events response\")?;\n Ok(resp.data)\n }\n\n fn submit_tool_results(\n &self,\n session_id: &str,\n tool_results: Vec<SubmitToolResult>,\n ) -> Result<()> {\n let path = format!(\"/v1/sessions/{}/tool-results\", session_id);\n let payload = SubmitToolResultsRequest { tool_results };\n let _ = self.post_json(&path, serde_json::to_value(payload)?)?;\n Ok(())\n }\n\n fn read_sse_batch(\n &self,\n session_id: &str,\n since_id: Option<&str>,\n timeout: Duration,\n ) -> Result<SseBatch> {\n let path = format!(\"/v1/sessions/{}/sse\", session_id);\n let url = format!(\"{}{}\", self.base_url, path);\n let mut query: Vec<(&str, String)> = vec![\n (\"exclude\", \"output.message.delta\".to_string()),\n (\"exclude\", \"reason.thinking.delta\".to_string()),\n ];\n if let Some(since_id) = since_id {\n query.push((\"since_id\", since_id.to_string()));\n }\n\n let request = self\n .with_auth(self.sse_client.get(url))\n .query(&query)\n .header(\"accept\", \"text/event-stream\")\n .timeout(timeout);\n let response = request\n .send()\n .with_context(|| format!(\"Everruns API GET {} request failed\", path))?;\n let status = response.status();\n if !status.is_success() {\n let body = response.text().unwrap_or_default();\n if status.as_u16() == 404 || status.as_u16() == 405 || status.as_u16() == 501 {\n bail!(\n \"sse endpoint unavailable: Everruns API GET {} returned {}: {}\",\n path,\n status,\n body\n );\n }\n bail!(\"Everruns API GET {} returned {}: {}\", path, status, body);\n }\n\n let mut reader = BufReader::new(response);\n let mut line = String::new();\n let mut current_event = String::new();\n let mut current_data: Vec<String> = Vec::new();\n let mut out = Vec::new();\n let mut saw_disconnect = false;\n\n loop {\n line.clear();\n let n = reader\n .read_line(&mut line)\n .with_context(|| format!(\"failed to read Everruns SSE line from {}\", path))?;\n if n == 0 {\n break;\n }\n\n let raw = line.trim_end_matches(&['\\r', '\\n'][..]);\n if raw.is_empty() {\n match decode_sse_frame(¤t_event, ¤t_data.join(\"\\n\"))? {\n SseFrame::Event(event) => out.push(event),\n SseFrame::Disconnecting => {\n saw_disconnect = true;\n break;\n }\n SseFrame::Ignore => {}\n }\n current_event.clear();\n current_data.clear();\n continue;\n }\n if raw.starts_with(':') {\n continue;\n }\n if let Some(rest) = raw.strip_prefix(\"event:\") {\n current_event = rest.trim().to_string();\n continue;\n }\n if let Some(rest) = raw.strip_prefix(\"data:\") {\n current_data.push(rest.trim_start().to_string());\n continue;\n }\n }\n\n if !current_event.is_empty() || !current_data.is_empty() {\n match decode_sse_frame(¤t_event, ¤t_data.join(\"\\n\"))? {\n SseFrame::Event(event) => out.push(event),\n SseFrame::Disconnecting => {\n saw_disconnect = true;\n }\n SseFrame::Ignore => {}\n }\n }\n\n Ok(SseBatch {\n events: out,\n saw_disconnect,\n })\n }\n\n fn get_json(&self, path: &str, query: &[(&str, String)]) -> Result<Value> {\n let url = format!(\"{}{}\", self.base_url, path);\n let request = self.with_auth(self.client.get(url)).query(query);\n self.send_json(request, \"GET\", path)\n }\n\n fn post_json(&self, path: &str, body: Value) -> Result<Value> {\n let url = format!(\"{}{}\", self.base_url, path);\n let request = self.with_auth(self.client.post(url)).json(&body);\n self.send_json(request, \"POST\", path)\n }\n\n fn with_auth(&self, request: RequestBuilder) -> RequestBuilder {\n if let Some(api_key) = self.api_key.as_deref() {\n request.bearer_auth(api_key)\n } else {\n request\n }\n }\n\n fn send_json(&self, request: RequestBuilder, method: &str, path: &str) -> Result<Value> {\n let response = request\n .send()\n .with_context(|| format!(\"Everruns API {} {} request failed\", method, path))?;\n let status = response.status();\n let body = response.text().with_context(|| {\n format!(\n \"Everruns API {} {} failed to read response body\",\n method, path\n )\n })?;\n if !status.is_success() {\n bail!(\n \"Everruns API {} {} returned {}: {}\",\n method,\n path,\n status,\n body\n );\n }\n serde_json::from_str(&body).with_context(|| {\n format!(\n \"Everruns API {} {} returned invalid JSON: {}\",\n method, path, body\n )\n })\n }\n}\n\nstruct SeqBridge {\n client: std::sync::Mutex<SeqClient>,\n maple_exporter: Option<MapleTraceExporter>,\n}\n\nimpl SeqBridge {\n fn connect(settings: &ResolvedSettings) -> Result<Self> {\n let timeout = Duration::from_millis(settings.seq_timeout_ms);\n let client =\n SeqClient::connect_with_timeout(&settings.seq_socket, timeout).with_context(|| {\n format!(\n \"failed to connect to seqd at {}\",\n settings.seq_socket.display()\n )\n })?;\n let maple_exporter =\n MapleTraceExporter::from_env().context(\"invalid SEQ_EVERRUNS_MAPLE_* configuration\")?;\n if maple_exporter.is_some() {\n eprintln!(\"maple dual-ingest telemetry enabled\");\n }\n Ok(Self {\n client: std::sync::Mutex::new(client),\n maple_exporter,\n })\n }\n\n fn execute_tool_call(\n &self,\n session_id: &str,\n event_id: &str,\n call: BridgeToolCall,\n ) -> SubmitToolResult {\n let started = Instant::now();\n let start_unix_nano = unix_time_nanos_now();\n let mut seq_op = \"unknown\".to_string();\n\n let result = match bridge_build_request(session_id, event_id, &call) {\n Ok(ext_req) => {\n seq_op = ext_req.op.clone();\n let req = RpcRequest {\n op: ext_req.op,\n args: ext_req.args,\n request_id: ext_req.request_id,\n run_id: ext_req.run_id,\n tool_call_id: ext_req.tool_call_id,\n };\n\n let result_call_id = req\n .tool_call_id\n .as_ref()\n .cloned()\n .unwrap_or_else(|| call.id.clone());\n\n match self.client.lock() {\n Ok(mut client) => match client.call(&req) {\n Ok(resp) => {\n if resp.ok {\n SubmitToolResult {\n tool_call_id: result_call_id,\n result: Some(resp.result.unwrap_or_else(|| json!({}))),\n error: None,\n }\n } else {\n SubmitToolResult {\n tool_call_id: result_call_id,\n result: None,\n error: Some(resp.error.unwrap_or_else(|| {\n format!(\"seq {} failed with unknown error\", seq_op)\n })),\n }\n }\n }\n Err(error) => SubmitToolResult {\n tool_call_id: result_call_id,\n result: None,\n error: Some(format!(\"seq {} call failed: {}\", seq_op, error)),\n },\n },\n Err(_) => SubmitToolResult {\n tool_call_id: result_call_id,\n result: None,\n error: Some(\"seq client mutex poisoned\".to_string()),\n },\n }\n }\n Err(err) => SubmitToolResult {\n tool_call_id: call.id.clone(),\n result: None,\n error: Some(err.to_string()),\n },\n };\n let elapsed = started.elapsed();\n let duration_ms = elapsed.as_millis() as u64;\n let end_unix_nano = start_unix_nano.saturating_add(elapsed.as_nanos() as u64);\n\n rl_signals::emit(json!({\n \"event_type\": \"everruns.tool_call_result\",\n \"runtime\": \"everruns\",\n \"session_id\": session_id,\n \"event_id\": event_id,\n \"tool_call_id\": result.tool_call_id,\n \"tool_name\": call.name,\n \"seq_op\": seq_op,\n \"ok\": result.error.is_none(),\n \"error\": result.error,\n \"error_class\": result.error.as_deref().map(classify_error_text),\n \"duration_ms\": duration_ms,\n }));\n\n if let Some(exporter) = self.maple_exporter.as_ref() {\n let span = MapleSpan::for_tool_call(\n session_id,\n event_id,\n &result.tool_call_id,\n &call.name,\n &seq_op,\n result.error.is_none(),\n result.error.as_deref(),\n start_unix_nano,\n end_unix_nano,\n duration_ms,\n );\n exporter.emit_span(span);\n }\n\n result\n }\n\n fn emit_runtime_event(\n &self,\n session_id: &str,\n event_id: &str,\n stage: &str,\n ok: bool,\n error: Option<&str>,\n start_unix_nano: u64,\n end_unix_nano: u64,\n extra_attributes: Vec<(String, String)>,\n ) {\n let duration_ms = (end_unix_nano.saturating_sub(start_unix_nano)) / 1_000_000;\n let attrs_obj = rl_signals::attrs_to_object(extra_attributes.clone());\n rl_signals::emit(json!({\n \"event_type\": \"everruns.runtime_event\",\n \"runtime\": \"everruns\",\n \"session_id\": session_id,\n \"event_id\": event_id,\n \"stage\": stage,\n \"ok\": ok,\n \"error\": error,\n \"error_class\": error.map(classify_error_text),\n \"duration_ms\": duration_ms,\n \"attrs\": attrs_obj,\n }));\n\n if let Some(exporter) = self.maple_exporter.as_ref() {\n let span = MapleSpan::for_runtime_event(\n session_id,\n event_id,\n stage,\n ok,\n error,\n start_unix_nano,\n end_unix_nano,\n extra_attributes,\n );\n exporter.emit_span(span);\n }\n }\n}\n\nfn unix_time_nanos_now() -> u64 {\n match SystemTime::now().duration_since(UNIX_EPOCH) {\n Ok(dur) => dur.as_nanos() as u64,\n Err(_) => 0,\n }\n}\n\nfn end_unix_nanos(start_unix_nano: u64, started: Instant) -> u64 {\n start_unix_nano.saturating_add(started.elapsed().as_nanos() as u64)\n}\n\n#[derive(Debug, Deserialize)]\nstruct ListResponse<T> {\n data: Vec<T>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ResourceStub {\n id: String,\n #[serde(default)]\n status: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct EverrunsEvent {\n id: String,\n #[serde(rename = \"type\")]\n event_type: String,\n #[serde(default)]\n context: EventContext,\n #[serde(default)]\n data: Value,\n}\n\n#[derive(Debug, Default, Deserialize)]\nstruct EventContext {\n #[serde(default)]\n input_message_id: Option<String>,\n}\n\n#[derive(Debug, Serialize)]\nstruct SubmitToolResultsRequest {\n tool_results: Vec<SubmitToolResult>,\n}\n\n#[derive(Debug, Serialize)]\nstruct SubmitToolResult {\n tool_call_id: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n result: Option<Value>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n error: Option<String>,\n}\n\nstruct SseBatch {\n events: Vec<EverrunsEvent>,\n saw_disconnect: bool,\n}\n\nenum SseFrame {\n Event(EverrunsEvent),\n Disconnecting,\n Ignore,\n}\n\nfn decode_sse_frame(event_type: &str, data: &str) -> Result<SseFrame> {\n if event_type.is_empty() {\n return Ok(SseFrame::Ignore);\n }\n\n let normalized = event_type.trim().to_ascii_lowercase();\n if normalized == \"connected\" {\n return Ok(SseFrame::Ignore);\n }\n if normalized == \"disconnecting\" {\n return Ok(SseFrame::Disconnecting);\n }\n if data.trim().is_empty() {\n return Ok(SseFrame::Ignore);\n }\n\n let parsed: EverrunsEvent = serde_json::from_str(data).with_context(|| {\n format!(\n \"failed to decode Everruns SSE event '{}' payload as JSON\",\n event_type\n )\n })?;\n Ok(SseFrame::Event(parsed))\n}\n" }, { "path": "src/ai_server.rs", "content": "//! Simple AI server client for task matching.\n\nuse std::collections::HashMap;\nuse std::env;\nuse std::thread;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result, bail};\nuse reqwest::blocking::Client;\nuse serde::{Deserialize, Serialize};\n\nuse crate::env as flow_env;\n\nconst DEFAULT_URL: &str = \"http://127.0.0.1:7331\";\nconst MAX_RETRIES: usize = 3;\n\n#[derive(Debug, Serialize)]\nstruct ChatRequest {\n model: String,\n messages: Vec<ChatMessage>,\n temperature: f32,\n}\n\n#[derive(Debug, Serialize)]\nstruct ChatMessage {\n role: String,\n content: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ChatResponse {\n choices: Vec<Choice>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct Choice {\n message: Option<ResponseMessage>,\n text: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ResponseMessage {\n content: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ModelsResponse {\n data: Vec<ModelInfo>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ModelInfo {\n id: String,\n}\n\nstruct AiServerConfig {\n base_url: String,\n model: String,\n token: Option<String>,\n}\n\n/// Send a prompt to the AI server and return a response.\npub fn quick_prompt(\n prompt: &str,\n model: Option<&str>,\n url: Option<&str>,\n token: Option<&str>,\n) -> Result<String> {\n let prompt = prompt.trim();\n if prompt.is_empty() {\n bail!(\"Prompt is empty.\");\n }\n\n let cfg = resolve_ai_config(model, url, token)?;\n\n let client = Client::builder()\n .timeout(Duration::from_secs(30))\n .build()\n .context(\"failed to create HTTP client\")?;\n\n let endpoint = format!(\"{}/v1/chat/completions\", cfg.base_url);\n\n let body = ChatRequest {\n model: cfg.model,\n messages: vec![ChatMessage {\n role: \"user\".to_string(),\n content: prompt.to_string(),\n }],\n temperature: 0.1,\n };\n\n let mut last_error: Option<anyhow::Error> = None;\n for attempt in 1..=MAX_RETRIES {\n let mut req = client.post(&endpoint).json(&body);\n if let Some(token) = cfg.token.as_deref() {\n req = req.bearer_auth(token);\n }\n\n let resp = match req\n .send()\n .with_context(|| format!(\"failed to connect to AI server at {}\", cfg.base_url))\n {\n Ok(resp) => resp,\n Err(err) => {\n let retryable = attempt < MAX_RETRIES;\n if retryable {\n thread::sleep(Duration::from_millis(300 * attempt as u64));\n last_error = Some(err);\n continue;\n }\n return Err(err);\n }\n };\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n let retryable_status = status.is_server_error() || status.as_u16() == 429;\n if retryable_status && attempt < MAX_RETRIES {\n thread::sleep(Duration::from_millis(300 * attempt as u64));\n last_error = Some(anyhow::anyhow!(\n \"AI server returned retryable status {}: {}\",\n status,\n body\n ));\n continue;\n }\n bail!(\"AI server returned status {}: {}\", status, body);\n }\n\n let text_body = resp.text().context(\"failed to read AI server response\")?;\n let parsed: ChatResponse =\n serde_json::from_str(&text_body).context(\"failed to parse AI server response\")?;\n\n let text = parsed\n .choices\n .first()\n .and_then(|c| {\n c.message\n .as_ref()\n .map(|m| m.content.clone())\n .or(c.text.clone())\n })\n .map(|t| t.trim().to_string())\n .unwrap_or_default();\n\n return Ok(text);\n }\n\n if let Some(err) = last_error {\n return Err(err);\n }\n bail!(\"AI request failed unexpectedly without a captured error.\")\n}\n\nfn resolve_ai_config(\n model_override: Option<&str>,\n url_override: Option<&str>,\n token_override: Option<&str>,\n) -> Result<AiServerConfig> {\n let mut resolved: HashMap<String, String> = HashMap::new();\n let mut missing = Vec::new();\n let keys = [\"AI_SERVER_URL\", \"AI_SERVER_MODEL\", \"AI_SERVER_TOKEN\"];\n\n for key in keys {\n if let Ok(value) = env::var(key) {\n if !value.trim().is_empty() {\n resolved.insert(key.to_string(), value);\n continue;\n }\n }\n missing.push(key.to_string());\n }\n\n if !missing.is_empty() {\n if let Ok(vars) = flow_env::fetch_personal_env_vars(&missing) {\n for (key, value) in vars {\n if !value.trim().is_empty() {\n resolved.insert(key, value);\n }\n }\n }\n }\n\n let mut url = url_override\n .map(|s| s.to_string())\n .or_else(|| resolved.get(\"AI_SERVER_URL\").cloned())\n .unwrap_or_else(|| DEFAULT_URL.to_string());\n if url.trim().is_empty() {\n url = DEFAULT_URL.to_string();\n }\n let base_url = base_ai_url(&url);\n\n let token = token_override\n .map(|s| s.to_string())\n .or_else(|| resolved.get(\"AI_SERVER_TOKEN\").cloned())\n .filter(|v| !v.trim().is_empty());\n\n let model = model_override\n .map(|s| s.to_string())\n .or_else(|| resolved.get(\"AI_SERVER_MODEL\").cloned())\n .unwrap_or_default();\n\n let model = if model.trim().is_empty() {\n fetch_default_model(&base_url, token.as_deref())?\n } else {\n model\n };\n\n Ok(AiServerConfig {\n base_url,\n model,\n token,\n })\n}\n\nfn fetch_default_model(base_url: &str, token: Option<&str>) -> Result<String> {\n let client = Client::builder()\n .timeout(Duration::from_secs(5))\n .build()\n .context(\"failed to create HTTP client\")?;\n let url = format!(\"{}/v1/models\", base_url);\n let mut req = client.get(&url);\n if let Some(token) = token {\n req = req.bearer_auth(token);\n }\n\n let resp = req\n .send()\n .with_context(|| format!(\"failed to query models at {}\", base_url))?;\n\n if !resp.status().is_success() {\n bail!(\n \"AI_SERVER_MODEL not set and /v1/models failed with status {}. Set it with: f env set --personal AI_SERVER_MODEL=<model>\",\n resp.status()\n );\n }\n\n let text_body = resp.text().context(\"failed to read models response\")?;\n let parsed: ModelsResponse =\n serde_json::from_str(&text_body).context(\"failed to parse models response\")?;\n\n let model = parsed\n .data\n .into_iter()\n .find(|m| !m.id.trim().is_empty())\n .map(|m| m.id)\n .unwrap_or_default();\n\n if model.trim().is_empty() {\n bail!(\n \"AI_SERVER_MODEL not set and no models returned. Set it with: f env set --personal AI_SERVER_MODEL=<model>\"\n );\n }\n\n Ok(model)\n}\n\nfn base_ai_url(url: &str) -> String {\n let trimmed = url.trim_end_matches('/');\n if let Some(idx) = trimmed.find(\"/v1/\") {\n return trimmed[..idx].to_string();\n }\n trimmed.to_string()\n}\n" }, { "path": "src/ai_taskd.rs", "content": "use std::collections::HashMap;\nuse std::fs;\nuse std::io::{Read, Write};\nuse std::os::unix::net::{UnixListener, UnixStream};\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\nuse std::time::{Duration, Instant};\n\nuse anyhow::{Context, Result, bail};\nuse serde::{Deserialize, Serialize};\nuse serde_json::json;\nuse uuid::Uuid;\n\nuse crate::rl_signals;\nuse crate::{ai_tasks, project_snapshot::AiTaskSnapshot};\n\nconst MSGPACK_WIRE_PREFIX: u8 = 0xFF;\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nenum WireEncoding {\n Json,\n Msgpack,\n}\n\n#[derive(Debug, Clone)]\nstruct CachedDiscovery {\n tasks: Vec<ai_tasks::DiscoveredAiTask>,\n refreshed_at: Instant,\n}\n\n#[derive(Debug, Clone)]\nstruct CachedArtifact {\n binary_path: PathBuf,\n refreshed_at: Instant,\n}\n\n#[derive(Debug, Default)]\nstruct TaskdState {\n discoveries: HashMap<PathBuf, CachedDiscovery>,\n artifacts: HashMap<String, CachedArtifact>,\n}\n\n#[derive(Debug, Serialize, Deserialize)]\n#[serde(tag = \"type\", rename_all = \"snake_case\")]\nenum TaskdRequest {\n Ping,\n Stop,\n Run {\n project_root: String,\n selector: String,\n args: Vec<String>,\n no_cache: bool,\n #[serde(default = \"default_capture_output\")]\n capture_output: bool,\n #[serde(default)]\n include_timings: bool,\n #[serde(default)]\n suggested_task: Option<String>,\n #[serde(default)]\n override_reason: Option<String>,\n },\n}\n\nfn default_capture_output() -> bool {\n true\n}\n\n#[derive(Debug, Serialize, Deserialize)]\nstruct TaskdResponse {\n ok: bool,\n message: String,\n exit_code: i32,\n stdout: String,\n stderr: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n timings: Option<RequestTimings>,\n}\n\n#[derive(Debug, Serialize, Deserialize, Clone)]\nstruct RequestTimings {\n resolve_selector_us: u64,\n run_task_us: u64,\n total_us: u64,\n used_fast_selector: bool,\n used_cache: bool,\n}\n\nimpl RequestTimings {\n fn to_kv_line(&self, selector: &str) -> String {\n format!(\n \"selector={} resolve_us={} run_us={} total_us={} fast_selector={} cache={}\",\n selector,\n self.resolve_selector_us,\n self.run_task_us,\n self.total_us,\n self.used_fast_selector,\n self.used_cache,\n )\n }\n}\n\npub fn start() -> Result<()> {\n if ping().is_ok() {\n println!(\"ai-taskd already running ({})\", socket_path().display());\n return Ok(());\n }\n\n let exe = std::env::current_exe().context(\"failed to resolve current executable\")?;\n let launch = format!(\n \"nohup {} tasks daemon serve >/dev/null 2>&1 &\",\n shell_quote(&exe.to_string_lossy())\n );\n let status = Command::new(\"sh\")\n .arg(\"-lc\")\n .arg(launch)\n .stdin(Stdio::null())\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .context(\"failed to launch ai-taskd\")?;\n if !status.success() {\n bail!(\"failed to launch ai-taskd (status {})\", status);\n }\n\n let deadline = Instant::now() + Duration::from_secs(3);\n while Instant::now() < deadline {\n if ping().is_ok() {\n println!(\"ai-taskd started ({})\", socket_path().display());\n return Ok(());\n }\n std::thread::sleep(Duration::from_millis(100));\n }\n\n bail!(\n \"ai-taskd failed to start within timeout (socket: {})\",\n socket_path().display()\n )\n}\n\npub fn stop() -> Result<()> {\n let response = match send_request(&TaskdRequest::Stop, WireEncoding::Json) {\n Ok(response) => response,\n Err(error) => {\n let message = format!(\"{error:#}\");\n if message.contains(\"Connection refused\")\n || message.contains(\"No such file or directory\")\n {\n fs::remove_file(socket_path()).ok();\n fs::remove_file(pid_path()).ok();\n println!(\"ai-taskd already stopped\");\n return Ok(());\n }\n return Err(error);\n }\n };\n if response.ok {\n println!(\"{}\", response.message);\n Ok(())\n } else {\n bail!(response.message)\n }\n}\n\npub fn status() -> Result<()> {\n if ping().is_ok() {\n println!(\"ai-taskd: running ({})\", socket_path().display());\n } else {\n println!(\"ai-taskd: stopped ({})\", socket_path().display());\n }\n Ok(())\n}\n\npub fn run_via_daemon(\n project_root: &Path,\n selector: &str,\n args: &[String],\n no_cache: bool,\n) -> Result<()> {\n let request = TaskdRequest::Run {\n project_root: project_root.to_string_lossy().to_string(),\n selector: selector.to_string(),\n args: args.to_vec(),\n no_cache,\n capture_output: true,\n include_timings: false,\n suggested_task: read_optional_env(\"FLOW_ROUTER_SUGGESTED_TASK\"),\n override_reason: read_optional_env(\"FLOW_ROUTER_OVERRIDE_REASON\"),\n };\n\n let response = send_request(&request, WireEncoding::Json)?;\n if !response.stdout.is_empty() {\n print!(\"{}\", response.stdout);\n }\n if !response.stderr.is_empty() {\n eprint!(\"{}\", response.stderr);\n }\n\n if response.ok {\n Ok(())\n } else {\n bail!(response.message)\n }\n}\n\npub fn serve() -> Result<()> {\n let socket = socket_path();\n if let Some(parent) = socket.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n\n if socket.exists() {\n fs::remove_file(&socket)\n .with_context(|| format!(\"failed to remove stale socket {}\", socket.display()))?;\n }\n\n let listener = UnixListener::bind(&socket)\n .with_context(|| format!(\"failed to bind ai-taskd socket {}\", socket.display()))?;\n\n if let Some(pid_parent) = pid_path().parent() {\n fs::create_dir_all(pid_parent)\n .with_context(|| format!(\"failed to create {}\", pid_parent.display()))?;\n }\n fs::write(pid_path(), std::process::id().to_string())\n .with_context(|| format!(\"failed to write {}\", pid_path().display()))?;\n\n let mut should_stop = false;\n let mut state = TaskdState::default();\n while !should_stop {\n let (mut stream, _) = match listener.accept() {\n Ok(tuple) => tuple,\n Err(error) => {\n eprintln!(\"warning: ai-taskd accept failed: {}\", error);\n continue;\n }\n };\n let mut payload = Vec::new();\n if let Err(error) = stream.read_to_end(&mut payload) {\n write_error_response(\n &mut stream,\n format!(\"ai-taskd read request failed: {error}\"),\n WireEncoding::Json,\n );\n continue;\n }\n\n let (request, encoding): (TaskdRequest, WireEncoding) = match decode_request(&payload) {\n Ok(request) => request,\n Err(error) => {\n write_error_response(\n &mut stream,\n format!(\"ai-taskd invalid request payload: {error}\"),\n infer_encoding_from_payload(&payload),\n );\n continue;\n }\n };\n let response = handle_request(&request, &mut state);\n if matches!(request, TaskdRequest::Stop) {\n should_stop = true;\n }\n\n let body = match encode_response(&response, encoding) {\n Ok(body) => body,\n Err(error) => {\n write_error_response(\n &mut stream,\n format!(\"ai-taskd encode response failed: {error}\"),\n encoding,\n );\n continue;\n }\n };\n if let Err(error) = stream.write_all(&body) {\n eprintln!(\"warning: ai-taskd write response failed: {}\", error);\n continue;\n }\n stream.flush().ok();\n }\n\n fs::remove_file(&socket).ok();\n fs::remove_file(pid_path()).ok();\n Ok(())\n}\n\nfn handle_request(request: &TaskdRequest, state: &mut TaskdState) -> TaskdResponse {\n match request {\n TaskdRequest::Ping => TaskdResponse {\n ok: true,\n message: \"pong\".to_string(),\n exit_code: 0,\n stdout: String::new(),\n stderr: String::new(),\n timings: None,\n },\n TaskdRequest::Stop => TaskdResponse {\n ok: true,\n message: \"ai-taskd stopping\".to_string(),\n exit_code: 0,\n stdout: String::new(),\n stderr: String::new(),\n timings: None,\n },\n TaskdRequest::Run {\n project_root,\n selector,\n args,\n no_cache,\n capture_output,\n include_timings,\n suggested_task,\n override_reason,\n } => {\n let root = PathBuf::from(project_root);\n match run_request(\n state,\n &root,\n selector,\n args,\n *no_cache,\n *capture_output,\n suggested_task.as_deref(),\n override_reason.as_deref(),\n ) {\n Ok(result) => {\n if (*include_timings || timings_log_enabled())\n && let Some(timings) = result.timings.as_ref()\n && timings_log_enabled()\n {\n eprintln!(\"[ai-taskd][timings] {}\", timings.to_kv_line(selector));\n }\n TaskdResponse {\n ok: result.code == 0,\n message: if result.code == 0 {\n format!(\"ai task '{}' completed\", selector)\n } else {\n format!(\"ai task '{}' failed with status {}\", selector, result.code)\n },\n exit_code: result.code,\n stdout: result.stdout,\n stderr: result.stderr,\n timings: if *include_timings {\n result.timings\n } else {\n None\n },\n }\n }\n Err(e) => TaskdResponse {\n ok: false,\n message: format!(\"ai-taskd run failed: {e}\"),\n exit_code: 1,\n stdout: String::new(),\n stderr: String::new(),\n timings: None,\n },\n }\n }\n }\n}\n\nstruct RunRequestOutcome {\n code: i32,\n stdout: String,\n stderr: String,\n timings: Option<RequestTimings>,\n}\n\nfn discovery_ttl() -> Duration {\n let ms = std::env::var(\"FLOW_AI_TASKD_DISCOVERY_TTL_MS\")\n .ok()\n .and_then(|raw| raw.trim().parse::<u64>().ok())\n .unwrap_or(750);\n Duration::from_millis(ms)\n}\n\nfn artifact_ttl() -> Duration {\n let ms = std::env::var(\"FLOW_AI_TASKD_ARTIFACT_TTL_MS\")\n .ok()\n .and_then(|raw| raw.trim().parse::<u64>().ok())\n .unwrap_or(1500);\n Duration::from_millis(ms)\n}\n\nfn discovery_key(project_root: &Path) -> PathBuf {\n project_root\n .canonicalize()\n .unwrap_or_else(|_| project_root.to_path_buf())\n}\n\nfn ensure_discovery_fresh(state: &mut TaskdState, key: &Path) -> Result<bool> {\n if let Some(entry) = state.discoveries.get(key)\n && entry.refreshed_at.elapsed() <= discovery_ttl()\n {\n return Ok(true);\n }\n refresh_discovery(state, key)?;\n Ok(false)\n}\n\nfn refresh_discovery(state: &mut TaskdState, key: &Path) -> Result<()> {\n let tasks = AiTaskSnapshot::from_canonical_root(key.to_path_buf())?.tasks;\n state.discoveries.insert(\n key.to_path_buf(),\n CachedDiscovery {\n tasks,\n refreshed_at: Instant::now(),\n },\n );\n Ok(())\n}\n\nfn run_request(\n state: &mut TaskdState,\n project_root: &Path,\n selector: &str,\n args: &[String],\n no_cache: bool,\n capture_output: bool,\n suggested_task: Option<&str>,\n override_reason: Option<&str>,\n) -> Result<RunRequestOutcome> {\n let started = Instant::now();\n let resolve_started = Instant::now();\n let mut used_fast_selector = true;\n let mut selected = ai_tasks::resolve_task_fast(project_root, selector)?;\n if selected.is_none() {\n used_fast_selector = false;\n let key = discovery_key(project_root);\n let from_cache = ensure_discovery_fresh(state, &key)?;\n let tasks = state\n .discoveries\n .get(&key)\n .map(|entry| entry.tasks.as_slice())\n .unwrap_or(&[]);\n selected = ai_tasks::select_task(tasks, selector)?.cloned();\n if selected.is_none() && from_cache {\n // If cache was stale, refresh once and retry task selection.\n refresh_discovery(state, &key)?;\n let fresh = state\n .discoveries\n .get(&key)\n .map(|entry| entry.tasks.as_slice())\n .unwrap_or(&[]);\n selected = ai_tasks::select_task(fresh, selector)?.cloned();\n }\n }\n let task = selected.with_context(|| format!(\"AI task '{}' not found\", selector))?;\n let resolve_selector_us = resolve_started.elapsed().as_micros() as u64;\n let decision_id = Uuid::new_v4().simple().to_string();\n let session_id = router_session_id(project_root);\n let context_path = project_root\n .canonicalize()\n .unwrap_or_else(|_| project_root.to_path_buf())\n .display()\n .to_string();\n\n emit_router_decision(\n &decision_id,\n &session_id,\n selector,\n &task.id,\n &context_path,\n args,\n no_cache,\n capture_output,\n used_fast_selector,\n resolve_selector_us,\n );\n if let Some(suggested) = suggested_task\n && !same_task_selector(suggested, &task.id)\n {\n emit_router_override(\n &decision_id,\n &session_id,\n suggested,\n &task.id,\n override_reason.unwrap_or(\"manual_selector_override\"),\n );\n }\n\n let run_started = Instant::now();\n let used_cache = !no_cache;\n if !capture_output && !no_cache {\n let status = run_cached_task_status_hot(state, project_root, &task, args);\n match status {\n Ok(status) => {\n let run_task_us = run_started.elapsed().as_micros() as u64;\n let total_us = started.elapsed().as_micros() as u64;\n let code = status.code().unwrap_or(1);\n emit_router_outcome(\n &decision_id,\n &session_id,\n &task.id,\n code,\n (run_task_us / 1000) as u64,\n \"\",\n used_cache,\n used_fast_selector,\n resolve_selector_us,\n run_task_us,\n total_us,\n );\n return Ok(RunRequestOutcome {\n code,\n stdout: String::new(),\n stderr: String::new(),\n timings: Some(RequestTimings {\n resolve_selector_us,\n run_task_us,\n total_us,\n used_fast_selector,\n used_cache,\n }),\n });\n }\n Err(err) => {\n let run_task_us = run_started.elapsed().as_micros() as u64;\n emit_router_outcome(\n &decision_id,\n &session_id,\n &task.id,\n 1,\n (run_task_us / 1000) as u64,\n &classify_error(&err.to_string()),\n used_cache,\n used_fast_selector,\n resolve_selector_us,\n run_task_us,\n started.elapsed().as_micros() as u64,\n );\n return Err(err);\n }\n }\n }\n\n let output = if no_cache {\n ai_tasks::run_task_via_moon_output(&task, project_root, args)\n } else {\n run_cached_task_output_hot(state, project_root, &task, args)\n };\n let output = match output {\n Ok(output) => output,\n Err(err) => {\n let run_task_us = run_started.elapsed().as_micros() as u64;\n emit_router_outcome(\n &decision_id,\n &session_id,\n &task.id,\n 1,\n (run_task_us / 1000) as u64,\n &classify_error(&err.to_string()),\n used_cache,\n used_fast_selector,\n resolve_selector_us,\n run_task_us,\n started.elapsed().as_micros() as u64,\n );\n return Err(err);\n }\n };\n\n let code = output.status.code().unwrap_or(1);\n let stdout = String::from_utf8_lossy(&output.stdout).to_string();\n let stderr = String::from_utf8_lossy(&output.stderr).to_string();\n let run_task_us = run_started.elapsed().as_micros() as u64;\n let total_us = started.elapsed().as_micros() as u64;\n emit_router_outcome(\n &decision_id,\n &session_id,\n &task.id,\n code,\n (run_task_us / 1000) as u64,\n \"\",\n used_cache,\n used_fast_selector,\n resolve_selector_us,\n run_task_us,\n total_us,\n );\n Ok(RunRequestOutcome {\n code,\n stdout,\n stderr,\n timings: Some(RequestTimings {\n resolve_selector_us,\n run_task_us,\n total_us,\n used_fast_selector,\n used_cache,\n }),\n })\n}\n\nfn router_session_id(project_root: &Path) -> String {\n if let Ok(raw) = std::env::var(\"FLOW_ROUTER_SESSION_ID\") {\n let trimmed = raw.trim();\n if !trimmed.is_empty() {\n return trimmed.to_string();\n }\n }\n\n let root_name = project_root\n .file_name()\n .map(|value| value.to_string_lossy().to_string())\n .unwrap_or_else(|| \"flow\".to_string());\n format!(\"ai-taskd-{}-{}\", std::process::id(), root_name)\n}\n\nfn emit_router_decision(\n decision_id: &str,\n session_id: &str,\n selector: &str,\n chosen_task: &str,\n project_path: &str,\n args: &[String],\n no_cache: bool,\n capture_output: bool,\n used_fast_selector: bool,\n resolve_selector_us: u64,\n) {\n rl_signals::emit(json!({\n \"event_type\": \"flow.router.decision.v1\",\n \"runtime\": \"flow-router\",\n \"source\": \"flow.ai_taskd\",\n \"session_id\": session_id,\n \"event_id\": format!(\"decision-{}\", decision_id),\n \"decision_id\": decision_id,\n \"ok\": true,\n \"subject\": {\n \"schema_version\": \"flow_router_decision_v1\",\n \"decision_id\": decision_id,\n \"source\": \"flow.ai_taskd\",\n \"session_id\": session_id,\n \"project_path\": project_path,\n \"project_fingerprint\": project_path,\n \"chosen_task\": chosen_task,\n \"confidence\": 1.0,\n \"user_intent\": selector,\n \"candidates\": [{\n \"task\": chosen_task,\n \"score\": 1.0,\n }],\n \"context\": {\n \"args\": args,\n \"no_cache\": no_cache,\n \"capture_output\": capture_output,\n \"used_fast_selector\": used_fast_selector,\n \"resolve_selector_us\": resolve_selector_us,\n }\n }\n }));\n}\n\nfn emit_router_override(\n decision_id: &str,\n session_id: &str,\n original_task: &str,\n override_task: &str,\n reason: &str,\n) {\n rl_signals::emit(json!({\n \"event_type\": \"flow.router.override.v1\",\n \"runtime\": \"flow-router\",\n \"source\": \"flow.ai_taskd\",\n \"session_id\": session_id,\n \"event_id\": format!(\"override-{}\", decision_id),\n \"decision_id\": decision_id,\n \"ok\": true,\n \"subject\": {\n \"schema_version\": \"flow_router_override_v1\",\n \"decision_id\": decision_id,\n \"source\": \"flow.ai_taskd\",\n \"session_id\": session_id,\n \"original_task\": original_task,\n \"override_task\": override_task,\n \"reason\": reason,\n }\n }));\n}\n\n#[allow(clippy::too_many_arguments)]\nfn emit_router_outcome(\n decision_id: &str,\n session_id: &str,\n task_executed: &str,\n exit_code: i32,\n time_to_resolution_ms: u64,\n error_kind: &str,\n used_cache: bool,\n used_fast_selector: bool,\n resolve_selector_us: u64,\n run_task_us: u64,\n total_us: u64,\n) {\n let outcome = if exit_code == 0 { \"success\" } else { \"failure\" };\n rl_signals::emit(json!({\n \"event_type\": \"flow.router.outcome.v1\",\n \"runtime\": \"flow-router\",\n \"source\": \"flow.ai_taskd\",\n \"session_id\": session_id,\n \"event_id\": format!(\"outcome-{}\", decision_id),\n \"decision_id\": decision_id,\n \"ok\": exit_code == 0,\n \"subject\": {\n \"schema_version\": \"flow_router_outcome_v1\",\n \"decision_id\": decision_id,\n \"source\": \"flow.ai_taskd\",\n \"session_id\": session_id,\n \"outcome\": outcome,\n \"task_executed\": task_executed,\n \"time_to_resolution_ms\": time_to_resolution_ms,\n \"manual_override_task\": \"\",\n \"error_kind\": error_kind,\n \"extra\": {\n \"exit_code\": exit_code,\n \"used_cache\": used_cache,\n \"used_fast_selector\": used_fast_selector,\n \"resolve_selector_us\": resolve_selector_us,\n \"run_task_us\": run_task_us,\n \"total_us\": total_us,\n }\n }\n }));\n}\n\nfn classify_error(message: &str) -> String {\n let lower = message.to_ascii_lowercase();\n if lower.contains(\"not found\") {\n return \"not_found\".to_string();\n }\n if lower.contains(\"timeout\") {\n return \"timeout\".to_string();\n }\n if lower.contains(\"permission denied\") {\n return \"permission_denied\".to_string();\n }\n if lower.contains(\"connection refused\") || lower.contains(\"failed to connect\") {\n return \"connection_error\".to_string();\n }\n \"runtime_error\".to_string()\n}\n\nfn read_optional_env(key: &str) -> Option<String> {\n let raw = std::env::var(key).ok()?;\n let trimmed = raw.trim();\n if trimmed.is_empty() {\n return None;\n }\n Some(trimmed.to_string())\n}\n\nfn normalize_selector_for_compare(value: &str) -> String {\n let mut out = value.trim().to_ascii_lowercase();\n if let Some(stripped) = out.strip_prefix(\"ai:\") {\n out = stripped.to_string();\n }\n out\n}\n\nfn same_task_selector(a: &str, b: &str) -> bool {\n normalize_selector_for_compare(a) == normalize_selector_for_compare(b)\n}\n\nfn run_cached_task_output_hot(\n state: &mut TaskdState,\n project_root: &Path,\n task: &ai_tasks::DiscoveredAiTask,\n args: &[String],\n) -> Result<std::process::Output> {\n let canonical_root = project_root\n .canonicalize()\n .unwrap_or_else(|_| project_root.to_path_buf());\n let key = format!(\"{}::{}\", canonical_root.display(), task.id);\n\n if let Some(entry) = state.artifacts.get(&key)\n && entry.refreshed_at.elapsed() <= artifact_ttl()\n && entry.binary_path.exists()\n {\n return run_artifact_output(&entry.binary_path, &canonical_root, &task.id, args);\n }\n\n let artifact = ai_tasks::build_task_cached(task, &canonical_root, false)?;\n let binary_path = artifact.binary_path.clone();\n state.artifacts.insert(\n key,\n CachedArtifact {\n binary_path: binary_path.clone(),\n refreshed_at: Instant::now(),\n },\n );\n run_artifact_output(&binary_path, &canonical_root, &task.id, args)\n}\n\nfn run_cached_task_status_hot(\n state: &mut TaskdState,\n project_root: &Path,\n task: &ai_tasks::DiscoveredAiTask,\n args: &[String],\n) -> Result<std::process::ExitStatus> {\n let canonical_root = project_root\n .canonicalize()\n .unwrap_or_else(|_| project_root.to_path_buf());\n let key = format!(\"{}::{}\", canonical_root.display(), task.id);\n\n if let Some(entry) = state.artifacts.get(&key)\n && entry.refreshed_at.elapsed() <= artifact_ttl()\n && entry.binary_path.exists()\n {\n return run_artifact_status(&entry.binary_path, &canonical_root, &task.id, args);\n }\n\n let artifact = ai_tasks::build_task_cached(task, &canonical_root, false)?;\n let binary_path = artifact.binary_path.clone();\n state.artifacts.insert(\n key,\n CachedArtifact {\n binary_path: binary_path.clone(),\n refreshed_at: Instant::now(),\n },\n );\n run_artifact_status(&binary_path, &canonical_root, &task.id, args)\n}\n\nfn run_artifact_output(\n binary_path: &Path,\n project_root: &Path,\n task_id: &str,\n args: &[String],\n) -> Result<std::process::Output> {\n let output = Command::new(binary_path)\n .args(args)\n .current_dir(project_root)\n .env(\n \"FLOW_AI_TASK_PROJECT_ROOT\",\n project_root.to_string_lossy().to_string(),\n )\n .output()\n .with_context(|| {\n format!(\n \"failed to run cached AI task '{}' binary {}\",\n task_id,\n binary_path.display()\n )\n })?;\n Ok(output)\n}\n\nfn run_artifact_status(\n binary_path: &Path,\n project_root: &Path,\n task_id: &str,\n args: &[String],\n) -> Result<std::process::ExitStatus> {\n let status = Command::new(binary_path)\n .args(args)\n .current_dir(project_root)\n .env(\n \"FLOW_AI_TASK_PROJECT_ROOT\",\n project_root.to_string_lossy().to_string(),\n )\n .status()\n .with_context(|| {\n format!(\n \"failed to run cached AI task '{}' binary {}\",\n task_id,\n binary_path.display()\n )\n })?;\n Ok(status)\n}\n\nfn ping() -> Result<()> {\n let response = send_request(&TaskdRequest::Ping, WireEncoding::Json)?;\n if response.ok {\n Ok(())\n } else {\n bail!(response.message)\n }\n}\n\nfn send_request(request: &TaskdRequest, encoding: WireEncoding) -> Result<TaskdResponse> {\n let socket = socket_path();\n let mut stream = UnixStream::connect(&socket)\n .with_context(|| format!(\"failed to connect to ai-taskd at {}\", socket.display()))?;\n let body = encode_request(request, encoding)?;\n stream\n .write_all(&body)\n .context(\"failed to write ai-taskd request\")?;\n stream\n .shutdown(std::net::Shutdown::Write)\n .context(\"failed to finalize ai-taskd request\")?;\n\n let mut response = Vec::new();\n stream\n .read_to_end(&mut response)\n .context(\"failed to read ai-taskd response\")?;\n let decoded = decode_response(&response)?;\n Ok(decoded)\n}\n\nfn encode_request(request: &TaskdRequest, encoding: WireEncoding) -> Result<Vec<u8>> {\n match encoding {\n WireEncoding::Json => {\n serde_json::to_vec(request).context(\"failed to encode ai-taskd request as json\")\n }\n WireEncoding::Msgpack => {\n let mut body = vec![MSGPACK_WIRE_PREFIX];\n let encoded = rmp_serde::to_vec_named(request)\n .context(\"failed to encode ai-taskd request as msgpack\")?;\n body.extend(encoded);\n Ok(body)\n }\n }\n}\n\nfn decode_request(payload: &[u8]) -> Result<(TaskdRequest, WireEncoding)> {\n match infer_encoding_from_payload(payload) {\n WireEncoding::Msgpack => {\n let request = rmp_serde::from_slice::<TaskdRequest>(&payload[1..])\n .context(\"failed to decode ai-taskd msgpack request\")?;\n Ok((request, WireEncoding::Msgpack))\n }\n WireEncoding::Json => {\n let request = serde_json::from_slice::<TaskdRequest>(payload)\n .context(\"failed to decode ai-taskd json request\")?;\n Ok((request, WireEncoding::Json))\n }\n }\n}\n\nfn encode_response(response: &TaskdResponse, encoding: WireEncoding) -> Result<Vec<u8>> {\n match encoding {\n WireEncoding::Json => {\n serde_json::to_vec(response).context(\"failed to encode ai-taskd json response\")\n }\n WireEncoding::Msgpack => {\n let mut body = vec![MSGPACK_WIRE_PREFIX];\n let encoded = rmp_serde::to_vec_named(response)\n .context(\"failed to encode ai-taskd msgpack response\")?;\n body.extend(encoded);\n Ok(body)\n }\n }\n}\n\nfn decode_response(payload: &[u8]) -> Result<TaskdResponse> {\n match infer_encoding_from_payload(payload) {\n WireEncoding::Msgpack => rmp_serde::from_slice::<TaskdResponse>(&payload[1..])\n .context(\"failed to decode ai-taskd msgpack response\"),\n WireEncoding::Json => serde_json::from_slice::<TaskdResponse>(payload)\n .context(\"failed to decode ai-taskd json response\"),\n }\n}\n\nfn infer_encoding_from_payload(payload: &[u8]) -> WireEncoding {\n if payload.first() == Some(&MSGPACK_WIRE_PREFIX) {\n WireEncoding::Msgpack\n } else {\n WireEncoding::Json\n }\n}\n\nfn socket_path() -> PathBuf {\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".flow\")\n .join(\"run\")\n .join(\"ai-taskd.sock\")\n}\n\nfn pid_path() -> PathBuf {\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".flow\")\n .join(\"run\")\n .join(\"ai-taskd.pid\")\n}\n\nfn shell_quote(raw: &str) -> String {\n let escaped = raw.replace('\\'', \"'\\\"'\\\"'\");\n format!(\"'{}'\", escaped)\n}\n\nfn write_error_response(stream: &mut UnixStream, message: String, encoding: WireEncoding) {\n let response = TaskdResponse {\n ok: false,\n message,\n exit_code: 1,\n stdout: String::new(),\n stderr: String::new(),\n timings: None,\n };\n if let Ok(body) = encode_response(&response, encoding) {\n let _ = stream.write_all(&body);\n let _ = stream.flush();\n }\n}\n\nfn timings_log_enabled() -> bool {\n matches!(\n std::env::var(\"FLOW_AI_TASKD_TIMINGS_LOG\")\n .ok()\n .as_deref()\n .map(str::trim)\n .map(str::to_ascii_lowercase)\n .as_deref(),\n Some(\"1\" | \"true\" | \"yes\" | \"on\")\n )\n}\n\n#[cfg(test)]\nmod tests {\n use super::same_task_selector;\n\n #[test]\n fn selector_compare_handles_ai_prefix() {\n assert!(same_task_selector(\"ai:flow/dev-check\", \"flow/dev-check\"));\n assert!(same_task_selector(\"flow/dev-check\", \"AI:FLOW/DEV-CHECK\"));\n assert!(!same_task_selector(\"ai:flow/noop\", \"ai:flow/dev-check\"));\n }\n}\n" }, { "path": "src/ai_tasks.rs", "content": "use std::fs;\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Output};\nuse std::time::{Duration, UNIX_EPOCH};\n\nuse anyhow::{Context, Result, bail};\nuse ignore::WalkBuilder;\nuse serde::{Deserialize, Serialize};\nuse sha2::{Digest, Sha256};\n\n#[cfg(unix)]\nuse std::os::unix::fs::PermissionsExt;\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct DiscoveredAiTask {\n pub id: String,\n pub selector: String,\n pub name: String,\n pub title: String,\n pub description: String,\n pub path: PathBuf,\n pub relative_path: String,\n pub tags: Vec<String>,\n}\n\n#[derive(Debug, Clone)]\npub(crate) struct AiTaskDiscoveryArtifacts {\n pub tasks: Vec<DiscoveredAiTask>,\n pub watched_paths: Vec<PathBuf>,\n}\n\n#[derive(Debug, Clone, Default)]\nstruct Metadata {\n title: Option<String>,\n description: Option<String>,\n tags: Vec<String>,\n}\n\n#[derive(Debug, Clone)]\npub struct CachedTaskArtifact {\n pub cache_key: String,\n pub binary_path: PathBuf,\n pub rebuilt: bool,\n}\n\npub fn discover_tasks(root: &Path) -> Result<Vec<DiscoveredAiTask>> {\n let root = if root.is_absolute() {\n root.to_path_buf()\n } else {\n std::env::current_dir()?.join(root)\n };\n let root = root.canonicalize().unwrap_or(root);\n discover_tasks_from_root(root)\n}\n\npub(crate) fn discover_tasks_from_root(root: PathBuf) -> Result<Vec<DiscoveredAiTask>> {\n Ok(discover_tasks_from_root_artifacts(root)?.tasks)\n}\n\npub(crate) fn discover_tasks_from_root_artifacts(\n root: PathBuf,\n) -> Result<AiTaskDiscoveryArtifacts> {\n let task_root = root.join(\".ai\").join(\"tasks\");\n let mut watched_paths = vec![root.clone()];\n\n let ai_root = root.join(\".ai\");\n if ai_root.exists() {\n watched_paths.push(ai_root);\n }\n\n if !task_root.exists() {\n return Ok(AiTaskDiscoveryArtifacts {\n tasks: Vec::new(),\n watched_paths,\n });\n }\n watched_paths.push(task_root.clone());\n\n let walker = WalkBuilder::new(&task_root)\n .hidden(false)\n .git_ignore(true)\n .git_global(true)\n .git_exclude(true)\n .max_depth(Some(12))\n .build();\n\n let mut out = Vec::new();\n for entry in walker.flatten() {\n let path = entry.path();\n if path.is_dir() {\n if !watched_paths.iter().any(|existing| existing == path) {\n watched_paths.push(path.to_path_buf());\n }\n continue;\n }\n if !path.is_file() {\n continue;\n }\n let relative = match path.strip_prefix(&task_root) {\n Ok(relative) => relative,\n Err(_) => continue,\n };\n let has_generated_component = relative.components().any(|component| {\n let s = component.as_os_str().to_string_lossy();\n s == \".mooncakes\" || s == \"_build\"\n });\n if has_generated_component {\n continue;\n }\n let ext = path\n .extension()\n .and_then(|e| e.to_str())\n .unwrap_or_default()\n .to_ascii_lowercase();\n if ext != \"mbt\" {\n continue;\n }\n watched_paths.push(path.to_path_buf());\n let task = parse_task(&task_root, path)?;\n out.push(task);\n }\n\n out.sort_by(|a, b| a.id.cmp(&b.id));\n Ok(AiTaskDiscoveryArtifacts {\n tasks: out,\n watched_paths,\n })\n}\n\npub fn resolve_task_fast(root: &Path, selector: &str) -> Result<Option<DiscoveredAiTask>> {\n let root = if root.is_absolute() {\n root.to_path_buf()\n } else {\n std::env::current_dir()?.join(root)\n };\n let root = root.canonicalize().unwrap_or(root);\n let task_root = root.join(\".ai\").join(\"tasks\");\n if !task_root.exists() {\n return Ok(None);\n }\n\n let mut needle = selector.trim().to_string();\n if needle.is_empty() {\n return Ok(None);\n }\n if let Some(stripped) = needle.strip_prefix(\"ai:\") {\n needle = stripped.trim().to_string();\n } else if let Some((scope, scoped)) = parse_scoped_selector(&needle)\n && scope.eq_ignore_ascii_case(\"ai\")\n {\n needle = scoped;\n }\n if needle.is_empty() {\n return Ok(None);\n }\n\n let mut candidates = Vec::new();\n let base = task_root.join(&needle);\n if base.extension().and_then(|e| e.to_str()) == Some(\"mbt\") {\n candidates.push(base);\n } else {\n candidates.push(base.with_extension(\"mbt\"));\n candidates.push(base.join(\"main.mbt\"));\n }\n if needle.contains(':') {\n let normalized = needle.replace(':', \"/\");\n let norm = task_root.join(normalized);\n candidates.push(norm.with_extension(\"mbt\"));\n candidates.push(norm.join(\"main.mbt\"));\n }\n\n for candidate in candidates {\n if candidate.is_file() {\n return Ok(Some(parse_task(&task_root, &candidate)?));\n }\n }\n Ok(None)\n}\n\npub fn select_task<'a>(\n tasks: &'a [DiscoveredAiTask],\n selector: &str,\n) -> Result<Option<&'a DiscoveredAiTask>> {\n let needle = selector.trim();\n if needle.is_empty() {\n return Ok(None);\n }\n\n let normalized = normalize_selector(needle);\n let mut matches: Vec<&DiscoveredAiTask> = tasks\n .iter()\n .filter(|t| {\n t.id.eq_ignore_ascii_case(needle)\n || t.selector.eq_ignore_ascii_case(needle)\n || t.name.eq_ignore_ascii_case(needle)\n || normalize_selector(&t.selector) == normalized\n || normalize_selector(&t.name) == normalized\n })\n .collect();\n\n if let Some((scope, scoped)) = parse_scoped_selector(needle)\n && scope.eq_ignore_ascii_case(\"ai\")\n {\n matches = tasks\n .iter()\n .filter(|t| {\n t.selector.eq_ignore_ascii_case(&scoped)\n || t.name.eq_ignore_ascii_case(&scoped)\n || normalize_selector(&t.selector) == normalize_selector(&scoped)\n })\n .collect();\n }\n\n if matches.is_empty() {\n return Ok(None);\n }\n if matches.len() == 1 {\n return Ok(Some(matches[0]));\n }\n\n let mut msg = String::new();\n msg.push_str(&format!(\"AI task '{}' is ambiguous.\\n\", selector));\n msg.push_str(\"Matches:\\n\");\n for m in &matches {\n msg.push_str(&format!(\" - {}\\n\", m.id));\n }\n msg.push_str(\"Try one of the full selectors above.\");\n bail!(msg);\n}\n\npub fn run_task(task: &DiscoveredAiTask, project_root: &Path, args: &[String]) -> Result<()> {\n if !task_has_workspace(task, project_root) {\n return run_task_via_moon(task, project_root, args);\n }\n\n let runtime = std::env::var(\"FLOW_AI_TASK_RUNTIME\")\n .ok()\n .unwrap_or_else(|| \"cached\".to_string())\n .to_ascii_lowercase();\n\n if runtime == \"moon-run\" || runtime == \"moon\" {\n return run_task_via_moon(task, project_root, args);\n }\n\n match run_task_cached(task, project_root, args) {\n Ok(()) => Ok(()),\n Err(cached_error) => {\n eprintln!(\n \"warning: ai task cache execution failed for {} ({}), falling back to moon run\",\n task.id, cached_error\n );\n run_task_via_moon(task, project_root, args)\n }\n }\n}\n\npub fn run_task_via_moon(\n task: &DiscoveredAiTask,\n project_root: &Path,\n args: &[String],\n) -> Result<()> {\n let mut cmd = moon_run_command(task, project_root, args);\n let status = cmd.status().with_context(|| {\n format!(\n \"failed to run AI task {} via moon ({})\",\n task.id,\n task.path.display()\n )\n })?;\n\n if !status.success() {\n bail!(\"AI task '{}' failed with status {}\", task.id, status);\n }\n Ok(())\n}\n\npub fn run_task_via_moon_output(\n task: &DiscoveredAiTask,\n project_root: &Path,\n args: &[String],\n) -> Result<Output> {\n let mut cmd = moon_run_command(task, project_root, args);\n let output = cmd.output().with_context(|| {\n format!(\n \"failed to run AI task {} via moon ({})\",\n task.id,\n task.path.display()\n )\n })?;\n Ok(output)\n}\n\npub fn build_task_cached(\n task: &DiscoveredAiTask,\n project_root: &Path,\n force_rebuild: bool,\n) -> Result<CachedTaskArtifact> {\n let (workspace_dir, run_path) = resolve_moon_workspace_and_entry(task, project_root);\n if !workspace_dir.join(\"moon.mod.json\").exists() && !workspace_dir.join(\"moon.mod\").exists() {\n bail!(\n \"AI task '{}' has no moon workspace root; cannot build cached binary\",\n task.id\n );\n }\n\n let cache_key = compute_cache_key(task, &workspace_dir, &run_path)?;\n let cache_dir = ai_task_cache_root()?.join(&cache_key);\n fs::create_dir_all(&cache_dir)\n .with_context(|| format!(\"failed to create ai task cache dir {}\", cache_dir.display()))?;\n let binary_path = cache_dir.join(\"task-bin\");\n if binary_path.exists() && !force_rebuild {\n return Ok(CachedTaskArtifact {\n cache_key,\n binary_path,\n rebuilt: false,\n });\n }\n\n let mut cmd = Command::new(\"moon\");\n cmd.arg(\"build\")\n .arg(\"--target\")\n .arg(\"native\")\n .arg(\"--release\");\n if std::env::var(\"FLOW_AI_TASK_NO_FROZEN\").is_err() {\n cmd.arg(\"--frozen\");\n }\n cmd.arg(&run_path).current_dir(&workspace_dir);\n let status = cmd.status().with_context(|| {\n format!(\n \"failed to build AI task '{}' with moon build (workspace: {})\",\n task.id,\n workspace_dir.display()\n )\n })?;\n if !status.success() {\n bail!(\n \"moon build failed for AI task '{}' with status {}\",\n task.id,\n status\n );\n }\n\n let built_binary = find_built_binary(&workspace_dir)?;\n fs::copy(&built_binary, &binary_path).with_context(|| {\n format!(\n \"failed to copy built binary {} -> {}\",\n built_binary.display(),\n binary_path.display()\n )\n })?;\n #[cfg(unix)]\n {\n let mut perms = fs::metadata(&binary_path)\n .with_context(|| format!(\"failed to stat {}\", binary_path.display()))?\n .permissions();\n perms.set_mode(0o755);\n fs::set_permissions(&binary_path, perms)\n .with_context(|| format!(\"failed to chmod {}\", binary_path.display()))?;\n }\n\n Ok(CachedTaskArtifact {\n cache_key,\n binary_path,\n rebuilt: true,\n })\n}\n\npub fn run_task_cached(\n task: &DiscoveredAiTask,\n project_root: &Path,\n args: &[String],\n) -> Result<()> {\n let artifact = build_task_cached(task, project_root, false)?;\n let status = Command::new(&artifact.binary_path)\n .args(args)\n .current_dir(project_root)\n .env(\n \"FLOW_AI_TASK_PROJECT_ROOT\",\n project_root.to_string_lossy().to_string(),\n )\n .status()\n .with_context(|| {\n format!(\n \"failed to run cached AI task '{}' binary {}\",\n task.id,\n artifact.binary_path.display()\n )\n })?;\n if !status.success() {\n bail!(\"AI task '{}' failed with status {}\", task.id, status);\n }\n Ok(())\n}\n\npub fn run_task_cached_output(\n task: &DiscoveredAiTask,\n project_root: &Path,\n args: &[String],\n) -> Result<Output> {\n let artifact = build_task_cached(task, project_root, false)?;\n let output = Command::new(&artifact.binary_path)\n .args(args)\n .current_dir(project_root)\n .env(\n \"FLOW_AI_TASK_PROJECT_ROOT\",\n project_root.to_string_lossy().to_string(),\n )\n .output()\n .with_context(|| {\n format!(\n \"failed to run cached AI task '{}' binary {}\",\n task.id,\n artifact.binary_path.display()\n )\n })?;\n Ok(output)\n}\n\npub fn default_cache_root() -> Result<PathBuf> {\n ai_task_cache_root()\n}\n\nfn moon_run_command(task: &DiscoveredAiTask, project_root: &Path, args: &[String]) -> Command {\n let mode = std::env::var(\"FLOW_AI_TASK_MODE\")\n .ok()\n .unwrap_or_else(|| \"dev\".to_string())\n .to_ascii_lowercase();\n\n let mut cmd = Command::new(\"moon\");\n cmd.arg(\"run\");\n\n // Keep \"dev\" mode fast to iterate; allow release mode for lower runtime overhead.\n match mode.as_str() {\n \"release\" | \"hot\" | \"prod\" => {\n cmd.arg(\"--target\").arg(\"native\").arg(\"--release\");\n }\n \"js\" => {\n cmd.arg(\"--target\").arg(\"js\");\n }\n _ => {\n cmd.arg(\"--target\").arg(\"native\");\n }\n }\n\n if std::env::var(\"FLOW_AI_TASK_NO_FROZEN\").is_err() {\n cmd.arg(\"--frozen\");\n }\n\n let (workspace_dir, run_path) = resolve_moon_workspace_and_entry(task, project_root);\n cmd.arg(&run_path);\n for arg in args {\n cmd.arg(arg);\n }\n cmd.current_dir(&workspace_dir);\n cmd.env(\n \"FLOW_AI_TASK_PROJECT_ROOT\",\n project_root.to_string_lossy().to_string(),\n );\n cmd\n}\n\npub fn task_reference(task: &DiscoveredAiTask) -> String {\n task.id.clone()\n}\n\nfn resolve_moon_workspace_and_entry(\n task: &DiscoveredAiTask,\n project_root: &Path,\n) -> (PathBuf, PathBuf) {\n let entry_path = task.path.clone();\n let start_dir = entry_path\n .parent()\n .map(|p| p.to_path_buf())\n .unwrap_or_else(|| project_root.to_path_buf());\n\n if let Some(workspace) = find_moon_workspace_root(&start_dir) {\n if let Ok(relative) = entry_path.strip_prefix(&workspace) {\n return (workspace, relative.to_path_buf());\n }\n }\n\n // Fallback to prior behavior if no moon workspace is found.\n (project_root.to_path_buf(), entry_path)\n}\n\nfn task_has_workspace(task: &DiscoveredAiTask, project_root: &Path) -> bool {\n let entry_path = task.path.clone();\n let start_dir = entry_path\n .parent()\n .map(|p| p.to_path_buf())\n .unwrap_or_else(|| project_root.to_path_buf());\n find_moon_workspace_root(&start_dir).is_some()\n}\n\nfn ai_task_cache_root() -> Result<PathBuf> {\n let root = dirs::cache_dir()\n .or_else(|| dirs::home_dir().map(|home| home.join(\".cache\")))\n .context(\"failed to resolve cache root for AI tasks\")?\n .join(\"flow\")\n .join(\"ai-tasks\");\n Ok(root)\n}\n\nfn compute_cache_key(\n task: &DiscoveredAiTask,\n workspace_dir: &Path,\n run_path: &Path,\n) -> Result<String> {\n let mut hasher = Sha256::new();\n hasher.update(b\"flow-ai-task-v2\");\n hasher.update(task.id.as_bytes());\n hasher.update(task.selector.as_bytes());\n hasher.update(task.path.to_string_lossy().as_bytes());\n hasher.update(run_path.to_string_lossy().as_bytes());\n hash_file_signature_if_exists(&mut hasher, &task.path)?;\n hash_file_signature_if_exists(&mut hasher, &workspace_dir.join(\"moon.mod.json\"))?;\n hash_file_signature_if_exists(&mut hasher, &workspace_dir.join(\"moon.mod\"))?;\n hash_file_signature_if_exists(&mut hasher, &workspace_dir.join(\"moon.pkg.json\"))?;\n hash_file_signature_if_exists(&mut hasher, &workspace_dir.join(\"moon.pkg\"))?;\n if let Some(version) = moon_version_for_cache_key() {\n hasher.update(version);\n }\n Ok(hex::encode(hasher.finalize()))\n}\n\nfn hash_file_signature_if_exists(hasher: &mut Sha256, path: &Path) -> Result<()> {\n if !path.exists() || !path.is_file() {\n return Ok(());\n }\n let meta = fs::metadata(path).with_context(|| format!(\"failed to stat {}\", path.display()))?;\n hasher.update(path.to_string_lossy().as_bytes());\n hasher.update(meta.len().to_le_bytes());\n if let Ok(modified) = meta.modified() {\n let duration = modified\n .duration_since(UNIX_EPOCH)\n .unwrap_or_else(|_| Duration::from_secs(0));\n hasher.update(duration.as_secs().to_le_bytes());\n hasher.update(duration.subsec_nanos().to_le_bytes());\n }\n Ok(())\n}\n\nfn moon_version_for_cache_key() -> Option<Vec<u8>> {\n if let Ok(raw) = std::env::var(\"FLOW_AI_TASK_MOON_VERSION\") {\n let trimmed = raw.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.as_bytes().to_vec());\n }\n }\n\n let ttl_secs = std::env::var(\"FLOW_AI_TASK_MOON_VERSION_TTL_SECS\")\n .ok()\n .and_then(|raw| raw.trim().parse::<u64>().ok())\n .unwrap_or(12 * 60 * 60);\n let ttl = Duration::from_secs(ttl_secs);\n\n let cache_file = ai_task_cache_root().ok()?.join(\"moon-version.txt\");\n if let Ok(meta) = fs::metadata(&cache_file)\n && let Ok(modified) = meta.modified()\n && modified.elapsed().ok().is_some_and(|age| age <= ttl)\n && let Ok(raw) = fs::read_to_string(&cache_file)\n {\n let trimmed = raw.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.as_bytes().to_vec());\n }\n }\n\n let out = Command::new(\"moon\").arg(\"--version\").output().ok()?;\n let mut version = String::from_utf8_lossy(&out.stdout).trim().to_string();\n if version.is_empty() {\n version = String::from_utf8_lossy(&out.stderr).trim().to_string();\n }\n if version.is_empty() {\n return None;\n }\n if let Some(parent) = cache_file.parent() {\n let _ = fs::create_dir_all(parent);\n }\n let _ = fs::write(&cache_file, format!(\"{version}\\n\"));\n Some(version.into_bytes())\n}\n\nfn find_built_binary(workspace_dir: &Path) -> Result<PathBuf> {\n let build_dir = workspace_dir\n .join(\"_build\")\n .join(\"native\")\n .join(\"release\")\n .join(\"build\");\n if !build_dir.exists() {\n bail!(\n \"moon build output directory missing: {}\",\n build_dir.display()\n );\n }\n\n if let Some(name) = moon_mod_package_name(workspace_dir)? {\n let candidates = [\n build_dir.join(format!(\"{name}.exe\")),\n build_dir.join(name.clone()),\n ];\n for candidate in candidates {\n if candidate.is_file() {\n return Ok(candidate);\n }\n }\n }\n\n let mut fallback = None;\n for entry in fs::read_dir(&build_dir)\n .with_context(|| format!(\"failed to read {}\", build_dir.display()))?\n {\n let entry = entry?;\n let path = entry.path();\n if !path.is_file() {\n continue;\n }\n let file_name = path\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or_default();\n if file_name.ends_with(\".exe\") || is_executable(&path) {\n fallback = Some(path);\n break;\n }\n }\n fallback.context(format!(\n \"failed to locate built AI task binary in {}\",\n build_dir.display()\n ))\n}\n\nfn moon_mod_package_name(workspace_dir: &Path) -> Result<Option<String>> {\n let path = workspace_dir.join(\"moon.mod.json\");\n if !path.exists() {\n return Ok(None);\n }\n let value: serde_json::Value = serde_json::from_slice(\n &fs::read(&path).with_context(|| format!(\"failed to read {}\", path.display()))?,\n )\n .with_context(|| format!(\"failed to parse {}\", path.display()))?;\n let raw = value\n .get(\"name\")\n .and_then(|v| v.as_str())\n .unwrap_or_default()\n .trim();\n if raw.is_empty() {\n return Ok(None);\n }\n Ok(Some(\n raw.rsplit('/').next().unwrap_or(raw).replace('.', \"-\"),\n ))\n}\n\nfn is_executable(path: &Path) -> bool {\n #[cfg(unix)]\n {\n fs::metadata(path)\n .map(|m| (m.permissions().mode() & 0o111) != 0)\n .unwrap_or(false)\n }\n #[cfg(not(unix))]\n {\n let _ = path;\n false\n }\n}\n\nfn find_moon_workspace_root(start: &Path) -> Option<PathBuf> {\n let mut current = Some(start);\n while let Some(dir) = current {\n if dir.join(\"moon.mod.json\").exists() || dir.join(\"moon.mod\").exists() {\n return Some(dir.to_path_buf());\n }\n current = dir.parent();\n }\n None\n}\n\nfn parse_task(task_root: &Path, path: &Path) -> Result<DiscoveredAiTask> {\n let content = std::fs::read_to_string(path)\n .with_context(|| format!(\"failed to read AI task {}\", path.display()))?;\n let metadata = parse_metadata(&content);\n\n let relative = path.strip_prefix(task_root).unwrap_or(path);\n let mut selector = relative\n .with_extension(\"\")\n .to_string_lossy()\n .replace('\\\\', \"/\");\n if let Some(trimmed) = selector.strip_suffix(\"/main\") {\n selector = trimmed.to_string();\n }\n\n let mut name = relative\n .file_stem()\n .and_then(|s| s.to_str())\n .unwrap_or(\"task\")\n .to_string();\n if name == \"main\" {\n if let Some(parent_name) = relative\n .parent()\n .and_then(|p| p.file_name())\n .and_then(|s| s.to_str())\n {\n name = parent_name.to_string();\n }\n }\n if selector.is_empty() {\n selector = name.clone();\n }\n let title = metadata.title.unwrap_or_else(|| name.replace('-', \" \"));\n let description = metadata.description.unwrap_or_default();\n let id = format!(\"ai:{}\", selector);\n\n Ok(DiscoveredAiTask {\n id,\n selector,\n name,\n title,\n description,\n path: path.to_path_buf(),\n relative_path: relative.to_string_lossy().replace('\\\\', \"/\"),\n tags: metadata.tags,\n })\n}\n\nfn parse_metadata(content: &str) -> Metadata {\n let mut md = Metadata::default();\n for raw in content.lines() {\n let line = raw.trim();\n if line.is_empty() {\n continue;\n }\n let Some(comment) = line.strip_prefix(\"//\") else {\n break;\n };\n let comment = comment.trim();\n let Some((key, value)) = comment.split_once(':') else {\n continue;\n };\n let key = key.trim().to_ascii_lowercase();\n let value = value.trim();\n if key == \"title\" {\n md.title = Some(strip_quotes(value));\n } else if key == \"description\" {\n md.description = Some(strip_quotes(value));\n } else if key == \"tags\" {\n md.tags = parse_tags(value);\n }\n }\n md\n}\n\nfn parse_tags(value: &str) -> Vec<String> {\n let v = strip_quotes(value);\n let trimmed = v.trim();\n let inner = if trimmed.starts_with('[') && trimmed.ends_with(']') && trimmed.len() >= 2 {\n &trimmed[1..trimmed.len() - 1]\n } else {\n trimmed\n };\n inner\n .split(',')\n .map(strip_quotes)\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n .collect()\n}\n\nfn strip_quotes(value: &str) -> String {\n let trimmed = value.trim();\n if trimmed.len() >= 2 {\n let bytes = trimmed.as_bytes();\n if (bytes[0] == b'\"' && bytes[trimmed.len() - 1] == b'\"')\n || (bytes[0] == b'\\'' && bytes[trimmed.len() - 1] == b'\\'')\n {\n return trimmed[1..trimmed.len() - 1].to_string();\n }\n }\n trimmed.to_string()\n}\n\nfn parse_scoped_selector(selector: &str) -> Option<(String, String)> {\n let trimmed = selector.trim();\n if let Some((scope, task)) = trimmed.split_once(':') {\n let scope = scope.trim();\n let task = task.trim();\n if !scope.is_empty() && !task.is_empty() {\n return Some((scope.to_string(), task.to_string()));\n }\n }\n if let Some((scope, task)) = trimmed.split_once('/') {\n let scope = scope.trim();\n let task = task.trim();\n if !scope.is_empty() && !task.is_empty() {\n return Some((scope.to_string(), task.to_string()));\n }\n }\n None\n}\n\nfn normalize_selector(raw: &str) -> String {\n raw.chars()\n .map(|ch| {\n if ch.is_ascii_alphanumeric() {\n ch.to_ascii_lowercase()\n } else {\n '-'\n }\n })\n .collect::<String>()\n .trim_matches('-')\n .to_string()\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn parses_metadata_comments() {\n let text = \"// title: Fast Open\\n\\\n// description: Open app quickly\\n\\\n// tags: [moonbit, fast]\\n\\\n\\n\\\nfn main {}\\n\";\n let md = parse_metadata(text);\n assert_eq!(md.title.as_deref(), Some(\"Fast Open\"));\n assert_eq!(md.description.as_deref(), Some(\"Open app quickly\"));\n assert_eq!(md.tags, vec![\"moonbit\".to_string(), \"fast\".to_string()]);\n }\n}\n" }, { "path": "src/ai_test.rs", "content": "use std::fs;\nuse std::path::{Component, Path, PathBuf};\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::AiTestNewOpts;\n\npub fn run(opts: AiTestNewOpts) -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to read current directory\")?;\n let project_root = find_project_root(&cwd)?;\n let base_dir = project_root.join(normalize_relative_dir(&opts.dir)?);\n let rel_file = normalize_test_name(&opts.name, opts.spec)?;\n let full_path = base_dir.join(&rel_file);\n\n if full_path.exists() && !opts.force {\n bail!(\n \"scratch test already exists: {} (use --force to overwrite)\",\n full_path.display()\n );\n }\n\n if let Some(parent) = full_path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n\n let title = rel_file\n .to_string_lossy()\n .replace('\\\\', \"/\")\n .trim_end_matches(\".ts\")\n .trim_end_matches(\".tsx\")\n .trim_end_matches(\".js\")\n .trim_end_matches(\".jsx\")\n .trim_end_matches(\".mjs\")\n .trim_end_matches(\".cjs\")\n .to_string();\n\n let template = format!(\n \"import {{ describe, it }} from \\\"bun:test\\\";\\n\\n\\\ndescribe(\\\"{}\\\", () => {{\\n\\\n it.todo(\\\"add assertions\\\");\\n\\\n}});\\n\",\n title\n );\n\n fs::write(&full_path, template)\n .with_context(|| format!(\"failed to write {}\", full_path.display()))?;\n\n let relative_to_project = full_path\n .strip_prefix(&project_root)\n .unwrap_or(&full_path)\n .to_path_buf();\n println!(\"Created scratch test: {}\", relative_to_project.display());\n println!(\"Run: f ai-test\");\n println!(\"Watch: f ai-test-watch\");\n Ok(())\n}\n\nfn find_project_root(start: &Path) -> Result<PathBuf> {\n let mut current = start.to_path_buf();\n loop {\n if current.join(\"flow.toml\").exists() {\n return Ok(current);\n }\n if !current.pop() {\n bail!(\"no flow.toml found in current directory or parents\");\n }\n }\n}\n\nfn normalize_relative_dir(raw: &str) -> Result<PathBuf> {\n let path = Path::new(raw);\n if path.is_absolute() {\n bail!(\"--dir must be relative to project root\");\n }\n let mut out = PathBuf::new();\n for comp in path.components() {\n match comp {\n Component::Normal(s) => out.push(s),\n Component::CurDir => {}\n Component::ParentDir | Component::RootDir | Component::Prefix(_) => {\n bail!(\"--dir must not contain parent traversal\")\n }\n }\n }\n if out.as_os_str().is_empty() {\n bail!(\"--dir cannot be empty\");\n }\n Ok(out)\n}\n\nfn normalize_test_name(raw: &str, use_spec: bool) -> Result<PathBuf> {\n let mut segments: Vec<String> = raw\n .replace('\\\\', \"/\")\n .split('/')\n .filter(|s| !s.trim().is_empty())\n .map(sanitize_segment)\n .filter(|s| !s.is_empty())\n .collect();\n if segments.is_empty() {\n bail!(\"name must contain at least one non-empty path segment\");\n }\n\n let file = segments.pop().expect(\"checked non-empty\");\n let file = normalize_file_component(&file, use_spec);\n let mut out = PathBuf::new();\n for segment in segments {\n out.push(segment);\n }\n out.push(file);\n Ok(out)\n}\n\nfn sanitize_segment(raw: &str) -> String {\n let mut out = String::new();\n let mut prev_dash = false;\n for ch in raw.chars() {\n let keep = ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || ch == '.';\n let next = if keep { ch } else { '-' };\n if next == '-' {\n if prev_dash {\n continue;\n }\n prev_dash = true;\n } else {\n prev_dash = false;\n }\n out.push(next);\n }\n out.trim_matches(&['-', '.'][..]).to_string()\n}\n\nfn normalize_file_component(file: &str, use_spec: bool) -> String {\n const KNOWN_EXTS: &[&str] = &[\"ts\", \"tsx\", \"js\", \"jsx\", \"mjs\", \"cjs\"];\n let suffix = if use_spec { \"spec\" } else { \"test\" };\n\n if let Some((stem, ext)) = file.rsplit_once('.') {\n let ext_lower = ext.to_ascii_lowercase();\n if KNOWN_EXTS.contains(&ext_lower.as_str()) {\n if stem.ends_with(\".test\") || stem.ends_with(\".spec\") {\n return file.to_string();\n }\n return format!(\"{stem}.{suffix}.{ext_lower}\");\n }\n }\n\n if file.contains(\".test.\") || file.contains(\".spec.\") {\n return file.to_string();\n }\n\n format!(\"{file}.{suffix}.ts\")\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn appends_test_suffix_for_plain_name() {\n let path = normalize_test_name(\"auth-login\", false).unwrap();\n assert_eq!(path, PathBuf::from(\"auth-login.test.ts\"));\n }\n\n #[test]\n fn preserves_existing_test_suffix() {\n let path = normalize_test_name(\"chat/loading.test.ts\", true).unwrap();\n assert_eq!(path, PathBuf::from(\"chat/loading.test.ts\"));\n }\n\n #[test]\n fn adds_spec_before_extension() {\n let path = normalize_test_name(\"chat/loading.tsx\", true).unwrap();\n assert_eq!(path, PathBuf::from(\"chat/loading.spec.tsx\"));\n }\n}\n" }, { "path": "src/analytics.rs", "content": "use anyhow::Result;\n\nuse crate::cli::{AnalyticsAction, AnalyticsCommand};\nuse crate::usage::{self, AnalyticsConsent};\n\npub fn run(cmd: AnalyticsCommand) -> Result<()> {\n match cmd.action.unwrap_or(AnalyticsAction::Status) {\n AnalyticsAction::Status => {\n let status = usage::status()?;\n println!(\"consent: {:?}\", status.consent);\n println!(\"effective_enabled: {}\", status.effective_enabled);\n println!(\"install_id: {}\", status.install_id);\n println!(\"endpoint: {}\", status.endpoint);\n println!(\"queue_path: {}\", status.queue_path.display());\n println!(\"queued_events: {}\", status.queued_events);\n }\n AnalyticsAction::Enable => {\n usage::set_consent(AnalyticsConsent::Enabled)?;\n println!(\"Anonymous usage tracking enabled.\");\n }\n AnalyticsAction::Disable => {\n usage::set_consent(AnalyticsConsent::Disabled)?;\n println!(\"Anonymous usage tracking disabled.\");\n }\n AnalyticsAction::Export => {\n let content = usage::export_queue()?;\n if content.trim().is_empty() {\n println!(\"(no queued analytics events)\");\n } else {\n print!(\"{content}\");\n }\n }\n AnalyticsAction::Purge => {\n usage::purge_queue()?;\n println!(\"Purged queued analytics events.\");\n }\n }\n Ok(())\n}\n" }, { "path": "src/archive.rs", "content": "use std::fs;\nuse std::path::Path;\n\nuse anyhow::{Context, Result, bail};\nuse chrono::Local;\n\nuse crate::ai_context;\nuse crate::cli::ArchiveOpts;\n\npub fn run(opts: ArchiveOpts) -> Result<()> {\n let root =\n ai_context::find_project_root().ok_or_else(|| anyhow::anyhow!(\"project root not found\"))?;\n let root = fs::canonicalize(&root).unwrap_or(root);\n let project_name = root\n .file_name()\n .and_then(|name| name.to_str())\n .filter(|name| !name.trim().is_empty())\n .unwrap_or(\"project\");\n\n let message = opts.message.trim();\n if message.is_empty() {\n bail!(\"archive message cannot be empty\");\n }\n let slug = sanitize_segment(message);\n if slug.is_empty() {\n bail!(\"archive message must include at least one letter or number\");\n }\n\n let home = dirs::home_dir()\n .ok_or_else(|| anyhow::anyhow!(\"could not resolve home directory\"))?\n .to_path_buf();\n let archive_root = home.join(\"archive\").join(\"code\");\n fs::create_dir_all(&archive_root).with_context(|| {\n format!(\n \"failed to create archive directory {}\",\n archive_root.display()\n )\n })?;\n\n let code_root = fs::canonicalize(home.join(\"code\")).unwrap_or_else(|_| home.join(\"code\"));\n let rel_path = root.strip_prefix(&code_root).ok();\n let (dest_parent, base_project) = if let Some(rel) = rel_path {\n let parent = rel\n .parent()\n .map(|p| archive_root.join(p))\n .unwrap_or_else(|| archive_root.clone());\n let name = rel\n .file_name()\n .and_then(|name| name.to_str())\n .filter(|name| !name.trim().is_empty())\n .unwrap_or(project_name)\n .to_string();\n (parent, name)\n } else {\n (archive_root.clone(), project_name.to_string())\n };\n\n fs::create_dir_all(&dest_parent).with_context(|| {\n format!(\n \"failed to create archive directory {}\",\n dest_parent.display()\n )\n })?;\n\n let date_suffix = Local::now()\n .format(\"%b-%d-%y\")\n .to_string()\n .to_ascii_lowercase();\n let base_name = format!(\"{}-{}-{}\", base_project, slug, date_suffix);\n let mut dest = dest_parent.join(&base_name);\n if dest.exists() {\n let suffix = Local::now().format(\"%Y%m%d-%H%M%S\");\n dest = dest_parent.join(format!(\"{}-{}\", base_name, suffix));\n }\n\n copy_dir_all(&root, &dest, &ArchiveFilter::default())?;\n println!(\"Archived {} -> {}\", root.display(), dest.display());\n Ok(())\n}\n\n#[derive(Default)]\nstruct ArchiveFilter {\n skip_names: Vec<&'static str>,\n}\n\nimpl ArchiveFilter {\n fn default() -> Self {\n Self {\n skip_names: vec![\n \".jj\",\n \"node_modules\",\n \"target\",\n \"dist\",\n \"build\",\n \".next\",\n \".turbo\",\n \".cache\",\n ],\n }\n }\n\n fn should_skip(&self, path: &Path) -> bool {\n path.file_name()\n .and_then(|name| name.to_str())\n .map(|name| self.skip_names.contains(&name))\n .unwrap_or(false)\n }\n}\n\nfn copy_dir_all(from: &Path, to: &Path, filter: &ArchiveFilter) -> Result<()> {\n fs::create_dir_all(to).with_context(|| format!(\"failed to create {}\", to.display()))?;\n for entry in fs::read_dir(from).with_context(|| format!(\"failed to read {}\", from.display()))? {\n let entry = entry?;\n let path = entry.path();\n if filter.should_skip(&path) {\n continue;\n }\n let file_type = entry.file_type()?;\n let target = to.join(entry.file_name());\n\n if target.exists() {\n bail!(\"Refusing to overwrite {}\", target.display());\n }\n\n if file_type.is_dir() {\n copy_dir_all(&path, &target, filter)?;\n } else if file_type.is_file() {\n fs::copy(&path, &target)\n .with_context(|| format!(\"failed to copy {}\", path.display()))?;\n } else if file_type.is_symlink() {\n let link_target = fs::read_link(&path)\n .with_context(|| format!(\"failed to read link {}\", path.display()))?;\n copy_symlink(&link_target, &target)?;\n }\n }\n Ok(())\n}\n\nfn copy_symlink(target: &Path, dest: &Path) -> Result<()> {\n #[cfg(unix)]\n {\n std::os::unix::fs::symlink(target, dest)\n .with_context(|| format!(\"failed to create symlink {}\", dest.display()))?;\n return Ok(());\n }\n #[cfg(not(unix))]\n {\n let metadata =\n fs::metadata(target).with_context(|| format!(\"failed to read {}\", target.display()))?;\n if metadata.is_dir() {\n copy_dir_all(target, dest, &ArchiveFilter::default())?;\n } else {\n fs::copy(target, dest)\n .with_context(|| format!(\"failed to copy {}\", target.display()))?;\n }\n Ok(())\n }\n}\n\nfn sanitize_segment(value: &str) -> String {\n let mut out = String::new();\n let mut prev_dash = false;\n for ch in value.chars() {\n if ch.is_ascii_alphanumeric() {\n out.push(ch.to_ascii_lowercase());\n prev_dash = false;\n } else if !prev_dash {\n out.push('-');\n prev_dash = true;\n }\n }\n out.trim_matches('-').to_string()\n}\n" }, { "path": "src/ask.rs", "content": "//! Ask the AI server to suggest a task or flow command.\n\nuse std::collections::HashSet;\nuse std::path::PathBuf;\n\nuse anyhow::{Result, bail};\nuse clap::CommandFactory;\n\nuse crate::ai_server;\nuse crate::cli::Cli;\nuse crate::discover::{self, DiscoveredTask};\n\n/// Options for the ask command.\n#[derive(Debug, Clone)]\npub struct AskOpts {\n /// The user's query as separate arguments (preserves quoting from shell).\n pub args: Vec<String>,\n /// AI server model to use.\n pub model: Option<String>,\n /// AI server URL override.\n pub url: Option<String>,\n}\n\nenum AskSelection {\n Task { name: String },\n Command { command: String },\n}\n\nstruct FlowCommand {\n name: String,\n aliases: Vec<String>,\n about: Option<String>,\n}\n\n/// Ask the AI server for a suggested task or command.\npub fn run(opts: AskOpts) -> Result<()> {\n let root = std::env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\"));\n let discovery = discover::discover_tasks(&root)?;\n run_with_tasks(opts, discovery.tasks)\n}\n\nfn run_with_tasks(opts: AskOpts, tasks: Vec<DiscoveredTask>) -> Result<()> {\n let query_display = opts.args.join(\" \");\n\n if let Some(direct) = try_direct_match(&opts.args, &tasks) {\n let matched = find_task(&direct.task_name, &tasks)?;\n print_task_suggestion(matched, &direct.args);\n return Ok(());\n }\n\n if is_cli_subcommand(&opts.args) {\n let command = format!(\"f {}\", opts.args.join(\" \"));\n print_command_suggestion(&command);\n return Ok(());\n }\n\n let commands = flow_command_candidates();\n let valid_subcommands = valid_subcommand_set(&commands);\n let prompt = build_prompt(&query_display, &tasks, &commands);\n\n let response =\n ai_server::quick_prompt(&prompt, opts.model.as_deref(), opts.url.as_deref(), None)?;\n\n let selection = parse_ask_response(&response, &tasks, &valid_subcommands)?;\n\n match selection {\n AskSelection::Task { name } => {\n let matched = find_task(&name, &tasks)?;\n print_task_suggestion(matched, &[]);\n }\n AskSelection::Command { command } => {\n print_command_suggestion(&command);\n }\n }\n\n Ok(())\n}\n\nfn print_task_suggestion(task: &DiscoveredTask, args: &[String]) {\n let command = if args.is_empty() {\n format!(\"f {}\", task.task.name)\n } else {\n format!(\"f {} {}\", task.task.name, args.join(\" \"))\n };\n\n println!(\"Suggested command:\");\n println!(\"{}\", command);\n\n let mut detail = format!(\"Matched task: {}\", task.task.name);\n if !task.relative_dir.is_empty() {\n detail.push_str(&format!(\" ({})\", task.relative_dir));\n }\n detail.push_str(&format!(\" - {}\", task.task.command));\n println!(\"{}\", detail);\n}\n\nfn print_command_suggestion(command: &str) {\n println!(\"Suggested command:\");\n println!(\"{}\", command.trim());\n}\n\nfn find_task<'a>(name: &str, tasks: &'a [DiscoveredTask]) -> Result<&'a DiscoveredTask> {\n tasks\n .iter()\n .find(|t| t.task.name.eq_ignore_ascii_case(name))\n .ok_or_else(|| anyhow::anyhow!(\"AI returned unknown task: {}\", name))\n}\n\nfn flow_command_candidates() -> Vec<FlowCommand> {\n let mut commands = Vec::new();\n let cmd = Cli::command();\n for sub in cmd.get_subcommands() {\n let name = sub.get_name().to_string();\n let about = sub\n .get_about()\n .map(|s| s.to_string())\n .filter(|s| !s.is_empty());\n let aliases = sub.get_all_aliases().map(|a| a.to_string()).collect();\n commands.push(FlowCommand {\n name,\n aliases,\n about,\n });\n }\n\n commands.push(FlowCommand {\n name: \"tasks list\".to_string(),\n aliases: Vec::new(),\n about: Some(\"List tasks from flow.toml.\".to_string()),\n });\n\n commands.sort_by(|a, b| a.name.cmp(&b.name));\n commands\n}\n\nfn valid_subcommand_set(commands: &[FlowCommand]) -> HashSet<String> {\n let mut set = HashSet::new();\n for cmd in commands {\n let name = cmd.name.split_whitespace().next().unwrap_or(\"\").to_string();\n if !name.is_empty() {\n set.insert(name.to_ascii_lowercase());\n }\n for alias in &cmd.aliases {\n set.insert(alias.to_ascii_lowercase());\n }\n }\n set.insert(\"help\".to_string());\n set.insert(\"-h\".to_string());\n set.insert(\"--help\".to_string());\n set\n}\n\nfn build_prompt(query: &str, tasks: &[DiscoveredTask], commands: &[FlowCommand]) -> String {\n let mut prompt = String::new();\n prompt.push_str(\"You are a Flow CLI assistant.\\n\");\n prompt.push_str(\"Choose the best command for the user to run.\\n\");\n prompt.push_str(\"Respond with ONE line in one of these formats only:\\n\");\n prompt.push_str(\"task:<task_name>\\n\");\n prompt.push_str(\"cmd:f <flow command>\\n\\n\");\n\n if tasks.is_empty() {\n prompt.push_str(\"No flow.toml tasks were discovered.\\n\");\n } else {\n prompt.push_str(\"Available tasks:\\n\");\n for task in tasks {\n let location = if task.relative_dir.is_empty() {\n String::new()\n } else {\n format!(\" (in {})\", task.relative_dir)\n };\n let desc = task\n .task\n .description\n .as_deref()\n .unwrap_or(&task.task.command);\n prompt.push_str(&format!(\"- {}{}: {}\\n\", task.task.name, location, desc));\n }\n }\n\n prompt.push_str(\"\\nFlow CLI commands:\\n\");\n for cmd in commands {\n let mut line = format!(\"- f {}\", cmd.name);\n if let Some(about) = &cmd.about {\n if !about.trim().is_empty() {\n line.push_str(&format!(\": {}\", about.trim()));\n }\n }\n prompt.push_str(&format!(\"{}\\n\", line));\n }\n\n prompt.push_str(&format!(\"\\nUser query: {}\\n\", query));\n prompt.push_str(\"Answer:\");\n\n prompt\n}\n\nfn parse_ask_response(\n response: &str,\n tasks: &[DiscoveredTask],\n valid_subcommands: &HashSet<String>,\n) -> Result<AskSelection> {\n let cleaned = response.trim().trim_matches('`').trim();\n if cleaned.is_empty() {\n bail!(\"AI returned an empty response.\");\n }\n\n if let Some(selection) = parse_structured_line(cleaned, tasks, valid_subcommands)? {\n return Ok(selection);\n }\n\n // Some models emit reasoning wrappers (e.g. <think>...</think>) before the\n // final machine-readable answer. Scan lines and parse the first valid one.\n for line in cleaned.lines() {\n let candidate = line.trim();\n if candidate.is_empty() {\n continue;\n }\n if let Some(selection) = parse_structured_line(candidate, tasks, valid_subcommands)? {\n return Ok(selection);\n }\n }\n\n if cleaned.starts_with(\"f \") || cleaned.starts_with(\"flow \") {\n let command = normalize_command(cleaned, valid_subcommands)?;\n return Ok(AskSelection::Command { command });\n }\n\n if let Ok(task_name) = extract_task_name(cleaned, tasks) {\n return Ok(AskSelection::Task { name: task_name });\n }\n\n if is_command_like(cleaned, valid_subcommands) {\n let command = normalize_command(cleaned, valid_subcommands)?;\n return Ok(AskSelection::Command { command });\n }\n\n bail!(\"Could not parse AI response: '{}'\", cleaned);\n}\n\nfn parse_structured_line(\n raw: &str,\n tasks: &[DiscoveredTask],\n valid_subcommands: &HashSet<String>,\n) -> Result<Option<AskSelection>> {\n if let Some(rest) = raw.strip_prefix(\"task:\") {\n let task_name = extract_task_name(rest.trim(), tasks)?;\n return Ok(Some(AskSelection::Task { name: task_name }));\n }\n if let Some(rest) = raw.strip_prefix(\"cmd:\") {\n let command = normalize_command(rest, valid_subcommands)?;\n return Ok(Some(AskSelection::Command { command }));\n }\n if let Some(rest) = raw.strip_prefix(\"command:\") {\n let command = normalize_command(rest, valid_subcommands)?;\n return Ok(Some(AskSelection::Command { command }));\n }\n Ok(None)\n}\n\nfn normalize_command(raw: &str, valid_subcommands: &HashSet<String>) -> Result<String> {\n let mut cmd = raw.trim().trim_matches('`').trim().to_string();\n if cmd.starts_with(\"cmd:\") {\n cmd = cmd.trim_start_matches(\"cmd:\").trim().to_string();\n } else if cmd.starts_with(\"command:\") {\n cmd = cmd.trim_start_matches(\"command:\").trim().to_string();\n }\n\n if cmd.starts_with(\"flow \") {\n cmd = format!(\"f {}\", cmd.trim_start_matches(\"flow \").trim());\n } else if !cmd.starts_with(\"f \") {\n cmd = format!(\"f {}\", cmd);\n }\n\n let tokens = shell_words::split(&cmd)\n .unwrap_or_else(|_| cmd.split_whitespace().map(|s| s.to_string()).collect());\n if tokens.len() < 2 {\n bail!(\"Command '{}' is incomplete.\", cmd);\n }\n let sub = tokens[1].to_ascii_lowercase();\n if !valid_subcommands.contains(&sub) {\n bail!(\"AI returned unknown command '{}'.\", cmd);\n }\n\n Ok(cmd)\n}\n\nfn is_command_like(raw: &str, valid_subcommands: &HashSet<String>) -> bool {\n let first = raw\n .split_whitespace()\n .next()\n .unwrap_or(\"\")\n .trim()\n .to_ascii_lowercase();\n if first.is_empty() {\n return false;\n }\n valid_subcommands.contains(&first)\n}\n\nfn cli_subcommands() -> Vec<String> {\n let mut names = Vec::new();\n let cmd = Cli::command();\n for sub in cmd.get_subcommands() {\n names.push(sub.get_name().to_string());\n for alias in sub.get_all_aliases() {\n names.push(alias.to_string());\n }\n }\n names\n}\n\nfn is_cli_subcommand(args: &[String]) -> bool {\n let Some(first) = args.first() else {\n return false;\n };\n let first_lower = first.to_ascii_lowercase();\n cli_subcommands()\n .iter()\n .any(|cmd| cmd.eq_ignore_ascii_case(&first_lower))\n}\n\n/// Normalize a string by removing hyphens, underscores, and lowercasing.\nfn normalize_name(s: &str) -> String {\n s.chars()\n .filter(|c| *c != '-' && *c != '_')\n .collect::<String>()\n .to_ascii_lowercase()\n}\n\n/// Result of a direct match attempt - includes task name and any extra args.\nstruct DirectMatchResult {\n task_name: String,\n args: Vec<String>,\n}\n\n/// Try to match query directly to a task name, shortcut, or abbreviation.\nfn try_direct_match(args: &[String], tasks: &[DiscoveredTask]) -> Option<DirectMatchResult> {\n if args.is_empty() {\n return None;\n }\n\n let first = args[0].trim();\n let rest: Vec<String> = args[1..].to_vec();\n\n if let Some(task) = tasks\n .iter()\n .find(|t| t.task.name.eq_ignore_ascii_case(first))\n {\n return Some(DirectMatchResult {\n task_name: task.task.name.clone(),\n args: rest,\n });\n }\n\n if let Some(task) = tasks.iter().find(|t| {\n t.task\n .shortcuts\n .iter()\n .any(|s| s.eq_ignore_ascii_case(first))\n }) {\n return Some(DirectMatchResult {\n task_name: task.task.name.clone(),\n args: rest,\n });\n }\n\n let normalized_query = normalize_name(first);\n let mut normalized_matches: Vec<_> = tasks\n .iter()\n .filter(|t| normalize_name(&t.task.name) == normalized_query)\n .collect();\n if normalized_matches.len() == 1 {\n return Some(DirectMatchResult {\n task_name: normalized_matches.remove(0).task.name.clone(),\n args: rest,\n });\n }\n\n let needle = first.to_ascii_lowercase();\n if needle.len() >= 2 {\n let mut matches = tasks.iter().filter(|t| {\n generate_abbreviation(&t.task.name)\n .map(|abbr| abbr == needle)\n .unwrap_or(false)\n });\n\n if let Some(first_match) = matches.next() {\n if matches.next().is_none() {\n return Some(DirectMatchResult {\n task_name: first_match.task.name.clone(),\n args: rest,\n });\n }\n }\n }\n\n if needle.len() >= 2 {\n let mut prefix_matches: Vec<_> = tasks\n .iter()\n .filter(|t| t.task.name.to_ascii_lowercase().starts_with(&needle))\n .collect();\n if prefix_matches.len() == 1 {\n return Some(DirectMatchResult {\n task_name: prefix_matches.remove(0).task.name.clone(),\n args: rest,\n });\n }\n }\n\n None\n}\n\nfn generate_abbreviation(name: &str) -> Option<String> {\n let mut abbr = String::new();\n let mut new_segment = true;\n for ch in name.chars() {\n if ch.is_ascii_alphanumeric() {\n if new_segment {\n abbr.push(ch.to_ascii_lowercase());\n new_segment = false;\n }\n } else {\n new_segment = true;\n }\n }\n if abbr.len() >= 2 { Some(abbr) } else { None }\n}\n\nfn extract_task_name(response: &str, tasks: &[DiscoveredTask]) -> Result<String> {\n let response = response.trim();\n\n for task in tasks {\n if task.task.name.eq_ignore_ascii_case(response) {\n return Ok(task.task.name.clone());\n }\n }\n\n for task in tasks {\n if response\n .to_lowercase()\n .contains(&task.task.name.to_lowercase())\n {\n return Ok(task.task.name.clone());\n }\n }\n\n let cleaned = response\n .trim_start_matches(|c: char| !c.is_alphanumeric())\n .trim_end_matches(|c: char| !c.is_alphanumeric() && c != '-' && c != '_')\n .to_string();\n\n for task in tasks {\n if task.task.name.eq_ignore_ascii_case(&cleaned) {\n return Ok(task.task.name.clone());\n }\n }\n\n bail!(\"Could not parse task name from AI response: '{}'\", response)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use crate::config::TaskConfig;\n\n fn make_discovered(name: &str) -> DiscoveredTask {\n DiscoveredTask {\n task: TaskConfig {\n name: name.to_string(),\n command: format!(\"echo {}\", name),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n },\n config_path: PathBuf::from(\"flow.toml\"),\n relative_dir: String::new(),\n depth: 0,\n scope: \"root\".to_string(),\n scope_aliases: vec![\"root\".to_string()],\n }\n }\n\n #[test]\n fn parse_task_response() {\n let tasks = vec![make_discovered(\"build\")];\n let mut cmds = HashSet::new();\n cmds.insert(\"tasks\".to_string());\n let parsed = parse_ask_response(\"task:build\", &tasks, &cmds).unwrap();\n match parsed {\n AskSelection::Task { name } => assert_eq!(name, \"build\"),\n _ => panic!(\"expected task\"),\n }\n }\n\n #[test]\n fn parse_command_response() {\n let tasks = vec![make_discovered(\"build\")];\n let mut cmds = HashSet::new();\n cmds.insert(\"tasks\".to_string());\n let parsed = parse_ask_response(\"cmd:f tasks list\", &tasks, &cmds).unwrap();\n match parsed {\n AskSelection::Command { command } => assert_eq!(command, \"f tasks list\"),\n _ => panic!(\"expected command\"),\n }\n }\n}\n" }, { "path": "src/auth.rs", "content": "use std::thread::sleep;\nuse std::time::{Duration, Instant};\n\nuse anyhow::{Context, Result, anyhow, bail};\nuse reqwest::blocking::Client;\nuse serde::Deserialize;\n\nuse crate::cli::AuthOpts;\nuse crate::env;\n\n#[derive(Debug, Deserialize)]\nstruct DeviceStartResponse {\n device_code: String,\n user_code: String,\n verification_url: String,\n expires_in: u64,\n #[serde(default = \"default_poll_interval\")]\n interval: u64,\n}\n\nfn default_poll_interval() -> u64 {\n 2\n}\n\n#[derive(Debug, Deserialize)]\nstruct DevicePollResponse {\n status: String,\n token: Option<String>,\n}\n\npub fn run(opts: AuthOpts) -> Result<()> {\n login(opts.api_url)\n}\n\nfn login(api_url_override: Option<String>) -> Result<()> {\n let api_url = api_url_override\n .or_else(|| env::load_ai_api_url().ok())\n .unwrap_or_else(|| \"https://myflow.sh\".to_string());\n let api_url = api_url.trim().trim_end_matches('/').to_string();\n\n let client = Client::builder()\n .timeout(Duration::from_secs(30))\n .build()\n .context(\"failed to create HTTP client for auth\")?;\n\n let start_url = format!(\"{}/api/auth/cli/start\", api_url);\n let response = client\n .post(&start_url)\n .json(&serde_json::json!({\"client\": \"flow\"}))\n .send()\n .context(\"failed to start device auth\")?;\n\n if !response.status().is_success() {\n bail!(\"device auth start failed: HTTP {}\", response.status());\n }\n\n let payload: DeviceStartResponse = response\n .json()\n .context(\"failed to parse device auth response\")?;\n\n println!(\"\\nFlow auth with myflow\");\n println!(\"───────────────────────\");\n println!(\"Code: {}\", payload.user_code);\n println!(\"Open: {}\\n\", payload.verification_url);\n\n open_in_browser(&payload.verification_url);\n\n let expires_at = Instant::now() + Duration::from_secs(payload.expires_in);\n let poll_url = format!(\"{}/api/auth/cli/poll\", api_url);\n\n println!(\"Waiting for approval...\");\n\n while Instant::now() < expires_at {\n sleep(Duration::from_secs(payload.interval.max(1)));\n\n let poll_response = client\n .post(&poll_url)\n .json(&serde_json::json!({\"device_code\": payload.device_code}))\n .send()\n .context(\"failed to poll device auth\")?;\n\n if !poll_response.status().is_success() {\n bail!(\"device auth poll failed: HTTP {}\", poll_response.status());\n }\n\n let poll: DevicePollResponse = poll_response\n .json()\n .context(\"failed to parse device auth poll response\")?;\n\n match poll.status.as_str() {\n \"approved\" => {\n let token = poll\n .token\n .ok_or_else(|| anyhow!(\"device auth approved without token\"))?;\n env::save_ai_auth_token(token, Some(api_url.clone()))?;\n println!(\"✓ Auth complete. You're ready to use Flow AI.\");\n return Ok(());\n }\n \"pending\" => continue,\n \"expired\" => bail!(\"device code expired. Run `f auth` again.\"),\n \"invalid\" => bail!(\"device code invalid. Run `f auth` again.\"),\n other => bail!(\"unexpected auth status: {}\", other),\n }\n }\n\n bail!(\"device code expired. Run `f auth` again.\")\n}\n\nfn open_in_browser(url: &str) {\n #[cfg(target_os = \"macos\")]\n {\n let _ = std::process::Command::new(\"open\").arg(url).status();\n }\n\n #[cfg(target_os = \"linux\")]\n {\n let _ = std::process::Command::new(\"xdg-open\").arg(url).status();\n }\n\n #[cfg(not(any(target_os = \"macos\", target_os = \"linux\")))]\n println!(\"Open this URL in your browser: {}\", url);\n}\n" }, { "path": "src/base_tool.rs", "content": "use std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result};\n\npub fn resolve_bin() -> Option<PathBuf> {\n if let Ok(value) = std::env::var(\"FLOW_BASE_BIN\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Some(PathBuf::from(trimmed));\n }\n }\n\n // Prefer a more specific name, but fall back to the current base repo binary name.\n for name in [\"base\", \"db\"] {\n if let Ok(path) = which::which(name) {\n return Some(path);\n }\n }\n\n None\n}\n\npub fn run_inherit_stdio(bin: &Path, args: &[String]) -> Result<()> {\n let status = Command::new(bin)\n .args(args)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .with_context(|| format!(\"failed to run {} {}\", bin.display(), args.join(\" \")))?;\n if !status.success() {\n anyhow::bail!(\"{} exited with {}\", bin.display(), status);\n }\n Ok(())\n}\n\npub fn run_with_stdin(bin: &Path, args: &[String], stdin: &str) -> Result<()> {\n let mut child = Command::new(bin)\n .args(args)\n .stdin(Stdio::piped())\n .stdout(Stdio::null())\n // This path is currently only used for best-effort \"task run\" ingestion.\n // If the user has some other `base` binary on PATH (or an older one),\n // it may print usage/errors like \"unrecognized subcommand 'ingest'\".\n // We intentionally silence stderr to avoid confusing noise during normal runs.\n .stderr(Stdio::null())\n .spawn()\n .with_context(|| format!(\"failed to spawn {} {}\", bin.display(), args.join(\" \")))?;\n\n {\n use std::io::Write;\n let child_stdin = child.stdin.as_mut().context(\"failed to open stdin\")?;\n child_stdin.write_all(stdin.as_bytes())?;\n }\n\n let status = child.wait()?;\n if !status.success() {\n anyhow::bail!(\"{} exited with {}\", bin.display(), status);\n }\n Ok(())\n}\n" }, { "path": "src/bin/ai_taskd_client.rs", "content": "use std::env;\nuse std::io::{self, Read, Write};\nuse std::os::unix::net::UnixStream;\nuse std::path::PathBuf;\nuse std::process;\n\nuse serde::{Deserialize, Serialize};\n\nconst MSGPACK_WIRE_PREFIX: u8 = 0xFF;\n\n#[derive(Debug, Clone, Copy)]\nenum WireProtocol {\n Json,\n Msgpack,\n}\n\n#[derive(Debug, Serialize)]\n#[serde(tag = \"type\", rename_all = \"snake_case\")]\nenum TaskdRequest {\n Run {\n project_root: String,\n selector: String,\n args: Vec<String>,\n no_cache: bool,\n capture_output: bool,\n include_timings: bool,\n suggested_task: Option<String>,\n override_reason: Option<String>,\n },\n}\n\n#[derive(Debug, Deserialize)]\nstruct TaskdResponse {\n ok: bool,\n message: String,\n exit_code: i32,\n stdout: String,\n stderr: String,\n timings: Option<RequestTimings>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct RequestTimings {\n resolve_selector_us: u64,\n run_task_us: u64,\n total_us: u64,\n used_fast_selector: bool,\n used_cache: bool,\n}\n\nfn main() {\n match run() {\n Ok(code) => process::exit(code),\n Err(msg) => {\n eprintln!(\"{msg}\");\n process::exit(1);\n }\n }\n}\n\nfn run() -> Result<i32, String> {\n let args: Vec<String> = env::args().skip(1).collect();\n if args.is_empty() || args.iter().any(|a| a == \"-h\" || a == \"--help\") {\n print_help();\n return Ok(0);\n }\n\n let mut root = env::current_dir()\n .map_err(|e| format!(\"failed to resolve cwd: {e}\"))?\n .to_string_lossy()\n .to_string();\n let mut no_cache = false;\n let mut capture_output = false;\n let mut include_timings = false;\n let mut batch_stdin = false;\n let mut protocol = WireProtocol::Msgpack;\n let mut socket = default_socket_path();\n\n let mut idx = 0usize;\n while idx < args.len() {\n let arg = args[idx].clone();\n match arg.as_str() {\n \"--root\" => {\n idx += 1;\n let value = args.get(idx).ok_or(\"--root requires a value\")?;\n root = value.clone();\n }\n \"--socket\" => {\n idx += 1;\n let value = args.get(idx).ok_or(\"--socket requires a value\")?;\n socket = PathBuf::from(value);\n }\n \"--protocol\" => {\n idx += 1;\n let value = args\n .get(idx)\n .ok_or(\"--protocol requires a value (json|msgpack)\")?;\n protocol = match value.trim().to_ascii_lowercase().as_str() {\n \"json\" => WireProtocol::Json,\n \"msgpack\" | \"mp\" => WireProtocol::Msgpack,\n other => return Err(format!(\"unsupported protocol '{other}'\")),\n };\n }\n \"--no-cache\" => {\n no_cache = true;\n }\n \"--capture-output\" => {\n capture_output = true;\n }\n \"--timings\" => {\n include_timings = true;\n }\n \"--batch-stdin\" => {\n batch_stdin = true;\n }\n _ => break,\n }\n idx += 1;\n }\n\n if batch_stdin {\n return run_batch(\n &socket,\n protocol,\n &root,\n no_cache,\n capture_output,\n include_timings,\n );\n }\n\n if idx >= args.len() {\n return Err(\"missing selector\".to_string());\n }\n let selector = args[idx].clone();\n let trailing = if idx + 1 < args.len() {\n if args[idx + 1] == \"--\" {\n args[(idx + 2)..].to_vec()\n } else {\n args[(idx + 1)..].to_vec()\n }\n } else {\n Vec::new()\n };\n\n let response = run_once(\n &socket,\n protocol,\n &root,\n &selector,\n &trailing,\n no_cache,\n capture_output,\n include_timings,\n )?;\n print_response(&response, include_timings, &selector);\n if response.ok {\n return Ok(0);\n }\n eprintln!(\"{}\", response.message);\n Ok(if response.exit_code == 0 {\n 1\n } else {\n response.exit_code\n })\n}\n\nfn run_batch(\n socket: &PathBuf,\n protocol: WireProtocol,\n root: &str,\n no_cache: bool,\n capture_output: bool,\n include_timings: bool,\n) -> Result<i32, String> {\n let mut input = String::new();\n io::stdin()\n .read_to_string(&mut input)\n .map_err(|e| format!(\"failed to read stdin: {e}\"))?;\n\n let mut any_failure = false;\n for (line_no, raw) in input.lines().enumerate() {\n let line = raw.trim();\n if line.is_empty() || line.starts_with('#') {\n continue;\n }\n let tokens = shell_words::split(line)\n .map_err(|e| format!(\"batch parse error at line {}: {e}\", line_no + 1))?;\n if tokens.is_empty() {\n continue;\n }\n let selector = tokens[0].clone();\n let args = if tokens.len() > 1 {\n tokens[1..].to_vec()\n } else {\n Vec::new()\n };\n let response = run_once(\n socket,\n protocol,\n root,\n &selector,\n &args,\n no_cache,\n capture_output,\n include_timings,\n )?;\n print_response(&response, include_timings, &selector);\n if !response.ok {\n any_failure = true;\n eprintln!(\"[batch][{}] {}\", selector, response.message);\n }\n }\n\n Ok(if any_failure { 1 } else { 0 })\n}\n\n#[allow(clippy::too_many_arguments)]\nfn run_once(\n socket: &PathBuf,\n protocol: WireProtocol,\n root: &str,\n selector: &str,\n args: &[String],\n no_cache: bool,\n capture_output: bool,\n include_timings: bool,\n) -> Result<TaskdResponse, String> {\n let req = TaskdRequest::Run {\n project_root: root.to_string(),\n selector: selector.to_string(),\n args: args.to_vec(),\n no_cache,\n capture_output,\n include_timings,\n suggested_task: read_optional_env(\"FLOW_ROUTER_SUGGESTED_TASK\"),\n override_reason: read_optional_env(\"FLOW_ROUTER_OVERRIDE_REASON\"),\n };\n send_request(socket, protocol, &req)\n}\n\nfn send_request(\n socket: &PathBuf,\n protocol: WireProtocol,\n request: &TaskdRequest,\n) -> Result<TaskdResponse, String> {\n let req_bytes = encode_request(request, protocol)?;\n let mut stream = UnixStream::connect(socket)\n .map_err(|e| format!(\"failed to connect to {}: {e}\", socket.display()))?;\n stream\n .write_all(&req_bytes)\n .map_err(|e| format!(\"failed to write request: {e}\"))?;\n stream\n .shutdown(std::net::Shutdown::Write)\n .map_err(|e| format!(\"failed to finalize request: {e}\"))?;\n\n let mut body = Vec::new();\n stream\n .read_to_end(&mut body)\n .map_err(|e| format!(\"failed to read response: {e}\"))?;\n decode_response(&body)\n}\n\nfn encode_request(request: &TaskdRequest, protocol: WireProtocol) -> Result<Vec<u8>, String> {\n match protocol {\n WireProtocol::Json => {\n serde_json::to_vec(request).map_err(|e| format!(\"failed to encode json request: {e}\"))\n }\n WireProtocol::Msgpack => {\n let mut out = vec![MSGPACK_WIRE_PREFIX];\n let encoded = rmp_serde::to_vec_named(request)\n .map_err(|e| format!(\"failed to encode msgpack request: {e}\"))?;\n out.extend(encoded);\n Ok(out)\n }\n }\n}\n\nfn decode_response(payload: &[u8]) -> Result<TaskdResponse, String> {\n if payload.first() == Some(&MSGPACK_WIRE_PREFIX) {\n return rmp_serde::from_slice::<TaskdResponse>(&payload[1..])\n .map_err(|e| format!(\"failed to decode msgpack response: {e}\"));\n }\n serde_json::from_slice::<TaskdResponse>(payload)\n .map_err(|e| format!(\"failed to decode json response: {e}\"))\n}\n\nfn print_response(response: &TaskdResponse, include_timings: bool, selector: &str) {\n if !response.stdout.is_empty() {\n print!(\"{}\", response.stdout);\n }\n if !response.stderr.is_empty() {\n eprint!(\"{}\", response.stderr);\n }\n if include_timings && let Some(t) = &response.timings {\n eprintln!(\n \"[timings][{}] resolve_us={} run_us={} total_us={} fast_selector={} cache={}\",\n selector,\n t.resolve_selector_us,\n t.run_task_us,\n t.total_us,\n t.used_fast_selector,\n t.used_cache\n );\n }\n}\n\nfn default_socket_path() -> PathBuf {\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".flow\")\n .join(\"run\")\n .join(\"ai-taskd.sock\")\n}\n\nfn read_optional_env(key: &str) -> Option<String> {\n let raw = env::var(key).ok()?;\n let trimmed = raw.trim();\n if trimmed.is_empty() {\n return None;\n }\n Some(trimmed.to_string())\n}\n\nfn print_help() {\n println!(\"ai-taskd-client\");\n println!(\"Usage:\");\n println!(\n \" ai-taskd-client [--root PATH] [--socket PATH] [--protocol json|msgpack] [--no-cache] [--capture-output] [--timings] <selector> [-- <args...>]\"\n );\n println!(\n \" ai-taskd-client [--root PATH] [--socket PATH] [--protocol json|msgpack] [--no-cache] [--capture-output] [--timings] --batch-stdin\"\n );\n println!();\n println!(\"Examples:\");\n println!(\" ai-taskd-client ai:flow/noop\");\n println!(\" ai-taskd-client --protocol msgpack --timings ai:flow/noop\");\n println!(\n \" printf 'ai:flow/noop\\\\nai:flow/dev-check -- --quick\\\\n' | ai-taskd-client --batch-stdin\"\n );\n}\n" }, { "path": "src/bin/lin.rs", "content": "include!(\"../main.rs\");\n" }, { "path": "src/branches.rs", "content": "//! Branch discovery and selection utilities.\n\nuse std::cmp::Ordering;\nuse std::collections::HashSet;\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::ai_server;\nuse crate::cli::{\n BranchAiOpts, BranchFindOpts, BranchListOpts, BranchesAction, BranchesCommand, SwitchCommand,\n};\nuse crate::sync;\n\n#[derive(Debug, Clone)]\nstruct BranchEntry {\n name: String,\n subject: String,\n upstream: Option<String>,\n is_remote: bool,\n}\n\npub fn run(cmd: BranchesCommand) -> Result<()> {\n match cmd.action {\n Some(BranchesAction::List(opts)) => run_list(opts),\n Some(BranchesAction::Find(opts)) => run_find(opts),\n Some(BranchesAction::Ai(opts)) => run_ai(opts),\n None => run_list(BranchListOpts {\n remote: false,\n limit: 40,\n }),\n }\n}\n\nfn run_list(opts: BranchListOpts) -> Result<()> {\n let branches = collect_branches(opts.remote)?;\n if branches.is_empty() {\n println!(\"No branches found.\");\n return Ok(());\n }\n\n let limit = opts.limit.max(1);\n for entry in branches.iter().take(limit) {\n print_branch(entry);\n }\n Ok(())\n}\n\nfn run_find(opts: BranchFindOpts) -> Result<()> {\n let query = opts.query.trim().to_string();\n if query.is_empty() {\n bail!(\"Query cannot be empty\");\n }\n\n let branches = collect_branches(opts.remote)?;\n if branches.is_empty() {\n bail!(\"No branches available to search\");\n }\n\n let ranked = rank_branches(&query, &branches);\n if ranked.is_empty() {\n bail!(\"No branches matched query '{}'.\", query);\n }\n\n let limit = opts.limit.max(1);\n for (_, entry) in ranked.iter().take(limit) {\n print_branch(entry);\n }\n\n if opts.switch {\n let best = ranked\n .first()\n .map(|(_, entry)| (*entry).clone())\n .context(\"No match available to switch\")?;\n println!(\"\\nSwitching to {}...\", best.name);\n switch_to_entry(&best)?;\n }\n\n Ok(())\n}\n\nfn run_ai(opts: BranchAiOpts) -> Result<()> {\n let query = opts.query.trim().to_string();\n if query.is_empty() {\n bail!(\"Query cannot be empty\");\n }\n\n let branches = collect_branches(opts.remote)?;\n if branches.is_empty() {\n bail!(\"No branches available for AI matching\");\n }\n\n let candidates = top_candidates_for_ai(&query, &branches, opts.limit.max(1));\n let prompt = build_ai_prompt(&query, &candidates);\n let response =\n ai_server::quick_prompt(&prompt, opts.model.as_deref(), opts.url.as_deref(), None)?;\n let cleaned_response = response.trim().trim_matches('`').trim();\n if cleaned_response.eq_ignore_ascii_case(\"none\") {\n println!(\"AI selected no matching branch.\");\n return Ok(());\n }\n let selected_name = parse_ai_branch_response(&response, &candidates)\n .with_context(|| format!(\"Could not parse AI branch response: {}\", response.trim()))?;\n\n let selected = candidates\n .iter()\n .find(|e| e.name == selected_name)\n .cloned()\n .context(\"AI selected branch that is not in candidate list\")?;\n\n println!(\"Selected branch:\");\n print_branch(&selected);\n\n if opts.switch {\n println!(\"\\nSwitching to {}...\", selected.name);\n switch_to_entry(&selected)?;\n }\n\n Ok(())\n}\n\nfn print_branch(entry: &BranchEntry) {\n let mut line = if entry.is_remote {\n format!(\"{} [remote]\", entry.name)\n } else {\n entry.name.clone()\n };\n\n if let Some(upstream) = entry.upstream.as_deref() {\n if !upstream.is_empty() {\n line.push_str(&format!(\" -> {}\", upstream));\n }\n }\n\n if !entry.subject.is_empty() {\n line.push_str(&format!(\" :: {}\", entry.subject));\n }\n\n println!(\"{}\", line);\n}\n\nfn collect_branches(include_remote: bool) -> Result<Vec<BranchEntry>> {\n let mut out = collect_local_branches()?;\n\n if include_remote {\n out.extend(collect_remote_branches()?);\n }\n\n Ok(out)\n}\n\nfn collect_local_branches() -> Result<Vec<BranchEntry>> {\n let raw = git_capture(&[\n \"for-each-ref\",\n \"--sort=-committerdate\",\n \"--format=%(refname:short)%00%(upstream:short)%00%(subject)\",\n \"refs/heads\",\n ])?;\n\n let mut branches = Vec::new();\n for line in raw.lines() {\n let mut parts = line.split('\\0');\n let name = parts.next().unwrap_or(\"\").trim();\n if name.is_empty() {\n continue;\n }\n let upstream = parts.next().unwrap_or(\"\").trim().to_string();\n let subject = parts.next().unwrap_or(\"\").trim().to_string();\n\n branches.push(BranchEntry {\n name: name.to_string(),\n subject,\n upstream: if upstream.is_empty() {\n None\n } else {\n Some(upstream)\n },\n is_remote: false,\n });\n }\n\n Ok(branches)\n}\n\nfn collect_remote_branches() -> Result<Vec<BranchEntry>> {\n let raw = git_capture(&[\n \"for-each-ref\",\n \"--sort=-committerdate\",\n \"--format=%(refname:short)%00%(subject)\",\n \"refs/remotes\",\n ])?;\n\n let mut branches = Vec::new();\n let mut seen = HashSet::new();\n for line in raw.lines() {\n let mut parts = line.split('\\0');\n let name = parts.next().unwrap_or(\"\").trim();\n if name.is_empty() || name.ends_with(\"/HEAD\") {\n continue;\n }\n if !seen.insert(name.to_string()) {\n continue;\n }\n\n let subject = parts.next().unwrap_or(\"\").trim().to_string();\n branches.push(BranchEntry {\n name: name.to_string(),\n subject,\n upstream: None,\n is_remote: true,\n });\n }\n\n Ok(branches)\n}\n\nfn rank_branches<'a>(query: &str, branches: &'a [BranchEntry]) -> Vec<(i64, &'a BranchEntry)> {\n let q = query.to_ascii_lowercase();\n let tokens: Vec<&str> = q.split_whitespace().filter(|t| !t.is_empty()).collect();\n\n let mut ranked = Vec::new();\n for (idx, entry) in branches.iter().enumerate() {\n let hay_name = entry.name.to_ascii_lowercase();\n let hay_subject = entry.subject.to_ascii_lowercase();\n\n let mut score: i64 = 0;\n let mut matched = false;\n\n if let Some(pos) = hay_name.find(&q) {\n matched = true;\n score += 10_000 - pos as i64;\n }\n if let Some(pos) = hay_subject.find(&q) {\n matched = true;\n score += 3_000 - pos as i64;\n }\n\n let mut all_tokens_match = true;\n for token in &tokens {\n if hay_name.contains(token) {\n score += 700;\n } else if hay_subject.contains(token) {\n score += 250;\n } else {\n all_tokens_match = false;\n }\n }\n\n if !tokens.is_empty() && all_tokens_match {\n matched = true;\n score += 1_500;\n }\n\n if !matched {\n continue;\n }\n\n // Stable tie-break using recency order from git listing (earlier index first).\n score -= idx as i64;\n ranked.push((score, entry));\n }\n\n ranked.sort_by(|a, b| match b.0.cmp(&a.0) {\n Ordering::Equal => a.1.name.cmp(&b.1.name),\n other => other,\n });\n\n ranked\n}\n\nfn top_candidates_for_ai(query: &str, branches: &[BranchEntry], limit: usize) -> Vec<BranchEntry> {\n let mut candidates: Vec<BranchEntry> = rank_branches(query, branches)\n .into_iter()\n .map(|(_, entry)| (*entry).clone())\n .take(limit)\n .collect();\n\n if candidates.is_empty() {\n candidates = branches.iter().take(limit).cloned().collect();\n }\n\n candidates\n}\n\nfn build_ai_prompt(query: &str, candidates: &[BranchEntry]) -> String {\n let mut prompt = String::new();\n prompt.push_str(\"You are selecting a git branch for a user query.\\\\n\");\n prompt.push_str(\"Return exactly one line in one of these formats:\\\\n\");\n prompt.push_str(\"branch:<exact branch name>\\\\n\");\n prompt.push_str(\"none\\\\n\\\\n\");\n prompt.push_str(\"Candidate branches:\\\\n\");\n\n for entry in candidates {\n let remote = if entry.is_remote { \"remote\" } else { \"local\" };\n prompt.push_str(&format!(\n \"- {} [{}] :: {}\\\\n\",\n entry.name,\n remote,\n if entry.subject.is_empty() {\n \"(no subject)\"\n } else {\n &entry.subject\n }\n ));\n }\n\n prompt.push_str(&format!(\"\\\\nUser query: {}\\\\n\", query));\n prompt.push_str(\"Answer:\");\n\n prompt\n}\n\nfn parse_ai_branch_response(response: &str, candidates: &[BranchEntry]) -> Option<String> {\n let cleaned = response.trim().trim_matches('`').trim();\n if cleaned.eq_ignore_ascii_case(\"none\") {\n return None;\n }\n\n if let Some(name) = cleaned.strip_prefix(\"branch:\") {\n let selected = name.trim();\n if candidates.iter().any(|c| c.name == selected) {\n return Some(selected.to_string());\n }\n }\n\n // Fallback: accept exact branch name response.\n if candidates.iter().any(|c| c.name == cleaned) {\n return Some(cleaned.to_string());\n }\n\n None\n}\n\nfn switch_to_entry(entry: &BranchEntry) -> Result<()> {\n if entry.is_remote {\n let (remote, branch) = entry\n .name\n .split_once('/')\n .context(\"Remote branch name is malformed\")?;\n sync::run_switch(SwitchCommand {\n branch: branch.to_string(),\n remote: Some(remote.to_string()),\n preserve: true,\n no_preserve: false,\n stash: true,\n no_stash: false,\n sync: false,\n })?;\n } else {\n sync::run_switch(SwitchCommand {\n branch: entry.name.clone(),\n remote: None,\n preserve: true,\n no_preserve: false,\n stash: true,\n no_stash: false,\n sync: false,\n })?;\n }\n\n Ok(())\n}\n\nfn git_capture(args: &[&str]) -> Result<String> {\n let output = Command::new(\"git\")\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n if !output.status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n" }, { "path": "src/changes.rs", "content": "use std::collections::BTreeMap;\nuse std::fs;\nuse std::io::{self, Read, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\nuse chrono::Utc;\nuse serde::{Deserialize, Serialize};\nuse sha2::{Digest, Sha256};\n\nuse crate::cli::{ChangesAction, ChangesCommand, DiffCommand};\nuse crate::{ai, config, env};\n\nfn trace_enabled() -> bool {\n matches!(\n std::env::var(\"FLOW_DIFF_TRACE\")\n .or_else(|_| std::env::var(\"FLOW_TRACE_DIFF\"))\n .or_else(|_| std::env::var(\"FLOW_DEBUG\"))\n .ok()\n .as_deref(),\n Some(\"1\") | Some(\"true\") | Some(\"yes\")\n )\n}\n\nfn trace(msg: &str) {\n if trace_enabled() {\n eprintln!(\"[diff] {}\", msg);\n }\n}\n\npub fn run(cmd: ChangesCommand) -> Result<()> {\n match cmd.action {\n Some(ChangesAction::CurrentDiff) => {\n print_current_diff()?;\n }\n Some(ChangesAction::Accept { diff, file }) => {\n apply_diff(diff, file)?;\n }\n None => {\n bail!(\n \"Missing changes subcommand. Use: f changes current-diff | f changes accept <diff>\"\n );\n }\n }\n Ok(())\n}\n\npub fn run_diff(cmd: DiffCommand) -> Result<()> {\n match cmd.hash {\n Some(hash) => {\n if !cmd.env.is_empty() {\n bail!(\"Env keys are only supported when creating a bundle.\");\n }\n trace(&format!(\"unroll bundle: {}\", hash));\n unroll_bundle(&hash)\n }\n None => {\n let env_keys = normalize_env_keys(&cmd.env)?;\n trace(&format!(\"create bundle (env keys: {})\", env_keys.len()));\n create_bundle(&env_keys)\n }\n }\n}\n\nfn repo_root() -> Result<PathBuf> {\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"--show-toplevel\"])\n .output()\n .context(\"failed to run git rev-parse\")?;\n if !output.status.success() {\n bail!(\"Not a git repository.\");\n }\n let root = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if root.is_empty() {\n bail!(\"Unable to resolve git root.\");\n }\n trace(&format!(\"repo root: {}\", root));\n Ok(PathBuf::from(root))\n}\n\nfn git_output_in(repo_root: &Path, args: &[&str]) -> Result<(String, bool)> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n let stdout = String::from_utf8_lossy(&output.stdout).to_string();\n let stderr = String::from_utf8_lossy(&output.stderr).to_string();\n let ok = output.status.success();\n if !ok && stdout.is_empty() {\n bail!(\"git {} failed: {}\", args.join(\" \"), stderr.trim());\n }\n Ok((stdout, ok))\n}\n\nfn git_ref_exists(repo_root: &Path, reference: &str) -> Result<bool> {\n let full_ref = format!(\"{}^{{commit}}\", reference);\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"rev-parse\", \"--verify\", &full_ref])\n .output()\n .with_context(|| format!(\"failed to verify git ref {}\", reference))?;\n Ok(output.status.success())\n}\n\nfn resolve_base_ref(repo_root: &Path) -> Result<String> {\n let candidates = [\"main\", \"origin/main\", \"master\", \"origin/master\"];\n for candidate in candidates {\n if git_ref_exists(repo_root, candidate)? {\n trace(&format!(\"base ref: {}\", candidate));\n return Ok(candidate.to_string());\n }\n }\n trace(\"base ref fallback: HEAD\");\n Ok(\"HEAD\".to_string())\n}\n\nfn list_untracked(repo_root: &Path) -> Result<Vec<String>> {\n let (status, _ok) = git_output_in(repo_root, &[\"status\", \"--porcelain\"])?;\n let mut untracked = Vec::new();\n for line in status.lines() {\n if let Some(path) = line.strip_prefix(\"?? \") {\n if !path.trim().is_empty() {\n untracked.push(path.trim().to_string());\n }\n }\n }\n Ok(untracked)\n}\n\nfn print_current_diff() -> Result<()> {\n let repo_root = repo_root()?;\n let base_ref = resolve_base_ref(&repo_root)?;\n let diff = diff_from_base(&repo_root, &base_ref)?;\n\n print!(\"{}\", diff);\n Ok(())\n}\n\nfn diff_from_base(repo_root: &Path, base_ref: &str) -> Result<String> {\n trace(&format!(\"diffing from {}\", base_ref));\n let (tracked_diff, _ok) = git_output_in(&repo_root, &[\"diff\", \"--binary\", base_ref])?;\n let mut diff = tracked_diff;\n\n for path in list_untracked(&repo_root)? {\n let (patch, _ok) = git_output_in(\n &repo_root,\n &[\"diff\", \"--no-index\", \"--binary\", \"--\", \"/dev/null\", &path],\n )?;\n diff.push_str(&patch);\n }\n\n Ok(diff)\n}\n\nfn read_diff_input(diff: Option<String>, file: Option<PathBuf>) -> Result<String> {\n if let Some(file) = file {\n return fs::read_to_string(&file)\n .with_context(|| format!(\"failed to read diff file {}\", file.display()));\n }\n\n if let Some(raw) = diff {\n if raw == \"-\" {\n return read_stdin();\n }\n let as_path = PathBuf::from(&raw);\n if as_path.exists() {\n return fs::read_to_string(&as_path)\n .with_context(|| format!(\"failed to read diff file {}\", as_path.display()));\n }\n return Ok(raw);\n }\n\n if atty::is(atty::Stream::Stdin) {\n bail!(\"No diff provided. Pass a diff string, a file path, or '-' to read stdin.\");\n }\n\n read_stdin()\n}\n\nfn read_stdin() -> Result<String> {\n let mut buffer = String::new();\n io::stdin()\n .read_to_string(&mut buffer)\n .context(\"failed to read diff from stdin\")?;\n Ok(buffer)\n}\n\nfn apply_diff(diff: Option<String>, file: Option<PathBuf>) -> Result<()> {\n let repo_root = repo_root()?;\n let content = read_diff_input(diff, file)?;\n if content.trim().is_empty() {\n bail!(\"Diff input is empty.\");\n }\n trace(&format!(\"applying diff (bytes: {})\", content.len()));\n apply_diff_content(&repo_root, &content)?;\n\n println!(\"Applied diff successfully.\");\n Ok(())\n}\n\nfn apply_diff_content(repo_root: &Path, content: &str) -> Result<()> {\n let mut child = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"apply\", \"--whitespace=fix\", \"-\"])\n .stdin(Stdio::piped())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .spawn()\n .context(\"failed to run git apply\")?;\n\n if let Some(mut stdin) = child.stdin.take() {\n stdin\n .write_all(content.as_bytes())\n .context(\"failed to write diff to git apply\")?;\n }\n\n let status = child.wait().context(\"failed to wait for git apply\")?;\n if !status.success() {\n bail!(\"git apply failed\");\n }\n\n Ok(())\n}\n\n#[derive(Debug, Serialize, Deserialize)]\nstruct DiffBundle {\n hash: String,\n version: u32,\n created_at: String,\n repo_root: String,\n #[serde(default)]\n project_name: Option<String>,\n base_ref: String,\n diff: String,\n ai_sessions: Vec<serde_json::Value>,\n #[serde(default)]\n env_target: Option<String>,\n #[serde(default)]\n env_vars: BTreeMap<String, String>,\n}\n\n#[derive(Debug, Serialize)]\nstruct DiffBundlePayload {\n version: u32,\n created_at: String,\n repo_root: String,\n project_name: Option<String>,\n base_ref: String,\n diff: String,\n ai_sessions: Vec<serde_json::Value>,\n env_target: Option<String>,\n env_vars: BTreeMap<String, String>,\n}\n\n#[derive(Debug, Serialize)]\nstruct DiffBundlePayloadV1 {\n version: u32,\n created_at: String,\n repo_root: String,\n base_ref: String,\n diff: String,\n ai_sessions: Vec<serde_json::Value>,\n}\n\n#[derive(Debug, Serialize)]\nstruct DiffBundlePayloadV2 {\n version: u32,\n created_at: String,\n repo_root: String,\n base_ref: String,\n diff: String,\n ai_sessions: Vec<serde_json::Value>,\n env_target: Option<String>,\n env_vars: BTreeMap<String, String>,\n}\n\n#[derive(Debug, Serialize, Deserialize)]\nstruct DiffStashRecord {\n stash_ref: String,\n created_at: String,\n repo_root: String,\n bundle_hash: String,\n message: String,\n}\n\nfn create_bundle(env_keys: &[String]) -> Result<()> {\n let repo_root = repo_root()?;\n let project_name = load_project_name(&repo_root)?;\n let base_ref = resolve_base_ref(&repo_root)?;\n let diff = diff_from_base(&repo_root, &base_ref)?;\n trace(&format!(\"project: {}\", project_name));\n let ai_sessions = match ai::get_sessions_for_gitedit(&repo_root) {\n Ok(sessions) => sessions\n .into_iter()\n .filter_map(|session| serde_json::to_value(session).ok())\n .collect(),\n Err(err) => {\n eprintln!(\"Warning: failed to collect AI sessions: {}\", err);\n Vec::new()\n }\n };\n let created_at = Utc::now().to_rfc3339();\n let repo_root_str = repo_root.display().to_string();\n let (env_target, env_vars) = gather_env_vars(env_keys)?;\n\n let payload = DiffBundlePayload {\n version: 3,\n created_at: created_at.clone(),\n repo_root: repo_root_str.clone(),\n project_name: Some(project_name.clone()),\n base_ref: base_ref.clone(),\n diff: diff.clone(),\n ai_sessions: ai_sessions.clone(),\n env_target: env_target.clone(),\n env_vars: env_vars.clone(),\n };\n\n let hash = bundle_hash(&payload)?;\n let bundle = DiffBundle {\n hash: hash.clone(),\n version: payload.version,\n created_at: payload.created_at,\n repo_root: payload.repo_root,\n project_name: payload.project_name,\n base_ref: payload.base_ref,\n diff: payload.diff,\n ai_sessions: payload.ai_sessions,\n env_target: payload.env_target,\n env_vars: payload.env_vars,\n };\n\n let bundle_path = write_bundle(&bundle)?;\n trace(&format!(\"bundle written: {}\", bundle_path.display()));\n\n println!(\"Diff hash: {}\", hash);\n println!(\"Project: {}\", project_name);\n println!(\"Base ref: {}\", base_ref);\n println!(\"AI sessions: {}\", ai_sessions.len());\n if !env_vars.is_empty() {\n println!(\"Env vars: {}\", env_vars.len());\n }\n println!(\"Bundle: {}\", bundle_path.display());\n println!(\"Unroll: f diff {}\", hash);\n\n Ok(())\n}\n\nfn normalize_env_keys(raw: &[String]) -> Result<Vec<String>> {\n let mut out = Vec::new();\n for item in raw {\n let trimmed = item.trim();\n if trimmed.is_empty() {\n continue;\n }\n\n if trimmed.starts_with('[') && trimmed.ends_with(']') {\n let parsed: Vec<String> =\n serde_json::from_str(trimmed).context(\"failed to parse --env JSON array\")?;\n for key in parsed {\n let key = key.trim().to_string();\n if !key.is_empty() {\n out.push(key);\n }\n }\n continue;\n }\n\n if trimmed.contains(',') {\n for key in trimmed.split(',') {\n let key = key.trim().to_string();\n if !key.is_empty() {\n out.push(key);\n }\n }\n continue;\n }\n\n out.push(trimmed.to_string());\n }\n\n out.sort();\n out.dedup();\n Ok(out)\n}\n\nfn load_project_name(repo_root: &Path) -> Result<String> {\n let flow_path = repo_root.join(\"flow.toml\");\n if !flow_path.exists() {\n bail!(\"flow.toml not found in repo root.\");\n }\n trace(&format!(\n \"reading project name from {}\",\n flow_path.display()\n ));\n let cfg = config::load(&flow_path)\n .with_context(|| format!(\"failed to read {}\", flow_path.display()))?;\n let name = cfg\n .project_name\n .ok_or_else(|| anyhow::anyhow!(\"flow.toml missing 'name'\"))?;\n Ok(name)\n}\n\nfn ensure_project_match(repo_root: &Path, bundle: &DiffBundle) -> Result<()> {\n let bundle_name = bundle.project_name.as_deref().ok_or_else(|| {\n anyhow::anyhow!(\"Diff bundle missing project name. Recreate with the latest flow.\")\n })?;\n let current_name = load_project_name(repo_root)?;\n if bundle_name != current_name {\n bail!(\n \"Project mismatch. Bundle is for '{}' but this repo is '{}'.\",\n bundle_name,\n current_name\n );\n }\n trace(&format!(\"project match: {}\", current_name));\n Ok(())\n}\n\nfn gather_env_vars(keys: &[String]) -> Result<(Option<String>, BTreeMap<String, String>)> {\n if keys.is_empty() {\n return Ok((None, BTreeMap::new()));\n }\n\n let vars = read_personal_local_env(keys)?;\n if vars.is_empty() {\n eprintln!(\"Warning: no matching env vars found in local store.\");\n return Ok((Some(\"personal\".to_string()), BTreeMap::new()));\n }\n\n let missing: Vec<_> = keys\n .iter()\n .filter(|key| !vars.contains_key(*key))\n .cloned()\n .collect();\n if !missing.is_empty() {\n eprintln!(\"Warning: missing env vars: {}\", missing.join(\", \"));\n }\n trace(&format!(\"env keys bundled: {}\", vars.len()));\n\n Ok((Some(\"personal\".to_string()), vars))\n}\n\nfn read_personal_local_env(keys: &[String]) -> Result<BTreeMap<String, String>> {\n let path = local_env_path(\"personal\")?;\n trace(&format!(\"reading local env: {}\", path.display()));\n if !path.exists() {\n return Ok(BTreeMap::new());\n }\n\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let vars = env::parse_env_file(&content);\n\n if keys.is_empty() {\n return Ok(vars.into_iter().collect());\n }\n\n let mut filtered = BTreeMap::new();\n for key in keys {\n if let Some(value) = vars.get(key) {\n filtered.insert(key.clone(), value.clone());\n }\n }\n\n Ok(filtered)\n}\n\nfn unroll_bundle(id: &str) -> Result<()> {\n let (bundle, source_path) = read_bundle(id)?;\n let repo_root = repo_root()?;\n ensure_project_match(&repo_root, &bundle)?;\n let output_dir = repo_root.join(\".ai\").join(\"diffs\").join(&bundle.hash);\n fs::create_dir_all(&output_dir)?;\n\n let diff_path = output_dir.join(\"diff.patch\");\n fs::write(&diff_path, &bundle.diff)\n .with_context(|| format!(\"failed to write {}\", diff_path.display()))?;\n\n let sessions_path = output_dir.join(\"sessions.json\");\n let sessions_json = serde_json::to_string_pretty(&bundle.ai_sessions)\n .context(\"failed to serialize AI sessions\")?;\n fs::write(&sessions_path, sessions_json)\n .with_context(|| format!(\"failed to write {}\", sessions_path.display()))?;\n\n let meta = serde_json::json!({\n \"hash\": bundle.hash,\n \"version\": bundle.version,\n \"created_at\": bundle.created_at,\n \"repo_root\": bundle.repo_root,\n \"base_ref\": bundle.base_ref,\n \"session_count\": bundle.ai_sessions.len(),\n \"env_count\": bundle.env_vars.len(),\n \"diff_bytes\": bundle.diff.as_bytes().len(),\n \"source_bundle\": source_path.as_ref().map(|p| p.display().to_string()),\n });\n let meta_path = output_dir.join(\"meta.json\");\n fs::write(&meta_path, serde_json::to_string_pretty(&meta)?)\n .with_context(|| format!(\"failed to write {}\", meta_path.display()))?;\n trace(&format!(\"unroll output: {}\", output_dir.display()));\n\n let stash_ref = stash_if_dirty(&repo_root, &bundle.hash)?;\n if let Err(err) = apply_diff_content(&repo_root, &bundle.diff) {\n if let Some(stash_ref) = stash_ref {\n eprintln!(\n \"Diff apply failed. Your previous state is stashed: {}\",\n stash_ref\n );\n }\n return Err(err);\n }\n\n if !bundle.env_vars.is_empty() {\n apply_env_vars(&bundle)?;\n }\n\n println!(\"Unrolled diff {} -> {}\", bundle.hash, output_dir.display());\n if let Some(path) = source_path {\n println!(\"Source bundle: {}\", path.display());\n }\n if let Some(stash_ref) = stash_ref {\n println!(\"Stashed previous state: {}\", stash_ref);\n println!(\"Restore: git stash pop {}\", stash_ref);\n }\n\n Ok(())\n}\n\nfn bundle_hash(payload: &DiffBundlePayload) -> Result<String> {\n let bytes = serde_json::to_vec(payload).context(\"failed to serialize diff bundle\")?;\n let mut hasher = Sha256::new();\n hasher.update(bytes);\n let digest = hasher.finalize();\n Ok(hex::encode(digest))\n}\n\nfn bundle_hash_v1(payload: &DiffBundlePayloadV1) -> Result<String> {\n let bytes = serde_json::to_vec(payload).context(\"failed to serialize diff bundle\")?;\n let mut hasher = Sha256::new();\n hasher.update(bytes);\n let digest = hasher.finalize();\n Ok(hex::encode(digest))\n}\n\nfn bundle_hash_v2(payload: &DiffBundlePayloadV2) -> Result<String> {\n let bytes = serde_json::to_vec(payload).context(\"failed to serialize diff bundle\")?;\n let mut hasher = Sha256::new();\n hasher.update(bytes);\n let digest = hasher.finalize();\n Ok(hex::encode(digest))\n}\n\nfn bundle_dir() -> Result<PathBuf> {\n let config_dir = config::ensure_global_config_dir()?;\n let diffs_dir = config_dir.join(\"diffs\");\n fs::create_dir_all(&diffs_dir)?;\n trace(&format!(\"bundle dir: {}\", diffs_dir.display()));\n Ok(diffs_dir)\n}\n\nfn write_bundle(bundle: &DiffBundle) -> Result<PathBuf> {\n let diffs_dir = bundle_dir()?;\n let path = diffs_dir.join(format!(\"{}.json\", bundle.hash));\n let payload = serde_json::to_string_pretty(bundle).context(\"failed to serialize bundle\")?;\n fs::write(&path, payload).with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(path)\n}\n\nfn read_bundle(id: &str) -> Result<(DiffBundle, Option<PathBuf>)> {\n let candidate = PathBuf::from(id);\n let path = if candidate.exists() {\n candidate\n } else {\n bundle_dir()?.join(format!(\"{}.json\", id))\n };\n\n if !path.exists() {\n trace(&format!(\"bundle lookup failed: {}\", path.display()));\n bail!(\n \"Diff bundle not found. Expected {} or pass a path to a bundle file.\",\n path.display()\n );\n }\n\n trace(&format!(\"bundle read: {}\", path.display()));\n let data =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let bundle: DiffBundle = serde_json::from_str(&data)\n .with_context(|| format!(\"failed to parse {}\", path.display()))?;\n\n let expected = if bundle.version <= 1 {\n let payload = DiffBundlePayloadV1 {\n version: bundle.version,\n created_at: bundle.created_at.clone(),\n repo_root: bundle.repo_root.clone(),\n base_ref: bundle.base_ref.clone(),\n diff: bundle.diff.clone(),\n ai_sessions: bundle.ai_sessions.clone(),\n };\n bundle_hash_v1(&payload)?\n } else if bundle.version == 2 {\n let payload = DiffBundlePayloadV2 {\n version: bundle.version,\n created_at: bundle.created_at.clone(),\n repo_root: bundle.repo_root.clone(),\n base_ref: bundle.base_ref.clone(),\n diff: bundle.diff.clone(),\n ai_sessions: bundle.ai_sessions.clone(),\n env_target: bundle.env_target.clone(),\n env_vars: bundle.env_vars.clone(),\n };\n bundle_hash_v2(&payload)?\n } else {\n let payload = DiffBundlePayload {\n version: bundle.version,\n created_at: bundle.created_at.clone(),\n repo_root: bundle.repo_root.clone(),\n project_name: bundle.project_name.clone(),\n base_ref: bundle.base_ref.clone(),\n diff: bundle.diff.clone(),\n ai_sessions: bundle.ai_sessions.clone(),\n env_target: bundle.env_target.clone(),\n env_vars: bundle.env_vars.clone(),\n };\n bundle_hash(&payload)?\n };\n if expected != bundle.hash {\n eprintln!(\n \"Warning: bundle hash mismatch (expected {}, got {}).\",\n expected, bundle.hash\n );\n }\n\n Ok((bundle, Some(path)))\n}\n\nfn apply_env_vars(bundle: &DiffBundle) -> Result<()> {\n let target = bundle.env_target.as_deref().unwrap_or(\"personal\");\n let path = local_env_path(target)?;\n\n let mut vars: BTreeMap<String, String> = if path.exists() {\n let content = fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n env::parse_env_file(&content).into_iter().collect()\n } else {\n BTreeMap::new()\n };\n\n for (key, value) in &bundle.env_vars {\n vars.insert(key.clone(), value.clone());\n }\n\n write_local_env(&path, target, \"production\", &vars)?;\n println!(\n \"Applied {} env var(s) to {}\",\n bundle.env_vars.len(),\n path.display()\n );\n Ok(())\n}\n\nfn local_env_path(target: &str) -> Result<PathBuf> {\n let config_dir = config::ensure_global_config_dir()?;\n let dir = config_dir\n .join(\"env-local\")\n .join(sanitize_env_segment(target));\n fs::create_dir_all(&dir)?;\n Ok(dir.join(\"production.env\"))\n}\n\nfn stash_log_path() -> Result<PathBuf> {\n let config_dir = config::ensure_global_config_dir()?;\n let dir = config_dir.join(\"diffs\");\n fs::create_dir_all(&dir)?;\n Ok(dir.join(\"stashes.json\"))\n}\n\nfn record_stash(repo_root: &Path, stash_ref: &str, bundle_hash: &str, message: &str) -> Result<()> {\n let path = stash_log_path()?;\n let mut records: Vec<DiffStashRecord> = if path.exists() {\n match fs::read_to_string(&path) {\n Ok(raw) => serde_json::from_str(&raw).unwrap_or_default(),\n Err(_) => Vec::new(),\n }\n } else {\n Vec::new()\n };\n\n records.push(DiffStashRecord {\n stash_ref: stash_ref.to_string(),\n created_at: Utc::now().to_rfc3339(),\n repo_root: repo_root.display().to_string(),\n bundle_hash: bundle_hash.to_string(),\n message: message.to_string(),\n });\n\n let payload = serde_json::to_string_pretty(&records)?;\n fs::write(&path, payload).with_context(|| format!(\"failed to write {}\", path.display()))?;\n trace(&format!(\"recorded stash: {}\", stash_ref));\n Ok(())\n}\n\nfn sanitize_env_segment(value: &str) -> String {\n let mut out = String::new();\n let mut last_sep = false;\n for ch in value.chars() {\n if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || ch == '.' {\n out.push(ch);\n last_sep = false;\n } else if !last_sep {\n out.push('_');\n last_sep = true;\n }\n }\n let trimmed = out.trim_matches('_').to_string();\n if trimmed.is_empty() {\n \"unnamed\".to_string()\n } else {\n trimmed\n }\n}\n\nfn write_local_env(\n path: &Path,\n target: &str,\n environment: &str,\n vars: &BTreeMap<String, String>,\n) -> Result<()> {\n let keys: Vec<_> = vars.keys().collect();\n\n let mut content = String::new();\n content.push_str(&format!(\n \"# Local env store (flow)\\n# Target: {}\\n# Environment: {}\\n\",\n target, environment\n ));\n for key in keys {\n let value = &vars[key];\n let escaped = value.replace('\\\\', \"\\\\\\\\\").replace('\"', \"\\\\\\\"\");\n content.push_str(&format!(\"{key}=\\\"{escaped}\\\"\\n\"));\n }\n\n fs::write(path, content).with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(())\n}\n\nfn stash_if_dirty(repo_root: &Path, bundle_hash: &str) -> Result<Option<String>> {\n let (status, _ok) = git_output_in(repo_root, &[\"status\", \"--porcelain\"])?;\n if status.trim().is_empty() {\n trace(\"working tree clean; no stash needed\");\n return Ok(None);\n }\n\n let message = format!(\n \"flow-diff-{}-{}\",\n &bundle_hash[..bundle_hash.len().min(8)],\n Utc::now().format(\"%Y%m%d-%H%M%S\")\n );\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"stash\", \"push\", \"-u\", \"-m\", &message])\n .output()\n .context(\"failed to stash working tree\")?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"failed to stash working tree: {}\", stderr.trim());\n }\n\n let (stash_ref, _ok) = git_output_in(repo_root, &[\"stash\", \"list\", \"-1\", \"--pretty=%gd\"])?;\n let stash_ref = stash_ref.trim().to_string();\n if stash_ref.is_empty() {\n return Ok(Some(message));\n }\n\n record_stash(repo_root, &stash_ref, bundle_hash, &message)?;\n Ok(Some(stash_ref))\n}\n" }, { "path": "src/cli.rs", "content": "use clap::{Args, Parser, Subcommand, ValueEnum};\nuse std::{net::IpAddr, path::PathBuf};\n\nuse crate::commit::ReviewModelArg;\n\n/// Command line interface for the flow daemon / CLI hybrid.\n#[derive(Parser, Debug)]\n#[command(\n name = \"flow\",\n version = version_with_build_time(),\n about = \"Your second OS\",\n subcommand_required = false,\n arg_required_else_help = false\n)]\npub struct Cli {\n #[command(subcommand)]\n pub command: Option<Commands>,\n\n /// Output all commands in machine-readable JSON format for external tools.\n #[arg(long, global = true)]\n pub help_full: bool,\n}\n\n/// Returns version string with relative build time (e.g., \"0.1.0 (built 5m ago)\")\nfn version_with_build_time() -> &'static str {\n use std::sync::OnceLock;\n static VERSION: OnceLock<String> = OnceLock::new();\n\n // Include the generated timestamp file to force recompilation when it changes\n const BUILD_TIMESTAMP_STR: &str =\n include_str!(concat!(env!(\"OUT_DIR\"), \"/build_timestamp.txt\"));\n\n VERSION.get_or_init(|| {\n let version = env!(\"CARGO_PKG_VERSION\");\n let build_timestamp: u64 = BUILD_TIMESTAMP_STR.trim().parse().unwrap_or(0);\n\n if build_timestamp == 0 {\n return version.to_string();\n }\n\n let now = std::time::SystemTime::now()\n .duration_since(std::time::UNIX_EPOCH)\n .map(|d| d.as_secs())\n .unwrap_or(0);\n\n let elapsed = now.saturating_sub(build_timestamp);\n let relative = format_relative_time(elapsed);\n\n format!(\"{version} (built {relative})\")\n })\n}\n\nfn format_relative_time(seconds: u64) -> String {\n if seconds < 60 {\n format!(\"{}s ago\", seconds)\n } else if seconds < 3600 {\n format!(\"{}m ago\", seconds / 60)\n } else if seconds < 86400 {\n let hours = seconds / 3600;\n format!(\"{}h ago\", hours)\n } else {\n let days = seconds / 86400;\n format!(\"{}d ago\", days)\n }\n}\n\n#[derive(Subcommand, Debug)]\npub enum Commands {\n #[command(\n about = \"Fuzzy search global commands/tasks without a project flow.toml.\",\n long_about = \"Browse global commands and tasks from your global flow config (e.g., ~/.config/flow/flow.toml). Useful when you are outside a project directory.\",\n alias = \"s\"\n )]\n Search,\n #[command(\n about = \"Run tasks from the global flow config.\",\n long_about = \"Run tasks defined in ~/.config/flow/flow.toml without project discovery.\",\n alias = \"g\"\n )]\n Global(GlobalCommand),\n #[command(\n about = \"Ensure the background hub daemon is running (spawns it if missing).\",\n long_about = \"Checks the /health endpoint on the configured host/port (defaults to 127.0.0.1:9050). If unreachable, a daemon is launched in the background using the lin runtime recorded via `lin register` (or PATH), then a TUI opens so you can inspect managed servers and aggregated logs.\"\n )]\n Hub(HubCommand),\n #[command(\n about = \"Scaffold a new flow.toml in the current directory.\",\n long_about = \"Creates a starter flow.toml with stub tasks (setup, dev) so you can fill in commands later.\"\n )]\n Init(InitOpts),\n #[command(\n about = \"Output shell integration script.\",\n long_about = \"Prints shell wrapper functions for commands like `f new` that need to cd. Add `eval (f shell-init fish)` to your fish config.\"\n )]\n ShellInit(ShellInitOpts),\n #[command(\n about = \"Manage shell integration.\",\n long_about = \"Helper commands for shell integration like refreshing the current session.\"\n )]\n Shell(ShellCommand),\n #[command(\n about = \"Create a new project from a template.\",\n long_about = \"Create a new project from ~/new/<template>. Path resolution:\\n f new <template> → ./<template>\\n f new <template> zerg → ~/code/zerg\\n f new <template> ./foo → ./foo\\n f new <template> ~/path → ~/path\"\n )]\n New(NewOpts),\n #[command(\n about = \"Home setup and config repo management.\",\n long_about = \"Set up your home environment or clone a GitHub config repo into ~/config, optionally pulling an internal repo into ~/config/i, then applying symlinked configs.\"\n )]\n Home(HomeCommand),\n #[command(\n about = \"Archive the current project to ~/archive/code.\",\n long_about = \"Copies the current project into ~/archive/code/<project>-<message> so you can keep a snapshot outside git history.\"\n )]\n Archive(ArchiveOpts),\n #[command(\n about = \"Verify required tools and shell integrations.\",\n long_about = \"Checks for flox (for managed deps), lin (hub helper), and direnv + shell hook presence.\"\n )]\n Doctor(DoctorOpts),\n #[command(\n about = \"Ensure your system matches Flow's expectations.\",\n long_about = \"Enforces fish shell, installs flow shell integration, and runs doctor checks.\"\n )]\n Health(HealthOpts),\n #[command(\n about = \"Check project invariants from flow.toml against working tree or staged changes.\",\n alias = \"inv\"\n )]\n Invariants(InvariantsOpts),\n #[command(\n about = \"Fuzzy search task history or list available tasks.\",\n long_about = \"Search through previously run tasks (most recent first) or list project tasks from flow.toml plus AI MoonBit tasks under .ai/tasks/*.mbt.\"\n )]\n Tasks(TasksCommand),\n #[command(\n about = \"Run an AI task via the low-latency fast client path.\",\n long_about = \"Dispatches AI task selectors through the fast daemon client when available (fai / ai-taskd-client), with safe fallback to Flow daemon execution.\"\n )]\n Fast(FastRunOpts),\n #[command(\n about = \"Bring a project up using lifecycle conventions.\",\n long_about = \"Runs optional local-domain setup from [lifecycle.domains], then runs the project up task. By default it tries task 'up', then falls back to 'dev'.\"\n )]\n Up(LifecycleRunOpts),\n #[command(\n about = \"Bring a project down using lifecycle conventions.\",\n long_about = \"Runs the project down task (default 'down'), then optional lifecycle domain teardown.\"\n )]\n Down(LifecycleRunOpts),\n #[command(\n about = \"Create a local AI scratch test file under .ai/test.\",\n long_about = \"Creates a gitignored test scaffold under .ai/test for fast AI-generated validation tests. Intended for local iteration without polluting tracked test suites.\"\n )]\n AiTestNew(AiTestNewOpts),\n /// Execute a specific project task (hidden; used by the palette and task shortcuts).\n #[command(hide = true)]\n Run(TaskRunOpts),\n /// Invoke tasks directly via `f <task>` without typing `run`.\n #[command(external_subcommand)]\n TaskShortcut(Vec<String>),\n #[command(about = \"Show the last task input and its output/error.\")]\n LastCmd,\n #[command(about = \"Show the last task run (command, status, and output) recorded by flow.\")]\n LastCmdFull,\n #[command(about = \"Show the last fish shell command and output (from fish io-trace).\")]\n FishLast,\n #[command(about = \"Show full details of the last fish shell command.\")]\n FishLastFull,\n #[command(about = \"Install traced fish shell (fish fork with always-on I/O tracing).\")]\n FishInstall(FishInstallOpts),\n #[command(about = \"Re-run the last task executed in this project.\")]\n Rerun(RerunOpts),\n #[command(\n about = \"List running flow processes for the current project.\",\n long_about = \"Lists flow-started processes tracked for this project. Use --all to see processes across all projects.\"\n )]\n Ps(ProcessOpts),\n #[command(\n about = \"Stop running flow processes.\",\n long_about = \"Kill flow-started processes by task name, PID, or all for the project. Sends SIGTERM first, then SIGKILL after timeout.\"\n )]\n Kill(KillOpts),\n #[command(\n about = \"View logs from running or recent tasks.\",\n long_about = \"Tail the log output of a running task. Use -f to follow in real-time.\"\n )]\n Logs(TaskLogsOpts),\n #[command(\n about = \"Quick traces for AI + task runs from jazz2 state.\",\n long_about = \"Print recent AI agent events and Flow task runs stored in the shared jazz2 state. Use --follow to stream.\",\n alias = \"traces\"\n )]\n Trace(TraceCommand),\n #[command(\n about = \"Manage anonymous usage analytics preferences and local queue.\",\n long_about = \"Inspect, enable/disable, export, or purge local anonymous usage analytics events.\"\n )]\n Analytics(AnalyticsCommand),\n #[command(\n about = \"List registered projects.\",\n long_about = \"Shows all projects that have been registered (projects with a 'name' field in flow.toml).\"\n )]\n Projects,\n #[command(\n about = \"Fuzzy search AI sessions across all projects and copy context.\",\n long_about = \"Browse AI sessions (Claude, Codex, Cursor) across all projects. On selection, copies the session context since last checkpoint to clipboard for passing to another session.\",\n alias = \"ss\"\n )]\n Sessions(SessionsOpts),\n #[command(\n about = \"Show or set the active project.\",\n long_about = \"The active project is used as a fallback for commands like `f logs` when not in a project directory.\"\n )]\n Active(ActiveOpts),\n #[command(\n about = \"Start the flow HTTP server for log ingestion and queries.\",\n long_about = \"Runs an HTTP server with endpoints for log ingestion (/logs/ingest) and queries (/logs/query).\\n\\nAlso provides a lightweight PR edit watcher for ~/.flow/pr-edit:\\n GET /pr-edit/status\\n POST /pr-edit/rescan\"\n )]\n Server(ServerOpts),\n #[command(\n about = \"Open the Flow web UI for this project.\",\n long_about = \"Serves the .ai/web UI and project metadata (including OpenAPI when available), then opens it in your browser.\"\n )]\n Web(WebOpts),\n #[command(\n about = \"Match a natural language query to a task using LM Studio.\",\n long_about = \"Uses a local LM Studio model to intelligently match your query to an available task. Requires LM Studio running on localhost:1234 (or custom port).\",\n alias = \"m\"\n )]\n Match(MatchOpts),\n #[command(\n about = \"Ask the AI server to suggest a task or Flow command.\",\n long_about = \"Uses the local AI server (zerg/ai) to match your query to a flow.toml task or a Flow CLI command you can run.\",\n alias = \"a\"\n )]\n Ask(AskOpts),\n #[command(\n about = \"List and search git branches quickly.\",\n long_about = \"Fast branch discovery for local + remote branches. Supports lexical search and AI-assisted natural-language matching via the local AI server (zerg/ai).\",\n alias = \"br\"\n )]\n Branches(BranchesCommand),\n #[command(\n about = \"AI-powered commit with code review and optional GitEdit sync.\",\n long_about = \"Stages all changes (or only paths passed via --path), commits quickly by default, starts deferred Codex deep review in the background, and syncs AI sessions to gitedit.dev when enabled in global config. Use --slow to run blocking review before commit.\",\n alias = \"c\"\n )]\n Commit(CommitOpts),\n #[command(\n about = \"Manage the commit review queue.\",\n long_about = \"List, inspect, approve, or drop queued commits before they push to remote.\",\n alias = \"cq\"\n )]\n CommitQueue(CommitQueueCommand),\n #[command(\n about = \"Manage deferred deep-review todos for queued commits.\",\n long_about = \"Workflow-friendly wrapper around commit queue reviews. Use `codex --all` to run deep Codex reviews across pending commits, then approve after issues are addressed.\",\n alias = \"rt\"\n )]\n ReviewsTodo(ReviewsTodoCommand),\n #[command(\n about = \"Create a GitHub PR from current changes or a queued commit.\",\n long_about = \"By default, stages and commits current changes (or only paths passed via --path) into the queue, then creates/updates a GitHub PR for the latest queued commit. Use --no-commit to skip committing and create a PR from an existing queued commit.\\n\\nSpecial:\\n `f pr open` opens the PR for the current branch (or falls back to the queued commit).\\n `f pr open edit` opens a local markdown editor file and syncs PR title/body on save.\\n `f pr feedback [<number|url>] [--todo]` fetches review comments/reviews and can store them as local todos.\"\n )]\n Pr(PrOpts),\n #[command(\n about = \"Manage personal tooling ignore policy across repos.\",\n long_about = \"Audit and clean personal tooling ignore patterns from project .gitignore files. This helps keep external repositories free of local-only patterns like .beads/ and .rise/.\"\n )]\n Gitignore(GitignoreCommand),\n #[command(\n about = \"Legacy recipe command (prefer task-centric .ai/tasks/.mbt).\",\n long_about = \"Legacy compatibility command for recipe files. Prefer task-centric workflows with flow.toml tasks + .ai/tasks/*.mbt.\",\n hide = true\n )]\n Recipe(RecipeCommand),\n #[command(\n about = \"Open queued commits for review in Rise.\",\n long_about = \"Open the latest queued commit (or a specific one in the future) in Rise's review UI.\",\n alias = \"rv\"\n )]\n Review(ReviewCommand),\n #[command(\n about = \"Simple AI commit without code review.\",\n long_about = \"Stages all changes (or only paths passed via --path), uses OpenAI to generate a commit message from the diff, commits, and pushes. No code review.\",\n visible_alias = \"commitSimple\",\n hide = true\n )]\n CommitSimple(CommitOpts),\n #[command(\n about = \"AI commit with code review (GitEdit sync honors config).\",\n long_about = \"Like 'commit' but without forcing gitedit.dev sync; respects the global gitedit setting.\",\n alias = \"cc\",\n visible_alias = \"commitWithCheck\",\n hide = true\n )]\n CommitWithCheck(CommitOpts),\n #[command(\n about = \"Undo the last undoable action (commit, push).\",\n long_about = \"Reverts the last recorded action. For commits, resets with --soft to keep changes staged. For pushes, force pushes the previous state.\",\n alias = \"u\"\n )]\n Undo(UndoCommand),\n #[command(\n about = \"Fix issues in the repo with help from Hive.\",\n long_about = \"Optionally unroll the last commit, then run a Hive agent to fix the issue (e.g., leaked secrets).\"\n )]\n Fix(FixOpts),\n #[command(\n about = \"Fix common TOML syntax errors in flow.toml.\",\n long_about = \"Automatically fixes common issues in flow.toml that can break parsing, such as invalid escape sequences (\\\\$, \\\\n in basic strings), unclosed quotes, and other TOML syntax errors.\"\n )]\n Fixup(FixupOpts),\n #[command(\n about = \"Share or apply git diffs without remotes.\",\n long_about = \"Print the current git diff for sharing or apply a diff string/file to this repo. Useful when git pull/push isn't available.\"\n )]\n Changes(ChangesCommand),\n #[command(\n about = \"Create or unpack a shareable diff bundle.\",\n long_about = \"Generates a diff against the main branch (including untracked files) plus AI sessions, stores it by hash, or unrolls a stored bundle by hash.\"\n )]\n Diff(DiffCommand),\n #[command(\n about = \"Hash files or sessions with unhash and copy a share link.\",\n long_about = \"Runs the unhash CLI, then copies unstash./<hash> to clipboard and prints the hash/link.\"\n )]\n Hash(HashOpts),\n #[command(\n about = \"Manage background daemons (start, stop, status).\",\n long_about = \"Start, stop, and monitor background daemons defined in flow.toml. Daemons are long-running processes like sync servers, API servers, or file watchers.\",\n alias = \"d\"\n )]\n Daemon(DaemonCommand),\n #[command(\n about = \"Run the Flow supervisor (daemon manager).\",\n long_about = \"Starts or checks the Flow supervisor, which manages background daemons via IPC.\"\n )]\n Supervisor(SupervisorCommand),\n #[command(\n about = \"Manage AI coding sessions (Claude Code).\",\n long_about = \"Track, list, and resume Claude Code sessions for the current project. Sessions are stored in .ai/sessions/claude/ and can be named for easy recall.\"\n )]\n Ai(AiCommand),\n #[command(about = \"Start or continue Codex session.\", alias = \"cx\")]\n Codex {\n #[command(subcommand)]\n action: Option<ProviderAiAction>,\n },\n #[command(\n about = \"Read Cursor agent transcripts for this project.\",\n alias = \"cu\"\n )]\n Cursor {\n #[command(subcommand)]\n action: Option<ProviderAiAction>,\n },\n #[command(about = \"Start or continue Claude session.\", alias = \"cl\")]\n Claude {\n #[command(subcommand)]\n action: Option<ProviderAiAction>,\n },\n #[command(\n about = \"Manage project env vars and cloud sync.\",\n long_about = \"With no arguments, lists project env vars for the current environment. Use subcommands to manage env vars via the cloud backend or run the sync workflow.\"\n )]\n Env(EnvCommand),\n #[command(\n about = \"Fetch one-time passwords from 1Password Connect.\",\n long_about = \"Uses OP_CONNECT_HOST + OP_CONNECT_TOKEN (from env or Flow personal env store) to fetch an item TOTP.\"\n )]\n Otp(OtpCommand),\n #[command(\n about = \"Authenticate Flow AI via myflow.\",\n long_about = \"Starts a device auth flow for myflow, storing a token for AI-powered CLI features.\"\n )]\n Auth(AuthOpts),\n #[command(\n about = \"Onboard third-party services (Stripe, etc.) with guided env setup.\",\n long_about = \"Guided setup flows for external services. Prompts for required env vars, stores them in the cloud backend, and can apply them to Cloudflare.\"\n )]\n Services(ServicesCommand),\n #[command(\n about = \"Manage macOS launch agents and daemons.\",\n long_about = \"List, audit, enable, and disable macOS launchd services. Helps keep your startup clean by identifying bloatware and unwanted background processes.\"\n )]\n Macos(MacosCommand),\n #[command(\n about = \"Manage SSH keys via the cloud backend.\",\n long_about = \"Generate, store, and unlock SSH keys stored in cloud personal env vars, then wire git to use the Flow SSH agent.\"\n )]\n Ssh(SshCommand),\n #[command(\n about = \"Manage project todos.\",\n long_about = \"Create, list, edit, and complete lightweight todos stored in .ai/todos/todos.json. With no arguments, opens the per-project Bike outliner stored in .ai/todos/<project>.bike.\"\n )]\n Todo(TodoCommand),\n #[command(\n about = \"Copy an external dependency into ext/ and ignore it.\",\n long_about = \"Copies a directory into <project>/ext/<name> and adds ext/ to .gitignore.\"\n )]\n Ext(ExtCommand),\n #[command(\n about = \"Manage Codex skills (.ai/skills/).\",\n long_about = \"Create, list, and manage Codex skills for this project. Skills are stored in .ai/skills/ (gitignored by default) and help Codex understand project-specific workflows.\"\n )]\n Skills(SkillsCommand),\n #[command(\n about = \"Inspect a URL into a thin, AI-friendly summary.\",\n long_about = \"Fetches and normalizes a URL with Cloudflare Browser Rendering markdown first when configured, then the local scraper backend, then a direct fetch fallback. Defaults to a compact summary so it can be safely pasted into AI sessions.\"\n )]\n Url(UrlCommand),\n #[command(\n about = \"Install or update project dependencies.\",\n long_about = \"Detects the package manager from lockfiles and runs install/update at the project root.\"\n )]\n Deps(DepsCommand),\n #[command(\n name = \"db\",\n about = \"Manage databases (Jazz, Postgres).\",\n long_about = \"Provision database backends and run database workflows (Jazz worker accounts, Postgres migrations). Defaults are tuned for Planetscale Postgres.\"\n )]\n Db(DbCommand),\n #[command(\n about = \"Manage AI tools (.ai/tools/*.ts).\",\n long_about = \"Create, list, and run TypeScript tools via Bun. Tools are fast, reusable scripts stored in .ai/tools/. Use 'codify' to generate tools from natural language.\",\n alias = \"t\"\n )]\n Tools(ToolsCommand),\n #[command(\n about = \"Send a proposal notification to Lin for approval.\",\n long_about = \"Sends a proposal to the Lin app widget for user approval. Used for human-in-the-loop AI workflows.\"\n )]\n Notify(NotifyCommand),\n #[command(\n about = \"Browse and analyze git commits with AI session metadata.\",\n long_about = \"Fuzzy search through git commits, showing attached AI sessions and review metadata. Supports notable commits and quick actions.\"\n )]\n Commits(CommitsCommand),\n #[command(\n name = \"seq-rpc\",\n about = \"Call seqd RPC v1 via native Rust client.\",\n long_about = \"Sends typed JSON RPC requests over Unix socket directly to seqd. Use this for OS-level automation integration without shelling out to `seq rpc`.\"\n )]\n SeqRpc(SeqRpcCommand),\n #[command(\n name = \"explain-commits\",\n about = \"Generate AI explanations for recent commits.\",\n long_about = \"Uses AI to generate markdown summaries for git commits. Writes one file per commit to docs/commits/ by default (local generated output). Skips already-processed commits unless --force is used.\"\n )]\n ExplainCommits(ExplainCommitsCommand),\n #[command(\n about = \"Bootstrap project and run setup task or aliases.\",\n long_about = \"Bootstraps the project if needed, creates flow.toml when missing, then runs the 'setup' task or prints shell aliases.\"\n )]\n Setup(SetupOpts),\n #[command(\n about = \"Invoke gen AI agents.\",\n long_about = \"Run gen agents with prompts. Supports project and global agents. Special: flow (flow-aware).\",\n alias = \"ag\"\n )]\n Agents(AgentsCommand),\n #[command(\n about = \"Manage and run hive agents.\",\n long_about = \"Hive agents are MoonBit-powered AI agents with tool use. Agents can be project-local (.flow/agents/) or global (~/.hive/agents/).\",\n alias = \"h\"\n )]\n Hive(HiveCommand),\n #[command(\n about = \"Sync git repo: pull + upstream merge (push optional).\",\n long_about = \"Comprehensive git sync: pulls from tracking/default remote and merges/rebases upstream changes when configured. Use --push to push to the configured git remote (defaults to origin).\"\n )]\n Sync(SyncCommand),\n #[command(\n about = \"Checkout a GitHub PR safely.\",\n long_about = \"Checks out a pull request by URL/number/branch via GitHub CLI. By default, auto-stashes local changes before checkout and restores them after. Also imports git refs into jj when available.\"\n )]\n Checkout(CheckoutCommand),\n #[command(\n about = \"Switch to a branch and align upstream tracking.\",\n long_about = \"Switches to a target branch (creating it from upstream/origin when needed), updates flow upstream tracking for that branch, and imports git changes into jj when present. Accepts branch names, PR numbers (for example: 123 or #123), and GitHub PR URLs.\"\n )]\n Switch(SwitchCommand),\n #[command(\n about = \"Push current branch to a configured private mirror remote.\",\n long_about = \"Pushes the current branch to a private mirror remote (typically on GitHub). When the repo is a read-only clone (origin == upstream), Flow can repoint origin to your mirror based on FLOW_PUSH_OWNER (or --owner) and push there.\"\n )]\n Push(PushCommand),\n #[command(\n about = \"Show JJ workflow status optimized for stacked home-branch work.\",\n long_about = \"Displays the current JJ workspace, home branch, intake branch, trunk relation, leaf branches, and the working-copy summary. This is intended to replace a raw `jj st` for repos that use a persistent home branch plus review/codex workspaces.\",\n alias = \"st\"\n )]\n Status(StatusOpts),\n #[command(\n about = \"Jujutsu (jj) workflow helpers.\",\n long_about = \"Initialize jj, manage workspaces/bookmarks, and sync with git remotes in a safe, structured flow.\"\n )]\n Jj(JjCommand),\n #[command(\n about = \"Repair git state (abort rebase/merge, leave detached HEAD).\",\n long_about = \"Aborts in-progress git operations (rebase, merge, cherry-pick, revert), resets bisect, and checks out the target branch if HEAD is detached.\"\n )]\n GitRepair(GitRepairOpts),\n #[command(\n about = \"Show project information.\",\n long_about = \"Display project details including git remotes, upstream configuration, and flow.toml settings.\",\n alias = \"i\"\n )]\n Info,\n #[command(\n about = \"Manage upstream fork workflow.\",\n long_about = \"Set up and manage upstream forks. Creates a local 'upstream' branch to cleanly track the original repo, making merges easier.\"\n )]\n Upstream(UpstreamCommand),\n #[command(\n about = \"Deploy project to host or cloud platform.\",\n long_about = \"Deploy your project to a Linux host (via SSH), Cloudflare Workers, or Railway. Automatically detects platform from flow.toml [host], [cloudflare], or [railway] sections.\"\n )]\n Deploy(DeployCommand),\n #[command(\n about = \"Deploy to production using flow.toml deploy config.\",\n long_about = \"Deploys using flow.toml [host], [cloudflare], [railway], or [web] configuration and skips [flow].deploy_task. If a deploy-prod or prod task exists, it will run that task instead.\",\n alias = \"production\"\n )]\n Prod(DeployCommand),\n #[command(\n about = \"Publish project to gitedit.dev or GitHub.\",\n long_about = \"Publish the current project. Without a subcommand, shows a fuzzy picker to choose the target.\"\n )]\n Publish(PublishCommand),\n #[command(\n about = \"Clone a repository into the current directory (git clone style).\",\n long_about = \"Clones into the current working directory by default, matching git clone destination behavior. GitHub inputs are normalized to SSH URLs.\"\n )]\n Clone(CloneOpts),\n #[command(\n about = \"Clone repositories into a structured local directory.\",\n long_about = \"Clone repositories into ~/repos/<owner>/<repo> with SSH URLs and optional upstream setup for forks.\"\n )]\n Repos(ReposCommand),\n #[command(\n about = \"Browse git repos under ~/code.\",\n long_about = \"Fuzzy search git repositories under ~/code and open the selected path. Also includes helpers to migrate AI sessions when paths move.\"\n )]\n Code(CodeCommand),\n #[command(\n about = \"Move or copy a folder to a new location, preserving symlinks and AI sessions.\",\n long_about = \"Migrate a project folder to a new location. Usage:\\n f migrate <target> - move current dir to target\\n f migrate <source> <target> - move source to target\\n f migrate -c <src> <target> - copy instead of move\\n f migrate code <relative> - move current dir to ~/code/<relative>\\n f migrate --copy code <rel> - copy current dir to ~/code/<relative>\\nUpdates ~/bin symlinks (move only). AI sessions are moved or copied based on the mode.\"\n )]\n Migrate(MigrateCommand),\n #[command(\n about = \"Run tasks in parallel with pretty status display.\",\n long_about = \"Execute multiple shell commands in parallel with a real-time status display showing spinners, progress, and output. Useful for running independent tasks concurrently.\",\n alias = \"p\"\n )]\n Parallel(ParallelCommand),\n #[command(\n about = \"Manage auto-generated documentation in .ai/docs/.\",\n long_about = \"AI-maintained documentation that stays in sync with the codebase. Docs are stored in .ai/docs/ and can be updated based on recent commits.\"\n )]\n Docs(DocsCommand),\n #[command(\n about = \"Upgrade flow to the latest version.\",\n long_about = \"Download and install the latest version of flow from GitHub releases. Checks for newer versions and replaces the current executable.\"\n )]\n Upgrade(UpgradeOpts),\n #[command(\n about = \"Pull ~/code/flow and rebuild the local flow binary.\",\n long_about = \"Updates ~/code/flow, runs f deploy in that repo, and reloads the fish shell.\"\n )]\n Latest,\n #[command(\n about = \"Release a project (registry, GitHub, or task).\",\n long_about = \"Release a project based on flow.toml defaults. Supports Flow registry releases, GitHub releases, or running a release task.\",\n alias = \"rel\"\n )]\n Release(ReleaseCommand),\n #[command(\n about = \"Install a CLI/tool binary (registry, parm, or flox).\",\n long_about = \"Install binaries via Flow registry, GitHub releases via parm, or flox. Auto mode tries registry first, then parm, then flox.\",\n alias = \"inst\"\n )]\n Install(InstallCommand),\n #[command(\n about = \"Manage the Flow registry (tokens, setup).\",\n long_about = \"Create registry tokens and wire them into worker secrets and local envs.\"\n )]\n Registry(RegistryCommand),\n #[command(\n about = \"Zero-cost traced reverse proxy for development.\",\n long_about = \"Start a reverse proxy that traces all HTTP requests with zero overhead. Writes trace-summary.json for AI agents to read.\",\n alias = \"px\"\n )]\n Proxy(ProxyCommand),\n #[command(\n about = \"Manage shared local *.localhost routing on port 80.\",\n long_about = \"Manages shared local *.localhost routing (host->target) in ~/.config/flow/local-domains. Default engine uses docker+nginx; optional native engine uses a local domains daemon.\",\n alias = \"dom\"\n )]\n Domains(DomainsCommand),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TracesOpts {\n /// Max rows per source (default: 40).\n #[arg(short = 'n', long, default_value = \"40\")]\n pub limit: usize,\n\n /// Follow and stream new entries.\n #[arg(short = 'f', long)]\n pub follow: bool,\n\n /// Filter by project path substring.\n #[arg(long)]\n pub project: Option<String>,\n\n /// Which source to show: all, tasks, ai.\n #[arg(long, value_enum, default_value = \"all\")]\n pub source: TraceSource,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TraceCommand {\n #[command(subcommand)]\n pub action: Option<TraceAction>,\n #[command(flatten)]\n pub events: TracesOpts,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct AnalyticsCommand {\n #[command(subcommand)]\n pub action: Option<AnalyticsAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum AnalyticsAction {\n /// Show analytics status and queue metadata.\n Status,\n /// Enable anonymous usage analytics.\n Enable,\n /// Disable anonymous usage analytics.\n Disable,\n /// Print queued analytics events.\n Export,\n /// Delete all queued analytics events.\n Purge,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum TraceAction {\n /// Show full history of the last active AI session for a project path.\n Session(TraceSessionOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TraceSessionOpts {\n /// Project path to load the latest session for.\n #[arg(value_name = \"PATH\")]\n pub path: PathBuf,\n}\n\n#[derive(ValueEnum, Clone, Debug)]\npub enum TraceSource {\n All,\n Tasks,\n Ai,\n}\n\n// === Proxy Commands ===\n\n#[derive(Args, Debug, Clone)]\npub struct ProxyCommand {\n #[command(subcommand)]\n pub action: ProxyAction,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ProxyAction {\n /// Start the proxy server (reads [[proxies]] from flow.toml).\n Start(ProxyStartOpts),\n /// View recent request traces.\n #[command(alias = \"t\")]\n Trace(ProxyTraceOpts),\n /// Show the last request details.\n Last(ProxyLastOpts),\n /// Add a new proxy target.\n Add(ProxyAddOpts),\n /// List configured proxy targets.\n List,\n /// Stop the proxy server.\n Stop,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ProxyStartOpts {\n /// Listen address (e.g., \":8080\" or \"127.0.0.1:8080\").\n #[arg(short, long)]\n pub listen: Option<String>,\n\n /// Run in foreground (don't daemonize).\n #[arg(short, long)]\n pub foreground: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ProxyTraceOpts {\n /// Number of records to show.\n #[arg(short = 'n', long, default_value = \"20\")]\n pub count: usize,\n\n /// Follow trace in real-time.\n #[arg(short, long)]\n pub follow: bool,\n\n /// Filter by target name.\n #[arg(long)]\n pub target: Option<String>,\n\n /// Show only errors (status >= 400).\n #[arg(long)]\n pub errors: bool,\n\n /// Filter by trace ID.\n #[arg(long)]\n pub id: Option<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ProxyLastOpts {\n /// Show only errors.\n #[arg(long)]\n pub errors: bool,\n\n /// Filter by target name.\n #[arg(long)]\n pub target: Option<String>,\n\n /// Include request/response body.\n #[arg(long)]\n pub body: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ProxyAddOpts {\n /// Target address (e.g., \"localhost:3000\").\n pub target: String,\n\n /// Proxy name (auto-suggested if not provided).\n #[arg(short, long)]\n pub name: Option<String>,\n\n /// Host-based routing.\n #[arg(long)]\n pub host: Option<String>,\n\n /// Path prefix routing.\n #[arg(long)]\n pub path: Option<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DomainsCommand {\n /// Routing engine to use (`docker` default, or `native` for experimental C++ daemon).\n #[arg(long, value_enum)]\n pub engine: Option<DomainsEngineArg>,\n\n #[command(subcommand)]\n pub action: Option<DomainsAction>,\n}\n\n#[derive(Copy, Clone, Debug, Eq, PartialEq, ValueEnum)]\npub enum DomainsEngineArg {\n Docker,\n Native,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum DomainsAction {\n /// Start the shared local-domain proxy on port 80.\n Up,\n /// Stop the shared local-domain proxy.\n Down,\n /// List configured host -> target routes.\n List,\n /// Print the public URL for a configured localhost route.\n #[command(alias = \"url\")]\n Get(DomainsGetOpts),\n /// Add a localhost route (for example: linsa.localhost -> 127.0.0.1:3481).\n Add(DomainsAddOpts),\n /// Remove a localhost route.\n #[command(alias = \"remove\", alias = \"delete\")]\n Rm(DomainsRmOpts),\n /// Show proxy ownership, port 80 conflicts, and route summary.\n Doctor,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DomainsAddOpts {\n /// Host name ending in .localhost.\n pub host: String,\n /// Upstream target in host:port format.\n pub target: String,\n /// Replace existing route target for this host.\n #[arg(long)]\n pub replace: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DomainsGetOpts {\n /// Host name ending in .localhost.\n pub host: String,\n /// Print the upstream host:port instead of the public URL.\n #[arg(long)]\n pub target: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DomainsRmOpts {\n /// Host name ending in .localhost.\n pub host: String,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DaemonOpts {\n /// Address to bind the Axum server to.\n #[arg(long, default_value = \"0.0.0.0\")]\n pub host: IpAddr,\n\n /// TCP port for the daemon's HTTP interface.\n #[arg(long, default_value_t = 9050)]\n pub port: u16,\n\n /// Target FPS for the mock frame generator until a real screen capture backend lands.\n #[arg(long, default_value_t = 5, value_parser = clap::value_parser!(u8).range(1..=120))]\n pub fps: u8,\n\n /// Buffer size for the broadcast channel that fans screen frames out to connected clients.\n #[arg(long, default_value_t = 512)]\n pub frame_buffer: usize,\n\n /// Optional path to the flow config TOML (defaults to ~/.config/flow/config.toml).\n #[arg(long)]\n pub config: Option<PathBuf>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ScreenOpts {\n /// Number of frames to preview before exiting.\n #[arg(long, default_value_t = 10)]\n pub frames: u16,\n\n /// Frame generation rate for the preview stream.\n #[arg(long, default_value_t = 5, value_parser = clap::value_parser!(u8).range(1..=60))]\n pub fps: u8,\n\n /// How many frames we keep buffered locally while previewing.\n #[arg(long, default_value_t = 64)]\n pub frame_buffer: usize,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct LogsOpts {\n /// Hostname or IP address of the running flowd daemon.\n #[arg(long, default_value = \"127.0.0.1\")]\n pub host: IpAddr,\n\n /// TCP port of the daemon's HTTP interface.\n #[arg(long, default_value_t = 9050)]\n pub port: u16,\n\n /// Specific server to fetch logs for (omit to dump all servers).\n #[arg(long)]\n pub server: Option<String>,\n\n /// Number of log lines to fetch per server when not streaming.\n #[arg(long, default_value_t = 200)]\n pub limit: usize,\n\n /// Stream logs in real-time (requires --server).\n #[arg(long)]\n pub follow: bool,\n\n /// Disable ANSI color output in log prefixes.\n #[arg(long)]\n pub no_color: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TraceOpts {\n /// Show the last command's input/output instead of streaming events.\n #[arg(long)]\n pub last_command: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ServersOpts {\n /// Hostname or IP address of the running flowd daemon.\n #[arg(long, default_value = \"127.0.0.1\")]\n pub host: IpAddr,\n\n /// TCP port of the daemon's HTTP interface.\n #[arg(long, default_value_t = 9050)]\n pub port: u16,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TasksCommand {\n #[command(subcommand)]\n pub action: Option<TasksAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum TasksAction {\n /// List tasks from the current project flow.toml.\n List(TasksListOpts),\n /// Show duplicate task names discovered across nested flow.toml files.\n Dupes(TasksDupesOpts),\n /// Initialize AI task directory with a MoonBit starter task.\n InitAi(TasksInitAiOpts),\n /// Prebuild and cache a specific AI task binary.\n BuildAi(TasksBuildAiOpts),\n /// Run a specific AI task with optional cache/daemon execution.\n RunAi(TasksRunAiOpts),\n /// Manage the AI task daemon.\n Daemon(TasksDaemonCommand),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TasksListOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n /// Show only duplicate task names and their scopes.\n #[arg(long)]\n pub dupes: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TasksDupesOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TasksInitAiOpts {\n /// Root directory where .ai/tasks should be created.\n #[arg(long, default_value = \".\")]\n pub root: PathBuf,\n /// Overwrite starter file if it already exists.\n #[arg(long)]\n pub force: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TasksBuildAiOpts {\n /// AI task selector (e.g. ai:flow/dev-check or flow/dev-check).\n #[arg(value_name = \"TASK\")]\n pub name: String,\n /// Root directory used for .ai/tasks discovery.\n #[arg(long, default_value = \".\")]\n pub root: PathBuf,\n /// Force rebuild even if a cached artifact exists.\n #[arg(long)]\n pub force: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TasksRunAiOpts {\n /// AI task selector (e.g. ai:flow/dev-check or flow/dev-check).\n #[arg(value_name = \"TASK\")]\n pub name: String,\n /// Root directory used for .ai/tasks discovery.\n #[arg(long, default_value = \".\")]\n pub root: PathBuf,\n /// Run through the AI task daemon.\n #[arg(long)]\n pub daemon: bool,\n /// Disable binary cache and use direct moon run.\n #[arg(long)]\n pub no_cache: bool,\n /// Additional arguments passed to the AI task.\n #[arg(value_name = \"ARGS\", trailing_var_arg = true)]\n pub args: Vec<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TasksDaemonCommand {\n #[command(subcommand)]\n pub action: TasksDaemonAction,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum TasksDaemonAction {\n /// Start task daemon in the background.\n Start,\n /// Stop task daemon.\n Stop,\n /// Show task daemon status.\n Status,\n /// Run daemon server loop (internal).\n #[command(hide = true)]\n Serve,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TasksOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n}\n\nimpl Default for TasksOpts {\n fn default() -> Self {\n Self {\n config: PathBuf::from(\"flow.toml\"),\n }\n }\n}\n\n#[derive(Args, Debug, Clone)]\npub struct AiTestNewOpts {\n /// Name or relative path for the scratch test (e.g. auth-login, chat/loading-state).\n pub name: String,\n\n /// Base scratch test directory, relative to project root.\n #[arg(long, default_value = \".ai/test\")]\n pub dir: String,\n\n /// Use `.spec.ts` instead of `.test.ts`.\n #[arg(long, default_value_t = false)]\n pub spec: bool,\n\n /// Overwrite existing file if present.\n #[arg(long, default_value_t = false)]\n pub force: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct GlobalCommand {\n #[command(subcommand)]\n pub action: Option<GlobalAction>,\n /// Task name to run (omit to list global tasks).\n #[arg(value_name = \"TASK\")]\n pub task: Option<String>,\n /// List global tasks.\n #[arg(long, short)]\n pub list: bool,\n /// Additional arguments passed to the task command.\n #[arg(value_name = \"ARGS\", trailing_var_arg = true)]\n pub args: Vec<String>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum GlobalAction {\n /// List global tasks.\n List,\n /// Run a global task by name.\n Run {\n /// Task name to run.\n #[arg(value_name = \"TASK\")]\n task: String,\n /// Additional arguments passed to the task command.\n #[arg(value_name = \"ARGS\", trailing_var_arg = true)]\n args: Vec<String>,\n },\n /// Match a query against global tasks (LM Studio).\n Match(MatchOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TaskRunOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n /// Hand off the task to the hub daemon instead of running it locally.\n #[arg(long)]\n pub delegate_to_hub: bool,\n /// Hub host to delegate tasks to (defaults to the local lin daemon).\n #[arg(long, default_value = \"127.0.0.1\")]\n pub hub_host: IpAddr,\n /// Hub port to delegate tasks to.\n #[arg(long, default_value_t = 9050)]\n pub hub_port: u16,\n /// Name of the task to execute.\n #[arg(value_name = \"TASK\")]\n pub name: String,\n /// Additional arguments passed to the task command.\n #[arg(value_name = \"ARGS\", trailing_var_arg = true)]\n pub args: Vec<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct LifecycleRunOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n /// Additional arguments passed to the lifecycle task.\n #[arg(value_name = \"ARGS\", trailing_var_arg = true)]\n pub args: Vec<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct FastRunOpts {\n /// AI task selector (e.g. ai:flow/dev-check).\n #[arg(value_name = \"TASK\")]\n pub name: String,\n /// Root directory used for .ai/tasks discovery.\n #[arg(long, default_value = \".\")]\n pub root: PathBuf,\n /// Disable binary cache and use direct moon run.\n #[arg(long)]\n pub no_cache: bool,\n /// Additional arguments passed to the AI task.\n #[arg(value_name = \"ARGS\", trailing_var_arg = true)]\n pub args: Vec<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TaskActivateOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ProcessOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n /// Show all running flow processes across all projects.\n #[arg(long)]\n pub all: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct KillOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n /// Kill by task name.\n #[arg(value_name = \"TASK\")]\n pub task: Option<String>,\n /// Kill by PID directly.\n #[arg(long)]\n pub pid: Option<u32>,\n /// Kill all processes for this project.\n #[arg(long)]\n pub all: bool,\n /// Force kill (SIGKILL) without graceful shutdown.\n #[arg(long, short)]\n pub force: bool,\n /// Timeout in seconds before sending SIGKILL (default: 5).\n #[arg(long, default_value_t = 5)]\n pub timeout: u64,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TaskLogsOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n /// Task name to view logs for.\n #[arg(value_name = \"TASK\")]\n pub task: Option<String>,\n /// Follow the log in real-time (like tail -f).\n #[arg(long, short)]\n pub follow: bool,\n /// Number of lines to show from the end.\n #[arg(long, short = 'n', default_value_t = 50)]\n pub lines: usize,\n /// Show logs for all projects.\n #[arg(long)]\n pub all: bool,\n /// List available log files instead of showing content.\n #[arg(long, short)]\n pub list: bool,\n /// Look up logs by registered project name instead of config path.\n #[arg(long, short)]\n pub project: Option<String>,\n /// Suppress headers, output only log content.\n #[arg(long, short)]\n pub quiet: bool,\n /// Hub task ID to fetch logs for (from delegated tasks).\n #[arg(long)]\n pub task_id: Option<String>,\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct DoctorOpts {}\n\n#[derive(Args, Debug, Clone)]\npub struct HealthOpts {}\n\n#[derive(Args, Debug, Clone)]\npub struct InvariantsOpts {\n /// Only check staged changes (default: check all changes vs HEAD).\n #[arg(long)]\n pub staged: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct RerunOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct ActiveOpts {\n /// Project name to set as active.\n #[arg(value_name = \"PROJECT\")]\n pub project: Option<String>,\n /// Clear the active project.\n #[arg(long, short)]\n pub clear: bool,\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct SessionsOpts {\n /// Filter by provider (claude, codex, cursor, or all).\n #[arg(long, short, default_value = \"all\")]\n pub provider: String,\n /// Number of exchanges to copy (default: all since checkpoint).\n #[arg(long, short)]\n pub count: Option<usize>,\n /// Show sessions but don't copy to clipboard.\n #[arg(long, short)]\n pub list: bool,\n /// Get full session context, ignoring checkpoints.\n #[arg(long, short)]\n pub full: bool,\n /// Generate summaries for stale sessions (uses Gemini).\n #[arg(long)]\n pub summarize: bool,\n /// Condense the selected session into a handoff summary (uses Gemini).\n #[arg(long)]\n pub handoff: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ServerOpts {\n /// Host to bind the server to.\n #[arg(long, default_value = \"127.0.0.1\")]\n pub host: String,\n /// Port for the HTTP server.\n #[arg(long, default_value_t = 9060)]\n pub port: u16,\n #[command(subcommand)]\n pub action: Option<ServerAction>,\n}\n\n#[derive(Subcommand, Debug, Clone, PartialEq, Eq)]\npub enum ServerAction {\n #[command(about = \"Start the server in the foreground\")]\n Foreground,\n #[command(about = \"Stop the background server\")]\n Stop,\n}\n\n#[derive(Args, Debug)]\npub struct WebOpts {\n /// Port to serve the web UI on.\n #[arg(long, default_value_t = 9310)]\n pub port: u16,\n /// Host to bind the web UI server to.\n #[arg(long, default_value = \"127.0.0.1\")]\n pub host: String,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct InitOpts {\n /// Where to write the scaffolded flow.toml (defaults to ./flow.toml).\n #[arg(long)]\n pub path: Option<PathBuf>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ShellInitOpts {\n /// Shell to generate init script for (fish, zsh, bash).\n pub shell: String,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ShellCommand {\n #[command(subcommand)]\n pub action: Option<ShellAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ShellAction {\n /// Refresh the current shell session.\n Reset,\n /// Disable fish terminal query to avoid PDA warning.\n FixTerminal,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct NewOpts {\n /// Template name (e.g., web, docs). If omitted, shows fuzzy picker.\n pub template: Option<String>,\n /// Destination path. Plain names go to ~/code/ (e.g., \"zerg\" → ~/code/zerg). Use ./ for cwd.\n pub path: Option<String>,\n /// Show what would change without writing.\n #[arg(long)]\n pub dry_run: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct HomeCommand {\n #[command(subcommand)]\n pub action: Option<HomeAction>,\n /// GitHub URL or owner/repo for the config repo.\n pub repo: Option<String>,\n /// Optional internal config repo URL (cloned into ~/config/i).\n #[arg(long)]\n pub internal: Option<String>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum HomeAction {\n /// Guide home setup and validate GitHub access.\n Setup,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ArchiveOpts {\n /// Message to include in the archive folder name.\n pub message: String,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct HubCommand {\n #[command(subcommand)]\n pub action: Option<HubAction>,\n\n #[command(flatten)]\n pub opts: HubOpts,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct HubOpts {\n /// Hostname or IP address of the hub daemon.\n #[arg(long, default_value = \"127.0.0.1\", global = true)]\n pub host: IpAddr,\n\n /// TCP port for the daemon's HTTP interface.\n #[arg(long, default_value_t = 9050, global = true)]\n pub port: u16,\n\n /// Optional path to the lin hub config (defaults to lin's built-in lookup).\n #[arg(long, global = true)]\n pub config: Option<PathBuf>,\n\n /// Skip launching the hub TUI after ensuring the daemon is running.\n #[arg(long, global = true)]\n pub no_ui: bool,\n\n /// Also start the docs hub (Next.js dev server).\n #[arg(long, global = true)]\n pub docs_hub: bool,\n}\n\n#[derive(Subcommand, Debug, Clone, PartialEq, Eq)]\npub enum HubAction {\n #[command(about = \"Start or ensure the hub daemon is running\")]\n Start,\n #[command(about = \"Stop the hub daemon if it was started by flow\")]\n Stop,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SecretsCommand {\n #[command(subcommand)]\n pub action: SecretsAction,\n}\n\n#[derive(Parser, Debug)]\npub struct OtpCommand {\n #[command(subcommand)]\n pub action: OtpAction,\n}\n\n#[derive(Subcommand, Debug)]\npub enum OtpAction {\n #[command(about = \"Get a TOTP code from 1Password Connect\")]\n Get {\n /// Vault name or id.\n vault: String,\n /// Item title or id.\n item: String,\n /// Optional field label to select when multiple TOTP fields exist.\n #[arg(long)]\n field: Option<String>,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum SecretsAction {\n #[command(about = \"List configured secret environments\")]\n List(SecretsListOpts),\n #[command(about = \"Fetch secrets for a specific environment\")]\n Pull(SecretsPullOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SecretsListOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SecretsPullOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n\n /// Environment name defined in the secrets config.\n #[arg(value_name = \"ENV\")]\n pub env: String,\n\n /// Optional override for the secrets hub URL (default myflow.sh).\n #[arg(long)]\n pub hub: Option<String>,\n\n /// Optional file to write secrets to (defaults to stdout).\n #[arg(long)]\n pub output: Option<PathBuf>,\n\n /// Output format for rendered secrets.\n #[arg(long, default_value_t = SecretsFormat::Shell, value_enum)]\n pub format: SecretsFormat,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DbCommand {\n #[command(subcommand)]\n pub action: DbAction,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum DbAction {\n /// Jazz2 app credentials and env wiring.\n Jazz(JazzStorageCommand),\n /// Postgres workflows (migrations/generation).\n Postgres(PostgresCommand),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct JazzStorageCommand {\n #[command(subcommand)]\n pub action: JazzStorageAction,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum JazzStorageAction {\n /// Create a new Jazz2 app credential set and store env vars.\n New {\n /// What the app credentials will be used for.\n #[arg(long, value_enum, default_value = \"mirror\")]\n kind: JazzStorageKind,\n /// Optional name for the app.\n #[arg(long)]\n name: Option<String>,\n /// Optional sync server URL (ws/wss urls are normalized to http/https).\n #[arg(long)]\n peer: Option<String>,\n /// Optional Jazz API key (for hosted cloud routing).\n #[arg(long)]\n api_key: Option<String>,\n /// Environment to store in (dev, staging, production).\n #[arg(short, long, default_value = \"production\")]\n environment: String,\n },\n}\n\n#[derive(Debug, Clone, Copy, ValueEnum)]\npub enum JazzStorageKind {\n /// Mirror app credentials (gitedit-style mirror sync).\n Mirror,\n /// Env store app credentials (cloud env store).\n EnvStore,\n /// App data app credentials (cloud app store).\n AppStore,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct PostgresCommand {\n #[command(subcommand)]\n pub action: PostgresAction,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum PostgresAction {\n /// Generate Drizzle migrations for the configured Postgres project.\n Generate {\n /// Override the Postgres project directory (defaults to ~/org/la/la/server).\n #[arg(long)]\n project: Option<PathBuf>,\n },\n /// Apply Drizzle migrations for the configured Postgres project.\n Migrate {\n /// Override the Postgres project directory (defaults to ~/org/la/la/server).\n #[arg(long)]\n project: Option<PathBuf>,\n /// Explicit DATABASE_URL (falls back to env/.env/Planetscale env vars).\n #[arg(long)]\n database_url: Option<String>,\n /// Generate migrations before applying them.\n #[arg(long, default_value_t = false)]\n generate: bool,\n },\n}\n\n#[derive(Debug, Clone, Copy, ValueEnum)]\npub enum SecretsFormat {\n Shell,\n Dotenv,\n}\n\n#[derive(Debug, Clone, Copy, ValueEnum)]\npub enum SetupTarget {\n Deploy,\n Release,\n Docs,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SetupOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n /// Optional setup target (e.g., deploy).\n #[arg(value_enum, value_name = \"TARGET\")]\n pub target: Option<SetupTarget>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct IndexOpts {\n /// Codanna binary to execute (defaults to looking up 'codanna' in PATH).\n #[arg(long, default_value = \"codanna\")]\n pub binary: String,\n\n /// Directory to index; defaults to the current working directory.\n #[arg(long)]\n pub project_root: Option<PathBuf>,\n\n /// SQLite destination for snapshots (defaults to ~/.db/flow/flow.sqlite).\n #[arg(long)]\n pub database: Option<PathBuf>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct MatchOpts {\n /// Natural language query describing the task you want to run.\n #[arg(value_name = \"QUERY\", trailing_var_arg = true, num_args = 1..)]\n pub query: Vec<String>,\n\n /// LM Studio model to use (defaults to qwen3-8b).\n #[arg(long)]\n pub model: Option<String>,\n\n /// LM Studio API port (defaults to 1234).\n #[arg(long, default_value_t = 1234)]\n pub port: u16,\n\n /// Only show the match without running the task.\n #[arg(long, short = 'n')]\n pub dry_run: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct AskOpts {\n /// Natural language query describing the task or command you want to run.\n #[arg(value_name = \"QUERY\", trailing_var_arg = true, num_args = 1..)]\n pub query: Vec<String>,\n\n /// AI server model to use (defaults to AI_SERVER_MODEL).\n #[arg(long)]\n pub model: Option<String>,\n\n /// AI server URL (defaults to AI_SERVER_URL or http://127.0.0.1:7331).\n #[arg(long)]\n pub url: Option<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct BranchesCommand {\n #[command(subcommand)]\n pub action: Option<BranchesAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum BranchesAction {\n /// List recent branches.\n List(BranchListOpts),\n /// Find branches by substring or token query.\n Find(BranchFindOpts),\n /// Use AI to map a natural language query to the best branch.\n Ai(BranchAiOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct BranchListOpts {\n /// Include remote branches.\n #[arg(long)]\n pub remote: bool,\n /// Maximum number of branches to show.\n #[arg(long, default_value_t = 40)]\n pub limit: usize,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct BranchFindOpts {\n /// Query text used to filter branch names and commit subjects.\n #[arg(value_name = \"QUERY\")]\n pub query: String,\n /// Include remote branches.\n #[arg(long)]\n pub remote: bool,\n /// Maximum number of matches to show.\n #[arg(long, default_value_t = 20)]\n pub limit: usize,\n /// Switch to the top match automatically.\n #[arg(long)]\n pub switch: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct BranchAiOpts {\n /// Natural language query describing the branch you want.\n #[arg(value_name = \"QUERY\")]\n pub query: String,\n /// Include remote branches.\n #[arg(long)]\n pub remote: bool,\n /// Maximum candidate branches to send to AI.\n #[arg(long, default_value_t = 80)]\n pub limit: usize,\n /// AI server model to use (defaults to AI_SERVER_MODEL).\n #[arg(long)]\n pub model: Option<String>,\n /// AI server URL (defaults to AI_SERVER_URL or http://127.0.0.1:7331).\n #[arg(long)]\n pub url: Option<String>,\n /// Switch to the selected branch automatically.\n #[arg(long)]\n pub switch: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct CommitOpts {\n /// Skip pushing after commit.\n #[arg(long, short = 'n')]\n pub no_push: bool,\n /// Queue the commit for review before pushing.\n #[arg(long)]\n pub queue: bool,\n /// Bypass commit queue and allow pushing immediately.\n #[arg(long, conflicts_with = \"queue\")]\n pub no_queue: bool,\n /// Force commit without queue (bypass stacked review).\n #[arg(long, conflicts_with = \"queue\")]\n pub force: bool,\n /// Commit and push immediately (bypass commit queue).\n #[arg(long, conflicts_with = \"queue\")]\n pub approved: bool,\n /// Open the queued commit in Rise for review after commit.\n #[arg(long)]\n pub review: bool,\n /// Run synchronously (don't delegate to hub).\n #[arg(long, visible_alias = \"no-hub\")]\n pub sync: bool,\n /// Include AI session context in code review (default: off).\n #[arg(long)]\n pub context: bool,\n /// Include an unhash.sh bundle/link in the commit message (opt-in).\n #[arg(long)]\n pub hashed: bool,\n /// Dry run: show context that would be passed to review without committing.\n #[arg(long)]\n pub dry: bool,\n /// Commit immediately and run Codex review asynchronously in the background.\n #[arg(long, conflicts_with = \"dry\")]\n pub quick: bool,\n /// Run blocking review before committing (legacy commitWithCheck behavior).\n #[arg(long, conflicts_with = \"quick\")]\n pub slow: bool,\n /// Use Codex instead of Claude for code review (default: Claude).\n #[arg(long)]\n pub codex: bool,\n /// Choose a specific review model (claude-opus, codex-high, codex-mini).\n #[arg(long, value_enum)]\n pub review_model: Option<ReviewModelArg>,\n /// Custom message to include in commit (appended after author line).\n #[arg(long, short = 'm')]\n pub message: Option<String>,\n /// Fast commit with optional message (defaults to \".\").\n #[arg(long, value_name = \"MESSAGE\", num_args = 0..=1, default_missing_value = \".\")]\n pub fast: Option<String>,\n /// Stage and commit only these paths (repeatable).\n #[arg(long = \"path\", value_name = \"PATH\")]\n pub paths: Vec<String>,\n /// Message to append after the AI-generated subject/body.\n #[arg(value_name = \"MESSAGE\", allow_hyphen_values = true)]\n pub message_arg: Option<String>,\n /// Max tokens for AI session context (default: 1000).\n #[arg(long, short = 't', default_value = \"1000\")]\n pub tokens: usize,\n /// Skip all quality gates for this commit.\n #[arg(long)]\n pub skip_quality: bool,\n /// Skip documentation requirements only.\n #[arg(long)]\n pub skip_docs: bool,\n /// Skip test requirements only.\n #[arg(long)]\n pub skip_tests: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct PrOpts {\n /// Optional message to append to the AI-generated commit message, or subcommands like:\n /// f pr open\n /// f pr open edit\n /// f pr feedback [<number|url>] [--todo]\n #[arg(value_name = \"ARGS\", allow_hyphen_values = true)]\n pub args: Vec<String>,\n /// Base branch for the PR (default: main).\n #[arg(long, default_value = \"main\")]\n pub base: String,\n /// Create as a draft PR.\n #[arg(long)]\n pub draft: bool,\n /// Do not open the PR in browser after creating/finding it.\n #[arg(long)]\n pub no_open: bool,\n /// Skip creating a new commit; use an existing queued commit.\n #[arg(long)]\n pub no_commit: bool,\n /// Specific queued commit hash to use (short or full).\n #[arg(long)]\n pub hash: Option<String>,\n /// Stage and commit only these paths before creating PR (repeatable).\n #[arg(long = \"path\", value_name = \"PATH\")]\n pub paths: Vec<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct GitignoreCommand {\n #[command(subcommand)]\n pub action: Option<GitignoreAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum GitignoreAction {\n /// Audit .gitignore files for blocked personal-tooling patterns.\n Audit(GitignoreScanOpts),\n /// Remove blocked personal-tooling patterns from .gitignore files.\n Fix(GitignoreScanOpts),\n /// Create ~/.config/flow/gitignore-policy.toml with defaults.\n PolicyInit(GitignorePolicyInitOpts),\n /// Configure a global git excludes file with blocked personal-tooling patterns.\n SetupGlobal {\n /// Print target path/entries without writing changes.\n #[arg(long)]\n print_only: bool,\n },\n /// Print the active policy file path.\n PolicyPath,\n}\n#[derive(Args, Debug, Clone)]\npub struct GitignoreScanOpts {\n /// Root directory to scan for repositories (defaults to policy repos_roots, then ~/repos).\n #[arg(long)]\n pub root: Option<String>,\n /// Include repos owned by allowed owners.\n #[arg(long)]\n pub all: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct GitignorePolicyInitOpts {\n /// Overwrite an existing policy file.\n #[arg(long)]\n pub force: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct RecipeCommand {\n #[command(subcommand)]\n pub action: Option<RecipeAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum RecipeAction {\n /// List available recipes.\n List(RecipeListOpts),\n /// Search recipes by text query.\n Search(RecipeSearchOpts),\n /// Run a recipe by id or name.\n Run(RecipeRunOpts),\n /// Initialize recipe directories and starter files.\n Init(RecipeInitOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct RecipeListOpts {\n /// Scope to include.\n #[arg(long, value_enum, default_value = \"all\")]\n pub scope: RecipeScopeArg,\n /// Optional text filter.\n #[arg(long)]\n pub query: Option<String>,\n /// Override global recipes directory.\n #[arg(long)]\n pub global_dir: Option<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct RecipeSearchOpts {\n /// Search text.\n pub query: String,\n /// Scope to include.\n #[arg(long, value_enum, default_value = \"all\")]\n pub scope: RecipeScopeArg,\n /// Override global recipes directory.\n #[arg(long)]\n pub global_dir: Option<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct RecipeRunOpts {\n /// Recipe id or name fragment.\n pub selector: String,\n /// Scope to include.\n #[arg(long, value_enum, default_value = \"all\")]\n pub scope: RecipeScopeArg,\n /// Override global recipes directory.\n #[arg(long)]\n pub global_dir: Option<String>,\n /// Working directory for execution.\n #[arg(long)]\n pub cwd: Option<String>,\n /// Print command without executing.\n #[arg(long)]\n pub dry_run: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct RecipeInitOpts {\n /// Scope to initialize.\n #[arg(long, value_enum, default_value = \"all\")]\n pub scope: RecipeScopeArg,\n /// Override global recipes directory.\n #[arg(long)]\n pub global_dir: Option<String>,\n}\n\n#[derive(ValueEnum, Debug, Clone, Copy, PartialEq, Eq)]\npub enum RecipeScopeArg {\n Project,\n Global,\n All,\n}\n#[derive(Args, Debug, Clone)]\npub struct CommitQueueCommand {\n #[command(subcommand)]\n pub action: Option<CommitQueueAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ReviewCommand {\n #[command(subcommand)]\n pub action: Option<ReviewAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ReviewsTodoCommand {\n #[command(subcommand)]\n pub action: Option<ReviewsTodoAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct GitRepairOpts {\n /// Branch to checkout if HEAD is detached (default: main).\n #[arg(long)]\n pub branch: Option<String>,\n /// Dry run - show what would be repaired.\n #[arg(long, short = 'n')]\n pub dry_run: bool,\n /// After repair, switch to target branch and cherry-pick current HEAD onto it.\n /// If conflicts occur, flow auto-aborts and returns to the source branch.\n #[arg(long)]\n pub land_main: bool,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum CommitQueueAction {\n /// List queued commits.\n List,\n /// Show details for a queued commit.\n Show {\n /// Commit hash (short or full).\n hash: String,\n },\n /// Open the queued commit diff in Rise app (multi-file diff UI).\n Open {\n /// Commit hash (short or full).\n hash: String,\n },\n /// Print the full diff for a queued commit to stdout.\n Diff {\n /// Commit hash (short or full).\n hash: String,\n },\n /// Re-run AI review for queued commits and refresh queue/todo metadata.\n Review {\n /// Commit hashes (short or full). If omitted, reviews current branch queue entries.\n hashes: Vec<String>,\n /// Review all queued commits across branches.\n #[arg(long)]\n all: bool,\n },\n /// Approve a queued commit and push it.\n Approve {\n /// Approve all queued commits on the current branch (push once).\n #[arg(long)]\n all: bool,\n /// Commit hash (short or full). Defaults to HEAD when omitted.\n hash: Option<String>,\n /// If hash is not queued but exists in git history, queue it first.\n #[arg(long)]\n queue_if_missing: bool,\n /// Mark an auto-queued commit as manually reviewed.\n #[arg(long)]\n mark_reviewed: bool,\n /// Push even if the commit is not at HEAD.\n #[arg(long, short = 'f')]\n force: bool,\n /// Allow pushing even if the queued commit has review issues recorded.\n #[arg(long)]\n allow_issues: bool,\n /// Allow pushing even if the review timed out or is missing.\n #[arg(long)]\n allow_unreviewed: bool,\n },\n /// Approve all queued commits on the current branch (push once).\n ApproveAll {\n /// Push even if the branch is behind its remote.\n #[arg(long, short = 'f')]\n force: bool,\n /// Allow pushing even if some queued commits have review issues recorded.\n #[arg(long)]\n allow_issues: bool,\n /// Allow pushing even if some queued commits have review timed out / missing.\n #[arg(long)]\n allow_unreviewed: bool,\n },\n /// Remove a commit from the queue without pushing.\n Drop {\n /// Commit hash (short or full).\n hash: String,\n },\n /// Create or update a GitHub PR for a queued commit (pushes a bookmark/branch as the PR head).\n PrCreate {\n /// Commit hash (short or full).\n hash: String,\n /// Base branch for the PR (default: main).\n #[arg(long, default_value = \"main\")]\n base: String,\n /// Create as a draft PR.\n #[arg(long)]\n draft: bool,\n /// Open PR in browser after creating/finding it.\n #[arg(long)]\n open: bool,\n },\n /// Open the PR for a queued commit in the browser (creates it if missing).\n PrOpen {\n /// Commit hash (short or full).\n hash: String,\n /// Base branch for the PR if it needs to be created (default: main).\n #[arg(long, default_value = \"main\")]\n base: String,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ReviewAction {\n /// Open the latest queued commit in Rise.\n Latest,\n /// Copy a ready-to-send review prompt for a queued commit to clipboard.\n Copy {\n /// Commit hash (short or full). Defaults to latest queued commit.\n hash: Option<String>,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ReviewsTodoAction {\n /// List pending review todos with priority indicators.\n #[command(alias = \"ls\")]\n List,\n /// Show details for a review todo.\n Show {\n /// Todo id (short prefix or full).\n id: String,\n },\n /// Mark a review todo as resolved.\n Done {\n /// Todo id (short prefix or full).\n id: String,\n },\n /// Auto-fix a review todo via Codex.\n Fix {\n /// Todo id to fix. If omitted with --all, fixes all open review todos.\n id: Option<String>,\n /// Fix all open review todos.\n #[arg(long)]\n all: bool,\n },\n /// Run Codex deep review for queued commits.\n Codex {\n /// Commit hashes (short or full). If omitted, reviews current branch queue entries.\n hashes: Vec<String>,\n /// Review all queued commits across branches.\n #[arg(long)]\n all: bool,\n },\n /// Approve all queued commits once deep review todos are resolved.\n ApproveAll {\n /// Push even if the branch is behind its remote.\n #[arg(long, short = 'f')]\n force: bool,\n /// Allow pushing even if some queued commits have review issues recorded.\n #[arg(long)]\n allow_issues: bool,\n /// Allow pushing even if some queued commits have review timed out / missing.\n #[arg(long)]\n allow_unreviewed: bool,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct JjCommand {\n #[command(subcommand)]\n pub action: Option<JjAction>,\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct StatusOpts {\n /// Show raw `jj status` output without Flow's workflow summary.\n #[arg(long)]\n pub raw: bool,\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct JjStatusOpts {\n /// Show raw `jj status` output without Flow's workflow summary.\n #[arg(long)]\n pub raw: bool,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum JjAction {\n /// Initialize jj in the repo (colocated with git when possible).\n Init {\n /// Optional path to initialize (defaults to current directory).\n #[arg(long)]\n path: Option<PathBuf>,\n },\n /// Show jj status.\n Status(JjStatusOpts),\n /// Fetch from git remotes.\n Fetch,\n /// Rebase current change onto a destination.\n Rebase(JjRebaseOpts),\n /// Push bookmarks to git.\n Push(JjPushOpts),\n /// Fetch, rebase, then push a bookmark.\n Sync(JjSyncOpts),\n /// Manage workspaces.\n #[command(subcommand)]\n Workspace(JjWorkspaceAction),\n /// Manage bookmarks.\n #[command(subcommand)]\n Bookmark(JjBookmarkAction),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct JjRebaseOpts {\n /// Destination to rebase onto (default: jj.default_branch or main/master).\n #[arg(long)]\n pub dest: Option<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct JjPushOpts {\n /// Bookmark to push.\n #[arg(long)]\n pub bookmark: Option<String>,\n /// Push all bookmarks.\n #[arg(long)]\n pub all: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct JjSyncOpts {\n /// Bookmark to push after rebase (optional).\n #[arg(long)]\n pub bookmark: Option<String>,\n /// Destination to rebase onto (default: jj.default_branch or main/master).\n #[arg(long)]\n pub dest: Option<String>,\n /// Remote to sync with (default: git.remote, then jj.remote, then origin).\n #[arg(long)]\n pub remote: Option<String>,\n /// Skip pushing after rebase.\n #[arg(long)]\n pub no_push: bool,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum JjWorkspaceAction {\n /// List workspaces.\n List,\n /// Add a workspace.\n Add {\n /// Workspace name.\n name: String,\n /// Optional path for workspace directory.\n #[arg(long)]\n path: Option<PathBuf>,\n /// Optional base revision for the new workspace working copy.\n #[arg(long)]\n rev: Option<String>,\n },\n /// Create an isolated parallel workspace lane anchored on trunk.\n Lane {\n /// Lane/workspace name.\n name: String,\n /// Optional path for workspace directory.\n #[arg(long)]\n path: Option<PathBuf>,\n /// Base revision (default: <default_branch>@<remote> if tracked, else <default_branch>).\n #[arg(long)]\n base: Option<String>,\n /// Remote used for default base resolution.\n #[arg(long)]\n remote: Option<String>,\n /// Skip fetch before creating the lane.\n #[arg(long)]\n no_fetch: bool,\n },\n /// Create or reuse a stable JJ workspace for a review branch without touching the current checkout.\n Review {\n /// Review branch name (for example: review/nikiv-feature).\n branch: String,\n /// Optional path for workspace directory.\n #[arg(long)]\n path: Option<PathBuf>,\n /// Optional base revision. Defaults to the branch commit when found, else trunk.\n #[arg(long)]\n base: Option<String>,\n /// Remote used for branch lookup and default base resolution.\n #[arg(long)]\n remote: Option<String>,\n /// Skip fetch before resolving the review branch.\n #[arg(long)]\n no_fetch: bool,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum JjBookmarkAction {\n /// List bookmarks.\n List,\n /// Track a bookmark from a remote.\n Track {\n /// Bookmark name.\n name: String,\n /// Remote name (default: git.remote, then jj.remote, then origin).\n #[arg(long)]\n remote: Option<String>,\n },\n /// Create a bookmark at a revision.\n Create {\n /// Bookmark name.\n name: String,\n /// Revision to attach to (default: @).\n #[arg(long)]\n rev: Option<String>,\n /// Whether to track the remote bookmark (default: jj.auto_track).\n #[arg(long)]\n track: Option<bool>,\n /// Remote to track (default: git.remote, then jj.remote, then origin).\n #[arg(long)]\n remote: Option<String>,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct FixupOpts {\n /// Path to the flow.toml to fix (defaults to ./flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n /// Only show what would be fixed without making changes.\n #[arg(long, short = 'n')]\n pub dry_run: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct FixOpts {\n /// Description of what to fix, or a path to a markdown fix report.\n #[arg(value_name = \"MESSAGE\", trailing_var_arg = true)]\n pub message: Vec<String>,\n /// Skip unrolling the last commit.\n #[arg(long)]\n pub no_unroll: bool,\n /// Stash local changes before unrolling, then restore after.\n #[arg(long)]\n pub stash: bool,\n /// Hive agent name to run (default: shell).\n #[arg(long, default_value = \"shell\")]\n pub agent: String,\n /// Skip running Hive agent (only unroll).\n #[arg(long)]\n pub no_agent: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct UndoCommand {\n #[command(subcommand)]\n pub action: Option<UndoAction>,\n /// Dry run - show what would be undone without doing it.\n #[arg(long, short = 'n')]\n pub dry_run: bool,\n /// Force undo even if it requires force push.\n #[arg(long, short = 'f')]\n pub force: bool,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum UndoAction {\n /// Show the last undoable action.\n Show,\n /// List recent undoable actions.\n List {\n /// Maximum number of actions to show.\n #[arg(short, long, default_value = \"10\")]\n limit: usize,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ChangesCommand {\n #[command(subcommand)]\n pub action: Option<ChangesAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DiffCommand {\n /// Hash to unroll. When omitted, creates a new diff bundle.\n pub hash: Option<String>,\n /// Include specific env vars from local personal env store.\n /// Examples: --env CEREBRAS_API_KEY --env CEREBRAS_MODEL\n /// --env CEREBRAS_API_KEY,CEREBRAS_MODEL\n /// --env='[\\\"CEREBRAS_API_KEY\\\",\\\"CEREBRAS_MODEL\\\"]'\n #[arg(long, value_name = \"KEY\", action = clap::ArgAction::Append)]\n pub env: Vec<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct HashOpts {\n /// Arguments passed to unhash (paths or session flags).\n #[arg(trailing_var_arg = true, required = true)]\n pub args: Vec<String>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ChangesAction {\n #[command(\n about = \"Print the current git diff for sharing.\",\n long_about = \"Outputs git diff (including untracked files) so it can be applied elsewhere.\"\n )]\n CurrentDiff,\n #[command(\n about = \"Apply a diff to the current repo.\",\n long_about = \"Accepts a diff string, a file path, or '-' to read from stdin.\"\n )]\n Accept {\n /// Diff content, '-' for stdin, or a path to a diff file.\n diff: Option<String>,\n /// Read diff from a file path.\n #[arg(short, long)]\n file: Option<PathBuf>,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DaemonCommand {\n #[command(subcommand)]\n pub action: Option<DaemonAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum DaemonAction {\n /// Start a daemon by name.\n Start {\n /// Name of the daemon to start.\n name: String,\n },\n /// Stop a running daemon.\n Stop {\n /// Name of the daemon to stop.\n name: String,\n },\n /// Restart a daemon (stop then start).\n Restart {\n /// Name of the daemon to restart.\n name: String,\n },\n /// Show status of all configured daemons.\n Status {\n /// Optional daemon name to filter status output.\n name: Option<String>,\n },\n /// List available daemons.\n #[command(alias = \"ls\")]\n List,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SupervisorCommand {\n #[command(subcommand)]\n pub action: Option<SupervisorAction>,\n /// Socket path for supervisor IPC (defaults to ~/.config/flow/supervisor.sock).\n #[arg(long, global = true)]\n pub socket: Option<PathBuf>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum SupervisorAction {\n /// Start the supervisor in the background.\n Start {\n /// Start boot daemons in addition to autostart daemons.\n #[arg(long)]\n boot: bool,\n },\n /// Run the supervisor in the foreground (blocking).\n Run {\n /// Start boot daemons in addition to autostart daemons.\n #[arg(long)]\n boot: bool,\n },\n /// Install a macOS LaunchAgent to keep the supervisor running.\n Install {\n /// Start boot daemons in addition to autostart daemons.\n #[arg(long)]\n boot: bool,\n },\n /// Remove the macOS LaunchAgent for the supervisor.\n Uninstall,\n /// Stop the supervisor if running.\n Stop,\n /// Show supervisor status.\n Status,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct AiCommand {\n #[command(subcommand)]\n pub action: Option<AiAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum AiAction {\n /// List all AI sessions for this project (Claude + Codex + Cursor).\n #[command(alias = \"ls\")]\n List,\n /// Cursor: inspect and read agent transcripts for this project.\n Cursor {\n #[command(subcommand)]\n action: Option<ProviderAiAction>,\n },\n /// Claude Code: continue last session or start new one.\n Claude {\n #[command(subcommand)]\n action: Option<ProviderAiAction>,\n },\n /// Codex: continue last session or start new one.\n Codex {\n #[command(subcommand)]\n action: Option<ProviderAiAction>,\n },\n /// Run a prompt through Everruns and bridge client-side tool calls to seqd.\n #[command(alias = \"er\")]\n Everruns(AiEverrunsOpts),\n /// Resume an AI session by name or ID.\n Resume {\n /// Session name or ID to resume.\n #[arg(value_name = \"SESSION\")]\n session: Option<String>,\n /// Project path to resume from instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n },\n /// Save/bookmark the current or most recent session with a name.\n Save {\n /// Name for the session.\n name: String,\n /// Session ID to save (defaults to most recent).\n #[arg(long)]\n id: Option<String>,\n },\n /// Open or create notes for a session.\n Notes {\n /// Session name or ID.\n session: String,\n },\n /// Remove a saved session from tracking (doesn't delete the actual session).\n Remove {\n /// Session name or ID to remove.\n session: String,\n },\n /// Initialize .ai folder structure in current project.\n Init,\n /// Import all existing sessions for this project.\n Import,\n /// Copy session history to clipboard (fuzzy search to select).\n Copy {\n /// Session name or ID to copy (if not provided, shows fuzzy search).\n session: Option<String>,\n },\n /// Copy last Claude session to clipboard. Optionally search for a session containing text.\n #[command(name = \"copy-claude\", alias = \"cc\")]\n CopyClaude {\n /// Search for a session containing this text.\n #[arg(value_name = \"SEARCH\", trailing_var_arg = true)]\n search: Vec<String>,\n },\n /// Copy last Codex session to clipboard. Optionally search for a session containing text.\n #[command(name = \"copy-codex\", alias = \"cx\")]\n CopyCodex {\n /// Search for a session containing this text.\n #[arg(value_name = \"SEARCH\", trailing_var_arg = true)]\n search: Vec<String>,\n },\n /// Copy last prompt and response from a session to clipboard (for context passing).\n /// Usage: f ai context [session] [path] [count]\n Context {\n /// Session name or ID (if not provided, shows fuzzy search).\n session: Option<String>,\n /// Path to project directory (default: current directory).\n path: Option<String>,\n /// Number of exchanges to include (default: 1).\n #[arg(default_value = \"1\")]\n count: usize,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct AiEverrunsOpts {\n /// Prompt to send as a user message.\n #[arg(value_name = \"PROMPT\", trailing_var_arg = true)]\n pub prompt: Vec<String>,\n /// Reuse an existing Everruns session ID.\n #[arg(long)]\n pub session_id: Option<String>,\n /// Agent ID to use when creating a new session.\n #[arg(long)]\n pub agent_id: Option<String>,\n /// Harness ID to use when creating a new session.\n #[arg(long)]\n pub harness_id: Option<String>,\n /// Model ID override when creating a new session.\n #[arg(long)]\n pub model_id: Option<String>,\n /// Everruns API base URL (default: http://127.0.0.1:9300/api).\n #[arg(long)]\n pub base_url: Option<String>,\n /// Everruns API key (Bearer token). Prefer env var when possible.\n #[arg(long)]\n pub api_key: Option<String>,\n /// Poll interval for /events while waiting for completion.\n #[arg(long, default_value_t = 250)]\n pub poll_ms: u64,\n /// Max seconds to wait for output/tool cycles before timing out.\n #[arg(long, default_value_t = 120)]\n pub wait_timeout_secs: u64,\n /// Path to seqd Unix socket (default: $SEQ_SOCKET_PATH, then /tmp/seqd.sock).\n #[arg(long)]\n pub seq_socket: Option<PathBuf>,\n /// Read/write timeout for seqd RPC calls in milliseconds.\n #[arg(long, default_value_t = 5000)]\n pub seq_timeout_ms: u64,\n /// Do not inject seq client-side tool definitions when creating a new session.\n #[arg(long)]\n pub no_seq_tools: bool,\n}\n\n/// Provider-specific AI actions (for claude/codex subcommands).\n#[derive(Subcommand, Debug, Clone)]\npub enum ProviderAiAction {\n /// List sessions for this provider.\n #[command(alias = \"ls\")]\n List,\n /// Print the most recent session ID for this provider.\n #[command(name = \"latest-id\", alias = \"latest\")]\n LatestId {\n /// Project path to inspect instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n },\n /// List provider sessions with IDs.\n #[command(alias = \"sess\")]\n Sessions {\n /// Project path to inspect instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Continue the most recent session for this provider.\n Continue {\n /// Session name or ID to continue (optional).\n #[arg(value_name = \"SESSION\")]\n session: Option<String>,\n /// Project path to continue from instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n },\n /// Start a new session (ignores existing sessions).\n New,\n /// Resume a session.\n Resume {\n /// Session name or ID to resume.\n #[arg(value_name = \"SESSION\")]\n session: Option<String>,\n /// Project path to resume from instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n },\n /// Connect to an existing Codex session selected by natural-language query.\n #[command(alias = \"home\")]\n Connect {\n /// Project path or repo root to search instead of the configured Codex home-session path.\n #[arg(long, alias = \"repo\")]\n path: Option<String>,\n /// Restrict --path lookup to an exact cwd match instead of a repo-tree prefix.\n #[arg(long, requires = \"path\")]\n exact_cwd: bool,\n /// Emit machine-readable JSON for the selected session instead of resuming it.\n #[arg(long, alias = \"print\")]\n json: bool,\n /// Natural-language query describing the target session. Defaults to the latest session.\n #[arg(value_name = \"QUERY\", trailing_var_arg = true)]\n query: Vec<String>,\n },\n /// Open a Codex session with fast repo-scoped recovery and reference unrolling.\n Open {\n /// Project path to open from instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Restrict session lookup to an exact cwd match instead of a repo-tree prefix.\n #[arg(long, requires = \"path\")]\n exact_cwd: bool,\n /// Query or initial prompt.\n #[arg(value_name = \"QUERY\", trailing_var_arg = true)]\n query: Vec<String>,\n },\n /// Resolve how `f codex open` would interpret a query.\n Resolve {\n /// Project path to resolve from instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Restrict session lookup to an exact cwd match instead of a repo-tree prefix.\n #[arg(long, requires = \"path\")]\n exact_cwd: bool,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n /// Query or reference text to resolve.\n #[arg(value_name = \"QUERY\", trailing_var_arg = true)]\n query: Vec<String>,\n },\n /// Print effective Codex control-plane settings for this path.\n Doctor {\n /// Project path to inspect instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Exit non-zero unless wrapper transport and runtime skills are active.\n #[arg(long)]\n assert_runtime: bool,\n /// Exit non-zero unless the scheduled scorecard refresher is installed and loaded.\n #[arg(long)]\n assert_schedule: bool,\n /// Exit non-zero unless Flow has grounded learning data for this target.\n #[arg(long)]\n assert_learning: bool,\n /// Exit non-zero unless runtime, schedule, and grounded learning are all active.\n #[arg(long)]\n assert_autonomous: bool,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Evaluate how well Flow-guided Codex usage is working for this repo/path.\n Eval {\n /// Project path to inspect instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Maximum number of recent logged events/outcomes to inspect.\n #[arg(long, default_value = \"200\")]\n limit: usize,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Record a fast-path Codex launch and ensure supporting daemons are warm (internal).\n #[command(hide = true, name = \"touch-launch\")]\n TouchLaunch {\n /// Quick launch mode.\n #[arg(long, value_parser = [\"resume-last\", \"new\"])]\n mode: String,\n /// Working directory used for the launch.\n #[arg(long)]\n cwd: Option<String>,\n },\n /// Enable the global Codex wrapper/runtime path so Flow features are actually used.\n #[command(name = \"enable-global\")]\n EnableGlobal {\n /// Show the resulting global config and actions without writing anything.\n #[arg(long)]\n dry_run: bool,\n /// Also install the macOS launchd scorecard refresher.\n #[arg(long)]\n install_launchd: bool,\n /// Start codexd immediately after enabling the global config.\n #[arg(long)]\n start_daemon: bool,\n /// Sync any discovered external skill sources after enabling the config.\n #[arg(long)]\n sync_skills: bool,\n /// Shortcut for --install-launchd --start-daemon --sync-skills.\n #[arg(long)]\n full: bool,\n /// Launchd cadence in minutes (used with --install-launchd/--full).\n #[arg(long, default_value = \"30\")]\n minutes: usize,\n /// Max logged events to scan per launchd run.\n #[arg(long, default_value = \"400\")]\n limit: usize,\n /// Max repos to rebuild per launchd run.\n #[arg(long, default_value = \"12\")]\n max_targets: usize,\n /// Recent-history window for launchd cron selection.\n #[arg(long, default_value = \"168\")]\n within_hours: u64,\n },\n /// Manage the Flow codexd query daemon.\n Daemon {\n #[command(subcommand)]\n action: Option<CodexDaemonAction>,\n },\n /// Inspect or sync the Jazz2-backed Codex memory mirror.\n Memory {\n #[command(subcommand)]\n action: Option<CodexMemoryAction>,\n },\n /// Export redacted Codex workflow telemetry to configured Maple endpoints.\n Telemetry {\n #[command(subcommand)]\n action: Option<CodexTelemetryAction>,\n },\n /// Inspect Flow-managed Codex traces for the current or a specific session.\n Trace {\n #[command(subcommand)]\n action: Option<CodexTraceAction>,\n },\n /// Build and inspect local Codex skill scorecards from Flow history.\n #[command(name = \"skill-eval\")]\n SkillEval {\n #[command(subcommand)]\n action: Option<CodexSkillEvalAction>,\n },\n /// Discover and sync external Codex skill sources.\n #[command(name = \"skill-source\")]\n SkillSource {\n #[command(subcommand)]\n action: Option<CodexSkillSourceAction>,\n },\n /// Inspect or manage Flow-managed Codex runtime helpers.\n Runtime {\n #[command(subcommand)]\n action: Option<CodexRuntimeAction>,\n },\n /// Search Codex sessions by prompt text and resume the best match.\n #[command(alias = \"search\")]\n Find {\n /// Limit search to sessions from this path or repo subtree (default: all Codex sessions).\n #[arg(long)]\n path: Option<String>,\n /// Restrict --path lookup to an exact cwd instead of a repo-tree prefix.\n #[arg(long, requires = \"path\")]\n exact_cwd: bool,\n /// Prompt or transcript text to search for.\n #[arg(value_name = \"QUERY\", trailing_var_arg = true)]\n query: Vec<String>,\n },\n /// Search Codex sessions by prompt text and copy the best match to clipboard.\n #[command(name = \"findAndCopy\", alias = \"find-and-copy\", alias = \"find-copy\")]\n FindAndCopy {\n /// Limit search to sessions from this path or repo subtree (default: all Codex sessions).\n #[arg(long)]\n path: Option<String>,\n /// Restrict --path lookup to an exact cwd instead of a repo-tree prefix.\n #[arg(long, requires = \"path\")]\n exact_cwd: bool,\n /// Prompt or transcript text to search for.\n #[arg(value_name = \"QUERY\", trailing_var_arg = true)]\n query: Vec<String>,\n },\n /// Copy session history to clipboard.\n Copy {\n /// Session name or ID to copy.\n session: Option<String>,\n },\n /// Copy last prompt and response to clipboard (for context passing).\n /// Usage: f ai claude context [session] [path] [count]\n Context {\n /// Session name or ID to copy.\n session: Option<String>,\n /// Path to project directory (default: current directory).\n path: Option<String>,\n /// Number of exchanges to include (default: 1).\n #[arg(default_value = \"1\")]\n count: usize,\n },\n /// Print a cleaned session excerpt to stdout.\n Show {\n /// Session name or ID to print. Defaults to the latest session for --path/current dir.\n session: Option<String>,\n /// Path to project directory (default: current directory).\n #[arg(long)]\n path: Option<String>,\n /// Number of exchanges to include (default: 12).\n #[arg(long, default_value = \"12\", conflicts_with = \"full\")]\n count: usize,\n /// Print the full cleaned transcript instead of just the trailing exchanges.\n #[arg(long)]\n full: bool,\n },\n /// Recover recent Codex session context for a repo or subpath.\n Recover {\n /// Path to recover context for (default: current directory).\n #[arg(long)]\n path: Option<String>,\n /// Restrict lookup to an exact cwd match instead of a repo-tree prefix.\n #[arg(long)]\n exact_cwd: bool,\n /// Maximum number of candidate sessions to return.\n #[arg(long, default_value = \"3\")]\n limit: usize,\n /// Emit machine-readable JSON.\n #[arg(long, conflicts_with = \"summary_only\")]\n json: bool,\n /// Emit only the compact recovery summary for prompt injection.\n #[arg(long = \"summary-only\", conflicts_with = \"json\")]\n summary_only: bool,\n /// Optional query used to rank recent sessions.\n #[arg(value_name = \"QUERY\", trailing_var_arg = true)]\n query: Vec<String>,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum CodexDaemonAction {\n /// Start codexd under Flow supervision.\n Start,\n /// Stop codexd.\n Stop,\n /// Restart codexd.\n Restart,\n /// Show codexd status.\n Status,\n /// Run codexd in the foreground (internal).\n #[command(hide = true)]\n Serve {\n /// Override the codexd socket path.\n #[arg(long)]\n socket: Option<PathBuf>,\n },\n /// Ping codexd and exit non-zero if unavailable (internal).\n #[command(hide = true)]\n Ping,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum CodexMemoryAction {\n /// Show memory mirror status and counts.\n Status {\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Sync recent Codex skill-eval logs into the Jazz2-backed memory mirror.\n Sync {\n /// Maximum number of recent events and outcomes to ingest.\n #[arg(long, default_value = \"400\")]\n limit: usize,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Query compact repo/code memory facts for a path.\n Query {\n /// Project path or repo root to query.\n #[arg(long)]\n path: Option<String>,\n /// Maximum number of fact hits to include.\n #[arg(long, default_value = \"6\")]\n limit: usize,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n /// Query text to rank facts.\n #[arg(value_name = \"QUERY\", trailing_var_arg = true)]\n query: Vec<String>,\n },\n /// Show recent memory rows, optionally scoped to a repo/path.\n Recent {\n /// Project path to inspect instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Maximum number of rows to print.\n #[arg(long, default_value = \"12\")]\n limit: usize,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum CodexTelemetryAction {\n /// Show Codex telemetry export config and current forwarder state.\n Status {\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Flush recently logged Codex telemetry to configured Maple endpoints once.\n Flush {\n /// Maximum number of unseen events/outcomes to export in one pass.\n #[arg(long, default_value = \"200\")]\n limit: usize,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum CodexTraceAction {\n /// Show Maple trace read status and configured credentials.\n Status {\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Inspect the trace associated with the active Flow-managed Codex session.\n #[command(name = \"current-session\")]\n CurrentSession {\n /// Flush recent Flow Codex telemetry before inspecting the trace.\n #[arg(long, default_value_t = true)]\n flush: bool,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Inspect a specific trace id.\n Inspect {\n /// Trace id to inspect.\n trace_id: String,\n /// Flush recent Flow Codex telemetry before inspecting the trace.\n #[arg(long, default_value_t = true)]\n flush: bool,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum CodexSkillEvalAction {\n /// Rebuild the local scorecard for this repo/path from recent Flow Codex history.\n Run {\n /// Project path to inspect instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Maximum number of recent events to use when rebuilding.\n #[arg(long, default_value = \"200\")]\n limit: usize,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Show the current scorecard for this repo/path.\n Show {\n /// Project path to inspect instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Show recent logged skill-eval events.\n Events {\n /// Project path to inspect instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Maximum number of events to print.\n #[arg(long, default_value = \"12\")]\n limit: usize,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Refresh scorecards for the most recent repos seen in Flow Codex history.\n Cron {\n /// Maximum number of logged events to scan for target repos.\n #[arg(long, default_value = \"400\")]\n limit: usize,\n /// Maximum number of repo targets to rebuild in one pass.\n #[arg(long, default_value = \"12\")]\n max_targets: usize,\n /// Only consider repos seen within this many recent hours.\n #[arg(long, default_value = \"168\")]\n within_hours: u64,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum CodexSkillSourceAction {\n /// List discovered external skills available for Codex runtime injection.\n List {\n /// Project path to inspect instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Copy discovered external skills into ~/.codex/skills for persistent use.\n Sync {\n /// Project path to inspect instead of the current directory.\n #[arg(long)]\n path: Option<String>,\n /// Restrict sync to the named discovered skills.\n #[arg(long = \"skill\")]\n skills: Vec<String>,\n /// Overwrite an existing ~/.codex/skills/<name> directory.\n #[arg(long)]\n force: bool,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum CodexRuntimeAction {\n /// Show recent Flow-managed Codex runtime skill activations.\n Show,\n /// Remove Flow-managed runtime skill state and stale symlinks.\n Clear,\n /// Write a markdown plan to ~/plan and print the final path.\n WritePlan {\n /// Human-readable title used to derive the filename.\n #[arg(long)]\n title: Option<String>,\n /// Explicit filename stem to use instead of deriving from the title.\n #[arg(long)]\n stem: Option<String>,\n /// Destination directory (defaults to ~/plan).\n #[arg(long)]\n dir: Option<String>,\n /// Codex session id to append as a footer (defaults to $CODEX_THREAD_ID).\n #[arg(long)]\n source_session: Option<String>,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct EnvCommand {\n #[command(subcommand)]\n pub action: Option<EnvAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct AuthOpts {\n /// Override API base URL for myflow (defaults to https://myflow.sh).\n #[arg(long)]\n pub api_url: Option<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ServicesCommand {\n #[command(subcommand)]\n pub action: Option<ServicesAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct PushCommand {\n /// Git remote name to push to (default: origin).\n #[arg(long, default_value = \"origin\")]\n pub remote: String,\n /// Owner/org for the mirror repo (overrides FLOW_PUSH_OWNER / personal env store).\n #[arg(long)]\n pub owner: Option<String>,\n /// Override repo name (defaults to upstream/origin repo name or folder name).\n #[arg(long)]\n pub repo: Option<String>,\n /// Create the target repo if it does not exist (requires `gh` auth).\n #[arg(long)]\n pub create_repo: bool,\n /// Overwrite an existing remote URL when it points elsewhere.\n #[arg(long)]\n pub force: bool,\n /// Do not attempt to unlock Flow-managed SSH key before pushing.\n #[arg(long)]\n pub no_ssh: bool,\n /// TTL (hours) for Flow SSH key unlock (default: 24).\n #[arg(long, default_value = \"24\")]\n pub ttl_hours: u64,\n /// Print what would be done without changing remotes or pushing.\n #[arg(long)]\n pub dry_run: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SshCommand {\n #[command(subcommand)]\n pub action: Option<SshAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum EnvAction {\n /// Sync project settings and set up autonomous agent workflow.\n Sync,\n /// Unlock env read access (Touch ID on macOS).\n Unlock,\n /// Create a new env token from available templates.\n New,\n /// Authenticate with cloud to fetch env vars.\n Login,\n /// Fetch env vars from cloud and write to .env.\n Pull {\n /// Environment to fetch (dev, staging, production).\n #[arg(short, long, default_value = \"production\")]\n environment: String,\n },\n /// Push local .env to cloud.\n Push {\n /// Environment to push to (dev, staging, production).\n #[arg(short, long, default_value = \"production\")]\n environment: String,\n },\n /// Guided prompt to set required env vars from flow.toml.\n Guide {\n /// Environment to set in (dev, staging, production).\n #[arg(short, long, default_value = \"production\")]\n environment: String,\n },\n /// Apply env vars from cloud to the configured Cloudflare worker.\n Apply,\n /// Bootstrap Cloudflare secrets from flow.toml (interactive).\n Bootstrap,\n /// Interactive env setup (uses flow.toml when configured).\n Setup {\n /// Optional .env file path to preselect.\n #[arg(short = 'f', long)]\n env_file: Option<PathBuf>,\n /// Optional environment to preselect.\n #[arg(short, long)]\n environment: Option<String>,\n },\n /// List env vars for this project.\n #[command(alias = \"ls\")]\n List {\n /// Environment to list (dev, staging, production).\n #[arg(short, long, default_value = \"production\")]\n environment: String,\n },\n /// Set a personal env var (default backend).\n Set {\n /// KEY=VALUE pair to set.\n pair: String,\n /// Compatibility flag (ignored; set always targets personal env).\n #[arg(long)]\n personal: bool,\n },\n /// Delete personal env var(s).\n Delete {\n /// Key(s) to delete.\n keys: Vec<String>,\n },\n /// Manage project-scoped env vars.\n Project {\n #[command(subcommand)]\n action: ProjectEnvAction,\n },\n /// Show current auth status.\n Status,\n /// Get specific env var(s) and print to stdout.\n Get {\n /// Key(s) to fetch.\n keys: Vec<String>,\n /// Fetch from personal env vars instead of project.\n #[arg(long)]\n personal: bool,\n /// Environment to fetch from (dev, staging, production).\n #[arg(short, long, default_value = \"production\")]\n environment: String,\n /// Output format: env (KEY=VALUE), json, or value (just the value, single key only).\n #[arg(short, long, default_value = \"env\")]\n format: String,\n },\n /// Run a command with env vars injected from cloud.\n Run {\n /// Fetch from personal env vars instead of project.\n #[arg(long)]\n personal: bool,\n /// Environment to fetch from (dev, staging, production).\n #[arg(short, long, default_value = \"production\")]\n environment: String,\n /// Specific keys to inject (if empty, injects all).\n #[arg(long, short = 'k')]\n keys: Vec<String>,\n /// Command and arguments to run.\n #[arg(trailing_var_arg = true, required = true)]\n command: Vec<String>,\n },\n /// Show configured env keys from flow.toml.\n Keys,\n /// Manage service tokens for host deployments.\n Token {\n #[command(subcommand)]\n action: TokenAction,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ServicesAction {\n /// Set up Stripe env vars with guided prompts.\n Stripe(StripeServiceOpts),\n /// List available service setup flows.\n #[command(alias = \"ls\")]\n List,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct MacosCommand {\n #[command(subcommand)]\n pub action: Option<MacosAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum MacosAction {\n /// List all launchd services.\n #[command(alias = \"ls\")]\n List(MacosListOpts),\n /// Show running non-Apple services.\n Status,\n /// Audit services with recommendations.\n Audit(MacosAuditOpts),\n /// Show detailed info about a service.\n Info(MacosInfoOpts),\n /// Disable a service.\n Disable(MacosDisableOpts),\n /// Enable a service.\n Enable(MacosEnableOpts),\n /// Disable known bloatware services.\n Clean(MacosCleanOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct MacosListOpts {\n /// Only show user agents.\n #[arg(long)]\n pub user: bool,\n /// Only show system agents/daemons.\n #[arg(long)]\n pub system: bool,\n /// Output as JSON.\n #[arg(long)]\n pub json: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct MacosAuditOpts {\n /// Output as JSON.\n #[arg(long)]\n pub json: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct MacosInfoOpts {\n /// Service identifier (e.g., com.google.keystone.agent).\n pub service: String,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct MacosDisableOpts {\n /// Service identifier to disable.\n pub service: String,\n /// Skip confirmation prompt.\n #[arg(short = 'y', long)]\n pub yes: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct MacosEnableOpts {\n /// Service identifier to enable.\n pub service: String,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct MacosCleanOpts {\n /// Only show what would be done.\n #[arg(long)]\n pub dry_run: bool,\n /// Skip confirmation prompt.\n #[arg(short = 'y', long)]\n pub yes: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct StripeServiceOpts {\n /// Path to the project root (defaults to current directory).\n #[arg(short, long)]\n pub path: Option<PathBuf>,\n /// Environment to store vars in (dev, staging, production).\n #[arg(short, long)]\n pub environment: Option<String>,\n /// Stripe mode (test or live).\n #[arg(long, value_enum, default_value_t = StripeModeArg::Test)]\n pub mode: StripeModeArg,\n /// Prompt even if keys are already set.\n #[arg(long)]\n pub force: bool,\n /// Apply env vars to Cloudflare after setting them.\n #[arg(long, conflicts_with = \"no_apply\")]\n pub apply: bool,\n /// Skip applying env vars to Cloudflare.\n #[arg(long, conflicts_with = \"apply\")]\n pub no_apply: bool,\n}\n\n#[derive(ValueEnum, Debug, Clone, Copy)]\npub enum StripeModeArg {\n Test,\n Live,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum SshAction {\n /// Generate a new SSH keypair and store it in cloud personal env vars.\n Setup {\n /// Optional key name (default: \"default\").\n #[arg(long, default_value = \"default\")]\n name: String,\n /// Skip automatically unlocking the key after setup.\n #[arg(long)]\n no_unlock: bool,\n },\n /// Unlock the SSH key from cloud and load it into the Flow SSH agent.\n Unlock {\n /// Optional key name (default: \"default\").\n #[arg(long, default_value = \"default\")]\n name: String,\n /// TTL for ssh-agent in hours (default: 24).\n #[arg(long, default_value = \"24\")]\n ttl_hours: u64,\n },\n /// Show whether the Flow SSH agent and key are available.\n Status {\n /// Optional key name (default: \"default\").\n #[arg(long, default_value = \"default\")]\n name: String,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum TokenAction {\n /// Create a new service token for a project.\n Create {\n /// Token name (e.g., \"pulse-production\").\n #[arg(short, long)]\n name: Option<String>,\n /// Permissions: read, write, or admin.\n #[arg(short, long, default_value = \"read\")]\n permissions: String,\n },\n /// List service tokens.\n #[command(alias = \"ls\")]\n List,\n /// Revoke a service token.\n Revoke {\n /// Token name to revoke.\n name: String,\n },\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ProjectEnvAction {\n /// Set a project-scoped env var.\n Set {\n /// KEY=VALUE pair to set.\n pair: String,\n /// Environment (dev, staging, production).\n #[arg(short, long, default_value = \"production\")]\n environment: String,\n },\n /// Delete project-scoped env var(s).\n Delete {\n /// Key(s) to delete.\n keys: Vec<String>,\n /// Environment (dev, staging, production).\n #[arg(short, long, default_value = \"production\")]\n environment: String,\n },\n /// List project env vars.\n #[command(alias = \"ls\")]\n List {\n /// Environment (dev, staging, production).\n #[arg(short, long, default_value = \"production\")]\n environment: String,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct TodoCommand {\n #[command(subcommand)]\n pub action: Option<TodoAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ExtCommand {\n /// Path to the external directory to move.\n pub path: String,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum TodoAction {\n /// Open the project Bike file.\n Bike,\n /// Add a new todo.\n Add {\n /// Short title for the todo.\n title: String,\n /// Optional note to store with the todo.\n #[arg(short, long)]\n note: Option<String>,\n /// Attach a specific AI session reference (provider:session_id).\n #[arg(long, conflicts_with = \"no_session\")]\n session: Option<String>,\n /// Skip attaching the most recent AI session.\n #[arg(long)]\n no_session: bool,\n /// Initial status (pending, in-progress, completed, blocked).\n #[arg(short, long, value_enum, default_value_t = TodoStatusArg::Pending)]\n status: TodoStatusArg,\n },\n /// List todos (active by default).\n #[command(alias = \"ls\")]\n List {\n /// Include completed todos.\n #[arg(long)]\n all: bool,\n },\n /// Mark a todo as completed.\n Done {\n /// Todo id (full or prefix).\n id: String,\n },\n /// Edit a todo.\n Edit {\n /// Todo id (full or prefix).\n id: String,\n /// Update the title.\n #[arg(short, long)]\n title: Option<String>,\n /// Update the status.\n #[arg(short, long, value_enum)]\n status: Option<TodoStatusArg>,\n /// Update the note (empty clears).\n #[arg(short, long)]\n note: Option<String>,\n },\n /// Remove a todo.\n Remove {\n /// Todo id (full or prefix).\n id: String,\n },\n}\n\n#[derive(ValueEnum, Debug, Clone, Copy)]\npub enum TodoStatusArg {\n Pending,\n #[value(alias = \"in_progress\")]\n InProgress,\n Completed,\n Blocked,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DepsCommand {\n #[command(subcommand)]\n pub action: Option<DepsAction>,\n /// Force a package manager instead of auto-detect.\n #[arg(long, value_enum)]\n pub manager: Option<DepsManager>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum DepsAction {\n /// Install dependencies.\n Install {\n /// Extra args to pass to the package manager.\n #[arg(trailing_var_arg = true)]\n args: Vec<String>,\n },\n /// Smart dependency updates based on inferred ecosystem.\n Update(UpdateDepsOpts),\n /// Fuzzy-pick a dependency or linked repo and fetch it to ~/repos.\n #[command(alias = \"pick\", alias = \"find\", alias = \"search\")]\n Pick,\n /// Add an external repo dependency and link it under .ai/repos.\n Repo {\n /// Repository URL, owner/repo, or repo name (searches ~/repos).\n repo: String,\n /// Root directory for clones (default: ~/repos).\n #[arg(long, default_value = \"~/repos\")]\n root: String,\n /// Create a private fork in your GitHub account and set origin.\n #[arg(long, alias = \"private-origin\")]\n private: bool,\n },\n}\n\n#[derive(ValueEnum, Debug, Clone, Copy)]\npub enum DepsManager {\n Pnpm,\n Npm,\n Yarn,\n Bun,\n}\n\n#[derive(ValueEnum, Debug, Clone, Copy, Eq, PartialEq)]\npub enum DepsEcosystem {\n Js,\n Rust,\n Go,\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct UpdateDepsOpts {\n /// Upgrade to latest versions when supported by ecosystem tooling.\n #[arg(long)]\n pub latest: bool,\n /// Print planned commands without executing them.\n #[arg(long)]\n pub dry_run: bool,\n /// Skip confirmation prompt.\n #[arg(short = 'y', long)]\n pub yes: bool,\n /// Disable OpenTUI confirmation and use plain prompt.\n #[arg(long)]\n pub no_tui: bool,\n /// Force a specific ecosystem instead of auto-detect.\n #[arg(long, value_enum)]\n pub ecosystem: Option<DepsEcosystem>,\n /// Force JS package manager (only used for js ecosystem).\n #[arg(long, value_enum)]\n pub manager: Option<DepsManager>,\n /// Extra arguments passed through to ecosystem update commands.\n #[arg(trailing_var_arg = true)]\n pub args: Vec<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SkillsCommand {\n #[command(subcommand)]\n pub action: Option<SkillsAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum SkillsAction {\n /// List all skills for this project.\n #[command(alias = \"ls\")]\n List,\n /// Create a new skill.\n New {\n /// Skill name (kebab-case recommended).\n name: String,\n /// Short description of what the skill does.\n #[arg(short, long)]\n description: Option<String>,\n },\n /// Show skill details.\n Show {\n /// Skill name.\n name: String,\n },\n /// Edit a skill in your editor.\n Edit {\n /// Skill name.\n name: String,\n },\n /// Remove a skill.\n Remove {\n /// Skill name.\n name: String,\n },\n /// Install a curated skill from the registry.\n Install {\n /// Skill name to install.\n name: String,\n },\n /// Publish a local skill to the shared registry.\n Publish {\n /// Skill name to publish.\n name: String,\n },\n /// Search for skills in the remote registry.\n Search {\n /// Search query (optional).\n query: Option<String>,\n },\n /// Sync flow.toml tasks as skills.\n Sync,\n /// Force Codex app-server to rescan skills from disk for this cwd.\n Reload,\n /// Fetch dependency skills via seq scraper integration.\n Fetch(SkillsFetchCommand),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SkillsFetchCommand {\n #[command(subcommand)]\n pub action: SkillsFetchAction,\n /// Path to seq repo (default: ~/code/seq).\n #[arg(long)]\n pub seq_repo: Option<String>,\n /// Path to seq teach script (overrides --seq-repo).\n #[arg(long)]\n pub script_path: Option<String>,\n /// Scraper daemon/API base URL.\n #[arg(long)]\n pub scraper_base_url: Option<String>,\n /// Scraper API token.\n #[arg(long)]\n pub scraper_api_key: Option<String>,\n /// Output directory for generated skills (relative to repo root).\n #[arg(long)]\n pub out_dir: Option<String>,\n /// Cache TTL in hours for scraper responses.\n #[arg(long)]\n pub cache_ttl_hours: Option<f64>,\n /// Allow direct fetch fallback when scraper queue/api is unavailable.\n #[arg(long)]\n pub allow_direct_fallback: bool,\n /// Disable seq.mem JSON event emission.\n #[arg(long)]\n pub no_mem_events: bool,\n /// Override seq.mem JSONEachRow path.\n #[arg(long)]\n pub mem_events_path: Option<String>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum SkillsFetchAction {\n /// Generate skills for one or more dependencies.\n Dep {\n /// Dependency names.\n deps: Vec<String>,\n /// Force ecosystem for all deps.\n #[arg(long)]\n ecosystem: Option<String>,\n /// Bypass cache and scrape fresh.\n #[arg(long)]\n force: bool,\n },\n /// Auto-discover dependencies from manifests and generate skills.\n Auto {\n /// Max dependencies per ecosystem.\n #[arg(long)]\n top: Option<usize>,\n /// Comma-separated ecosystem list (npm,pypi,cargo,swift).\n #[arg(long)]\n ecosystems: Option<String>,\n /// Bypass cache and scrape fresh.\n #[arg(long)]\n force: bool,\n },\n /// Generate skills from one or more URLs.\n Url {\n /// URLs to scrape.\n urls: Vec<String>,\n /// Skill name override.\n #[arg(long)]\n name: Option<String>,\n /// Bypass cache and scrape fresh.\n #[arg(long)]\n force: bool,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct UrlCommand {\n #[command(subcommand)]\n pub action: UrlAction,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum UrlAction {\n /// Inspect a URL and return a compact normalized summary.\n Inspect(UrlInspectOpts),\n /// Crawl a site and return a compact multi-page summary.\n Crawl(UrlCrawlOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct UrlInspectOpts {\n /// URL to inspect.\n pub url: String,\n /// Print machine-readable JSON.\n #[arg(long)]\n pub json: bool,\n /// Include the full markdown/content body when available.\n #[arg(long)]\n pub full: bool,\n /// Provider to use. `auto` tries Cloudflare first, then scraper, then direct fetch.\n #[arg(long, value_enum, default_value = \"auto\")]\n pub provider: UrlInspectProvider,\n /// Request timeout in seconds.\n #[arg(long, default_value_t = 20.0)]\n pub timeout_s: f64,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct UrlCrawlOpts {\n /// Starting URL to crawl.\n pub url: String,\n /// Print machine-readable JSON.\n #[arg(long)]\n pub json: bool,\n /// Include full markdown for returned records.\n #[arg(long)]\n pub full: bool,\n /// Maximum number of pages to crawl.\n #[arg(long, default_value_t = 10)]\n pub limit: usize,\n /// Maximum crawl depth from the starting URL.\n #[arg(long, default_value_t = 2)]\n pub depth: usize,\n /// Maximum number of completed records to return in the final summary.\n #[arg(long, default_value_t = 5)]\n pub records: usize,\n /// Crawl source: all discovered URLs, only sitemaps, or only links.\n #[arg(long, value_enum, default_value = \"all\")]\n pub source: UrlCrawlSource,\n /// Render pages in a browser before extraction. Disabled by default for faster static crawls.\n #[arg(long, default_value_t = false)]\n pub render: bool,\n /// Include external links during crawl.\n #[arg(long)]\n pub include_external_links: bool,\n /// Include subdomains during crawl.\n #[arg(long)]\n pub include_subdomains: bool,\n /// Only include URLs matching these wildcard patterns.\n #[arg(long = \"include-pattern\")]\n pub include_patterns: Vec<String>,\n /// Exclude URLs matching these wildcard patterns.\n #[arg(long = \"exclude-pattern\")]\n pub exclude_patterns: Vec<String>,\n /// Max crawl cache age in seconds.\n #[arg(long)]\n pub max_age_s: Option<u64>,\n /// Max time to wait for crawl completion in seconds.\n #[arg(long, default_value_t = 60.0)]\n pub wait_timeout_s: f64,\n /// Poll interval while waiting for completion, in seconds.\n #[arg(long, default_value_t = 2.0)]\n pub poll_interval_s: f64,\n}\n\n#[derive(ValueEnum, Debug, Clone, Copy, PartialEq, Eq)]\npub enum UrlInspectProvider {\n Auto,\n Cloudflare,\n Scraper,\n Direct,\n}\n\n#[derive(ValueEnum, Debug, Clone, Copy, PartialEq, Eq)]\npub enum UrlCrawlSource {\n All,\n Sitemaps,\n Links,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ToolsCommand {\n #[command(subcommand)]\n pub action: Option<ToolsAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ToolsAction {\n /// List all tools for this project.\n #[command(alias = \"ls\")]\n List,\n /// Run a tool.\n Run {\n /// Tool name (without .ts extension).\n name: String,\n /// Arguments to pass to the tool.\n #[arg(trailing_var_arg = true)]\n args: Vec<String>,\n },\n /// Create a new tool.\n New {\n /// Tool name (kebab-case recommended).\n name: String,\n /// Short description of what the tool does.\n #[arg(short, long)]\n description: Option<String>,\n /// Use AI (localcode) to generate the tool implementation.\n #[arg(long)]\n ai: bool,\n },\n /// Edit a tool in your editor.\n Edit {\n /// Tool name.\n name: String,\n },\n /// Remove a tool.\n Remove {\n /// Tool name.\n name: String,\n },\n}\n\n#[derive(Args, Debug, Clone)]\n#[command(args_conflicts_with_subcommands = true)]\npub struct AgentsCommand {\n #[command(subcommand)]\n pub action: Option<AgentsAction>,\n /// Run a global agent directly (e.g., `f agents explore`).\n #[arg(trailing_var_arg = true)]\n pub agent: Vec<String>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum AgentsAction {\n /// List available agents.\n #[command(alias = \"ls\")]\n List,\n /// Run an agent with a prompt.\n Run {\n /// Agent name (flow, codify, explore, general).\n agent: String,\n /// Prompt for the agent.\n #[arg(trailing_var_arg = true)]\n prompt: Vec<String>,\n },\n /// Run a global agent (prompt optional).\n #[command(alias = \"g\")]\n Global {\n /// Global agent name.\n agent: String,\n /// Optional custom prompt (uses default if not provided).\n #[arg(trailing_var_arg = true)]\n prompt: Option<Vec<String>>,\n },\n /// Copy agent instructions to clipboard (fuzzy select).\n #[command(alias = \"cp\")]\n Copy {\n /// Optional agent name (fuzzy select if not provided).\n agent: Option<String>,\n },\n /// Switch agents.md profile (fuzzy select if not provided).\n Rules {\n /// Optional profile name (e.g., light).\n profile: Option<String>,\n /// Optional repo path (defaults to cwd).\n repo: Option<String>,\n },\n}\n\n/// Hive agent management.\n#[derive(Args, Debug, Clone)]\npub struct HiveCommand {\n #[command(subcommand)]\n pub action: Option<HiveAction>,\n /// Run an agent directly (e.g., `f hive fish \"wrap ls\"`).\n #[arg(trailing_var_arg = true)]\n pub agent: Vec<String>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum HiveAction {\n /// List available hive agents.\n #[command(alias = \"ls\")]\n List,\n /// Run a hive agent with a prompt.\n Run {\n /// Agent name.\n agent: String,\n /// Prompt for the agent.\n #[arg(trailing_var_arg = true)]\n prompt: Vec<String>,\n },\n /// Create a new agent spec.\n New {\n /// Agent name.\n name: String,\n /// Create as global agent (default: project-local).\n #[arg(short, long)]\n global: bool,\n },\n /// Edit an agent spec file.\n Edit {\n /// Agent name (fuzzy select if not provided).\n agent: Option<String>,\n },\n /// Show an agent's spec.\n Show {\n /// Agent name.\n agent: String,\n },\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct PublishOpts {\n /// GitHub repository URL (e.g., https://github.com/org/repo or git@github.com:org/repo.git).\n #[arg(value_name = \"URL\")]\n pub url: Option<String>,\n /// Repository name (defaults to current folder name).\n #[arg(short, long)]\n pub name: Option<String>,\n /// Repository owner/org (GitHub) or owner (gitedit.dev).\n #[arg(long)]\n pub owner: Option<String>,\n /// Update existing origin remote to match the target repo (GitHub).\n #[arg(long)]\n pub set_origin: bool,\n /// Make the repository public.\n #[arg(long)]\n pub public: bool,\n /// Make the repository private.\n #[arg(long)]\n pub private: bool,\n /// Description for the repository.\n #[arg(short, long)]\n pub description: Option<String>,\n /// Skip confirmation prompts.\n #[arg(short, long)]\n pub yes: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct PublishCommand {\n #[command(subcommand)]\n pub action: Option<PublishAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct CloneOpts {\n /// Repository URL or owner/repo.\n pub url: String,\n /// Optional destination directory (same as git clone <url> <dir>).\n pub directory: Option<String>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum PublishAction {\n /// Publish to gitedit.dev.\n Gitedit(PublishOpts),\n /// Publish to GitHub.\n Github(PublishOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ReposCommand {\n #[command(subcommand)]\n pub action: Option<ReposAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct CodeCommand {\n #[command(subcommand)]\n pub action: Option<CodeAction>,\n /// Root directory to scan (default: ~/code).\n #[arg(long, default_value = \"~/code\")]\n pub root: String,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum CodeAction {\n /// List git repos under ~/code.\n List,\n /// Create a new project from a template in ~/new/<name>.\n New(CodeNewOpts),\n /// Move a folder into ~/code/<relative-path> and migrate AI sessions.\n Migrate(CodeMigrateOpts),\n /// Move AI sessions when a project path changes.\n MoveSessions(CodeMoveSessionsOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct CodeNewOpts {\n /// Template name under ~/new (e.g., \"docs\").\n pub template: String,\n /// Destination folder name or relative path under the code root.\n pub name: String,\n /// Add the new path to .gitignore in the containing repo.\n #[arg(long)]\n pub ignored: bool,\n /// Show what would change without writing.\n #[arg(long)]\n pub dry_run: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct CodeMigrateOpts {\n /// Source folder to migrate.\n pub from: String,\n /// Relative path under the code root (e.g., \"flow/myflow\").\n pub relative: String,\n /// Copy instead of move (keeps original).\n #[arg(long, short)]\n pub copy: bool,\n /// Show what would change without writing.\n #[arg(long)]\n pub dry_run: bool,\n /// Skip migrating Claude sessions.\n #[arg(long)]\n pub skip_claude: bool,\n /// Skip migrating Codex sessions.\n #[arg(long)]\n pub skip_codex: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct CodeMoveSessionsOpts {\n /// Old project path.\n #[arg(long)]\n pub from: String,\n /// New project path.\n #[arg(long)]\n pub to: String,\n /// Show what would change without writing.\n #[arg(long)]\n pub dry_run: bool,\n /// Skip migrating Claude sessions.\n #[arg(long)]\n pub skip_claude: bool,\n /// Skip migrating Codex sessions.\n #[arg(long)]\n pub skip_codex: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct MigrateCommand {\n #[command(subcommand)]\n pub action: Option<MigrateAction>,\n /// Source path (defaults to current directory if only one path given).\n pub source: Option<String>,\n /// Target path (if source is given, this is the destination).\n pub target: Option<String>,\n /// Copy instead of move (keeps original).\n #[arg(long, short)]\n pub copy: bool,\n /// Show what would change without writing.\n #[arg(long)]\n pub dry_run: bool,\n /// Skip migrating Claude sessions.\n #[arg(long)]\n pub skip_claude: bool,\n /// Skip migrating Codex sessions.\n #[arg(long)]\n pub skip_codex: bool,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum MigrateAction {\n /// Move or copy current folder to ~/code/<relative-path>.\n Code(MigrateCodeOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct MigrateCodeOpts {\n /// Relative path under ~/code (e.g., \"flow/myflow\").\n pub relative: String,\n /// Copy instead of move (keeps original).\n #[arg(long, short)]\n pub copy: bool,\n /// Show what would change without writing.\n #[arg(long)]\n pub dry_run: bool,\n /// Skip migrating Claude sessions.\n #[arg(long)]\n pub skip_claude: bool,\n /// Skip migrating Codex sessions.\n #[arg(long)]\n pub skip_codex: bool,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ReposAction {\n /// Clone a repository into ~/repos/<owner>/<repo>.\n Clone(ReposCloneOpts),\n /// Create a GitHub repository from the current folder and push it.\n Create(PublishOpts),\n /// Build or inspect a compact repo capsule for path-based Codex context.\n Capsule(RepoCapsuleOpts),\n /// Manage repo aliases used by Codex repo-reference resolution.\n Alias(RepoAliasCommand),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ReposCloneOpts {\n /// Repository URL or owner/repo.\n pub url: String,\n /// Root directory for clones (default: ~/repos).\n #[arg(long, default_value = \"~/repos\")]\n pub root: String,\n /// Perform a full clone (skip shallow clone + background history fetch).\n #[arg(long)]\n pub full: bool,\n /// Skip automatic upstream setup for forks.\n #[arg(long)]\n pub no_upstream: bool,\n /// Upstream URL override (defaults to fork parent via gh).\n #[arg(short = 'u', long)]\n pub upstream_url: Option<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct RepoCapsuleOpts {\n /// Repo or project path to inspect (defaults to the current directory).\n #[arg(long)]\n pub path: Option<String>,\n /// Force a fresh capsule rebuild before printing.\n #[arg(long)]\n pub refresh: bool,\n /// Emit machine-readable JSON.\n #[arg(long)]\n pub json: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct RepoAliasCommand {\n #[command(subcommand)]\n pub action: Option<RepoAliasAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum RepoAliasAction {\n /// List registered repo aliases.\n #[command(alias = \"ls\")]\n List {\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Register or update an alias for a repo path.\n Set {\n /// Alias name to register.\n alias: String,\n /// Repo or project path for this alias.\n path: String,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n /// Remove a registered alias.\n Remove {\n /// Alias name to remove.\n alias: String,\n },\n /// Import aliases from Shelf config.\n #[command(name = \"import-shelf\")]\n ImportShelf {\n /// Override the Shelf config path (default: ~/.agents/shelf/config.json).\n #[arg(long)]\n config: Option<String>,\n /// Emit machine-readable JSON.\n #[arg(long)]\n json: bool,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SyncCommand {\n /// Use rebase instead of merge when pulling.\n #[arg(long, short)]\n pub rebase: bool,\n /// Push to configured git remote after sync (default: false).\n #[arg(long)]\n pub push: bool,\n /// Skip pushing to configured git remote (legacy; default is already no push).\n #[arg(long, overrides_with = \"push\")]\n pub no_push: bool,\n /// Auto-stash uncommitted changes (default: true).\n #[arg(long, short, default_value = \"true\")]\n pub stash: bool,\n /// Stash local JJ commits to a bookmark before syncing (JJ-only).\n #[arg(long, default_value = \"false\")]\n pub stash_commits: bool,\n /// Allow sync/rebase even when commit queue is non-empty.\n #[arg(long)]\n pub allow_queue: bool,\n /// Create origin repo on GitHub if it doesn't exist.\n #[arg(long)]\n pub create_repo: bool,\n /// Auto-fix conflicts and errors using Claude (default: true).\n #[arg(long, short, default_value = \"true\", action = clap::ArgAction::Set)]\n pub fix: bool,\n /// Disable auto-fix (same as --fix=false).\n #[arg(long, overrides_with = \"fix\")]\n pub no_fix: bool,\n /// Maximum fix attempts before giving up.\n #[arg(long, default_value = \"3\")]\n pub max_fix_attempts: u32,\n /// Allow push even if P1/P2 review todos are open.\n #[arg(long)]\n pub allow_review_issues: bool,\n /// Reduce sync output noise (show remote update counts without commit line listings).\n #[arg(long)]\n pub compact: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SwitchCommand {\n /// Branch name, PR number (for example: 123 or #123), or PR URL.\n pub branch: String,\n /// Preferred remote to track from (default: upstream, then origin).\n #[arg(long)]\n pub remote: Option<String>,\n /// Auto-preserve a safety snapshot branch/bookmark before switching (default: true).\n #[arg(long, default_value = \"true\", action = clap::ArgAction::Set)]\n pub preserve: bool,\n /// Disable safety snapshot preservation (same as --preserve=false).\n #[arg(long, overrides_with = \"preserve\")]\n pub no_preserve: bool,\n /// Auto-stash uncommitted changes before switching (default: true).\n #[arg(long, default_value = \"true\", action = clap::ArgAction::Set)]\n pub stash: bool,\n /// Disable auto-stash (same as --stash=false).\n #[arg(long, overrides_with = \"stash\")]\n pub no_stash: bool,\n /// Run sync after switching (uses --no-push).\n #[arg(long)]\n pub sync: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct CheckoutCommand {\n /// PR URL, PR number, or branch accepted by `gh pr checkout`.\n pub target: String,\n /// Preferred remote to use when checking out a PR branch.\n #[arg(long)]\n pub remote: Option<String>,\n /// Auto-stash uncommitted changes before checkout (default: true).\n #[arg(long, default_value = \"true\", action = clap::ArgAction::Set)]\n pub stash: bool,\n /// Disable auto-stash (same as --stash=false).\n #[arg(long, overrides_with = \"stash\")]\n pub no_stash: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct UpstreamCommand {\n #[command(subcommand)]\n pub action: Option<UpstreamAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum UpstreamAction {\n /// Show current upstream configuration.\n Status,\n /// Set up upstream remote and local tracking branch.\n Setup {\n /// URL of the upstream repository.\n #[arg(short, long)]\n upstream_url: Option<String>,\n /// Branch name on upstream (default: main).\n #[arg(short, long)]\n upstream_branch: Option<String>,\n },\n /// Pull changes from upstream into local 'upstream' branch.\n Pull {\n /// Also merge into this branch after pulling.\n #[arg(short, long)]\n branch: Option<String>,\n },\n /// Checkout local 'upstream' branch synced to upstream.\n Check,\n /// Full sync: pull upstream, merge to dev/main, push to origin.\n Sync {\n /// Skip pushing to origin.\n #[arg(long)]\n no_push: bool,\n /// Create origin repo on GitHub if it doesn't exist.\n #[arg(long)]\n create_repo: bool,\n },\n /// Open upstream repository URL in browser.\n Open,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct NotifyCommand {\n /// Title of the proposal (shown in widget header).\n #[arg(short, long)]\n pub title: Option<String>,\n\n /// The action/command to propose (e.g., \"f deploy\").\n pub action: String,\n\n /// Optional context or description.\n #[arg(short, long)]\n pub context: Option<String>,\n\n /// Expiration time in seconds (default: 300 = 5 minutes).\n #[arg(short, long, default_value = \"300\")]\n pub expires: u64,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct CommitsCommand {\n #[command(subcommand)]\n pub action: Option<CommitsAction>,\n #[command(flatten)]\n pub opts: CommitsOpts,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum CommitsAction {\n /// List notable commits.\n Top,\n /// Mark a commit as notable.\n Mark {\n /// Commit hash (short or full).\n hash: String,\n },\n /// Remove a commit from notable list.\n Unmark {\n /// Commit hash (short or full).\n hash: String,\n },\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct CommitsOpts {\n /// Number of commits to show (default: 100).\n #[arg(long, short = 'n', default_value_t = 100)]\n pub limit: usize,\n /// Show commits across all branches.\n #[arg(long)]\n pub all: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SeqRpcCommand {\n /// Path to seqd Unix socket (default: $SEQ_SOCKET_PATH, then /tmp/seqd.sock).\n #[arg(long)]\n pub socket: Option<PathBuf>,\n /// Read/write timeout in milliseconds.\n #[arg(long, default_value_t = 5000)]\n pub timeout_ms: u64,\n /// Pretty-print JSON response.\n #[arg(long)]\n pub pretty: bool,\n #[command(subcommand)]\n pub action: SeqRpcAction,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum SeqRpcAction {\n /// Health check.\n Ping(SeqRpcIdOpts),\n /// Current/previous foreground app snapshot.\n AppState(SeqRpcIdOpts),\n /// Daemon perf/rusage snapshot.\n Perf(SeqRpcIdOpts),\n /// Open application by name.\n OpenApp(SeqRpcOpenAppOpts),\n /// Toggle application by name.\n OpenAppToggle(SeqRpcOpenAppOpts),\n /// Save screenshot to path.\n Screenshot(SeqRpcScreenshotOpts),\n /// Raw operation and optional JSON args.\n Rpc(SeqRpcRawOpts),\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct SeqRpcIdOpts {\n /// Caller-owned id for request correlation.\n #[arg(long)]\n pub request_id: Option<String>,\n /// Caller run id.\n #[arg(long)]\n pub run_id: Option<String>,\n /// Caller tool call id.\n #[arg(long)]\n pub tool_call_id: Option<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SeqRpcOpenAppOpts {\n /// Application name (e.g., \"Safari\", \"Google Chrome\").\n pub name: String,\n #[command(flatten)]\n pub ids: SeqRpcIdOpts,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SeqRpcScreenshotOpts {\n /// Output file path.\n pub path: String,\n #[command(flatten)]\n pub ids: SeqRpcIdOpts,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct SeqRpcRawOpts {\n /// Operation name (e.g., ping, open_app, click).\n pub op: String,\n /// Optional JSON args payload.\n #[arg(long)]\n pub args_json: Option<String>,\n #[command(flatten)]\n pub ids: SeqRpcIdOpts,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ExplainCommitsCommand {\n /// Number of commits to explain (default: 1).\n pub count: Option<usize>,\n /// Re-explain even if already processed.\n #[arg(long)]\n pub force: bool,\n /// Output directory (relative to repo root unless absolute).\n #[arg(long)]\n pub out_dir: Option<PathBuf>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DeployCommand {\n #[command(subcommand)]\n pub action: Option<DeployAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ReleaseOpts {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n /// Additional arguments passed to the release task command.\n #[arg(value_name = \"ARGS\", trailing_var_arg = true)]\n pub args: Vec<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ReleaseCommand {\n /// Path to the project flow config (flow.toml).\n #[arg(long, default_value = \"flow.toml\")]\n pub config: PathBuf,\n #[command(subcommand)]\n pub action: Option<ReleaseAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ReleaseAction {\n /// Run the configured release task.\n Task(ReleaseTaskOpts),\n /// Publish a release to a Flow registry.\n Registry(RegistryReleaseOpts),\n /// Manage GitHub releases.\n #[command(alias = \"gh\")]\n Github(GhReleaseCommand),\n /// Manage macOS code signing and GitHub Actions secrets for releases.\n Signing(ReleaseSigningCommand),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ReleaseSigningCommand {\n #[command(subcommand)]\n pub action: ReleaseSigningAction,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum ReleaseSigningAction {\n /// Show current signing setup status (Keychain + Flow env store).\n Status,\n /// Store signing secrets into Flow personal env store.\n Store(ReleaseSigningStoreOpts),\n /// Sync signing secrets from Flow env store into GitHub Actions secrets.\n Sync(ReleaseSigningSyncOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ReleaseSigningStoreOpts {\n /// Path to exported .p12 file (Developer ID Application certificate + key).\n #[arg(long)]\n pub p12: Option<PathBuf>,\n /// Password for the .p12 (must match what the release workflow imports with).\n #[arg(long)]\n pub p12_password: Option<String>,\n /// Signing identity passed to `codesign` (e.g. \"Developer ID Application: ... (TEAMID)\").\n #[arg(long)]\n pub identity: Option<String>,\n /// Dry run: show what would be stored without writing to env store.\n #[arg(long)]\n pub dry_run: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ReleaseSigningSyncOpts {\n /// GitHub repo in \"owner/repo\" form (defaults to repo inferred from current directory).\n #[arg(long)]\n pub repo: Option<String>,\n /// Dry run: show what would be synced without calling `gh`.\n #[arg(long)]\n pub dry_run: bool,\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct ReleaseTaskOpts {\n /// Additional arguments passed to the release task command.\n #[arg(value_name = \"ARGS\", trailing_var_arg = true)]\n pub args: Vec<String>,\n}\n\n#[derive(Args, Debug, Clone, Default)]\npub struct RegistryReleaseOpts {\n /// Version to publish (auto-detected if omitted).\n #[arg(long, short)]\n pub version: Option<String>,\n /// Registry base URL (overrides flow.toml).\n #[arg(long)]\n pub registry: Option<String>,\n /// Override package name for the registry.\n #[arg(long)]\n pub package: Option<String>,\n /// Override the binary name(s) to upload.\n #[arg(long, value_name = \"BIN\")]\n pub bin: Vec<String>,\n /// Skip building binaries before publishing.\n #[arg(long)]\n pub no_build: bool,\n /// Mark this version as latest in the registry.\n #[arg(long, conflicts_with = \"no_latest\")]\n pub latest: bool,\n /// Skip updating the latest pointer.\n #[arg(long, conflicts_with = \"latest\")]\n pub no_latest: bool,\n /// Dry run: show what would be published without publishing.\n #[arg(long, short = 'n')]\n pub dry_run: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct InstallOpts {\n /// Package name to install (leave blank to search).\n pub name: Option<String>,\n /// Registry base URL (defaults to FLOW_REGISTRY_URL).\n #[arg(long)]\n pub registry: Option<String>,\n /// Install backend (auto tries registry, then parm, then flox).\n #[arg(long, value_enum, default_value = \"auto\")]\n pub backend: InstallBackend,\n /// Version to install (defaults to latest).\n #[arg(long, short)]\n pub version: Option<String>,\n /// Binary name to install (defaults to the package name or manifest default).\n #[arg(long)]\n pub bin: Option<String>,\n /// Install directory (defaults to ~/bin).\n #[arg(long)]\n pub bin_dir: Option<PathBuf>,\n /// Skip checksum verification.\n #[arg(long)]\n pub no_verify: bool,\n /// Overwrite existing binary if present.\n #[arg(long)]\n pub force: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct InstallCommand {\n #[command(subcommand)]\n pub action: Option<InstallAction>,\n\n #[command(flatten)]\n pub opts: InstallOpts,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum InstallAction {\n /// Index flox packages into Typesense.\n Index(InstallIndexOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct InstallIndexOpts {\n /// Search term to index (defaults to prompt).\n pub query: Option<String>,\n /// File with newline-separated search terms.\n #[arg(long)]\n pub queries: Option<PathBuf>,\n /// Typesense base URL (overrides FLOW_TYPESENSE_URL).\n #[arg(long)]\n pub url: Option<String>,\n /// Typesense API key (overrides FLOW_TYPESENSE_API_KEY).\n #[arg(long)]\n pub api_key: Option<String>,\n /// Typesense collection name (overrides FLOW_TYPESENSE_COLLECTION).\n #[arg(long, default_value = \"flox-packages\")]\n pub collection: String,\n /// Index server URL (defaults to local base server).\n #[arg(long, default_value = \"http://127.0.0.1:9417\")]\n pub server: String,\n /// Skip index server and write directly to Typesense.\n #[arg(long)]\n pub direct: bool,\n /// Max results per search term.\n #[arg(long, default_value_t = 200)]\n pub per_page: usize,\n /// Dry run (do not write to Typesense).\n #[arg(long, short = 'n')]\n pub dry_run: bool,\n}\n\n#[derive(ValueEnum, Debug, Clone, Copy)]\npub enum InstallBackend {\n Auto,\n Registry,\n Flox,\n /// Install GitHub release binaries via the external `parm` tool.\n Parm,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct FishInstallOpts {\n /// Path to fish-shell source repo (auto-detected if not set).\n #[arg(long)]\n pub source: Option<PathBuf>,\n /// Install directory for the fish binary (defaults to ~/.local/bin).\n #[arg(long)]\n pub bin_dir: Option<PathBuf>,\n /// Force reinstall even if already installed.\n #[arg(long)]\n pub force: bool,\n /// Skip confirmation prompt.\n #[arg(long, short = 'y')]\n pub yes: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct RegistryCommand {\n #[command(subcommand)]\n pub action: Option<RegistryAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum RegistryAction {\n /// Create a registry token and configure worker + env.\n Init(RegistryInitOpts),\n}\n\n#[derive(Args, Debug, Clone)]\npub struct RegistryInitOpts {\n /// Path to the worker project (defaults to packages/worker).\n #[arg(long, short)]\n pub worker: Option<PathBuf>,\n /// Registry base URL (overrides flow.toml or FLOW_REGISTRY_URL).\n #[arg(long)]\n pub registry: Option<String>,\n /// Env var name for the registry token.\n #[arg(long)]\n pub token_env: Option<String>,\n /// Provide an explicit token instead of generating one.\n #[arg(long)]\n pub token: Option<String>,\n /// Skip updating the worker secret.\n #[arg(long)]\n pub no_worker: bool,\n /// Print the generated token to stdout.\n #[arg(long)]\n pub show_token: bool,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum DeployAction {\n /// Deploy to Linux host via SSH.\n #[command(alias = \"h\")]\n Host {\n /// Build remotely instead of syncing local build artifacts.\n #[arg(long)]\n remote_build: bool,\n /// Run setup script even if already deployed.\n #[arg(long)]\n setup: bool,\n },\n /// Deploy to Cloudflare Workers.\n #[command(alias = \"cf\")]\n Cloudflare {\n /// Also set secrets from env_file.\n #[arg(long)]\n secrets: bool,\n /// Run in dev mode instead of deploying.\n #[arg(long)]\n dev: bool,\n },\n /// Deploy the web site (Cloudflare).\n Web,\n /// Interactive deploy setup (Cloudflare Workers for now).\n Setup,\n /// Deploy to Railway.\n Railway,\n /// Configure deployment defaults (Linux host).\n Config,\n /// Run the project's release task.\n Release(ReleaseOpts),\n /// Show deployment status.\n Status,\n /// View deployment logs.\n Logs {\n /// Follow logs in real-time.\n #[arg(long, short)]\n follow: bool,\n /// Show logs since the last successful deploy (default).\n #[arg(long, default_value_t = true)]\n since_deploy: bool,\n /// Show full log history (ignores --since-deploy).\n #[arg(long)]\n all: bool,\n /// Number of lines to show.\n #[arg(long, short = 'n', default_value_t = 100)]\n lines: usize,\n },\n /// Restart the deployed service.\n Restart,\n /// Stop the deployed service.\n Stop,\n /// SSH into the host (for host deployments).\n Shell,\n /// Configure host for deployment.\n #[command(alias = \"set\")]\n SetHost {\n /// SSH connection string (user@host:port or user@host).\n connection: String,\n },\n /// Show current host configuration.\n ShowHost,\n /// Check if deployment is healthy (HTTP health check).\n Health {\n /// Custom URL to check (defaults to domain from config).\n #[arg(long)]\n url: Option<String>,\n /// Expected HTTP status code.\n #[arg(long, default_value_t = 200)]\n status: u16,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct ParallelCommand {\n /// Maximum number of concurrent jobs (default: number of CPU cores).\n #[arg(long, short = 'j')]\n pub jobs: Option<usize>,\n /// Stop all tasks on first failure.\n #[arg(long, short = 'f')]\n pub fail_fast: bool,\n /// Tasks to run as \"label:command\" pairs, or just commands (auto-labeled).\n #[arg(value_name = \"TASK\", trailing_var_arg = true, num_args = 1..)]\n pub tasks: Vec<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DocsCommand {\n #[command(subcommand)]\n pub action: Option<DocsAction>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct UpgradeOpts {\n /// Upgrade to a specific version (e.g., \"0.2.0\" or \"v0.2.0\").\n #[arg(value_name = \"VERSION\")]\n pub version: Option<String>,\n /// Upgrade to the latest canary build (GitHub release tag: \"canary\").\n ///\n /// This is similar to `bun upgrade --canary`: canary releases are updated frequently and may\n /// contain untested changes.\n #[arg(long, conflicts_with = \"stable\", conflicts_with = \"version\")]\n pub canary: bool,\n /// Upgrade to the latest stable release (GitHub \"latest\" release).\n ///\n /// This is useful to switch back after installing canary.\n #[arg(long, conflicts_with = \"canary\", conflicts_with = \"version\")]\n pub stable: bool,\n /// Print what would happen without making changes.\n #[arg(long, short = 'n')]\n pub dry_run: bool,\n /// Force upgrade even if already on the latest version.\n #[arg(long, short)]\n pub force: bool,\n /// Download to a specific path instead of replacing the current executable.\n #[arg(long, short)]\n pub output: Option<String>,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct GhReleaseCommand {\n #[command(subcommand)]\n pub action: Option<GhReleaseAction>,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum GhReleaseAction {\n /// Create a new GitHub release.\n Create(GhReleaseCreateOpts),\n /// List recent releases.\n #[command(alias = \"ls\")]\n List {\n /// Number of releases to show.\n #[arg(short, long, default_value = \"10\")]\n limit: usize,\n },\n /// Delete a release.\n Delete {\n /// Release tag to delete.\n tag: String,\n /// Skip confirmation.\n #[arg(short, long)]\n yes: bool,\n },\n /// Download release assets.\n Download {\n /// Release tag (defaults to latest).\n #[arg(short, long)]\n tag: Option<String>,\n /// Output directory.\n #[arg(short, long, default_value = \".\")]\n output: String,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct GhReleaseCreateOpts {\n /// Version tag (e.g., \"v0.1.0\"). Auto-detected from Cargo.toml if not provided.\n #[arg(value_name = \"TAG\")]\n pub tag: Option<String>,\n /// Release title (defaults to tag name).\n #[arg(short, long)]\n pub title: Option<String>,\n /// Release notes (reads from stdin or file if not provided).\n #[arg(short, long)]\n pub notes: Option<String>,\n /// Read release notes from a file.\n #[arg(long)]\n pub notes_file: Option<String>,\n /// Generate release notes automatically from commits.\n #[arg(long)]\n pub generate_notes: bool,\n /// Create as draft release.\n #[arg(long)]\n pub draft: bool,\n /// Mark as prerelease.\n #[arg(long)]\n pub prerelease: bool,\n /// Asset files to upload (can be specified multiple times).\n #[arg(short, long, value_name = \"FILE\")]\n pub asset: Vec<String>,\n /// Target commit/branch for the release tag.\n #[arg(long)]\n pub target: Option<String>,\n /// Skip confirmation prompts.\n #[arg(short, long)]\n pub yes: bool,\n}\n\n#[derive(Subcommand, Debug, Clone)]\npub enum DocsAction {\n /// Create a docs/ folder with starter markdown files.\n New(DocsNewOpts),\n /// Run the docs hub that aggregates docs from ~/code and ~/org.\n Hub(DocsHubOpts),\n /// Deploy the docs hub to Cloudflare Pages.\n Deploy(DocsDeployOpts),\n /// Sync documentation with recent commits.\n Sync {\n /// Number of commits to analyze (default: 10).\n #[arg(long, short = 'n', default_value_t = 10)]\n commits: usize,\n /// Dry run: show what would be updated without changing files.\n #[arg(long)]\n dry: bool,\n },\n /// List documentation files.\n #[command(alias = \"ls\")]\n List,\n /// Show documentation status (what needs updating).\n Status,\n /// Open a doc file in editor.\n Edit {\n /// Doc file name (without .md).\n name: String,\n },\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DocsNewOpts {\n /// Path to create docs in (defaults to current directory).\n #[arg(long)]\n pub path: Option<PathBuf>,\n /// Overwrite if docs/ already exists.\n #[arg(long)]\n pub force: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DocsDeployOpts {\n /// Cloudflare Pages project name (defaults to flow.toml name).\n #[arg(long)]\n pub project: Option<String>,\n /// Custom domain to attach (optional).\n #[arg(long)]\n pub domain: Option<String>,\n /// Skip confirmation prompts.\n #[arg(short, long)]\n pub yes: bool,\n}\n\n#[derive(Args, Debug, Clone)]\npub struct DocsHubOpts {\n /// Host to bind the docs hub to.\n #[arg(long, default_value = \"127.0.0.1\")]\n pub host: String,\n /// Port for the docs hub.\n #[arg(long, default_value_t = 4410)]\n pub port: u16,\n /// Docs hub root (defaults to ~/.config/flow/docs-hub).\n #[arg(long, default_value = \"~/.config/flow/docs-hub\")]\n pub hub_root: String,\n /// Template root (defaults to ~/new/docs).\n #[arg(long, default_value = \"~/new/docs\")]\n pub template_root: String,\n /// Code root to scan for docs (defaults to ~/code).\n #[arg(long, default_value = \"~/code\")]\n pub code_root: String,\n /// Org root to scan for docs (defaults to ~/org).\n #[arg(long, default_value = \"~/org\")]\n pub org_root: String,\n /// Skip scanning for .ai/docs.\n #[arg(long)]\n pub no_ai: bool,\n /// Skip opening the browser.\n #[arg(long)]\n pub no_open: bool,\n /// Sync content and exit without running the dev server.\n #[arg(long)]\n pub sync_only: bool,\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use clap::Parser;\n\n #[test]\n fn parses_codex_resume_with_path_override() {\n let cli = Cli::parse_from([\n \"f\",\n \"ai\",\n \"codex\",\n \"resume\",\n \"--path\",\n \"~/work/example-project\",\n \"session-123\",\n ]);\n\n match cli.command {\n Some(Commands::Ai(AiCommand {\n action:\n Some(AiAction::Codex {\n action: Some(ProviderAiAction::Resume { session, path }),\n }),\n })) => {\n assert_eq!(session.as_deref(), Some(\"session-123\"));\n assert_eq!(path.as_deref(), Some(\"~/work/example-project\"));\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_codex_continue_with_path_override() {\n let cli = Cli::parse_from([\"f\", \"ai\", \"codex\", \"continue\", \"--path\", \"/tmp/rev\"]);\n\n match cli.command {\n Some(Commands::Ai(AiCommand {\n action:\n Some(AiAction::Codex {\n action: Some(ProviderAiAction::Continue { session, path }),\n }),\n })) => {\n assert_eq!(session, None);\n assert_eq!(path.as_deref(), Some(\"/tmp/rev\"));\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_codex_find_with_path_and_query() {\n let cli = Cli::parse_from([\n \"f\",\n \"ai\",\n \"codex\",\n \"find\",\n \"--path\",\n \"~/repos/acme/app\",\n \"make\",\n \"plan\",\n \"designer\",\n ]);\n\n match cli.command {\n Some(Commands::Ai(AiCommand {\n action:\n Some(AiAction::Codex {\n action:\n Some(ProviderAiAction::Find {\n path,\n exact_cwd,\n query,\n }),\n }),\n })) => {\n assert_eq!(path.as_deref(), Some(\"~/repos/acme/app\"));\n assert!(!exact_cwd);\n assert_eq!(query, vec![\"make\", \"plan\", \"designer\"]);\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_codex_find_and_copy_with_query() {\n let cli = Cli::parse_from([\n \"f\",\n \"ai\",\n \"codex\",\n \"findAndCopy\",\n \"make\",\n \"plan\",\n \"designer\",\n ]);\n\n match cli.command {\n Some(Commands::Ai(AiCommand {\n action:\n Some(AiAction::Codex {\n action:\n Some(ProviderAiAction::FindAndCopy {\n path,\n exact_cwd,\n query,\n }),\n }),\n })) => {\n assert_eq!(path, None);\n assert!(!exact_cwd);\n assert_eq!(query, vec![\"make\", \"plan\", \"designer\"]);\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_codex_open_with_path_and_query() {\n let cli = Cli::parse_from([\n \"f\",\n \"codex\",\n \"open\",\n \"--path\",\n \"~/repos/acme/app\",\n \"continue\",\n \"the\",\n \"deploy\",\n \"work\",\n ]);\n\n match cli.command {\n Some(Commands::Codex {\n action:\n Some(ProviderAiAction::Open {\n path,\n exact_cwd,\n query,\n }),\n }) => {\n assert_eq!(path.as_deref(), Some(\"~/repos/acme/app\"));\n assert!(!exact_cwd);\n assert_eq!(query, vec![\"continue\", \"the\", \"deploy\", \"work\"]);\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_codex_resolve_json() {\n let cli = Cli::parse_from([\n \"f\",\n \"ai\",\n \"codex\",\n \"resolve\",\n \"--json\",\n \"https://linear.app/fl2024008/project/llm-proxy-v1-6cd0a041bd76/overview\",\n ]);\n\n match cli.command {\n Some(Commands::Ai(AiCommand {\n action:\n Some(AiAction::Codex {\n action:\n Some(ProviderAiAction::Resolve {\n path,\n exact_cwd,\n json,\n query,\n }),\n }),\n })) => {\n assert_eq!(path, None);\n assert!(!exact_cwd);\n assert!(json);\n assert_eq!(\n query,\n vec![\"https://linear.app/fl2024008/project/llm-proxy-v1-6cd0a041bd76/overview\"]\n );\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_codex_doctor_assertions() {\n let cli = Cli::parse_from([\n \"f\",\n \"codex\",\n \"doctor\",\n \"--path\",\n \"~/docs\",\n \"--assert-runtime\",\n \"--assert-learning\",\n \"--json\",\n ]);\n\n match cli.command {\n Some(Commands::Codex {\n action:\n Some(ProviderAiAction::Doctor {\n path,\n assert_runtime,\n assert_schedule,\n assert_learning,\n assert_autonomous,\n json,\n }),\n }) => {\n assert_eq!(path.as_deref(), Some(\"~/docs\"));\n assert!(assert_runtime);\n assert!(!assert_schedule);\n assert!(assert_learning);\n assert!(!assert_autonomous);\n assert!(json);\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_codex_enable_global_full() {\n let cli = Cli::parse_from([\"f\", \"codex\", \"enable-global\", \"--full\", \"--dry-run\"]);\n\n match cli.command {\n Some(Commands::Codex {\n action:\n Some(ProviderAiAction::EnableGlobal {\n dry_run,\n install_launchd,\n start_daemon,\n sync_skills,\n full,\n minutes,\n limit,\n max_targets,\n within_hours,\n }),\n }) => {\n assert!(dry_run);\n assert!(!install_launchd);\n assert!(!start_daemon);\n assert!(!sync_skills);\n assert!(full);\n assert_eq!(minutes, 30);\n assert_eq!(limit, 400);\n assert_eq!(max_targets, 12);\n assert_eq!(within_hours, 168);\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_repos_capsule_with_refresh_and_json() {\n let cli = Cli::parse_from([\n \"f\",\n \"repos\",\n \"capsule\",\n \"--path\",\n \"~/repos/Effect-TS/effect-smol\",\n \"--refresh\",\n \"--json\",\n ]);\n\n match cli.command {\n Some(Commands::Repos(ReposCommand {\n action:\n Some(ReposAction::Capsule(RepoCapsuleOpts {\n path,\n refresh,\n json,\n })),\n })) => {\n assert_eq!(path.as_deref(), Some(\"~/repos/Effect-TS/effect-smol\"));\n assert!(refresh);\n assert!(json);\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_repos_alias_set() {\n let cli = Cli::parse_from([\n \"f\",\n \"repos\",\n \"alias\",\n \"set\",\n \"effect-smol\",\n \"~/repos/Effect-TS/effect-smol\",\n \"--json\",\n ]);\n\n match cli.command {\n Some(Commands::Repos(ReposCommand {\n action:\n Some(ReposAction::Alias(RepoAliasCommand {\n action: Some(RepoAliasAction::Set { alias, path, json }),\n })),\n })) => {\n assert_eq!(alias, \"effect-smol\");\n assert_eq!(path, \"~/repos/Effect-TS/effect-smol\");\n assert!(json);\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_repos_alias_import_shelf() {\n let cli = Cli::parse_from([\n \"f\",\n \"repos\",\n \"alias\",\n \"import-shelf\",\n \"--config\",\n \"~/.agents/shelf/config.json\",\n \"--json\",\n ]);\n\n match cli.command {\n Some(Commands::Repos(ReposCommand {\n action:\n Some(ReposAction::Alias(RepoAliasCommand {\n action: Some(RepoAliasAction::ImportShelf { config, json }),\n })),\n })) => {\n assert_eq!(config.as_deref(), Some(\"~/.agents/shelf/config.json\"));\n assert!(json);\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_domains_get_with_target_flag() {\n let cli = Cli::parse_from([\n \"f\",\n \"domains\",\n \"--engine\",\n \"native\",\n \"get\",\n \"myflow.localhost\",\n \"--target\",\n ]);\n\n match cli.command {\n Some(Commands::Domains(DomainsCommand {\n engine: Some(DomainsEngineArg::Native),\n action: Some(DomainsAction::Get(DomainsGetOpts { host, target })),\n })) => {\n assert_eq!(host, \"myflow.localhost\");\n assert!(target);\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_url_crawl_with_filters() {\n let cli = Cli::parse_from([\n \"f\",\n \"url\",\n \"crawl\",\n \"https://developers.cloudflare.com/\",\n \"--limit\",\n \"6\",\n \"--records\",\n \"3\",\n \"--include-pattern\",\n \"https://developers.cloudflare.com/browser-rendering/*\",\n \"--exclude-pattern\",\n \"*/changelog/*\",\n \"--render\",\n ]);\n\n match cli.command {\n Some(Commands::Url(UrlCommand {\n action:\n UrlAction::Crawl(UrlCrawlOpts {\n url,\n json,\n full,\n limit,\n depth,\n records,\n source,\n render,\n include_external_links,\n include_subdomains,\n include_patterns,\n exclude_patterns,\n max_age_s,\n wait_timeout_s,\n poll_interval_s,\n }),\n })) => {\n assert_eq!(url, \"https://developers.cloudflare.com/\");\n assert!(!json);\n assert!(!full);\n assert_eq!(limit, 6);\n assert_eq!(depth, 2);\n assert_eq!(records, 3);\n assert_eq!(source, UrlCrawlSource::All);\n assert!(render);\n assert!(!include_external_links);\n assert!(!include_subdomains);\n assert_eq!(\n include_patterns,\n vec![\"https://developers.cloudflare.com/browser-rendering/*\"]\n );\n assert_eq!(exclude_patterns, vec![\"*/changelog/*\"]);\n assert_eq!(max_age_s, None);\n assert_eq!(wait_timeout_s, 60.0);\n assert_eq!(poll_interval_s, 2.0);\n }\n other => panic!(\"unexpected parsed command: {other:?}\"),\n }\n }\n}\n" }, { "path": "src/code.rs", "content": "use std::collections::HashSet;\nuse std::collections::hash_map::DefaultHasher;\nuse std::fs;\nuse std::hash::{Hash, Hasher};\nuse std::io::{BufRead, BufReader, BufWriter, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\nuse serde_json::Value;\n\nuse crate::cli::{\n CodeAction, CodeCommand, CodeMigrateOpts, CodeMoveSessionsOpts, CodeNewOpts, MigrateAction,\n MigrateCommand, NewOpts,\n};\nuse crate::config;\n\nconst DEFAULT_CODE_ROOT: &str = \"~/code\";\nconst DEFAULT_TEMPLATE_ROOT: &str = \"~/new\";\nconst DEFAULT_AGENT_QA_ZVEC_JSONL: &str = \"~/repos/alibaba/zvec/data/agent_qa.jsonl\";\nconst FLOW_AGENT_QA_ZVEC_JSONL_ENV: &str = \"FLOW_AGENT_QA_ZVEC_JSONL\";\n\nstruct ZvecMoveSummary {\n updated_docs: usize,\n index_found: bool,\n}\n\nstruct ZvecCopySummary {\n copied_docs: usize,\n index_found: bool,\n}\n\n/// List available templates from ~/new/.\nfn list_templates() -> Result<Vec<String>> {\n let template_root = config::expand_path(DEFAULT_TEMPLATE_ROOT);\n if !template_root.exists() {\n return Ok(vec![]);\n }\n\n let mut templates = Vec::new();\n for entry in fs::read_dir(&template_root)? {\n let entry = entry?;\n let path = entry.path();\n if path.is_dir() {\n if let Some(name) = path.file_name().and_then(|n| n.to_str()) {\n if !name.starts_with('.') {\n templates.push(name.to_string());\n }\n }\n }\n }\n templates.sort();\n Ok(templates)\n}\n\n/// Fuzzy select a template from ~/new/.\nfn fuzzy_select_template() -> Result<Option<String>> {\n let templates = list_templates()?;\n if templates.is_empty() {\n bail!(\"No templates found in ~/new/\");\n }\n\n let input = templates.join(\"\\n\");\n\n let mut fzf = Command::new(\"fzf\")\n .args([\"--height=50%\", \"--reverse\", \"--prompt=Template: \"])\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n fzf.stdin.as_mut().unwrap().write_all(input.as_bytes())?;\n\n let output = fzf.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n\n let selected = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if selected.is_empty() {\n return Ok(None);\n }\n\n Ok(Some(selected))\n}\n\n/// Create a new project from a template at a specific path.\n/// Usage: f new [template] [path]\npub fn new_from_template(opts: NewOpts) -> Result<()> {\n let template_root = config::expand_path(DEFAULT_TEMPLATE_ROOT);\n\n // Get template name (fuzzy select if not provided)\n let template_name = match opts.template {\n Some(t) => t,\n None => match fuzzy_select_template()? {\n Some(t) => t,\n None => return Ok(()), // User cancelled\n },\n };\n\n let template_dir = template_root.join(template_name.trim());\n\n if !template_dir.exists() {\n bail!(\"Template not found: {}\", template_dir.display());\n }\n if !template_dir.is_dir() {\n bail!(\n \"Template path is not a directory: {}\",\n template_dir.display()\n );\n }\n\n // Resolve target path:\n // - No path: ./<template_name>\n // - Starts with ./ or ../: relative to cwd\n // - Starts with ~ or /: absolute path\n // - Otherwise: relative to ~/code/\n let target = match opts.path {\n None => std::env::current_dir()?.join(&template_name),\n Some(p) => {\n let trimmed = p.trim();\n if trimmed.starts_with(\"./\")\n || trimmed.starts_with(\"../\")\n || trimmed.starts_with('/')\n || trimmed.starts_with('~')\n {\n let expanded = config::expand_path(trimmed);\n if expanded.is_absolute() {\n expanded\n } else {\n std::env::current_dir()?.join(&expanded)\n }\n } else {\n // Relative name like \"zerg\" → ~/code/zerg\n config::expand_path(DEFAULT_CODE_ROOT).join(trimmed)\n }\n }\n };\n\n if target.exists() {\n bail!(\"Destination already exists: {}\", target.display());\n }\n\n if opts.dry_run {\n println!(\n \"Would copy template {} -> {}\",\n template_dir.display(),\n target.display()\n );\n return Ok(());\n }\n\n // Create parent directories if needed\n if let Some(parent) = target.parent() {\n if !parent.exists() {\n fs::create_dir_all(parent).with_context(|| {\n format!(\"failed to create parent directory {}\", parent.display())\n })?;\n }\n }\n\n copy_dir_all(&template_dir, &target)?;\n println!(\"Created {}\", target.display());\n Ok(())\n}\n\npub fn run(cmd: CodeCommand) -> Result<()> {\n match cmd.action {\n Some(CodeAction::List) => list_code(&cmd.root),\n Some(CodeAction::New(opts)) => new_project(opts, &cmd.root),\n Some(CodeAction::Migrate(opts)) => migrate_project(opts, &cmd.root),\n Some(CodeAction::MoveSessions(opts)) => move_sessions(opts),\n None => fuzzy_select_code(&cmd.root),\n }\n}\n\npub(crate) fn migrate_sessions_between_paths(\n from: &Path,\n to: &Path,\n dry_run: bool,\n skip_claude: bool,\n skip_codex: bool,\n) -> Result<()> {\n let opts = CodeMoveSessionsOpts {\n from: from.display().to_string(),\n to: to.display().to_string(),\n dry_run,\n skip_claude,\n skip_codex,\n };\n move_sessions(opts)\n}\n\n/// Migrate current folder to a new location.\n/// `f migrate code <relative>` → moves to ~/code/<relative>\n/// `f migrate <target>` → moves to any specified path\npub fn run_migrate(cmd: MigrateCommand) -> Result<()> {\n let from = std::env::current_dir().context(\"failed to get current directory\")?;\n\n // Handle `f migrate code <relative>` subcommand\n if let Some(MigrateAction::Code(opts)) = cmd.action {\n // Merge flags from parent command and subcommand (subcommand takes precedence if set)\n let copy = opts.copy || cmd.copy;\n let dry_run = opts.dry_run || cmd.dry_run;\n let skip_claude = opts.skip_claude || cmd.skip_claude;\n let skip_codex = opts.skip_codex || cmd.skip_codex;\n\n let migrate_opts = CodeMigrateOpts {\n from: from.to_string_lossy().to_string(),\n relative: opts.relative,\n copy,\n dry_run,\n skip_claude,\n skip_codex,\n };\n return migrate_project(migrate_opts, DEFAULT_CODE_ROOT);\n }\n\n // Handle `f migrate <source> <target>` or `f migrate <target>`\n let (from, target) = match (cmd.source, cmd.target) {\n // Both source and target provided: f migrate <source> <target>\n (Some(src), Some(tgt)) => {\n let src_path = config::expand_path(&src);\n let src_path = if src_path.is_absolute() {\n src_path\n } else {\n std::env::current_dir()?.join(&src_path)\n };\n let tgt_path = config::expand_path(&tgt);\n let tgt_path = if tgt_path.is_absolute() {\n tgt_path\n } else {\n std::env::current_dir()?.join(&tgt_path)\n };\n (src_path, tgt_path)\n }\n // Only one path: f migrate <target> (source is cwd)\n (Some(tgt), None) => {\n let tgt_path = config::expand_path(&tgt);\n let tgt_path = if tgt_path.is_absolute() {\n tgt_path\n } else {\n std::env::current_dir()?.join(&tgt_path)\n };\n (from, tgt_path)\n }\n // No paths provided\n (None, _) => {\n bail!(\n \"Usage: f migrate <target> OR f migrate <source> <target> OR f migrate code <relative>\"\n );\n }\n };\n\n migrate_to_path(\n &from,\n &target,\n cmd.copy,\n cmd.dry_run,\n cmd.skip_claude,\n cmd.skip_codex,\n )\n}\n\n/// Migrate a folder to an arbitrary target path (not necessarily ~/code).\nfn migrate_to_path(\n from: &Path,\n target: &Path,\n copy: bool,\n dry_run: bool,\n skip_claude: bool,\n skip_codex: bool,\n) -> Result<()> {\n let target_display = target.display().to_string();\n let action = if copy { \"copy\" } else { \"move\" };\n let action_past = if copy { \"Copied\" } else { \"Moved\" };\n\n if from == target {\n bail!(\"Source and destination are the same path.\");\n }\n if !from.exists() {\n bail!(\"Source folder does not exist: {}\", from.display());\n }\n if !from.is_dir() {\n bail!(\"Source path is not a directory: {}\", from.display());\n }\n if target.exists() {\n bail!(\"Destination already exists: {}\", target.display());\n }\n if target.starts_with(from) {\n bail!(\"Destination cannot be inside the source folder.\");\n }\n\n // Create parent directories if needed\n if let Some(parent) = target.parent() {\n if !parent.exists() {\n if dry_run {\n println!(\"Would create {}\", parent.display());\n } else {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n }\n }\n\n if dry_run {\n println!(\"Would {} {} -> {}\", action, from.display(), target_display);\n } else if copy {\n copy_dir_all(from, target)?;\n println!(\"{} {} -> {}\", action_past, from.display(), target_display);\n } else {\n move_dir(from, target)?;\n println!(\"{} {} -> {}\", action_past, from.display(), target_display);\n }\n\n // Only relink symlinks if moving (not copying)\n if !copy {\n let relinked = relink_bin_symlinks(from, target, dry_run)?;\n if relinked > 0 {\n println!(\"Updated {} symlink(s) in ~/bin\", relinked);\n }\n }\n\n let session_opts = CodeMoveSessionsOpts {\n from: from.to_string_lossy().to_string(),\n to: target.to_string_lossy().to_string(),\n dry_run,\n skip_claude,\n skip_codex,\n };\n if copy {\n copy_sessions(session_opts)\n .with_context(|| format!(\"copied to {}, but session copy failed\", target_display))?;\n } else {\n move_sessions(session_opts).with_context(|| {\n format!(\"moved to {}, but session migration failed\", target_display)\n })?;\n }\n\n Ok(())\n}\n\nfn list_code(root: &str) -> Result<()> {\n let root = normalize_root(root)?;\n if !root.exists() {\n println!(\"No code directory found at {}\", root.display());\n return Ok(());\n }\n\n let repos = discover_code_repos(&root)?;\n if repos.is_empty() {\n println!(\"No git repositories found in {}\", root.display());\n return Ok(());\n }\n\n println!(\"Available repositories:\");\n for repo in &repos {\n println!(\" {}\", repo.display);\n }\n Ok(())\n}\n\nfn fuzzy_select_code(root: &str) -> Result<()> {\n let root = normalize_root(root)?;\n if !root.exists() {\n println!(\"No code directory found at {}\", root.display());\n return Ok(());\n }\n\n let repos = discover_code_repos(&root)?;\n if repos.is_empty() {\n println!(\"No git repositories found in {}\", root.display());\n return Ok(());\n }\n\n if which::which(\"fzf\").is_err() {\n println!(\"fzf not found on PATH – install it to use fuzzy selection.\");\n println!(\"Available repositories:\");\n for repo in &repos {\n println!(\" {}\", repo.display);\n }\n return Ok(());\n }\n\n if let Some(selected) = run_fzf(&repos)? {\n open_in_zed(&selected.path)?;\n }\n\n Ok(())\n}\n\nfn normalize_root(root: &str) -> Result<PathBuf> {\n let trimmed = root.trim();\n let expanded = if trimmed.is_empty() {\n config::expand_path(DEFAULT_CODE_ROOT)\n } else {\n config::expand_path(trimmed)\n };\n Ok(expanded)\n}\n\nstruct CodeEntry {\n display: String,\n path: PathBuf,\n}\n\nfn discover_code_repos(root: &Path) -> Result<Vec<CodeEntry>> {\n let mut repos = Vec::new();\n let mut seen = HashSet::new();\n let mut stack = vec![root.to_path_buf()];\n\n while let Some(dir) = stack.pop() {\n let entries = match fs::read_dir(&dir) {\n Ok(entries) => entries,\n Err(_) => continue,\n };\n\n for entry in entries.flatten() {\n let path = entry.path();\n let file_type = match entry.file_type() {\n Ok(ft) => ft,\n Err(_) => continue,\n };\n if !file_type.is_dir() {\n continue;\n }\n\n let name = entry.file_name().to_string_lossy().to_string();\n if should_skip_dir(&name) {\n continue;\n }\n\n let git_dir = path.join(\".git\");\n if git_dir.is_dir() || git_dir.is_file() {\n let display = path\n .strip_prefix(root)\n .unwrap_or(&path)\n .to_string_lossy()\n .to_string();\n let key = path.to_string_lossy().to_string();\n if seen.insert(key) {\n repos.push(CodeEntry { display, path });\n }\n continue;\n }\n\n stack.push(path);\n }\n }\n\n repos.sort_by(|a, b| a.display.cmp(&b.display));\n Ok(repos)\n}\n\nfn should_skip_dir(name: &str) -> bool {\n if name.starts_with('.') {\n return true;\n }\n matches!(\n name,\n \"node_modules\"\n | \"target\"\n | \"dist\"\n | \"build\"\n | \".git\"\n | \".hg\"\n | \".svn\"\n | \"__pycache__\"\n | \".pytest_cache\"\n | \".mypy_cache\"\n | \"venv\"\n | \".venv\"\n | \"vendor\"\n | \"Pods\"\n | \".cargo\"\n | \".rustup\"\n | \".next\"\n | \".turbo\"\n | \".cache\"\n )\n}\n\nfn run_fzf(entries: &[CodeEntry]) -> Result<Option<&CodeEntry>> {\n let mut child = Command::new(\"fzf\")\n .arg(\"--prompt\")\n .arg(\"code> \")\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n {\n let stdin = child.stdin.as_mut().context(\"failed to open fzf stdin\")?;\n for entry in entries {\n writeln!(stdin, \"{}\", entry.display)?;\n }\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n\n let selection = String::from_utf8(output.stdout).context(\"fzf output was not valid UTF-8\")?;\n let selection = selection.trim();\n if selection.is_empty() {\n return Ok(None);\n }\n\n Ok(entries.iter().find(|e| e.display == selection))\n}\n\nfn open_in_zed(path: &Path) -> Result<()> {\n Command::new(\"open\")\n .args([\"-a\", \"/Applications/Zed.app\"])\n .arg(path)\n .status()\n .context(\"failed to open Zed\")?;\n Ok(())\n}\n\nfn new_project(opts: CodeNewOpts, root: &str) -> Result<()> {\n let root = normalize_root(root)?;\n let template_root = config::expand_path(DEFAULT_TEMPLATE_ROOT);\n let template_dir = template_root.join(opts.template.trim());\n if !template_dir.exists() {\n bail!(\"Template not found: {}\", template_dir.display());\n }\n if !template_dir.is_dir() {\n bail!(\n \"Template path is not a directory: {}\",\n template_dir.display()\n );\n }\n\n let relative = normalize_relative_path(&opts.name)?;\n let target = root.join(&relative);\n let target_display = target.display().to_string();\n let mut planned_dirs = Vec::new();\n\n if target.exists() {\n bail!(\"Destination already exists: {}\", target.display());\n }\n\n ensure_dir(&root, opts.dry_run, &mut planned_dirs)?;\n if let Some(parent) = target.parent() {\n if parent != root {\n ensure_dir(parent, opts.dry_run, &mut planned_dirs)?;\n }\n }\n\n if opts.dry_run {\n println!(\n \"Would copy template {} -> {}\",\n template_dir.display(),\n target_display\n );\n if opts.ignored {\n if let Some((repo_root, entry)) = gitignore_entry_for_target(&target)? {\n println!(\n \"Would add {} to {}\",\n entry,\n repo_root.join(\".gitignore\").display()\n );\n } else {\n bail!(\"--ignored requires the target to be inside a git repository\");\n }\n }\n return Ok(());\n }\n\n copy_dir_all(&template_dir, &target)?;\n println!(\"Created {}\", target_display);\n if opts.ignored {\n if let Some((repo_root, entry)) = gitignore_entry_for_target(&target)? {\n ensure_gitignore_entry(&repo_root, &entry)?;\n } else {\n bail!(\"--ignored requires the target to be inside a git repository\");\n }\n }\n Ok(())\n}\n\nfn migrate_project(opts: CodeMigrateOpts, root: &str) -> Result<()> {\n let root = normalize_root(root)?;\n let from = normalize_path(&opts.from)?;\n let relative = normalize_relative_path(&opts.relative)?;\n let target = root.join(&relative);\n let target_display = target.display().to_string();\n let root_display = root.to_string_lossy().to_string();\n let mut planned_dirs = Vec::new();\n\n if from == target {\n bail!(\"Source and destination are the same path.\");\n }\n if !from.exists() {\n bail!(\"Source folder does not exist: {}\", from.display());\n }\n if !from.is_dir() {\n bail!(\"Source path is not a directory: {}\", from.display());\n }\n if target.exists() {\n bail!(\"Destination already exists: {}\", target.display());\n }\n if target.starts_with(&from) {\n bail!(\"Destination cannot be inside the source folder.\");\n }\n\n ensure_dir(&root, opts.dry_run, &mut planned_dirs)?;\n if let Some(parent) = target.parent() {\n if parent.to_string_lossy() != root_display {\n ensure_dir(parent, opts.dry_run, &mut planned_dirs)?;\n }\n }\n\n if opts.dry_run {\n let action = if opts.copy { \"copy\" } else { \"move\" };\n println!(\"Would {} {} -> {}\", action, from.display(), target_display);\n } else if opts.copy {\n copy_dir_all(&from, &target)?;\n println!(\"Copied {} -> {}\", from.display(), target_display);\n } else {\n move_dir(&from, &target)?;\n println!(\"Moved {} -> {}\", from.display(), target_display);\n }\n\n if !opts.copy {\n let relinked = relink_bin_symlinks(&from, &target, opts.dry_run)?;\n if relinked > 0 {\n println!(\"Updated {} symlink(s) in ~/bin\", relinked);\n }\n }\n\n let session_opts = CodeMoveSessionsOpts {\n from: from.to_string_lossy().to_string(),\n to: target.to_string_lossy().to_string(),\n dry_run: opts.dry_run,\n skip_claude: opts.skip_claude,\n skip_codex: opts.skip_codex,\n };\n if opts.copy {\n copy_sessions(session_opts)\n .with_context(|| format!(\"copied to {}, but session copy failed\", target_display))?;\n } else {\n move_sessions(session_opts).with_context(|| {\n format!(\"moved to {}, but session migration failed\", target_display)\n })?;\n }\n\n Ok(())\n}\n\nfn copy_sessions(opts: CodeMoveSessionsOpts) -> Result<()> {\n let from = normalize_path(&opts.from)?;\n let to = normalize_path(&opts.to)?;\n\n if from == to {\n bail!(\"Source and destination are the same path.\");\n }\n\n let mut copied_claude = 0;\n let mut copied_codex = 0;\n let mut copied_codex_files = 0;\n let mut copied_zvec_docs = 0;\n let mut zvec_index_found = false;\n\n if !opts.skip_claude {\n let base = claude_projects_dir();\n copied_claude = copy_project_dir(&base, &from, &to, opts.dry_run)?;\n }\n if !opts.skip_codex {\n let base = codex_projects_dir();\n copied_codex = copy_project_dir(&base, &from, &to, opts.dry_run)?;\n let codex_copy = copy_codex_sessions(&from, &to, opts.dry_run)?;\n copied_codex_files = codex_copy.copied_files;\n }\n if let Some(zvec_path) = resolve_agent_qa_zvec_path() {\n let zvec_copy = copy_zvec_agent_qa_paths(&zvec_path, &from, &to, opts.dry_run)?;\n copied_zvec_docs = zvec_copy.copied_docs;\n zvec_index_found = zvec_copy.index_found;\n }\n\n println!(\"Session copy summary:\");\n println!(\" Claude project dirs copied: {}\", copied_claude);\n println!(\" Codex legacy dirs copied: {}\", copied_codex);\n println!(\" Codex jsonl files copied: {}\", copied_codex_files);\n if zvec_index_found {\n println!(\" Seq zvec docs copied: {}\", copied_zvec_docs);\n } else {\n println!(\n \" Seq zvec docs copied: {} (index not found)\",\n copied_zvec_docs\n );\n }\n if opts.dry_run {\n println!(\"Dry run only; no files were changed.\");\n }\n\n Ok(())\n}\n\nfn move_sessions(opts: CodeMoveSessionsOpts) -> Result<()> {\n let from = normalize_path(&opts.from)?;\n let to = normalize_path(&opts.to)?;\n\n if from == to {\n bail!(\"Source and destination are the same path.\");\n }\n\n let mut moved_claude = 0;\n let mut moved_codex = 0;\n let mut updated_codex_files = 0;\n let mut remaining_codex_files = Vec::new();\n let mut updated_zvec_docs = 0;\n let mut zvec_index_found = false;\n\n if !opts.skip_claude {\n let base = claude_projects_dir();\n let from_dir = base.join(path_to_project_name(&from));\n let to_dir = base.join(path_to_project_name(&to));\n let from_exists = from_dir.exists();\n let to_exists = to_dir.exists();\n moved_claude = move_project_dir(&base, &from, &to, opts.dry_run)?;\n if from_exists && !opts.dry_run {\n if from_dir.exists() {\n println!(\n \"WARN Claude session dir still present: {}\",\n from_dir.display()\n );\n }\n if !to_dir.exists() && !to_exists {\n println!(\n \"WARN Claude session dir missing after migration: {}\",\n to_dir.display()\n );\n }\n }\n }\n if !opts.skip_codex {\n let base = codex_projects_dir();\n let from_dir = base.join(path_to_project_name(&from));\n let to_dir = base.join(path_to_project_name(&to));\n let from_exists = from_dir.exists();\n let to_exists = to_dir.exists();\n moved_codex = move_project_dir(&base, &from, &to, opts.dry_run)?;\n let codex_update = update_codex_sessions(&from, &to, opts.dry_run)?;\n updated_codex_files = codex_update.updated_files;\n remaining_codex_files = codex_update.remaining_files;\n if from_exists && !opts.dry_run {\n if from_dir.exists() {\n println!(\n \"WARN Codex session dir still present: {}\",\n from_dir.display()\n );\n }\n if !to_dir.exists() && !to_exists {\n println!(\n \"WARN Codex session dir missing after migration: {}\",\n to_dir.display()\n );\n }\n }\n }\n if let Some(zvec_path) = resolve_agent_qa_zvec_path() {\n let zvec_update = update_zvec_agent_qa_paths(&zvec_path, &from, &to, opts.dry_run)?;\n updated_zvec_docs = zvec_update.updated_docs;\n zvec_index_found = zvec_update.index_found;\n }\n\n println!(\"Session migration summary:\");\n println!(\" Claude project dirs moved: {}\", moved_claude);\n println!(\" Codex legacy dirs moved: {}\", moved_codex);\n println!(\" Codex jsonl files updated: {}\", updated_codex_files);\n if zvec_index_found {\n println!(\" Seq zvec docs updated: {}\", updated_zvec_docs);\n } else {\n println!(\n \" Seq zvec docs updated: {} (index not found)\",\n updated_zvec_docs\n );\n }\n if !remaining_codex_files.is_empty() {\n println!(\"WARN Codex sessions still reference the old path:\");\n for path in &remaining_codex_files {\n println!(\" {}\", path.display());\n }\n }\n if opts.dry_run {\n println!(\"Dry run only; no files were changed.\");\n }\n\n Ok(())\n}\n\nfn normalize_path(path: &str) -> Result<PathBuf> {\n let expanded = config::expand_path(path);\n let canonical = expanded.canonicalize().unwrap_or(expanded);\n Ok(canonical)\n}\n\nfn normalize_relative_path(path: &str) -> Result<PathBuf> {\n let trimmed = path.trim();\n if trimmed.is_empty() {\n bail!(\"Relative path cannot be empty.\");\n }\n let rel = PathBuf::from(trimmed);\n if rel.is_absolute() {\n bail!(\"Relative path must not be absolute.\");\n }\n for component in rel.components() {\n if matches!(component, std::path::Component::ParentDir) {\n bail!(\"Relative path must not contain '..'.\");\n }\n }\n Ok(rel)\n}\n\nfn move_dir(from: &Path, to: &Path) -> Result<()> {\n match fs::rename(from, to) {\n Ok(()) => Ok(()),\n Err(err) => {\n if is_cross_device(&err) {\n copy_dir_all(from, to)?;\n fs::remove_dir_all(from)\n .with_context(|| format!(\"failed to remove {}\", from.display()))?;\n Ok(())\n } else {\n Err(err).with_context(|| {\n format!(\"failed to move {} to {}\", from.display(), to.display())\n })\n }\n }\n }\n}\n\nfn is_cross_device(err: &std::io::Error) -> bool {\n #[cfg(unix)]\n {\n err.raw_os_error() == Some(libc::EXDEV)\n }\n #[cfg(not(unix))]\n {\n let _ = err;\n false\n }\n}\n\nfn copy_dir_all(from: &Path, to: &Path) -> Result<()> {\n fs::create_dir_all(to).with_context(|| format!(\"failed to create {}\", to.display()))?;\n for entry in fs::read_dir(from).with_context(|| format!(\"failed to read {}\", from.display()))? {\n let entry = entry?;\n let path = entry.path();\n let file_type = entry.file_type()?;\n let target = to.join(entry.file_name());\n\n if target.exists() {\n bail!(\"Refusing to overwrite {}\", target.display());\n }\n\n if file_type.is_dir() {\n copy_dir_all(&path, &target)?;\n } else if file_type.is_file() {\n fs::copy(&path, &target)\n .with_context(|| format!(\"failed to copy {}\", path.display()))?;\n } else if file_type.is_symlink() {\n let link_target = fs::read_link(&path)\n .with_context(|| format!(\"failed to read link {}\", path.display()))?;\n copy_symlink(&link_target, &target)?;\n }\n }\n Ok(())\n}\n\nfn copy_symlink(target: &Path, dest: &Path) -> Result<()> {\n #[cfg(unix)]\n {\n std::os::unix::fs::symlink(target, dest)\n .with_context(|| format!(\"failed to create symlink {}\", dest.display()))?;\n return Ok(());\n }\n #[cfg(not(unix))]\n {\n let metadata =\n fs::metadata(target).with_context(|| format!(\"failed to read {}\", target.display()))?;\n if metadata.is_dir() {\n copy_dir_all(target, dest)?;\n } else {\n fs::copy(target, dest)\n .with_context(|| format!(\"failed to copy {}\", target.display()))?;\n }\n Ok(())\n }\n}\n\nfn relink_bin_symlinks(from: &Path, to: &Path, dry_run: bool) -> Result<usize> {\n let bin_dir = dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"bin\");\n if !bin_dir.exists() {\n return Ok(0);\n }\n\n let mut updated = 0;\n for entry in fs::read_dir(&bin_dir)\n .with_context(|| format!(\"failed to read bin directory {}\", bin_dir.display()))?\n {\n let entry = entry?;\n let path = entry.path();\n let meta = fs::symlink_metadata(&path)?;\n if !meta.file_type().is_symlink() {\n continue;\n }\n\n let link_target = fs::read_link(&path)?;\n let resolved = if link_target.is_absolute() {\n link_target.clone()\n } else {\n path.parent().unwrap_or(&bin_dir).join(&link_target)\n };\n\n if !resolved.starts_with(from) {\n continue;\n }\n\n let suffix = match resolved.strip_prefix(from) {\n Ok(value) => value,\n Err(_) => continue,\n };\n let new_target = to.join(suffix);\n if dry_run {\n println!(\n \"Would relink {} -> {}\",\n path.display(),\n new_target.display()\n );\n } else {\n relink_symlink(&path, &new_target)?;\n }\n updated += 1;\n }\n\n Ok(updated)\n}\n\nfn relink_symlink(path: &Path, target: &Path) -> Result<()> {\n fs::remove_file(path).with_context(|| format!(\"failed to remove {}\", path.display()))?;\n #[cfg(unix)]\n {\n std::os::unix::fs::symlink(target, path)\n .with_context(|| format!(\"failed to create {}\", path.display()))?;\n return Ok(());\n }\n #[cfg(windows)]\n {\n if target.is_dir() {\n std::os::windows::fs::symlink_dir(target, path)\n .with_context(|| format!(\"failed to create {}\", path.display()))?;\n } else {\n std::os::windows::fs::symlink_file(target, path)\n .with_context(|| format!(\"failed to create {}\", path.display()))?;\n }\n return Ok(());\n }\n #[cfg(not(any(unix, windows)))]\n {\n let _ = (path, target);\n Ok(())\n }\n}\n\nfn claude_projects_dir() -> PathBuf {\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".claude\")\n .join(\"projects\")\n}\n\nfn codex_projects_dir() -> PathBuf {\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".codex\")\n .join(\"projects\")\n}\n\nfn codex_sessions_dir() -> PathBuf {\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".codex\")\n .join(\"sessions\")\n}\n\nfn resolve_agent_qa_zvec_path() -> Option<PathBuf> {\n match std::env::var(FLOW_AGENT_QA_ZVEC_JSONL_ENV) {\n Ok(raw) => {\n let trimmed = raw.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(config::expand_path(trimmed))\n }\n }\n Err(_) => Some(config::expand_path(DEFAULT_AGENT_QA_ZVEC_JSONL)),\n }\n}\n\nfn update_zvec_agent_qa_paths(\n zvec_jsonl: &Path,\n from: &Path,\n to: &Path,\n dry_run: bool,\n) -> Result<ZvecMoveSummary> {\n if !zvec_jsonl.exists() {\n return Ok(ZvecMoveSummary {\n updated_docs: 0,\n index_found: false,\n });\n }\n\n let from_str = from.to_string_lossy().to_string();\n let to_str = to.to_string_lossy().to_string();\n let from_project_key = path_to_project_name(from);\n let to_project_key = path_to_project_name(to);\n\n let input = fs::File::open(zvec_jsonl)\n .with_context(|| format!(\"failed to read {}\", zvec_jsonl.display()))?;\n let reader = BufReader::new(input);\n let tmp_path = zvec_jsonl.with_extension(\"jsonl.tmp\");\n let mut writer = if dry_run {\n None\n } else {\n Some(BufWriter::new(fs::File::create(&tmp_path).with_context(\n || format!(\"failed to write {}\", tmp_path.display()),\n )?))\n };\n\n let mut updated_docs = 0;\n for line in reader.lines() {\n let line =\n line.with_context(|| format!(\"failed to read line from {}\", zvec_jsonl.display()))?;\n let mut output_line = line.clone();\n if line.contains(&from_str) || line.contains(&from_project_key) {\n if let Ok(mut value) = serde_json::from_str::<Value>(&line) {\n if rewrite_zvec_doc_paths(\n &mut value,\n &from_str,\n &to_str,\n &from_project_key,\n &to_project_key,\n ) {\n output_line = serde_json::to_string(&value)?;\n updated_docs += 1;\n }\n }\n }\n if let Some(writer) = writer.as_mut() {\n writer.write_all(output_line.as_bytes())?;\n writer.write_all(b\"\\n\")?;\n }\n }\n\n if let Some(mut writer) = writer {\n writer.flush()?;\n fs::rename(&tmp_path, zvec_jsonl)\n .with_context(|| format!(\"failed to replace {}\", zvec_jsonl.display()))?;\n }\n\n Ok(ZvecMoveSummary {\n updated_docs,\n index_found: true,\n })\n}\n\nfn copy_zvec_agent_qa_paths(\n zvec_jsonl: &Path,\n from: &Path,\n to: &Path,\n dry_run: bool,\n) -> Result<ZvecCopySummary> {\n if !zvec_jsonl.exists() {\n return Ok(ZvecCopySummary {\n copied_docs: 0,\n index_found: false,\n });\n }\n\n let from_str = from.to_string_lossy().to_string();\n let to_str = to.to_string_lossy().to_string();\n let from_project_key = path_to_project_name(from);\n let to_project_key = path_to_project_name(to);\n\n let input = fs::File::open(zvec_jsonl)\n .with_context(|| format!(\"failed to read {}\", zvec_jsonl.display()))?;\n let reader = BufReader::new(input);\n let tmp_path = zvec_jsonl.with_extension(\"jsonl.tmp\");\n let mut writer = if dry_run {\n None\n } else {\n Some(BufWriter::new(fs::File::create(&tmp_path).with_context(\n || format!(\"failed to write {}\", tmp_path.display()),\n )?))\n };\n\n let mut copied_docs = 0;\n for line in reader.lines() {\n let line =\n line.with_context(|| format!(\"failed to read line from {}\", zvec_jsonl.display()))?;\n if let Some(writer) = writer.as_mut() {\n writer.write_all(line.as_bytes())?;\n writer.write_all(b\"\\n\")?;\n }\n\n if !line.contains(&from_str) && !line.contains(&from_project_key) {\n continue;\n }\n let Ok(mut value) = serde_json::from_str::<Value>(&line) else {\n continue;\n };\n if !rewrite_zvec_doc_paths(\n &mut value,\n &from_str,\n &to_str,\n &from_project_key,\n &to_project_key,\n ) {\n continue;\n }\n\n let old_id = value.get(\"id\").and_then(|v| v.as_str());\n let new_id = derive_copy_doc_id(old_id, &line, &to_str);\n if let Some(obj) = value.as_object_mut() {\n obj.insert(\"id\".to_string(), Value::String(new_id));\n }\n\n copied_docs += 1;\n if let Some(writer) = writer.as_mut() {\n let copied_line = serde_json::to_string(&value)?;\n writer.write_all(copied_line.as_bytes())?;\n writer.write_all(b\"\\n\")?;\n }\n }\n\n if let Some(mut writer) = writer {\n writer.flush()?;\n fs::rename(&tmp_path, zvec_jsonl)\n .with_context(|| format!(\"failed to replace {}\", zvec_jsonl.display()))?;\n }\n\n Ok(ZvecCopySummary {\n copied_docs,\n index_found: true,\n })\n}\n\nfn rewrite_zvec_doc_paths(\n doc: &mut Value,\n from_path: &str,\n to_path: &str,\n from_project_key: &str,\n to_project_key: &str,\n) -> bool {\n let Some(root) = doc.as_object_mut() else {\n return false;\n };\n let Some(meta_value) = root.get_mut(\"metadata\") else {\n return false;\n };\n let Some(meta) = meta_value.as_object_mut() else {\n return false;\n };\n\n let mut changed = false;\n\n if let Some(project_path) = meta.get(\"project_path\").and_then(|v| v.as_str()) {\n if let Some(rewritten) = rewrite_path_prefix(project_path, from_path, to_path) {\n meta.insert(\"project_path\".to_string(), Value::String(rewritten));\n changed = true;\n }\n }\n\n if let Some(source_path) = meta.get(\"source_path\").and_then(|v| v.as_str()) {\n if let Some(rewritten) =\n rewrite_project_source_path(source_path, from_project_key, to_project_key)\n {\n meta.insert(\"source_path\".to_string(), Value::String(rewritten));\n changed = true;\n }\n }\n\n changed\n}\n\nfn rewrite_path_prefix(value: &str, from: &str, to: &str) -> Option<String> {\n if value == from {\n return Some(to.to_string());\n }\n let prefix = format!(\"{from}/\");\n if let Some(suffix) = value.strip_prefix(&prefix) {\n return Some(format!(\"{to}/{suffix}\"));\n }\n None\n}\n\nfn rewrite_project_source_path(\n source_path: &str,\n from_project_key: &str,\n to_project_key: &str,\n) -> Option<String> {\n for marker in [\"/.claude/projects/\", \"/.codex/projects/\"] {\n let old = format!(\"{marker}{from_project_key}\");\n if source_path.contains(&old) {\n let new = format!(\"{marker}{to_project_key}\");\n return Some(source_path.replacen(&old, &new, 1));\n }\n }\n None\n}\n\nfn derive_copy_doc_id(existing_id: Option<&str>, line: &str, to: &str) -> String {\n if let Some(id) = existing_id {\n return derive_copy_id(id, to);\n }\n let mut hasher = DefaultHasher::new();\n line.hash(&mut hasher);\n to.hash(&mut hasher);\n let hash = hasher.finish();\n format!(\"agent-qa-copy-{hash:x}\")\n}\n\nfn move_project_dir(base: &Path, from: &Path, to: &Path, dry_run: bool) -> Result<usize> {\n if !base.exists() {\n return Ok(0);\n }\n\n let from_name = path_to_project_name(from);\n let to_name = path_to_project_name(to);\n let from_dir = base.join(&from_name);\n let to_dir = base.join(&to_name);\n\n if !from_dir.exists() {\n return Ok(0);\n }\n if to_dir.exists() {\n println!(\"Skip: {} already exists\", to_dir.display());\n return Ok(0);\n }\n\n if dry_run {\n println!(\"Would move {} -> {}\", from_dir.display(), to_dir.display());\n } else {\n if let Some(parent) = to_dir.parent() {\n fs::create_dir_all(parent)?;\n }\n fs::rename(&from_dir, &to_dir).with_context(|| {\n format!(\n \"failed to move {} to {}\",\n from_dir.display(),\n to_dir.display()\n )\n })?;\n }\n\n Ok(1)\n}\n\nfn copy_project_dir(base: &Path, from: &Path, to: &Path, dry_run: bool) -> Result<usize> {\n if !base.exists() {\n return Ok(0);\n }\n\n let from_name = path_to_project_name(from);\n let to_name = path_to_project_name(to);\n let from_dir = base.join(&from_name);\n let to_dir = base.join(&to_name);\n\n if !from_dir.exists() {\n return Ok(0);\n }\n if to_dir.exists() {\n println!(\"Skip: {} already exists\", to_dir.display());\n return Ok(0);\n }\n\n if dry_run {\n println!(\"Would copy {} -> {}\", from_dir.display(), to_dir.display());\n } else {\n if let Some(parent) = to_dir.parent() {\n fs::create_dir_all(parent)?;\n }\n copy_dir_all(&from_dir, &to_dir)?;\n }\n\n Ok(1)\n}\n\nfn path_to_project_name(path: &Path) -> String {\n path.to_string_lossy().replace('/', \"-\")\n}\n\nstruct CodexCopySummary {\n copied_files: usize,\n}\n\nfn copy_codex_sessions(from: &Path, to: &Path, dry_run: bool) -> Result<CodexCopySummary> {\n let root = codex_sessions_dir();\n if !root.exists() {\n return Ok(CodexCopySummary { copied_files: 0 });\n }\n\n let from_str = from.to_string_lossy().to_string();\n let to_str = to.to_string_lossy().to_string();\n let mut copied_files = 0;\n\n try_for_each_codex_session_file(&root, |file_path| {\n if let Some(copy_path) = copy_codex_session_file(&file_path, &from_str, &to_str, dry_run)? {\n copied_files += 1;\n if dry_run {\n println!(\n \"Would copy session {} -> {}\",\n file_path.display(),\n copy_path.display()\n );\n }\n }\n Ok(())\n })?;\n\n Ok(CodexCopySummary { copied_files })\n}\n\nstruct CodexUpdateSummary {\n updated_files: usize,\n remaining_files: Vec<PathBuf>,\n}\n\nfn copy_codex_session_file(\n path: &Path,\n from: &str,\n to: &str,\n dry_run: bool,\n) -> Result<Option<PathBuf>> {\n let content =\n fs::read_to_string(path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let ends_with_newline = content.ends_with('\\n');\n let mut matched = false;\n let mut old_id: Option<String> = None;\n let mut parsed_lines: Vec<(String, Option<Value>)> = Vec::new();\n\n for line in content.lines() {\n if line.trim().is_empty() {\n parsed_lines.push((String::new(), None));\n continue;\n }\n if !line.contains(\"\\\"session_meta\\\"\") {\n parsed_lines.push((line.to_string(), None));\n continue;\n }\n\n match serde_json::from_str::<Value>(line) {\n Ok(value) => {\n if value.get(\"type\").and_then(|v| v.as_str()) == Some(\"session_meta\") {\n if let Some(payload) = value.get(\"payload\").and_then(|v| v.as_object()) {\n if old_id.is_none() {\n old_id = payload\n .get(\"id\")\n .and_then(|v| v.as_str())\n .map(|s| s.to_string());\n }\n if payload.get(\"cwd\").and_then(|v| v.as_str()) == Some(from) {\n matched = true;\n }\n }\n }\n parsed_lines.push((line.to_string(), Some(value)));\n }\n Err(_) => parsed_lines.push((line.to_string(), None)),\n }\n }\n\n if !matched {\n return Ok(None);\n }\n\n let fallback_id = path\n .file_stem()\n .and_then(|s| s.to_str())\n .unwrap_or(\"session\")\n .to_string();\n let old_id = old_id.unwrap_or(fallback_id);\n let new_id = derive_copy_id(&old_id, to);\n let copy_path = derive_copy_path(path, &old_id, &new_id);\n\n let mut lines = Vec::new();\n for (raw, value) in parsed_lines {\n if let Some(mut value) = value {\n if value.get(\"type\").and_then(|v| v.as_str()) == Some(\"session_meta\") {\n if let Some(payload) = value.get_mut(\"payload\") {\n if let Some(obj) = payload.as_object_mut() {\n if obj.get(\"cwd\").and_then(|v| v.as_str()) == Some(from) {\n obj.insert(\"cwd\".to_string(), Value::String(to.to_string()));\n obj.insert(\"id\".to_string(), Value::String(new_id.clone()));\n lines.push(serde_json::to_string(&value)?);\n continue;\n }\n }\n }\n }\n }\n lines.push(raw);\n }\n\n if dry_run {\n return Ok(Some(copy_path));\n }\n\n let mut output = lines.join(\"\\n\");\n if ends_with_newline {\n output.push('\\n');\n }\n fs::write(©_path, output.as_bytes())\n .with_context(|| format!(\"failed to write {}\", copy_path.display()))?;\n\n Ok(Some(copy_path))\n}\n\nfn derive_copy_id(old_id: &str, to: &str) -> String {\n let mut hasher = DefaultHasher::new();\n old_id.hash(&mut hasher);\n to.hash(&mut hasher);\n let hash = hasher.finish();\n format!(\"{old_id}-copy-{hash:x}\")\n}\n\nfn derive_copy_path(path: &Path, old_id: &str, new_id: &str) -> PathBuf {\n let parent = path.parent().unwrap_or_else(|| Path::new(\".\"));\n let filename = path\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(\"session.jsonl\");\n let base_name = if filename.contains(old_id) {\n filename.replace(old_id, new_id)\n } else {\n let stem = path\n .file_stem()\n .and_then(|s| s.to_str())\n .unwrap_or(\"session\");\n format!(\"{stem}-{new_id}.jsonl\")\n };\n unique_copy_path(parent, &base_name)\n}\n\nfn unique_copy_path(parent: &Path, base_name: &str) -> PathBuf {\n let mut candidate = parent.join(base_name);\n if !candidate.exists() {\n return candidate;\n }\n for i in 1..=1000 {\n let alt = insert_suffix(base_name, &format!(\"-{}\", i));\n candidate = parent.join(&alt);\n if !candidate.exists() {\n return candidate;\n }\n }\n candidate\n}\n\nfn insert_suffix(filename: &str, suffix: &str) -> String {\n if let Some(idx) = filename.rfind('.') {\n format!(\"{}{}{}\", &filename[..idx], suffix, &filename[idx..])\n } else {\n format!(\"{}{}\", filename, suffix)\n }\n}\n\nfn update_codex_sessions(from: &Path, to: &Path, dry_run: bool) -> Result<CodexUpdateSummary> {\n let root = codex_sessions_dir();\n if !root.exists() {\n return Ok(CodexUpdateSummary {\n updated_files: 0,\n remaining_files: Vec::new(),\n });\n }\n\n let from_str = from.to_string_lossy().to_string();\n let to_str = to.to_string_lossy().to_string();\n let mut updated_files = 0;\n let mut remaining_files = Vec::new();\n\n try_for_each_codex_session_file(&root, |file_path| {\n let result = update_codex_session_file(&file_path, &from_str, &to_str, dry_run)?;\n if result.updated {\n updated_files += 1;\n }\n if result.remaining {\n remaining_files.push(file_path);\n }\n Ok(())\n })?;\n\n Ok(CodexUpdateSummary {\n updated_files,\n remaining_files,\n })\n}\n\nfn try_for_each_codex_session_file(\n root: &Path,\n mut visit: impl FnMut(PathBuf) -> Result<()>,\n) -> Result<()> {\n let mut stack = vec![root.to_path_buf()];\n\n while let Some(dir) = stack.pop() {\n let entries = match fs::read_dir(&dir) {\n Ok(v) => v,\n Err(_) => continue,\n };\n\n for entry in entries.flatten() {\n let path = entry.path();\n if path.is_dir() {\n stack.push(path);\n } else if path.extension().map(|e| e == \"jsonl\").unwrap_or(false) {\n visit(path)?;\n }\n }\n }\n\n Ok(())\n}\n\nstruct CodexFileUpdate {\n updated: bool,\n remaining: bool,\n}\n\nfn update_codex_session_file(\n path: &Path,\n from: &str,\n to: &str,\n dry_run: bool,\n) -> Result<CodexFileUpdate> {\n let content =\n fs::read_to_string(path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let mut changed = false;\n let mut matched = false;\n let mut lines = Vec::new();\n let ends_with_newline = content.ends_with('\\n');\n\n for line in content.lines() {\n if line.trim().is_empty() {\n lines.push(String::new());\n continue;\n }\n if !line.contains(\"\\\"session_meta\\\"\") {\n lines.push(line.to_string());\n continue;\n }\n\n match serde_json::from_str::<Value>(line) {\n Ok(mut value) => {\n let mut updated_line = false;\n if value.get(\"type\").and_then(|v| v.as_str()) == Some(\"session_meta\") {\n if let Some(payload) = value.get_mut(\"payload\") {\n if let Some(obj) = payload.as_object_mut() {\n if obj.get(\"cwd\").and_then(|v| v.as_str()) == Some(from) {\n matched = true;\n obj.insert(\"cwd\".to_string(), Value::String(to.to_string()));\n updated_line = true;\n }\n }\n }\n }\n if updated_line {\n changed = true;\n lines.push(serde_json::to_string(&value)?);\n } else {\n lines.push(line.to_string());\n }\n }\n Err(_) => lines.push(line.to_string()),\n }\n }\n\n if !changed {\n let remaining = if matched && !dry_run {\n file_has_session_meta_cwd(path, from)?\n } else {\n false\n };\n return Ok(CodexFileUpdate {\n updated: false,\n remaining,\n });\n }\n\n if dry_run {\n println!(\"Would update {}\", path.display());\n return Ok(CodexFileUpdate {\n updated: true,\n remaining: true,\n });\n }\n\n let mut output = lines.join(\"\\n\");\n if ends_with_newline {\n output.push('\\n');\n }\n let tmp_path = path.with_extension(\"jsonl.tmp\");\n fs::write(&tmp_path, output.as_bytes())\n .with_context(|| format!(\"failed to write {}\", tmp_path.display()))?;\n fs::rename(&tmp_path, path).with_context(|| format!(\"failed to replace {}\", path.display()))?;\n let remaining = file_has_session_meta_cwd(path, from)?;\n Ok(CodexFileUpdate {\n updated: true,\n remaining,\n })\n}\n\nfn file_has_session_meta_cwd(path: &Path, from: &str) -> Result<bool> {\n let content =\n fs::read_to_string(path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n Ok(content\n .lines()\n .any(|line| session_meta_cwd_matches(line, from)))\n}\n\nfn session_meta_cwd_matches(line: &str, from: &str) -> bool {\n if line.trim().is_empty() {\n return false;\n }\n if !line.contains(\"\\\"session_meta\\\"\") {\n return false;\n }\n let Ok(value) = serde_json::from_str::<Value>(line) else {\n return false;\n };\n if value.get(\"type\").and_then(|v| v.as_str()) != Some(\"session_meta\") {\n return false;\n }\n let Some(payload) = value.get(\"payload\") else {\n return false;\n };\n let Some(obj) = payload.as_object() else {\n return false;\n };\n obj.get(\"cwd\").and_then(|v| v.as_str()) == Some(from)\n}\n\nfn ensure_dir(path: &Path, dry_run: bool, planned: &mut Vec<PathBuf>) -> Result<()> {\n if path.exists() {\n return Ok(());\n }\n if planned.iter().any(|p| p == path) {\n return Ok(());\n }\n if dry_run {\n println!(\"Would create {}\", path.display());\n planned.push(path.to_path_buf());\n return Ok(());\n }\n fs::create_dir_all(path).with_context(|| format!(\"failed to create {}\", path.display()))?;\n planned.push(path.to_path_buf());\n Ok(())\n}\n\nfn gitignore_entry_for_target(target: &Path) -> Result<Option<(PathBuf, String)>> {\n let root = find_git_root(target)?;\n let Some(repo_root) = root else {\n return Ok(None);\n };\n let relative = target\n .strip_prefix(&repo_root)\n .unwrap_or(target)\n .to_string_lossy()\n .replace('\\\\', \"/\");\n let mut entry = relative.trim().trim_start_matches(\"./\").to_string();\n if entry.is_empty() {\n return Ok(None);\n }\n if !entry.ends_with('/') {\n entry.push('/');\n }\n Ok(Some((repo_root, entry)))\n}\n\nfn find_git_root(start: &Path) -> Result<Option<PathBuf>> {\n let mut current = start.to_path_buf();\n if !current.exists() {\n if let Some(parent) = current.parent() {\n current = parent.to_path_buf();\n }\n }\n loop {\n let git_dir = current.join(\".git\");\n if git_dir.is_dir() || git_dir.is_file() {\n return Ok(Some(current));\n }\n if !current.pop() {\n return Ok(None);\n }\n }\n}\n\nfn ensure_gitignore_entry(repo_root: &Path, entry: &str) -> Result<()> {\n let gitignore = repo_root.join(\".gitignore\");\n let entry_trimmed = entry.trim().trim_end_matches('/');\n let entry_with_slash = format!(\"{}/\", entry_trimmed);\n let mut existing = String::new();\n if gitignore.exists() {\n existing = fs::read_to_string(&gitignore)\n .with_context(|| format!(\"failed to read {}\", gitignore.display()))?;\n if existing.lines().any(|line| {\n let trimmed = line.trim();\n trimmed == entry_trimmed || trimmed == entry_with_slash\n }) {\n return Ok(());\n }\n }\n let mut output = existing;\n if !output.is_empty() && !output.ends_with('\\n') {\n output.push('\\n');\n }\n output.push_str(&entry_with_slash);\n output.push('\\n');\n fs::write(&gitignore, output.as_bytes())\n .with_context(|| format!(\"failed to write {}\", gitignore.display()))?;\n Ok(())\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use tempfile::tempdir;\n\n #[test]\n fn rewrite_path_prefix_rewrites_exact_and_nested_paths() {\n let from = \"~/code/org/linsa/linsa-mac\";\n let to = \"~/code/org/linsa/linsa-native\";\n assert_eq!(rewrite_path_prefix(from, from, to), Some(to.to_string()));\n assert_eq!(\n rewrite_path_prefix(\"~/code/org/linsa/linsa-mac/src/ui\", from, to),\n Some(\"~/code/org/linsa/linsa-native/src/ui\".to_string())\n );\n assert_eq!(\n rewrite_path_prefix(\"~/code/org/linsa/linsa\", from, to),\n None\n );\n }\n\n #[test]\n fn rewrite_zvec_doc_paths_updates_project_and_source_paths() {\n let from = \"~/code/org/linsa/linsa-mac\";\n let to = \"~/code/org/linsa/linsa-native\";\n let from_key = path_to_project_name(Path::new(from));\n let to_key = path_to_project_name(Path::new(to));\n let mut value = serde_json::json!({\n \"id\": \"doc-1\",\n \"text\": \"Question: q\\n\\nAnswer: a\",\n \"metadata\": {\n \"project_path\": \"~/code/org/linsa/linsa-mac/src\",\n \"source_path\": format!(\n \"~/.claude/projects/{from_key}/session.jsonl\"\n )\n }\n });\n\n let changed = rewrite_zvec_doc_paths(&mut value, from, to, &from_key, &to_key);\n assert!(changed);\n assert_eq!(\n value\n .get(\"metadata\")\n .and_then(|m| m.get(\"project_path\"))\n .and_then(|v| v.as_str()),\n Some(\"~/code/org/linsa/linsa-native/src\")\n );\n assert_eq!(\n value\n .get(\"metadata\")\n .and_then(|m| m.get(\"source_path\"))\n .and_then(|v| v.as_str()),\n Some(format!(\"~/.claude/projects/{to_key}/session.jsonl\").as_str())\n );\n }\n\n #[test]\n fn zvec_move_and_copy_update_project_scope() -> Result<()> {\n let tmp = tempdir()?;\n let zvec_path = tmp.path().join(\"agent_qa.jsonl\");\n let from = Path::new(\"~/code/org/linsa/linsa-mac\");\n let to = Path::new(\"~/code/org/linsa/linsa-native\");\n let from_key = path_to_project_name(from);\n\n let row = serde_json::json!({\n \"id\": \"doc-1\",\n \"text\": \"Question: q\\n\\nAnswer: a\",\n \"metadata\": {\n \"agent\": \"codex\",\n \"session_id\": \"s1\",\n \"project_path\": \"~/code/org/linsa/linsa-mac\",\n \"source_path\": format!(\"~/.claude/projects/{from_key}/s1.jsonl\"),\n \"ts_ms\": 1\n }\n });\n fs::write(&zvec_path, format!(\"{}\\n\", serde_json::to_string(&row)?))?;\n\n let move_summary = update_zvec_agent_qa_paths(&zvec_path, from, to, false)?;\n assert_eq!(move_summary.updated_docs, 1);\n let moved = fs::read_to_string(&zvec_path)?;\n assert!(moved.contains(\"~/code/org/linsa/linsa-native\"));\n assert!(!moved.contains(\"~/code/org/linsa/linsa-mac\\\"\"));\n\n fs::write(&zvec_path, format!(\"{}\\n\", serde_json::to_string(&row)?))?;\n let copy_summary = copy_zvec_agent_qa_paths(&zvec_path, from, to, false)?;\n assert_eq!(copy_summary.copied_docs, 1);\n let copied = fs::read_to_string(&zvec_path)?;\n assert!(copied.contains(\"~/code/org/linsa/linsa-mac\"));\n assert!(copied.contains(\"~/code/org/linsa/linsa-native\"));\n assert!(copied.contains(\"doc-1-copy-\"));\n\n Ok(())\n }\n}\n" }, { "path": "src/codex_memory.rs", "content": "use std::fs;\nuse std::path::{Path, PathBuf};\nuse std::time::Duration;\n\nuse anyhow::{Context, Result};\nuse ignore::WalkBuilder;\nuse rusqlite::{Connection, params};\nuse serde::Serialize;\nuse sha2::{Digest, Sha256};\n\nuse crate::codex_skill_eval::{self, CodexSkillEvalEvent, CodexSkillOutcomeEvent};\nuse crate::{ai, codex_text, config, jazz_state, repo_capsule};\n\nconst MEMORY_ROOT_ENV: &str = \"FLOW_CODEX_MEMORY_ROOT\";\nconst REPO_SYMBOL_INDEX_KIND: &str = \"repo_symbols\";\nconst REPO_SYMBOL_INDEX_VERSION: u32 = 1;\nconst REPO_SESSION_INDEX_KIND: &str = \"repo_sessions\";\nconst REPO_SESSION_INDEX_VERSION: u32 = 1;\nconst MAX_SYMBOL_FILES: usize = 24;\nconst MAX_SYMBOLS_PER_FILE: usize = 8;\nconst MAX_SYMBOL_FILE_BYTES: usize = 256 * 1024;\nconst MAX_SNIPPET_LINES: usize = 4;\nconst MAX_SNIPPET_CHARS: usize = 220;\nconst MAX_SESSION_THREADS: usize = 6;\nconst MAX_SESSION_EXCHANGES_PER_THREAD: usize = 2;\nconst MAX_SESSION_TEXT_CHARS: usize = 240;\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexMemoryStats {\n pub root_dir: String,\n pub db_path: String,\n pub total_events: usize,\n pub total_facts: usize,\n pub skill_eval_events: usize,\n pub skill_eval_outcomes: usize,\n pub latest_recorded_at_unix: Option<u64>,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexMemoryRecentEntry {\n pub event_kind: String,\n pub recorded_at_unix: u64,\n pub target_path: Option<String>,\n pub session_id: Option<String>,\n pub route: Option<String>,\n pub query: Option<String>,\n pub success: Option<f64>,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexMemorySyncSummary {\n pub total_considered: usize,\n pub inserted: usize,\n pub skipped: usize,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexMemoryFactHit {\n pub fact_kind: String,\n pub title: String,\n pub body: String,\n pub path_hint: Option<String>,\n pub source_tag: String,\n pub score: f64,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexMemoryCodeHit {\n pub path: String,\n pub score: f64,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexMemorySnippetHit {\n pub path: String,\n pub symbol: String,\n pub snippet: String,\n pub score: f64,\n}\n\n#[derive(Debug, Clone, Serialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexMemoryQueryResult {\n pub repo_root: String,\n pub query: String,\n pub facts: Vec<CodexMemoryFactHit>,\n pub code_paths: Vec<CodexMemoryCodeHit>,\n pub snippets: Vec<CodexMemorySnippetHit>,\n pub rendered: String,\n}\n\n#[derive(Debug, Clone, PartialEq, Eq)]\nstruct RepoSymbolFact {\n fact_kind: &'static str,\n title: String,\n body: String,\n path_hint: String,\n}\n\n#[derive(Debug, Clone)]\nstruct QueryProfile {\n tokens: Vec<String>,\n code_intent: bool,\n docs_intent: bool,\n explicit_paths: Vec<String>,\n}\n\npub fn root_dir() -> PathBuf {\n if let Ok(path) = std::env::var(MEMORY_ROOT_ENV) {\n let trimmed = path.trim();\n if !trimmed.is_empty() {\n return config::expand_path(trimmed);\n }\n }\n jazz_state::state_dir().join(\"codex-memory\")\n}\n\npub fn db_path() -> PathBuf {\n root_dir().join(\"memory.sqlite\")\n}\n\npub fn mirror_skill_eval_event(event: &CodexSkillEvalEvent) -> Result<bool> {\n let mut sanitized = event.clone();\n let Some(query) = codex_text::sanitize_codex_query_text(&sanitized.query) else {\n return Ok(false);\n };\n sanitized.query = query;\n let payload = serde_json::to_string(&sanitized).context(\"failed to encode skill-eval event\")?;\n let conn = open_connection()?;\n insert_marshaled(\n &conn,\n \"skill_eval_event\",\n sanitized.recorded_at_unix,\n Some(sanitized.target_path.as_str()),\n sanitized.session_id.as_deref(),\n sanitized.runtime_token.as_deref(),\n Some(sanitized.route.as_str()),\n Some(sanitized.query.as_str()),\n None,\n &payload,\n )\n}\n\npub fn mirror_skill_outcome_event(outcome: &CodexSkillOutcomeEvent) -> Result<bool> {\n let payload = serde_json::to_string(outcome).context(\"failed to encode skill outcome\")?;\n let conn = open_connection()?;\n insert_marshaled(\n &conn,\n \"skill_eval_outcome\",\n outcome.recorded_at_unix,\n outcome.target_path.as_deref(),\n outcome.session_id.as_deref(),\n outcome.runtime_token.as_deref(),\n None,\n None,\n Some(outcome.success),\n &payload,\n )\n}\n\npub fn stats() -> Result<CodexMemoryStats> {\n let conn = open_connection()?;\n let mut stmt = conn.prepare(\n \"SELECT \\\n COUNT(*), \\\n (SELECT COUNT(*) FROM codex_memory_facts), \\\n COALESCE(SUM(CASE WHEN event_kind = 'skill_eval_event' THEN 1 ELSE 0 END), 0), \\\n COALESCE(SUM(CASE WHEN event_kind = 'skill_eval_outcome' THEN 1 ELSE 0 END), 0), \\\n MAX(recorded_at_unix) \\\n FROM codex_memory_events\",\n )?;\n let (total, facts, evals, outcomes, latest): (i64, i64, i64, i64, Option<i64>) = stmt\n .query_row([], |row| {\n Ok((\n row.get(0)?,\n row.get(1)?,\n row.get(2)?,\n row.get(3)?,\n row.get(4)?,\n ))\n })?;\n Ok(CodexMemoryStats {\n root_dir: root_dir().display().to_string(),\n db_path: db_path().display().to_string(),\n total_events: total.max(0) as usize,\n total_facts: facts.max(0) as usize,\n skill_eval_events: evals.max(0) as usize,\n skill_eval_outcomes: outcomes.max(0) as usize,\n latest_recorded_at_unix: latest.map(|value| value.max(0) as u64),\n })\n}\n\npub fn recent(target_path: Option<&Path>, limit: usize) -> Result<Vec<CodexMemoryRecentEntry>> {\n let conn = open_connection()?;\n let mut rows = Vec::new();\n if let Some(target_path) = target_path {\n let target = target_path.display().to_string();\n let target_prefix = format!(\"{}/%\", target.trim_end_matches('/'));\n let mut stmt = conn.prepare(\n \"SELECT event_kind, recorded_at_unix, target_path, session_id, route, query, success \\\n FROM codex_memory_events \\\n WHERE target_path = ?1 OR target_path LIKE ?2 \\\n ORDER BY recorded_at_unix DESC \\\n LIMIT ?3\",\n )?;\n let mut query = stmt.query(params![target, target_prefix, limit as i64])?;\n while let Some(row) = query.next()? {\n rows.push(map_recent_entry(row)?);\n }\n } else {\n let mut stmt = conn.prepare(\n \"SELECT event_kind, recorded_at_unix, target_path, session_id, route, query, success \\\n FROM codex_memory_events \\\n ORDER BY recorded_at_unix DESC \\\n LIMIT ?1\",\n )?;\n let mut query = stmt.query(params![limit as i64])?;\n while let Some(row) = query.next()? {\n rows.push(map_recent_entry(row)?);\n }\n }\n Ok(rows)\n}\n\npub fn sync_from_skill_eval_logs(limit: usize) -> Result<CodexMemorySyncSummary> {\n let mut total_considered = 0usize;\n let mut inserted = 0usize;\n\n for event in codex_skill_eval::load_events(None, limit)? {\n total_considered += 1;\n if mirror_skill_eval_event(&event)? {\n inserted += 1;\n }\n }\n for outcome in codex_skill_eval::load_outcomes(None, limit)? {\n total_considered += 1;\n if mirror_skill_outcome_event(&outcome)? {\n inserted += 1;\n }\n }\n\n Ok(CodexMemorySyncSummary {\n total_considered,\n inserted,\n skipped: total_considered.saturating_sub(inserted),\n })\n}\n\npub fn sync_repo_capsule_for_path(path: &Path) -> Result<usize> {\n let capsule = repo_capsule::load_or_refresh_capsule_for_path(path)?;\n mirror_repo_capsule(&capsule)\n}\n\npub fn mirror_repo_capsule(capsule: &repo_capsule::RepoCapsule) -> Result<usize> {\n let conn = open_connection()?;\n let mut changes = 0usize;\n let repo_root = capsule.repo_root.as_str();\n let updated_at_unix = capsule.updated_at_unix;\n\n changes += upsert_fact(\n &conn,\n repo_root,\n \"summary\",\n &format!(\"Summary for {}\", capsule.repo_id),\n &capsule.summary,\n None,\n \"repo_capsule\",\n updated_at_unix,\n )?;\n\n if !capsule.languages.is_empty() {\n changes += upsert_fact(\n &conn,\n repo_root,\n \"languages\",\n &format!(\"Languages in {}\", capsule.repo_id),\n &capsule.languages.join(\", \"),\n None,\n \"repo_capsule\",\n updated_at_unix,\n )?;\n }\n\n if !capsule.manifests.is_empty() {\n changes += upsert_fact(\n &conn,\n repo_root,\n \"manifests\",\n &format!(\"Manifests in {}\", capsule.repo_id),\n &capsule.manifests.join(\", \"),\n None,\n \"repo_capsule\",\n updated_at_unix,\n )?;\n }\n\n for command in &capsule.commands {\n changes += upsert_fact(\n &conn,\n repo_root,\n \"command\",\n &format!(\"Command: {}\", command),\n &format!(\"Use `{command}` in {}\", capsule.repo_id),\n None,\n \"repo_capsule\",\n updated_at_unix,\n )?;\n }\n\n for path in &capsule.important_paths {\n changes += upsert_fact(\n &conn,\n repo_root,\n \"important_path\",\n &format!(\"Important path: {}\", path),\n &format!(\"Key file or directory in {}: {}\", capsule.repo_id, path),\n Some(path),\n \"repo_capsule\",\n updated_at_unix,\n )?;\n }\n\n for hint in &capsule.docs_hints {\n changes += upsert_fact(\n &conn,\n repo_root,\n \"docs_hint\",\n &format!(\"Docs hint for {}\", capsule.repo_id),\n hint,\n None,\n \"repo_capsule\",\n updated_at_unix,\n )?;\n }\n\n changes += sync_repo_symbol_facts(&conn, capsule)?;\n if let Ok(session_changes) = sync_repo_session_facts(&conn, capsule) {\n changes += session_changes;\n }\n\n Ok(changes)\n}\n\npub fn query_repo_facts(\n path: &Path,\n query: &str,\n limit: usize,\n) -> Result<Option<CodexMemoryQueryResult>> {\n let capsule = repo_capsule::load_or_refresh_capsule_for_path(path)?;\n let _ = mirror_repo_capsule(&capsule);\n let profile = build_query_profile(query);\n let conn = open_connection()?;\n let mut stmt = conn.prepare(\n \"SELECT fact_kind, title, body, path_hint, source_tag \\\n FROM codex_memory_facts \\\n WHERE target_path = ?1 \\\n ORDER BY updated_at_unix DESC\",\n )?;\n let mut rows = stmt.query(params![capsule.repo_root.as_str()])?;\n let mut hits = Vec::new();\n while let Some(row) = rows.next()? {\n let fact_kind: String = row.get(0)?;\n let title: String = row.get(1)?;\n let body: String = row.get(2)?;\n let path_hint: Option<String> = row.get(3)?;\n let source_tag: String = row.get(4)?;\n let score = fact_score(&profile, &fact_kind, &title, &body, path_hint.as_deref());\n if score <= 0.0 {\n continue;\n }\n hits.push(CodexMemoryFactHit {\n fact_kind,\n title,\n body,\n path_hint,\n source_tag,\n score,\n });\n }\n\n hits.sort_by(|a, b| b.score.total_cmp(&a.score));\n let mut code_paths = search_code_paths(Path::new(&capsule.repo_root), &profile, limit);\n let dynamic_symbols =\n search_symbols_for_code_paths(Path::new(&capsule.repo_root), &code_paths, &profile, limit);\n merge_dynamic_symbol_hits(&mut hits, dynamic_symbols);\n hits.sort_by(|a, b| b.score.total_cmp(&a.score));\n hits.truncate(limit);\n if hits.is_empty() && code_paths.is_empty() {\n return Ok(None);\n }\n let snippets = extract_symbol_snippets(Path::new(&capsule.repo_root), &hits, 2);\n\n if !hits.is_empty() {\n let hinted_paths: std::collections::BTreeSet<_> = hits\n .iter()\n .filter_map(|hit| hit.path_hint.as_deref())\n .collect();\n code_paths.retain(|hit| !hinted_paths.contains(hit.path.as_str()));\n }\n\n let rendered = render_query_result(\n &capsule.repo_root,\n query,\n &profile,\n &hits,\n &code_paths,\n &snippets,\n );\n Ok(Some(CodexMemoryQueryResult {\n repo_root: capsule.repo_root,\n query: query.trim().to_string(),\n facts: hits,\n code_paths,\n snippets,\n rendered,\n }))\n}\n\nfn open_connection() -> Result<Connection> {\n open_connection_at(&db_path())\n}\n\nfn open_connection_at(path: &Path) -> Result<Connection> {\n let parent = path\n .parent()\n .ok_or_else(|| anyhow::anyhow!(\"missing parent for {}\", path.display()))?;\n fs::create_dir_all(parent).with_context(|| format!(\"failed to create {}\", parent.display()))?;\n let conn =\n Connection::open(path).with_context(|| format!(\"failed to open {}\", path.display()))?;\n conn.busy_timeout(Duration::from_millis(1500))?;\n conn.pragma_update(None, \"journal_mode\", \"WAL\")?;\n conn.pragma_update(None, \"synchronous\", \"NORMAL\")?;\n conn.pragma_update(None, \"temp_store\", \"MEMORY\")?;\n conn.execute_batch(\n \"CREATE TABLE IF NOT EXISTS codex_memory_events (\n event_key TEXT PRIMARY KEY,\n event_kind TEXT NOT NULL,\n recorded_at_unix INTEGER NOT NULL,\n target_path TEXT,\n session_id TEXT,\n runtime_token TEXT,\n route TEXT,\n query TEXT,\n success REAL,\n payload_json TEXT NOT NULL\n );\n CREATE INDEX IF NOT EXISTS idx_codex_memory_events_target_time\n ON codex_memory_events(target_path, recorded_at_unix DESC);\n CREATE INDEX IF NOT EXISTS idx_codex_memory_events_session_time\n ON codex_memory_events(session_id, recorded_at_unix DESC);\n CREATE INDEX IF NOT EXISTS idx_codex_memory_events_kind_time\n ON codex_memory_events(event_kind, recorded_at_unix DESC);\n CREATE TABLE IF NOT EXISTS codex_memory_facts (\n fact_key TEXT PRIMARY KEY,\n target_path TEXT NOT NULL,\n fact_kind TEXT NOT NULL,\n title TEXT NOT NULL,\n body TEXT NOT NULL,\n path_hint TEXT,\n source_tag TEXT NOT NULL,\n updated_at_unix INTEGER NOT NULL\n );\n CREATE INDEX IF NOT EXISTS idx_codex_memory_facts_target_time\n ON codex_memory_facts(target_path, updated_at_unix DESC);\n CREATE INDEX IF NOT EXISTS idx_codex_memory_facts_kind\n ON codex_memory_facts(fact_kind);\n CREATE TABLE IF NOT EXISTS codex_memory_indexes (\n target_path TEXT NOT NULL,\n index_kind TEXT NOT NULL,\n version INTEGER NOT NULL,\n source_updated_at_unix INTEGER NOT NULL,\n updated_at_unix INTEGER NOT NULL,\n PRIMARY KEY(target_path, index_kind)\n );\",\n )?;\n Ok(conn)\n}\n\nfn insert_marshaled(\n conn: &Connection,\n event_kind: &str,\n recorded_at_unix: u64,\n target_path: Option<&str>,\n session_id: Option<&str>,\n runtime_token: Option<&str>,\n route: Option<&str>,\n query: Option<&str>,\n success: Option<f64>,\n payload_json: &str,\n) -> Result<bool> {\n let key = event_key(event_kind, payload_json);\n let changed = conn.execute(\n \"INSERT OR IGNORE INTO codex_memory_events (\n event_key,\n event_kind,\n recorded_at_unix,\n target_path,\n session_id,\n runtime_token,\n route,\n query,\n success,\n payload_json\n ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)\",\n params![\n key,\n event_kind,\n recorded_at_unix as i64,\n target_path,\n session_id,\n runtime_token,\n route,\n query,\n success,\n payload_json\n ],\n )?;\n Ok(changed > 0)\n}\n\nfn event_key(event_kind: &str, payload_json: &str) -> String {\n let mut hasher = Sha256::new();\n hasher.update(event_kind.as_bytes());\n hasher.update([0u8]);\n hasher.update(payload_json.as_bytes());\n format!(\"{:x}\", hasher.finalize())\n}\n\nfn fact_key(\n target_path: &str,\n fact_kind: &str,\n title: &str,\n body: &str,\n path_hint: Option<&str>,\n) -> String {\n let mut hasher = Sha256::new();\n hasher.update(target_path.as_bytes());\n hasher.update([0u8]);\n hasher.update(fact_kind.as_bytes());\n hasher.update([0u8]);\n hasher.update(title.as_bytes());\n hasher.update([0u8]);\n hasher.update(body.as_bytes());\n hasher.update([0u8]);\n hasher.update(path_hint.unwrap_or(\"\").as_bytes());\n format!(\"{:x}\", hasher.finalize())\n}\n\nfn upsert_fact(\n conn: &Connection,\n target_path: &str,\n fact_kind: &str,\n title: &str,\n body: &str,\n path_hint: Option<&str>,\n source_tag: &str,\n updated_at_unix: u64,\n) -> Result<usize> {\n let key = fact_key(target_path, fact_kind, title, body, path_hint);\n let changed = conn.execute(\n \"INSERT INTO codex_memory_facts (\n fact_key, target_path, fact_kind, title, body, path_hint, source_tag, updated_at_unix\n ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)\n ON CONFLICT(fact_key) DO UPDATE SET\n target_path = excluded.target_path,\n fact_kind = excluded.fact_kind,\n title = excluded.title,\n body = excluded.body,\n path_hint = excluded.path_hint,\n source_tag = excluded.source_tag,\n updated_at_unix = excluded.updated_at_unix\",\n params![\n key,\n target_path,\n fact_kind,\n title,\n body,\n path_hint,\n source_tag,\n updated_at_unix as i64,\n ],\n )?;\n Ok(changed)\n}\n\nfn fact_score(\n profile: &QueryProfile,\n fact_kind: &str,\n title: &str,\n body: &str,\n path_hint: Option<&str>,\n) -> f64 {\n if profile.tokens.is_empty() && profile.explicit_paths.is_empty() {\n return 0.0;\n }\n let title_lower = title.to_ascii_lowercase();\n let body_lower = body.to_ascii_lowercase();\n let path_lower = path_hint.unwrap_or(\"\").to_ascii_lowercase();\n let kind_lower = fact_kind.to_ascii_lowercase();\n\n let mut score = 0.0;\n for token in &profile.tokens {\n if title_lower.contains(token.as_str()) {\n score += 3.0;\n }\n if body_lower.contains(token.as_str()) {\n score += 1.5;\n }\n if path_lower.contains(token.as_str()) {\n score += 2.0;\n }\n if kind_lower.contains(token.as_str()) {\n score += 0.5;\n }\n }\n for explicit_path in &profile.explicit_paths {\n if path_lower == *explicit_path {\n score += 10.0;\n } else if path_lower.contains(explicit_path) {\n score += 6.0;\n }\n }\n\n if profile.code_intent {\n match fact_kind {\n \"symbol\" => score += 5.0,\n \"entrypoint\" => score += 3.0,\n \"session_exchange\" => score += 2.5,\n \"session_intent\" => score += 1.5,\n \"session_recent\" => score += 1.0,\n \"important_path\" | \"command\" => score += 1.5,\n \"doc_heading\" | \"docs_hint\" | \"summary\" => score -= 2.0,\n _ => {}\n }\n if path_lower.starts_with(\"src/\")\n || path_lower.ends_with(\".rs\")\n || path_lower.ends_with(\".ts\")\n {\n score += 1.0;\n }\n }\n if profile.docs_intent {\n match fact_kind {\n \"doc_heading\" => score += 4.0,\n \"docs_hint\" | \"summary\" => score += 2.0,\n \"session_recent\" => score += 0.5,\n \"symbol\" => score -= 2.0,\n \"session_exchange\" => score -= 1.0,\n _ => {}\n }\n if path_lower.starts_with(\"docs/\")\n || path_lower.ends_with(\".md\")\n || path_lower.ends_with(\".mdx\")\n {\n score += 1.5;\n }\n }\n score\n}\n\nfn tokenize_query(query: &str) -> Vec<String> {\n query\n .split(|ch: char| !ch.is_ascii_alphanumeric() && ch != '_' && ch != '-' && ch != '/')\n .filter(|part| !part.is_empty())\n .map(|part| part.to_ascii_lowercase())\n .filter(|part| {\n part.len() >= 3\n && !matches!(\n part.as_str(),\n \"see\"\n | \"with\"\n | \"this\"\n | \"that\"\n | \"from\"\n | \"into\"\n | \"repo\"\n | \"code\"\n | \"work\"\n | \"what\"\n | \"latest\"\n | \"codex\"\n )\n })\n .collect()\n}\n\nfn build_query_profile(query: &str) -> QueryProfile {\n let query_lower = query.to_ascii_lowercase();\n let tokens = tokenize_query(query);\n let code_intent = tokens.iter().any(|token| {\n matches!(\n token.as_str(),\n \"implement\"\n | \"fix\"\n | \"refactor\"\n | \"edit\"\n | \"change\"\n | \"update\"\n | \"patch\"\n | \"function\"\n | \"struct\"\n | \"class\"\n | \"type\"\n | \"module\"\n | \"file\"\n | \"bug\"\n | \"perf\"\n | \"performance\"\n | \"optimize\"\n )\n }) || query_lower.contains(\"src/\")\n || query_lower.contains(\".rs\")\n || query_lower.contains(\".ts\")\n || query_lower.contains(\".py\");\n let docs_intent = tokens.iter().any(|token| {\n matches!(\n token.as_str(),\n \"summarize\" | \"summary\" | \"roadmap\" | \"docs\" | \"document\" | \"guide\" | \"readme\"\n )\n });\n let explicit_paths = extract_explicit_paths(&query_lower);\n\n QueryProfile {\n tokens,\n code_intent,\n docs_intent,\n explicit_paths,\n }\n}\n\nfn extract_explicit_paths(query_lower: &str) -> Vec<String> {\n query_lower\n .split_whitespace()\n .filter_map(|part| {\n let trimmed = part.trim_matches(|ch: char| {\n matches!(ch, ',' | '.' | ':' | ';' | ')' | '(' | '\"' | '\\'')\n });\n if trimmed.contains('/')\n && (trimmed.starts_with(\"src/\")\n || trimmed.starts_with(\"docs/\")\n || trimmed.starts_with(\"crates/\")\n || trimmed.starts_with(\"scripts/\")\n || trimmed.ends_with(\".rs\")\n || trimmed.ends_with(\".ts\")\n || trimmed.ends_with(\".tsx\")\n || trimmed.ends_with(\".py\")\n || trimmed.ends_with(\".md\")\n || trimmed.ends_with(\".mdx\"))\n {\n Some(trimmed.to_string())\n } else {\n None\n }\n })\n .collect()\n}\n\nfn trim_chars(value: &str, limit: usize) -> String {\n if value.chars().count() <= limit {\n return value.to_string();\n }\n let keep = limit.saturating_sub(3);\n value.chars().take(keep).collect::<String>() + \"...\"\n}\n\nfn session_label(session_id: &str, title: Option<&str>) -> String {\n if let Some(title) = title\n && !title.trim().is_empty()\n {\n return trim_chars(title.trim(), 80);\n }\n let short = session_id.chars().take(8).collect::<String>();\n format!(\"session {}\", short)\n}\n\nfn session_summary_body(row: &ai::CodexRecoverRow) -> String {\n let mut parts = Vec::new();\n if let Some(title) = row\n .title\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n {\n parts.push(format!(\n \"Title: {}\",\n trim_chars(title.trim(), MAX_SESSION_TEXT_CHARS)\n ));\n }\n if let Some(branch) = row\n .git_branch\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n {\n parts.push(format!(\"Branch: {}\", branch.trim()));\n }\n if let Some(first) = row\n .first_user_message\n .as_deref()\n .and_then(codex_text::sanitize_codex_query_text)\n {\n parts.push(format!(\n \"First user message: {}\",\n trim_chars(&first, MAX_SESSION_TEXT_CHARS)\n ));\n }\n if parts.is_empty() {\n format!(\"Recent Codex session in {}\", row.cwd)\n } else {\n parts.join(\" | \")\n }\n}\n\nfn sync_repo_symbol_facts(conn: &Connection, capsule: &repo_capsule::RepoCapsule) -> Result<usize> {\n if index_is_fresh(\n conn,\n &capsule.repo_root,\n REPO_SYMBOL_INDEX_KIND,\n REPO_SYMBOL_INDEX_VERSION,\n capsule.updated_at_unix,\n )? {\n return Ok(0);\n }\n\n conn.execute(\n \"DELETE FROM codex_memory_facts WHERE target_path = ?1 AND source_tag = 'repo_symbols'\",\n params![capsule.repo_root.as_str()],\n )?;\n\n let repo_root = Path::new(&capsule.repo_root);\n let mut changes = 0usize;\n for fact in collect_repo_symbol_facts(repo_root, capsule)? {\n changes += upsert_fact(\n conn,\n &capsule.repo_root,\n fact.fact_kind,\n &fact.title,\n &fact.body,\n Some(&fact.path_hint),\n \"repo_symbols\",\n capsule.updated_at_unix,\n )?;\n }\n\n mark_index_fresh(\n conn,\n &capsule.repo_root,\n REPO_SYMBOL_INDEX_KIND,\n REPO_SYMBOL_INDEX_VERSION,\n capsule.updated_at_unix,\n )?;\n\n Ok(changes)\n}\n\nfn sync_repo_session_facts(\n conn: &Connection,\n capsule: &repo_capsule::RepoCapsule,\n) -> Result<usize> {\n let repo_root = Path::new(&capsule.repo_root);\n let recent = ai::read_recent_codex_threads_local(repo_root, false, MAX_SESSION_THREADS, None)?;\n let source_updated_at = recent\n .iter()\n .map(|row| row.updated_at.max(0) as u64)\n .max()\n .unwrap_or(0);\n\n if index_is_fresh(\n conn,\n &capsule.repo_root,\n REPO_SESSION_INDEX_KIND,\n REPO_SESSION_INDEX_VERSION,\n source_updated_at,\n )? {\n return Ok(0);\n }\n\n conn.execute(\n \"DELETE FROM codex_memory_facts WHERE target_path = ?1 AND source_tag = 'repo_sessions'\",\n params![capsule.repo_root.as_str()],\n )?;\n\n let mut changes = 0usize;\n for row in recent {\n let session_label = session_label(&row.id, row.title.as_deref());\n let updated_at_unix = row.updated_at.max(0) as u64;\n changes += upsert_fact(\n conn,\n &capsule.repo_root,\n \"session_recent\",\n &format!(\"Recent Codex session: {}\", session_label),\n &session_summary_body(&row),\n None,\n \"repo_sessions\",\n updated_at_unix,\n )?;\n\n if let Some(intent) = row\n .first_user_message\n .as_deref()\n .and_then(codex_text::sanitize_codex_query_text)\n {\n changes += upsert_fact(\n conn,\n &capsule.repo_root,\n \"session_intent\",\n &format!(\"Recent Codex intent: {}\", session_label),\n &trim_chars(&intent, MAX_SESSION_TEXT_CHARS),\n None,\n \"repo_sessions\",\n updated_at_unix,\n )?;\n }\n\n if let Ok(exchanges) =\n ai::read_codex_memory_exchanges(&row.id, MAX_SESSION_EXCHANGES_PER_THREAD)\n {\n for (index, (user, assistant)) in exchanges.into_iter().enumerate() {\n let body = format!(\n \"User: {}\\nAssistant: {}\",\n trim_chars(&user, MAX_SESSION_TEXT_CHARS),\n trim_chars(&assistant, MAX_SESSION_TEXT_CHARS)\n );\n changes += upsert_fact(\n conn,\n &capsule.repo_root,\n \"session_exchange\",\n &format!(\"Recent Codex exchange {}: {}\", index + 1, session_label),\n &body,\n None,\n \"repo_sessions\",\n updated_at_unix,\n )?;\n }\n }\n }\n\n mark_index_fresh(\n conn,\n &capsule.repo_root,\n REPO_SESSION_INDEX_KIND,\n REPO_SESSION_INDEX_VERSION,\n source_updated_at,\n )?;\n\n Ok(changes)\n}\n\nfn collect_repo_symbol_facts(\n repo_root: &Path,\n capsule: &repo_capsule::RepoCapsule,\n) -> Result<Vec<RepoSymbolFact>> {\n let candidates = collect_symbol_candidate_paths(repo_root, capsule);\n let mut facts = Vec::new();\n\n for relative_path in candidates {\n let absolute = repo_root.join(&relative_path);\n let Ok(metadata) = fs::metadata(&absolute) else {\n continue;\n };\n if !metadata.is_file() || metadata.len() as usize > MAX_SYMBOL_FILE_BYTES {\n continue;\n }\n if let Some(entrypoint_body) = entrypoint_body_for_path(&relative_path) {\n facts.push(RepoSymbolFact {\n fact_kind: \"entrypoint\",\n title: format!(\"Entrypoint: {}\", relative_path),\n body: format!(\n \"{} in {}: {}\",\n entrypoint_body, capsule.repo_id, relative_path\n ),\n path_hint: relative_path.clone(),\n });\n }\n\n let Ok(content) = fs::read_to_string(&absolute) else {\n continue;\n };\n facts.extend(extract_symbol_facts(&relative_path, &content));\n }\n\n Ok(facts)\n}\n\nfn collect_symbol_candidate_paths(\n repo_root: &Path,\n capsule: &repo_capsule::RepoCapsule,\n) -> Vec<String> {\n let mut seen = std::collections::BTreeSet::new();\n let mut candidates = Vec::new();\n\n for path in &capsule.important_paths {\n let absolute = repo_root.join(path);\n if absolute.is_file() && matches_code_extension(&absolute) && seen.insert(path.clone()) {\n candidates.push(path.clone());\n }\n }\n\n let preferred = [\n \"src/main.rs\",\n \"src/lib.rs\",\n \"src/mod.rs\",\n \"src/index.ts\",\n \"src/index.tsx\",\n \"src/main.ts\",\n \"src/main.tsx\",\n \"src/app.ts\",\n \"src/app.tsx\",\n \"src/App.tsx\",\n \"main.py\",\n \"app.py\",\n \"__init__.py\",\n \"index.ts\",\n \"index.js\",\n \"README.md\",\n \"AGENTS.md\",\n \"flow.toml\",\n ];\n for path in preferred {\n let absolute = repo_root.join(path);\n if absolute.is_file() && seen.insert(path.to_string()) {\n candidates.push(path.to_string());\n }\n }\n\n let mut builder = WalkBuilder::new(repo_root);\n builder\n .standard_filters(true)\n .hidden(false)\n .git_ignore(true)\n .git_exclude(true)\n .git_global(true)\n .max_depth(Some(4));\n\n let mut considered = 0usize;\n let mut scored = Vec::new();\n for entry in builder.build() {\n let Ok(entry) = entry else {\n continue;\n };\n if considered >= 600 {\n break;\n }\n let path = entry.path();\n if !path.is_file() || !matches_code_extension(path) {\n continue;\n }\n considered += 1;\n let Some(relative) = path.strip_prefix(repo_root).ok() else {\n continue;\n };\n let relative_text = relative.display().to_string();\n let score = entrypoint_path_score(&relative_text);\n if score <= 0.0 || seen.contains(&relative_text) {\n continue;\n }\n scored.push((score, relative_text));\n }\n\n scored.sort_by(|a, b| {\n b.0.total_cmp(&a.0)\n .then_with(|| a.1.len().cmp(&b.1.len()))\n .then_with(|| a.1.cmp(&b.1))\n });\n\n for (_, path) in scored {\n if seen.insert(path.clone()) {\n candidates.push(path);\n }\n if candidates.len() >= MAX_SYMBOL_FILES {\n break;\n }\n }\n\n candidates.truncate(MAX_SYMBOL_FILES);\n candidates\n}\n\nfn entrypoint_path_score(relative_path: &str) -> f64 {\n let path_lower = relative_path.to_ascii_lowercase();\n let file_name = Path::new(relative_path)\n .file_name()\n .and_then(|value| value.to_str())\n .unwrap_or(\"\")\n .to_ascii_lowercase();\n\n let mut score = 0.0;\n if matches!(\n file_name.as_str(),\n \"main.rs\"\n | \"lib.rs\"\n | \"mod.rs\"\n | \"index.ts\"\n | \"index.tsx\"\n | \"index.js\"\n | \"main.ts\"\n | \"main.tsx\"\n | \"app.ts\"\n | \"app.tsx\"\n | \"app.py\"\n | \"main.py\"\n | \"__init__.py\"\n | \"readme.md\"\n | \"agents.md\"\n | \"flow.toml\"\n ) {\n score += 6.0;\n }\n if path_lower.starts_with(\"src/\") {\n score += 2.0;\n } else if path_lower.starts_with(\"app/\") || path_lower.starts_with(\"lib/\") {\n score += 1.5;\n } else if path_lower.starts_with(\"docs/\") {\n score += 1.0;\n }\n if path_lower.contains(\"/cli/\") || path_lower.contains(\"/bin/\") {\n score += 1.0;\n }\n score\n}\n\nfn entrypoint_body_for_path(relative_path: &str) -> Option<&'static str> {\n let path_lower = relative_path.to_ascii_lowercase();\n let file_name = Path::new(relative_path)\n .file_name()\n .and_then(|value| value.to_str())\n .unwrap_or(\"\")\n .to_ascii_lowercase();\n\n if matches!(\n file_name.as_str(),\n \"main.rs\" | \"main.ts\" | \"main.tsx\" | \"main.py\" | \"index.ts\" | \"index.tsx\" | \"index.js\"\n ) {\n return Some(\"Likely runtime entrypoint\");\n }\n if matches!(file_name.as_str(), \"lib.rs\" | \"__init__.py\") {\n return Some(\"Likely library entrypoint\");\n }\n if matches!(\n file_name.as_str(),\n \"app.ts\" | \"app.tsx\" | \"app.py\" | \"app.js\"\n ) {\n return Some(\"Likely application entrypoint\");\n }\n if file_name == \"flow.toml\" {\n return Some(\"Flow project entrypoint/config\");\n }\n if path_lower.starts_with(\"docs/\") || file_name == \"readme.md\" || file_name == \"agents.md\" {\n return Some(\"Likely docs/operating guide entrypoint\");\n }\n None\n}\n\nfn extract_symbol_facts(relative_path: &str, content: &str) -> Vec<RepoSymbolFact> {\n let extension = Path::new(relative_path)\n .extension()\n .and_then(|value| value.to_str())\n .unwrap_or(\"\");\n let mut facts = match extension {\n \"rs\" => extract_rust_symbol_facts(relative_path, content),\n \"ts\" | \"tsx\" | \"js\" | \"jsx\" | \"mjs\" | \"cjs\" => {\n extract_ts_symbol_facts(relative_path, content)\n }\n \"py\" => extract_python_symbol_facts(relative_path, content),\n \"go\" => extract_go_symbol_facts(relative_path, content),\n \"md\" | \"mdx\" => extract_markdown_heading_facts(relative_path, content),\n _ => Vec::new(),\n };\n facts.truncate(MAX_SYMBOLS_PER_FILE);\n facts\n}\n\nfn extract_rust_symbol_facts(relative_path: &str, content: &str) -> Vec<RepoSymbolFact> {\n let mut facts = Vec::new();\n for line in content.lines() {\n let trimmed = line.trim();\n let (kind, name) = if let Some(name) = parse_prefixed_name(trimmed, &[\"pub fn \", \"fn \"]) {\n (\"fn\", name)\n } else if let Some(name) =\n parse_prefixed_name(trimmed, &[\"pub struct \", \"struct \", \"pub(crate) struct \"])\n {\n (\"struct\", name)\n } else if let Some(name) = parse_prefixed_name(trimmed, &[\"pub enum \", \"enum \"]) {\n (\"enum\", name)\n } else if let Some(name) = parse_prefixed_name(trimmed, &[\"pub trait \", \"trait \"]) {\n (\"trait\", name)\n } else if let Some(name) = parse_prefixed_name(trimmed, &[\"pub mod \", \"mod \"]) {\n (\"mod\", name)\n } else {\n continue;\n };\n facts.push(symbol_fact(relative_path, kind, &name));\n if facts.len() >= MAX_SYMBOLS_PER_FILE {\n break;\n }\n }\n facts\n}\n\nfn extract_ts_symbol_facts(relative_path: &str, content: &str) -> Vec<RepoSymbolFact> {\n let mut facts = Vec::new();\n for line in content.lines() {\n let trimmed = line.trim();\n let (kind, name) = if let Some(name) = parse_prefixed_name(\n trimmed,\n &[\n \"export async function \",\n \"export function \",\n \"async function \",\n \"function \",\n ],\n ) {\n (\"function\", name)\n } else if let Some(name) = parse_prefixed_name(\n trimmed,\n &[\"export class \", \"class \", \"export default class \"],\n ) {\n (\"class\", name)\n } else if let Some(name) =\n parse_prefixed_name(trimmed, &[\"export interface \", \"interface \"])\n {\n (\"interface\", name)\n } else if let Some(name) = parse_prefixed_name(trimmed, &[\"export type \", \"type \"]) {\n (\"type\", name)\n } else if let Some(name) = parse_const_name(trimmed) {\n (\"const\", name)\n } else {\n continue;\n };\n facts.push(symbol_fact(relative_path, kind, &name));\n if facts.len() >= MAX_SYMBOLS_PER_FILE {\n break;\n }\n }\n facts\n}\n\nfn extract_python_symbol_facts(relative_path: &str, content: &str) -> Vec<RepoSymbolFact> {\n let mut facts = Vec::new();\n for line in content.lines() {\n let trimmed = line.trim();\n let (kind, name) = if let Some(name) = parse_prefixed_name(trimmed, &[\"def \", \"async def \"])\n {\n (\"function\", name)\n } else if let Some(name) = parse_prefixed_name(trimmed, &[\"class \"]) {\n (\"class\", name)\n } else {\n continue;\n };\n facts.push(symbol_fact(relative_path, kind, &name));\n if facts.len() >= MAX_SYMBOLS_PER_FILE {\n break;\n }\n }\n facts\n}\n\nfn extract_go_symbol_facts(relative_path: &str, content: &str) -> Vec<RepoSymbolFact> {\n let mut facts = Vec::new();\n for line in content.lines() {\n let trimmed = line.trim();\n let (kind, name) = if let Some(name) = parse_go_func_name(trimmed) {\n (\"func\", name)\n } else if let Some(name) = parse_prefixed_name(trimmed, &[\"type \"]) {\n (\"type\", name)\n } else {\n continue;\n };\n facts.push(symbol_fact(relative_path, kind, &name));\n if facts.len() >= MAX_SYMBOLS_PER_FILE {\n break;\n }\n }\n facts\n}\n\nfn extract_markdown_heading_facts(relative_path: &str, content: &str) -> Vec<RepoSymbolFact> {\n let mut facts = Vec::new();\n for line in content.lines() {\n let trimmed = line.trim();\n if !trimmed.starts_with('#') {\n continue;\n }\n let heading = trimmed.trim_start_matches('#').trim();\n if heading.len() < 3 {\n continue;\n }\n facts.push(RepoSymbolFact {\n fact_kind: \"doc_heading\",\n title: format!(\"Doc heading: {}\", heading),\n body: format!(\"Heading in {}: {}\", relative_path, heading),\n path_hint: relative_path.to_string(),\n });\n if facts.len() >= 4 {\n break;\n }\n }\n facts\n}\n\nfn symbol_fact(relative_path: &str, kind: &str, name: &str) -> RepoSymbolFact {\n RepoSymbolFact {\n fact_kind: \"symbol\",\n title: format!(\"Symbol: {}\", name),\n body: format!(\"{} {} in {}\", kind, name, relative_path),\n path_hint: relative_path.to_string(),\n }\n}\n\nfn parse_prefixed_name(trimmed: &str, prefixes: &[&str]) -> Option<String> {\n for prefix in prefixes {\n let Some(rest) = trimmed.strip_prefix(prefix) else {\n continue;\n };\n let name: String = rest\n .chars()\n .take_while(|ch| ch.is_ascii_alphanumeric() || *ch == '_' || *ch == '-')\n .collect();\n if !name.is_empty() {\n return Some(name);\n }\n }\n None\n}\n\nfn parse_const_name(trimmed: &str) -> Option<String> {\n let rest = if let Some(value) = trimmed.strip_prefix(\"export const \") {\n value\n } else if let Some(value) = trimmed.strip_prefix(\"const \") {\n value\n } else {\n return None;\n };\n let name: String = rest\n .chars()\n .take_while(|ch| ch.is_ascii_alphanumeric() || *ch == '_' || *ch == '$')\n .collect();\n if name.is_empty() { None } else { Some(name) }\n}\n\nfn parse_go_func_name(trimmed: &str) -> Option<String> {\n let rest = trimmed.strip_prefix(\"func \")?;\n let rest = if rest.starts_with('(') {\n let idx = rest.find(')')?;\n rest.get(idx + 1..)?.trim_start()\n } else {\n rest\n };\n let name: String = rest\n .chars()\n .take_while(|ch| ch.is_ascii_alphanumeric() || *ch == '_')\n .collect();\n if name.is_empty() { None } else { Some(name) }\n}\n\nfn index_is_fresh(\n conn: &Connection,\n target_path: &str,\n index_kind: &str,\n version: u32,\n source_updated_at_unix: u64,\n) -> Result<bool> {\n let row = conn.query_row(\n \"SELECT version, source_updated_at_unix FROM codex_memory_indexes \\\n WHERE target_path = ?1 AND index_kind = ?2\",\n params![target_path, index_kind],\n |row| Ok((row.get::<_, i64>(0)?, row.get::<_, i64>(1)?)),\n );\n match row {\n Ok((stored_version, stored_source_updated)) => Ok(stored_version == version as i64\n && stored_source_updated == source_updated_at_unix as i64),\n Err(rusqlite::Error::QueryReturnedNoRows) => Ok(false),\n Err(err) => Err(err.into()),\n }\n}\n\nfn mark_index_fresh(\n conn: &Connection,\n target_path: &str,\n index_kind: &str,\n version: u32,\n source_updated_at_unix: u64,\n) -> Result<()> {\n let updated_at_unix = std::time::SystemTime::now()\n .duration_since(std::time::UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(source_updated_at_unix);\n conn.execute(\n \"INSERT INTO codex_memory_indexes (\n target_path, index_kind, version, source_updated_at_unix, updated_at_unix\n ) VALUES (?1, ?2, ?3, ?4, ?5)\n ON CONFLICT(target_path, index_kind) DO UPDATE SET\n version = excluded.version,\n source_updated_at_unix = excluded.source_updated_at_unix,\n updated_at_unix = excluded.updated_at_unix\",\n params![\n target_path,\n index_kind,\n version as i64,\n source_updated_at_unix as i64,\n updated_at_unix as i64,\n ],\n )?;\n Ok(())\n}\n\nfn search_code_paths(\n repo_root: &Path,\n profile: &QueryProfile,\n limit: usize,\n) -> Vec<CodexMemoryCodeHit> {\n if (profile.tokens.is_empty() && profile.explicit_paths.is_empty())\n || limit == 0\n || !repo_root.exists()\n {\n return Vec::new();\n }\n\n let mut builder = WalkBuilder::new(repo_root);\n builder\n .standard_filters(true)\n .hidden(false)\n .git_ignore(true)\n .git_exclude(true)\n .git_global(true)\n .max_depth(Some(8));\n\n let mut considered = 0usize;\n let mut hits = Vec::new();\n\n for entry in builder.build() {\n let Ok(entry) = entry else {\n continue;\n };\n if considered >= 2000 {\n break;\n }\n let path = entry.path();\n if !path.is_file() || !matches_code_extension(path) {\n continue;\n }\n considered += 1;\n let Some(relative) = path.strip_prefix(repo_root).ok() else {\n continue;\n };\n let relative_text = relative.display().to_string();\n let score = score_code_path(&relative_text, profile);\n if score <= 0.0 {\n continue;\n }\n hits.push(CodexMemoryCodeHit {\n path: relative_text,\n score,\n });\n }\n\n hits.sort_by(|a, b| {\n b.score\n .total_cmp(&a.score)\n .then_with(|| a.path.len().cmp(&b.path.len()))\n .then_with(|| a.path.cmp(&b.path))\n });\n hits.truncate(limit);\n hits\n}\n\nfn search_symbols_for_code_paths(\n repo_root: &Path,\n code_paths: &[CodexMemoryCodeHit],\n profile: &QueryProfile,\n limit: usize,\n) -> Vec<CodexMemoryFactHit> {\n let mut hits = Vec::new();\n for code_path in code_paths.iter().take(limit.min(4)) {\n let extension = Path::new(&code_path.path)\n .extension()\n .and_then(|value| value.to_str())\n .unwrap_or(\"\");\n if matches!(extension, \"md\" | \"mdx\") {\n continue;\n }\n let absolute = repo_root.join(&code_path.path);\n let Ok(metadata) = fs::metadata(&absolute) else {\n continue;\n };\n if !metadata.is_file() || metadata.len() as usize > MAX_SYMBOL_FILE_BYTES {\n continue;\n }\n let Ok(content) = fs::read_to_string(&absolute) else {\n continue;\n };\n for fact in extract_symbol_facts(&code_path.path, &content) {\n let score = fact_score(\n profile,\n fact.fact_kind,\n &fact.title,\n &fact.body,\n Some(&fact.path_hint),\n ) + (code_path.score * 0.6);\n if score <= 0.0 {\n continue;\n }\n hits.push(CodexMemoryFactHit {\n fact_kind: fact.fact_kind.to_string(),\n title: fact.title,\n body: fact.body,\n path_hint: Some(fact.path_hint),\n source_tag: \"live_symbol\".to_string(),\n score,\n });\n }\n }\n hits.sort_by(|a, b| b.score.total_cmp(&a.score));\n hits.truncate(limit);\n hits\n}\n\nfn merge_dynamic_symbol_hits(\n hits: &mut Vec<CodexMemoryFactHit>,\n dynamic_symbols: Vec<CodexMemoryFactHit>,\n) {\n let mut seen = std::collections::BTreeSet::new();\n for hit in hits.iter() {\n seen.insert((\n hit.fact_kind.clone(),\n hit.title.clone(),\n hit.path_hint.clone().unwrap_or_default(),\n ));\n }\n for hit in dynamic_symbols {\n let key = (\n hit.fact_kind.clone(),\n hit.title.clone(),\n hit.path_hint.clone().unwrap_or_default(),\n );\n if seen.insert(key) {\n hits.push(hit);\n }\n }\n}\n\nfn extract_symbol_snippets(\n repo_root: &Path,\n facts: &[CodexMemoryFactHit],\n limit: usize,\n) -> Vec<CodexMemorySnippetHit> {\n let mut snippets = Vec::new();\n let mut seen = std::collections::BTreeSet::new();\n\n for fact in facts {\n if snippets.len() >= limit {\n break;\n }\n if fact.fact_kind != \"symbol\" {\n continue;\n }\n let Some(path) = fact.path_hint.as_deref() else {\n continue;\n };\n if !seen.insert(path.to_string()) {\n continue;\n }\n let Some(symbol_name) = fact.title.strip_prefix(\"Symbol: \").map(str::trim) else {\n continue;\n };\n let absolute = repo_root.join(path);\n let Ok(metadata) = fs::metadata(&absolute) else {\n continue;\n };\n if !metadata.is_file() || metadata.len() as usize > MAX_SYMBOL_FILE_BYTES {\n continue;\n }\n let Ok(content) = fs::read_to_string(&absolute) else {\n continue;\n };\n let Some(snippet) = find_symbol_snippet(&content, symbol_name) else {\n continue;\n };\n snippets.push(CodexMemorySnippetHit {\n path: path.to_string(),\n symbol: symbol_name.to_string(),\n snippet,\n score: fact.score,\n });\n }\n\n snippets\n}\n\nfn find_symbol_snippet(content: &str, symbol_name: &str) -> Option<String> {\n let lines: Vec<&str> = content.lines().collect();\n let symbol_lower = symbol_name.to_ascii_lowercase();\n\n let start_idx = lines.iter().position(|line| {\n let trimmed = line.trim();\n let lower = trimmed.to_ascii_lowercase();\n lower.contains(&symbol_lower)\n && (trimmed.starts_with(\"pub \")\n || trimmed.starts_with(\"fn \")\n || trimmed.starts_with(\"struct \")\n || trimmed.starts_with(\"enum \")\n || trimmed.starts_with(\"trait \")\n || trimmed.starts_with(\"class \")\n || trimmed.starts_with(\"interface \")\n || trimmed.starts_with(\"type \")\n || trimmed.starts_with(\"export \")\n || trimmed.starts_with(\"async \")\n || trimmed.starts_with(\"def \")\n || trimmed.starts_with(\"func \"))\n })?;\n\n let mut excerpt = Vec::new();\n for line in lines.iter().skip(start_idx).take(MAX_SNIPPET_LINES) {\n let trimmed = line.trim_end();\n if trimmed.is_empty() && !excerpt.is_empty() {\n break;\n }\n if !trimmed.is_empty() {\n excerpt.push(trimmed.trim().to_string());\n }\n }\n if excerpt.is_empty() {\n return None;\n }\n Some(trim_chars(&excerpt.join(\" | \"), MAX_SNIPPET_CHARS))\n}\n\nfn matches_code_extension(path: &Path) -> bool {\n let Some(name) = path.file_name().and_then(|value| value.to_str()) else {\n return false;\n };\n if matches!(name, \"README.md\" | \"README.mdx\" | \"AGENTS.md\" | \"flow.toml\") {\n return true;\n }\n\n let Some(extension) = path.extension().and_then(|value| value.to_str()) else {\n return false;\n };\n matches!(\n extension,\n \"rs\" | \"ts\"\n | \"tsx\"\n | \"js\"\n | \"jsx\"\n | \"mjs\"\n | \"cjs\"\n | \"py\"\n | \"go\"\n | \"md\"\n | \"mdx\"\n | \"toml\"\n | \"json\"\n | \"jsonc\"\n | \"yaml\"\n | \"yml\"\n | \"moon\"\n | \"cpp\"\n | \"cc\"\n | \"c\"\n | \"h\"\n | \"hpp\"\n | \"java\"\n | \"kt\"\n | \"swift\"\n )\n}\n\nfn score_code_path(relative_path: &str, profile: &QueryProfile) -> f64 {\n let path_lower = relative_path.to_ascii_lowercase();\n let file_name = Path::new(relative_path)\n .file_name()\n .and_then(|value| value.to_str())\n .unwrap_or(\"\")\n .to_ascii_lowercase();\n\n let mut score = 0.0;\n for token in &profile.tokens {\n if file_name == *token || file_name.starts_with(&format!(\"{token}.\")) {\n score += 6.0;\n continue;\n }\n if file_name.contains(token) {\n score += 4.0;\n }\n if path_lower.contains(&format!(\"/{token}/\")) {\n score += 3.0;\n } else if path_lower.contains(token) {\n score += 2.0;\n }\n }\n for explicit_path in &profile.explicit_paths {\n if path_lower == *explicit_path {\n score += 14.0;\n } else if path_lower.contains(explicit_path) {\n score += 8.0;\n }\n }\n\n if profile.code_intent {\n if path_lower.starts_with(\"src/\") || path_lower.contains(\"/src/\") {\n score += 2.0;\n } else if path_lower.starts_with(\"crates/\") || path_lower.starts_with(\"app/\") {\n score += 1.0;\n } else if path_lower.starts_with(\"docs/\") {\n score -= 1.0;\n }\n } else if profile.docs_intent {\n if path_lower.starts_with(\"docs/\")\n || path_lower.ends_with(\".md\")\n || path_lower.ends_with(\".mdx\")\n {\n score += 2.0;\n } else if path_lower.starts_with(\"src/\") {\n score -= 0.5;\n }\n } else if path_lower.starts_with(\"src/\") {\n score += 0.5;\n } else if path_lower.starts_with(\"docs/\") {\n score += 0.3;\n }\n score\n}\n\nfn render_query_result(\n repo_root: &str,\n query: &str,\n profile: &QueryProfile,\n facts: &[CodexMemoryFactHit],\n code_paths: &[CodexMemoryCodeHit],\n snippets: &[CodexMemorySnippetHit],\n) -> String {\n let mut lines = vec![format!(\"- Memory repo root: {}\", repo_root)];\n lines.push(format!(\"- Memory query: {}\", query.trim()));\n for fact in select_render_fact_hits(facts, profile, 6) {\n let mut line = format!(\"- {}: {}\", fact.fact_kind, fact.body);\n if let Some(path) = fact.path_hint.as_deref() {\n line.push_str(&format!(\" ({})\", path));\n }\n lines.push(line);\n }\n for snippet in snippets {\n lines.push(format!(\n \"- snippet {}::{} => {}\",\n snippet.path, snippet.symbol, snippet.snippet\n ));\n }\n for hit in code_paths {\n lines.push(format!(\"- code_path: {}\", hit.path));\n }\n lines.join(\"\\n\")\n}\n\nfn select_render_fact_hits<'a>(\n facts: &'a [CodexMemoryFactHit],\n profile: &QueryProfile,\n limit: usize,\n) -> Vec<&'a CodexMemoryFactHit> {\n let mut selected = Vec::new();\n let mut seen = std::collections::BTreeSet::new();\n\n let preferred_kinds: &[&str] = if profile.code_intent {\n &[\n \"symbol\",\n \"entrypoint\",\n \"session_exchange\",\n \"session_intent\",\n \"important_path\",\n \"command\",\n ]\n } else if profile.docs_intent {\n &[\"doc_heading\", \"docs_hint\", \"summary\", \"important_path\"]\n } else {\n &[\n \"session_intent\",\n \"session_exchange\",\n \"symbol\",\n \"entrypoint\",\n \"command\",\n \"important_path\",\n ]\n };\n\n for preferred_kind in preferred_kinds {\n for fact in facts {\n if fact.fact_kind != *preferred_kind {\n continue;\n }\n let key = (\n fact.fact_kind.as_str(),\n fact.title.as_str(),\n fact.path_hint.as_deref().unwrap_or(\"\"),\n );\n if seen.insert(key) {\n selected.push(fact);\n break;\n }\n }\n }\n\n for fact in facts {\n if selected.len() >= limit {\n break;\n }\n if profile.code_intent\n && matches!(\n fact.fact_kind.as_str(),\n \"doc_heading\" | \"docs_hint\" | \"summary\"\n )\n && selected\n .iter()\n .filter(|item| item.fact_kind == \"doc_heading\")\n .count()\n >= 1\n {\n continue;\n }\n if matches!(fact.fact_kind.as_str(), \"doc_heading\" | \"docs_hint\")\n && selected\n .iter()\n .filter(|item| item.fact_kind == \"doc_heading\")\n .count()\n >= 2\n {\n continue;\n }\n let key = (\n fact.fact_kind.as_str(),\n fact.title.as_str(),\n fact.path_hint.as_deref().unwrap_or(\"\"),\n );\n if seen.insert(key) {\n selected.push(fact);\n }\n }\n\n selected.truncate(limit);\n selected\n}\n\nfn map_recent_entry(row: &rusqlite::Row<'_>) -> Result<CodexMemoryRecentEntry, rusqlite::Error> {\n let recorded_at_unix: i64 = row.get(1)?;\n Ok(CodexMemoryRecentEntry {\n event_kind: row.get(0)?,\n recorded_at_unix: recorded_at_unix.max(0) as u64,\n target_path: row.get(2)?,\n session_id: row.get(3)?,\n route: row.get(4)?,\n query: row.get(5)?,\n success: row.get(6)?,\n })\n}\n\n#[cfg(test)]\nmod tests {\n use super::{\n CodexMemoryFactHit, CodexMemoryStats, QueryProfile, REPO_SYMBOL_INDEX_KIND,\n REPO_SYMBOL_INDEX_VERSION, build_query_profile, entrypoint_body_for_path, event_key,\n extract_symbol_facts, extract_symbol_snippets, fact_score, find_symbol_snippet,\n index_is_fresh, insert_marshaled, map_recent_entry, mark_index_fresh,\n matches_code_extension, open_connection_at, score_code_path, search_code_paths,\n select_render_fact_hits, session_summary_body, upsert_fact,\n };\n use rusqlite::params;\n use std::fs;\n use std::path::Path;\n use tempfile::tempdir;\n\n #[test]\n fn event_key_changes_with_kind_and_payload() {\n let a = event_key(\"skill_eval_event\", \"{\\\"a\\\":1}\");\n let b = event_key(\"skill_eval_event\", \"{\\\"a\\\":2}\");\n let c = event_key(\"skill_eval_outcome\", \"{\\\"a\\\":1}\");\n assert_ne!(a, b);\n assert_ne!(a, c);\n }\n\n #[test]\n fn inserts_are_deduped_and_recent_rows_roundtrip() {\n let temp = tempdir().expect(\"tempdir\");\n let db_path = temp.path().join(\"memory.sqlite\");\n let conn = open_connection_at(&db_path).expect(\"open db\");\n\n let inserted = insert_marshaled(\n &conn,\n \"skill_eval_event\",\n 42,\n Some(\"/tmp/repo\"),\n Some(\"session-1\"),\n Some(\"runtime-1\"),\n Some(\"new-with-context\"),\n Some(\"write plan\"),\n None,\n \"{\\\"route\\\":\\\"new-with-context\\\"}\",\n )\n .expect(\"insert event\");\n assert!(inserted);\n\n let inserted_again = insert_marshaled(\n &conn,\n \"skill_eval_event\",\n 42,\n Some(\"/tmp/repo\"),\n Some(\"session-1\"),\n Some(\"runtime-1\"),\n Some(\"new-with-context\"),\n Some(\"write plan\"),\n None,\n \"{\\\"route\\\":\\\"new-with-context\\\"}\",\n )\n .expect(\"dedupe event\");\n assert!(!inserted_again);\n\n let mut stmt = conn\n .prepare(\n \"SELECT event_kind, recorded_at_unix, target_path, session_id, route, query, success \\\n FROM codex_memory_events\",\n )\n .expect(\"prepare select\");\n let row = stmt\n .query_row(params![], map_recent_entry)\n .expect(\"query first row\");\n assert_eq!(row.event_kind, \"skill_eval_event\");\n assert_eq!(row.recorded_at_unix, 42);\n assert_eq!(row.target_path.as_deref(), Some(\"/tmp/repo\"));\n assert_eq!(row.route.as_deref(), Some(\"new-with-context\"));\n }\n\n #[test]\n fn stats_query_counts_rows() {\n let temp = tempdir().expect(\"tempdir\");\n let db_path = temp.path().join(\"memory.sqlite\");\n let conn = open_connection_at(&db_path).expect(\"open db\");\n insert_marshaled(\n &conn,\n \"skill_eval_event\",\n 100,\n Some(\"/tmp/repo\"),\n None,\n None,\n Some(\"route\"),\n Some(\"query\"),\n None,\n \"{\\\"kind\\\":\\\"event\\\"}\",\n )\n .expect(\"insert event\");\n insert_marshaled(\n &conn,\n \"skill_eval_outcome\",\n 101,\n Some(\"/tmp/repo\"),\n Some(\"session-1\"),\n None,\n None,\n None,\n Some(1.0),\n \"{\\\"kind\\\":\\\"outcome\\\"}\",\n )\n .expect(\"insert outcome\");\n\n let mut stmt = conn\n .prepare(\n \"SELECT COUNT(*), \\\n 0, \\\n COALESCE(SUM(CASE WHEN event_kind = 'skill_eval_event' THEN 1 ELSE 0 END), 0), \\\n COALESCE(SUM(CASE WHEN event_kind = 'skill_eval_outcome' THEN 1 ELSE 0 END), 0), \\\n MAX(recorded_at_unix) \\\n FROM codex_memory_events\",\n )\n .expect(\"prepare stats\");\n let stats: CodexMemoryStats = stmt\n .query_row([], |row| {\n Ok(CodexMemoryStats {\n root_dir: String::new(),\n db_path: String::new(),\n total_events: row.get::<_, i64>(0)? as usize,\n total_facts: row.get::<_, i64>(1)? as usize,\n skill_eval_events: row.get::<_, i64>(2)? as usize,\n skill_eval_outcomes: row.get::<_, i64>(3)? as usize,\n latest_recorded_at_unix: row.get::<_, Option<i64>>(4)?.map(|v| v as u64),\n })\n })\n .expect(\"read stats\");\n assert_eq!(stats.total_events, 2);\n assert_eq!(stats.total_facts, 0);\n assert_eq!(stats.skill_eval_events, 1);\n assert_eq!(stats.skill_eval_outcomes, 1);\n assert_eq!(stats.latest_recorded_at_unix, Some(101));\n }\n\n #[test]\n fn fact_score_prefers_title_and_paths() {\n let profile = build_query_profile(\"reload speed build123d keyboard\");\n let score = fact_score(\n &profile,\n \"important_path\",\n \"Important path: projects/keyboard/keyboard.py\",\n \"Key file or directory in gumyr/build123d: projects/keyboard/keyboard.py\",\n Some(\"projects/keyboard/keyboard.py\"),\n );\n assert!(score > 5.0);\n }\n\n #[test]\n fn upsert_fact_replaces_existing_row() {\n let temp = tempdir().expect(\"tempdir\");\n let db_path = temp.path().join(\"memory.sqlite\");\n let conn = open_connection_at(&db_path).expect(\"open db\");\n upsert_fact(\n &conn,\n \"/tmp/repo\",\n \"summary\",\n \"Summary\",\n \"first body\",\n None,\n \"repo_capsule\",\n 10,\n )\n .expect(\"insert fact\");\n upsert_fact(\n &conn,\n \"/tmp/repo\",\n \"summary\",\n \"Summary\",\n \"first body\",\n None,\n \"repo_capsule\",\n 20,\n )\n .expect(\"update fact\");\n let updated_at: i64 = conn\n .query_row(\n \"SELECT updated_at_unix FROM codex_memory_facts WHERE target_path = '/tmp/repo'\",\n [],\n |row| row.get(0),\n )\n .expect(\"select fact\");\n assert_eq!(updated_at, 20);\n }\n\n #[test]\n fn code_path_search_prefers_matching_files() {\n let temp = tempdir().expect(\"tempdir\");\n let root = temp.path().join(\"repo\");\n fs::create_dir_all(root.join(\"src\")).expect(\"create src\");\n fs::create_dir_all(root.join(\"docs\")).expect(\"create docs\");\n fs::write(root.join(\"src/codex_runtime.rs\"), \"// runtime\\n\").expect(\"write runtime\");\n fs::write(root.join(\"src/ai.rs\"), \"// ai\\n\").expect(\"write ai\");\n fs::write(root.join(\"docs/runtime-skills.md\"), \"# Runtime skills\\n\").expect(\"write docs\");\n\n let profile = build_query_profile(\"codex runtime skills\");\n let hits = search_code_paths(&root, &profile, 3);\n assert!(!hits.is_empty());\n assert!(hits.iter().any(|hit| hit.path == \"src/codex_runtime.rs\"));\n }\n\n #[test]\n fn code_extension_filter_accepts_repo_docs_and_code() {\n assert!(matches_code_extension(Path::new(\"README.md\")));\n assert!(matches_code_extension(Path::new(\"src/main.rs\")));\n assert!(matches_code_extension(Path::new(\"docs/guide.mdx\")));\n assert!(!matches_code_extension(Path::new(\"target/debug/f\")));\n }\n\n #[test]\n fn code_path_scoring_prefers_exact_filename_hits() {\n let profile = QueryProfile {\n tokens: vec![\"codex_runtime\".to_string()],\n code_intent: true,\n docs_intent: false,\n explicit_paths: Vec::new(),\n };\n let exact = score_code_path(\"src/codex_runtime.rs\", &profile);\n let loose = score_code_path(\"src/runtime.rs\", &profile);\n assert!(exact > loose);\n }\n\n #[test]\n fn symbol_extraction_finds_rust_and_ts_entrypoints() {\n let rust = extract_symbol_facts(\n \"src/codex_memory.rs\",\n \"pub fn query_repo_facts() {}\\nstruct RepoMemory {}\\nmod helpers {}\\n\",\n );\n assert!(\n rust.iter()\n .any(|fact| fact.title == \"Symbol: query_repo_facts\")\n );\n assert!(rust.iter().any(|fact| fact.title == \"Symbol: RepoMemory\"));\n\n let ts = extract_symbol_facts(\n \"src/index.ts\",\n \"export function startFlow() {}\\nexport class CodexBridge {}\\nexport const runtimeSkill = 1;\\n\",\n );\n assert!(ts.iter().any(|fact| fact.title == \"Symbol: startFlow\"));\n assert!(ts.iter().any(|fact| fact.title == \"Symbol: CodexBridge\"));\n assert_eq!(\n entrypoint_body_for_path(\"src/index.ts\"),\n Some(\"Likely runtime entrypoint\")\n );\n }\n\n #[test]\n fn symbol_index_freshness_roundtrips() {\n let temp = tempdir().expect(\"tempdir\");\n let db_path = temp.path().join(\"memory.sqlite\");\n let conn = open_connection_at(&db_path).expect(\"open db\");\n\n assert!(\n !index_is_fresh(\n &conn,\n \"/tmp/repo\",\n REPO_SYMBOL_INDEX_KIND,\n REPO_SYMBOL_INDEX_VERSION,\n 42,\n )\n .expect(\"initial freshness\")\n );\n\n mark_index_fresh(\n &conn,\n \"/tmp/repo\",\n REPO_SYMBOL_INDEX_KIND,\n REPO_SYMBOL_INDEX_VERSION,\n 42,\n )\n .expect(\"mark fresh\");\n\n assert!(\n index_is_fresh(\n &conn,\n \"/tmp/repo\",\n REPO_SYMBOL_INDEX_KIND,\n REPO_SYMBOL_INDEX_VERSION,\n 42,\n )\n .expect(\"fresh after mark\")\n );\n assert!(\n !index_is_fresh(\n &conn,\n \"/tmp/repo\",\n REPO_SYMBOL_INDEX_KIND,\n REPO_SYMBOL_INDEX_VERSION,\n 43,\n )\n .expect(\"stale after source change\")\n );\n }\n\n #[test]\n fn render_selection_prefers_symbols_before_doc_noise() {\n let facts = vec![\n CodexMemoryFactHit {\n fact_kind: \"doc_heading\".to_string(),\n title: \"Doc heading: Skills\".to_string(),\n body: \"Heading in docs/skills.md: Skills\".to_string(),\n path_hint: Some(\"docs/skills.md\".to_string()),\n source_tag: \"repo_symbols\".to_string(),\n score: 10.0,\n },\n CodexMemoryFactHit {\n fact_kind: \"symbol\".to_string(),\n title: \"Symbol: query_repo_facts\".to_string(),\n body: \"fn query_repo_facts in src/codex_memory.rs\".to_string(),\n path_hint: Some(\"src/codex_memory.rs\".to_string()),\n source_tag: \"live_symbol\".to_string(),\n score: 8.0,\n },\n CodexMemoryFactHit {\n fact_kind: \"entrypoint\".to_string(),\n title: \"Entrypoint: src/main.rs\".to_string(),\n body: \"Likely runtime entrypoint in repo: src/main.rs\".to_string(),\n path_hint: Some(\"src/main.rs\".to_string()),\n source_tag: \"repo_symbols\".to_string(),\n score: 7.0,\n },\n ];\n\n let profile = QueryProfile {\n tokens: vec![\"implement\".to_string()],\n code_intent: true,\n docs_intent: false,\n explicit_paths: Vec::new(),\n };\n let selected = select_render_fact_hits(&facts, &profile, 3);\n assert_eq!(selected[0].fact_kind, \"symbol\");\n assert_eq!(selected[1].fact_kind, \"entrypoint\");\n }\n\n #[test]\n fn query_profile_detects_code_intent_and_explicit_path() {\n let profile = build_query_profile(\"implement codex runtime skill ranking in src/ai.rs\");\n assert!(profile.code_intent);\n assert!(!profile.docs_intent);\n assert!(\n profile\n .explicit_paths\n .iter()\n .any(|value| value == \"src/ai.rs\")\n );\n }\n\n #[test]\n fn query_profile_detects_docs_intent() {\n let profile = build_query_profile(\"summarize codex control plane roadmap\");\n assert!(profile.docs_intent);\n }\n\n #[test]\n fn session_summary_body_strips_contextual_first_prompt_noise() {\n let row = crate::ai::CodexRecoverRow {\n id: \"019ce6ce-c77a-7d52-838e-c01f8820f6b8\".to_string(),\n updated_at: 42,\n cwd: \"/tmp/repo\".to_string(),\n title: Some(\"Session title\".to_string()),\n first_user_message: Some(\n \"# AGENTS.md instructions for /tmp\\n\\n<INSTRUCTIONS>\\nbody\\n</INSTRUCTIONS>\\n<environment_context>\\n<cwd>/tmp</cwd>\\n</environment_context>\\nwrite plan for rollout\"\n .to_string(),\n ),\n git_branch: Some(\"main\".to_string()),\n model: None,\n reasoning_effort: None,\n };\n\n let body = session_summary_body(&row);\n assert!(body.contains(\"write plan for rollout\"));\n assert!(!body.contains(\"AGENTS.md\"));\n assert!(!body.contains(\"<environment_context>\"));\n }\n\n #[test]\n fn snippet_extraction_returns_compact_symbol_excerpt() {\n let content =\n \"pub struct CodexRuntimeSkill {\\n pub name: String,\\n pub path: String,\\n}\\n\";\n let snippet = find_symbol_snippet(content, \"CodexRuntimeSkill\").expect(\"snippet\");\n assert!(snippet.contains(\"pub struct CodexRuntimeSkill\"));\n assert!(snippet.contains(\"pub name: String\") || snippet.contains(\"pub name: String,\"));\n }\n\n #[test]\n fn extract_symbol_snippets_picks_top_symbol_hits() {\n let temp = tempdir().expect(\"tempdir\");\n let root = temp.path().join(\"repo\");\n fs::create_dir_all(root.join(\"src\")).expect(\"create src\");\n fs::write(\n root.join(\"src/codex_runtime.rs\"),\n \"pub struct CodexRuntimeSkill {\\n pub name: String,\\n}\\n\",\n )\n .expect(\"write runtime\");\n\n let hits = vec![CodexMemoryFactHit {\n fact_kind: \"symbol\".to_string(),\n title: \"Symbol: CodexRuntimeSkill\".to_string(),\n body: \"struct CodexRuntimeSkill in src/codex_runtime.rs\".to_string(),\n path_hint: Some(\"src/codex_runtime.rs\".to_string()),\n source_tag: \"live_symbol\".to_string(),\n score: 9.0,\n }];\n\n let snippets = extract_symbol_snippets(&root, &hits, 2);\n assert_eq!(snippets.len(), 1);\n assert_eq!(snippets[0].path, \"src/codex_runtime.rs\");\n assert!(snippets[0].snippet.contains(\"CodexRuntimeSkill\"));\n }\n\n #[test]\n fn render_selection_prefers_session_context_for_general_queries() {\n let facts = vec![\n CodexMemoryFactHit {\n fact_kind: \"symbol\".to_string(),\n title: \"Symbol: CodexRuntimeSkill\".to_string(),\n body: \"struct CodexRuntimeSkill in src/codex_runtime.rs\".to_string(),\n path_hint: Some(\"src/codex_runtime.rs\".to_string()),\n source_tag: \"repo_symbols\".to_string(),\n score: 8.0,\n },\n CodexMemoryFactHit {\n fact_kind: \"session_intent\".to_string(),\n title: \"Recent Codex intent: runtime work\".to_string(),\n body: \"implement codex runtime skill ranking\".to_string(),\n path_hint: None,\n source_tag: \"repo_sessions\".to_string(),\n score: 9.0,\n },\n CodexMemoryFactHit {\n fact_kind: \"session_exchange\".to_string(),\n title: \"Recent Codex exchange 1: runtime work\".to_string(),\n body: \"User: implement codex runtime skill ranking\\nAssistant: focus on ai.rs\"\n .to_string(),\n path_hint: None,\n source_tag: \"repo_sessions\".to_string(),\n score: 8.5,\n },\n ];\n\n let profile = QueryProfile {\n tokens: vec![\"runtime\".to_string()],\n code_intent: false,\n docs_intent: false,\n explicit_paths: Vec::new(),\n };\n let selected = select_render_fact_hits(&facts, &profile, 3);\n assert_eq!(selected[0].fact_kind, \"session_intent\");\n assert_eq!(selected[1].fact_kind, \"session_exchange\");\n }\n}\n" }, { "path": "src/codex_runtime.rs", "content": "use std::collections::{BTreeMap, BTreeSet};\nuse std::env;\nuse std::fs;\nuse std::io::{self, Read};\nuse std::path::{Path, PathBuf};\nuse std::time::{SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result, bail};\nuse serde::{Deserialize, Serialize};\nuse sha2::{Digest, Sha256};\n\nuse crate::{activity_log, codex_skill_eval, config};\n\nconst RUNTIME_VERSION: u32 = 1;\nconst RUNTIME_PREFIX: &str = \"flow-runtime-\";\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexRuntimeSkill {\n pub name: String,\n pub kind: String,\n pub path: String,\n pub trigger: String,\n #[serde(default)]\n pub source: Option<String>,\n #[serde(default)]\n pub original_name: Option<String>,\n #[serde(default)]\n pub estimated_chars: Option<usize>,\n #[serde(default)]\n pub match_reason: Option<String>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexRuntimeState {\n pub version: u32,\n pub token: String,\n pub created_at_unix: u64,\n pub target_path: String,\n pub query: String,\n pub skills: Vec<CodexRuntimeSkill>,\n}\n\n#[derive(Debug, Clone, PartialEq, Eq)]\npub struct CodexRuntimeActivation {\n pub state_path: PathBuf,\n pub skills: Vec<CodexRuntimeSkill>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexExternalSkill {\n pub source_name: String,\n pub name: String,\n pub path: String,\n pub description: String,\n pub estimated_chars: usize,\n pub category: String,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexSkillSourceSnapshot {\n pub name: String,\n pub path: String,\n pub enabled: bool,\n pub skill_count: usize,\n pub skills: Vec<CodexExternalSkill>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexInstalledSkillSnapshot {\n pub name: String,\n pub path: String,\n pub description: String,\n pub runtime_managed: bool,\n pub category: String,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexSkillCatalogEntry {\n pub name: String,\n pub description: String,\n pub category: String,\n pub path: String,\n pub sources: Vec<String>,\n pub installed: bool,\n pub runtime_managed: bool,\n #[serde(default)]\n pub estimated_chars: Option<usize>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexRuntimeStateSnapshot {\n pub token: String,\n pub created_at_unix: u64,\n pub target_path: String,\n pub query: String,\n pub skills: Vec<String>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexSkillsDashboardSnapshot {\n pub target_path: String,\n pub sources: Vec<CodexSkillSourceSnapshot>,\n pub installed_skills: Vec<CodexInstalledSkillSnapshot>,\n pub catalog: Vec<CodexSkillCatalogEntry>,\n pub recent_runtime_states: Vec<CodexRuntimeStateSnapshot>,\n pub runtime_states_for_target: usize,\n}\n\n#[derive(Debug, Clone)]\nstruct RuntimeSkillCandidate {\n score: f64,\n skill: CodexRuntimeSkill,\n source_dir: Option<PathBuf>,\n}\n\nimpl CodexRuntimeActivation {\n fn prompt_skill_names(&self) -> Vec<String> {\n self.skills\n .iter()\n .map(|skill| {\n skill\n .original_name\n .as_deref()\n .unwrap_or(skill.name.as_str())\n .to_string()\n })\n .collect()\n }\n\n pub fn inject_into_prompt(&self, prompt: &str) -> String {\n let names = self.prompt_skill_names();\n if names.is_empty() {\n return prompt.trim().to_string();\n }\n format!(\n \"[Active Flow skills: {}]\\n\\n{}\",\n names.join(\", \"),\n prompt.trim()\n )\n }\n}\n\nfn runtime_root() -> Result<PathBuf> {\n Ok(config::ensure_global_state_dir()?\n .join(\"codex\")\n .join(\"runtime\"))\n}\n\nfn runtime_roots() -> Vec<PathBuf> {\n config::global_state_dir_candidates()\n .into_iter()\n .map(|root| root.join(\"codex\").join(\"runtime\"))\n .collect()\n}\n\nfn runtime_states_dir() -> Result<PathBuf> {\n let dir = runtime_root()?.join(\"states\");\n fs::create_dir_all(&dir)?;\n Ok(dir)\n}\n\nfn runtime_skills_dir() -> Result<PathBuf> {\n let dir = runtime_root()?.join(\"skills\");\n fs::create_dir_all(&dir)?;\n Ok(dir)\n}\n\nfn agents_skill_root() -> PathBuf {\n env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".agents/skills\")\n}\n\nfn codex_global_skill_root() -> PathBuf {\n env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".codex/skills\")\n}\n\nfn slugify(value: &str) -> String {\n let mut out = String::new();\n let mut last_dash = false;\n for ch in value.chars() {\n let mapped = if ch.is_ascii_alphanumeric() {\n Some(ch.to_ascii_lowercase())\n } else {\n Some('-')\n };\n if let Some(mapped) = mapped {\n if mapped == '-' {\n if !out.is_empty() && !last_dash {\n out.push('-');\n last_dash = true;\n }\n } else {\n out.push(mapped);\n last_dash = false;\n }\n }\n }\n out.trim_matches('-').to_string()\n}\n\nfn parse_frontmatter_field(content: &str, field: &str) -> Option<String> {\n let after_start = content.strip_prefix(\"---\\n\")?;\n let end = after_start.find(\"\\n---\")?;\n let frontmatter = &after_start[..end];\n for line in frontmatter.lines() {\n let trimmed = line.trim();\n let prefix = format!(\"{field}:\");\n if let Some(value) = trimmed.strip_prefix(&prefix) {\n return Some(\n value\n .trim()\n .trim_matches('\"')\n .trim_matches('\\'')\n .to_string(),\n );\n }\n }\n None\n}\n\nfn default_skill_sources() -> Vec<config::CodexSkillSourceConfig> {\n let vercel_path = config::expand_path(\"~/repos/vercel-labs/skills\");\n if looks_like_skill_source_root(&vercel_path) {\n return vec![config::CodexSkillSourceConfig {\n name: \"vercel-labs-skills\".to_string(),\n path: \"~/repos/vercel-labs/skills\".to_string(),\n enabled: Some(true),\n }];\n }\n Vec::new()\n}\n\nfn configured_skill_sources(\n codex_cfg: &config::CodexConfig,\n) -> Vec<config::CodexSkillSourceConfig> {\n let mut sources = if codex_cfg.skill_sources.is_empty() {\n default_skill_sources()\n } else {\n codex_cfg.skill_sources.clone()\n };\n sources.retain(|source| source.enabled.unwrap_or(true));\n sources\n}\n\nfn looks_like_skill_source_root(root: &Path) -> bool {\n collect_skill_dirs(root)\n .map(|dirs| !dirs.is_empty())\n .unwrap_or(false)\n}\n\nfn collect_skill_dirs(root: &Path) -> Result<Vec<PathBuf>> {\n let mut dirs = BTreeSet::new();\n let nested_root = root.join(\"skills\");\n for base in [nested_root.as_path(), root] {\n if !base.is_dir() {\n continue;\n }\n for entry in fs::read_dir(base)? {\n let entry = entry?;\n let skill_dir = entry.path();\n if !skill_dir.is_dir() {\n continue;\n }\n if skill_dir.join(\"SKILL.md\").is_file() {\n dirs.insert(skill_dir);\n }\n }\n }\n Ok(dirs.into_iter().collect())\n}\n\nfn discover_source_skills(\n source: &config::CodexSkillSourceConfig,\n) -> Result<Vec<CodexExternalSkill>> {\n let root = config::expand_path(&source.path);\n let skill_dirs = collect_skill_dirs(&root)?;\n let mut skills = Vec::new();\n for skill_dir in skill_dirs {\n let skill_file = skill_dir.join(\"SKILL.md\");\n let raw = fs::read_to_string(&skill_file)\n .with_context(|| format!(\"failed to read {}\", skill_file.display()))?;\n let name = parse_frontmatter_field(&raw, \"name\")\n .filter(|value| !value.is_empty())\n .unwrap_or_else(|| {\n skill_dir\n .file_name()\n .map(|value| value.to_string_lossy().to_string())\n .unwrap_or_else(|| \"skill\".to_string())\n });\n let description = parse_frontmatter_field(&raw, \"description\").unwrap_or_default();\n let category = classify_skill_category(&name, &description).to_string();\n skills.push(CodexExternalSkill {\n source_name: source.name.clone(),\n name,\n path: skill_dir.display().to_string(),\n description,\n estimated_chars: raw.chars().count(),\n category,\n });\n }\n skills.sort_by(|a, b| a.name.cmp(&b.name));\n Ok(skills)\n}\n\nfn tokenize_keywords(value: &str) -> Vec<String> {\n value\n .split(|ch: char| !ch.is_ascii_alphanumeric())\n .filter(|part| !part.is_empty())\n .map(|part| part.to_ascii_lowercase())\n .filter(|part| {\n part.len() >= 4\n && !matches!(\n part.as_str(),\n \"skill\"\n | \"skills\"\n | \"with\"\n | \"from\"\n | \"that\"\n | \"this\"\n | \"used\"\n | \"when\"\n | \"help\"\n | \"helps\"\n | \"agent\"\n | \"agents\"\n | \"their\"\n | \"into\"\n | \"your\"\n )\n })\n .collect()\n}\n\nfn contains_any(haystack: &str, needles: &[&str]) -> bool {\n needles.iter().any(|needle| haystack.contains(needle))\n}\n\nfn classify_skill_category(name: &str, description: &str) -> &'static str {\n let normalized = format!(\"{name} {description}\").to_ascii_lowercase();\n if contains_any(\n &normalized,\n &[\n \"review\",\n \"lint\",\n \"style\",\n \"testing-practice\",\n \"test-practice\",\n \"code quality\",\n \"adversarial\",\n ],\n ) {\n return \"quality\";\n }\n if contains_any(\n &normalized,\n &[\n \"verify\",\n \"verification\",\n \"playwright\",\n \"driver\",\n \"assert\",\n \"smoke\",\n \"e2e\",\n \"tmux\",\n \"checkout\",\n \"signup\",\n ],\n ) {\n return \"verification\";\n }\n if contains_any(\n &normalized,\n &[\n \"grafana\",\n \"dashboard\",\n \"query\",\n \"cohort\",\n \"analysis\",\n \"trace\",\n \"funnel\",\n \"retention\",\n \"log\",\n \"metric\",\n ],\n ) {\n return \"analysis\";\n }\n if contains_any(\n &normalized,\n &[\n \"scaffold\",\n \"template\",\n \"migration\",\n \"boilerplate\",\n \"create-app\",\n \"new-\",\n ],\n ) {\n return \"scaffold\";\n }\n if contains_any(\n &normalized,\n &[\n \"deploy\",\n \"release\",\n \"rollback\",\n \"ci/cd\",\n \"cicd\",\n \"prod\",\n \"cherry-pick\",\n \"merge\",\n ],\n ) {\n return \"delivery\";\n }\n if contains_any(\n &normalized,\n &[\n \"runbook\",\n \"debug\",\n \"oncall\",\n \"alert\",\n \"incident\",\n \"correlat\",\n \"investigation\",\n ],\n ) {\n return \"runbook\";\n }\n if contains_any(\n &normalized,\n &[\n \"orphan\",\n \"cleanup\",\n \"kubectl\",\n \"volume\",\n \"pod\",\n \"infra\",\n \"cost\",\n \"dependency-management\",\n ],\n ) {\n return \"ops\";\n }\n if contains_any(\n &normalized,\n &[\n \"workflow\",\n \"ticket\",\n \"standup\",\n \"recap\",\n \"automation\",\n \"process\",\n \"slack\",\n ],\n ) {\n return \"workflow\";\n }\n \"reference\"\n}\n\nfn match_external_skill(query: &str, skill: &CodexExternalSkill) -> f64 {\n let normalized_query = query.to_ascii_lowercase();\n let skill_phrase = tokenize_keywords(&skill.name).join(\" \");\n if !skill_phrase.is_empty() && normalized_query.contains(&skill_phrase) {\n return 1.0;\n }\n\n let mut terms = tokenize_keywords(&skill.name);\n terms.extend(tokenize_keywords(&skill.description));\n terms.sort();\n terms.dedup();\n if terms.is_empty() {\n return 0.0;\n }\n let hits = terms\n .iter()\n .filter(|term| normalized_query.contains(term.as_str()))\n .count();\n hits as f64 / terms.len().min(6) as f64\n}\n\nfn describe_external_skill_match(query: &str, skill: &CodexExternalSkill) -> Option<String> {\n let normalized_query = query.to_ascii_lowercase();\n let skill_phrase = tokenize_keywords(&skill.name).join(\" \");\n if !skill_phrase.is_empty() && normalized_query.contains(&skill_phrase) {\n return Some(format!(\"matched skill name phrase `{skill_phrase}`\"));\n }\n\n let mut terms = tokenize_keywords(&skill.name);\n terms.extend(tokenize_keywords(&skill.description));\n terms.sort();\n terms.dedup();\n let hits = terms\n .into_iter()\n .filter(|term| normalized_query.contains(term.as_str()))\n .collect::<Vec<_>>();\n if hits.is_empty() {\n return None;\n }\n\n let preview = hits.into_iter().take(4).collect::<Vec<_>>().join(\", \");\n Some(format!(\"matched query terms: {preview}\"))\n}\n\nfn copy_dir_recursive(source: &Path, dest: &Path) -> Result<()> {\n fs::create_dir_all(dest)?;\n for entry in fs::read_dir(source)? {\n let entry = entry?;\n let source_path = entry.path();\n let dest_path = dest.join(entry.file_name());\n let metadata = fs::symlink_metadata(&source_path)?;\n if metadata.is_dir() {\n copy_dir_recursive(&source_path, &dest_path)?;\n } else if metadata.file_type().is_symlink() {\n let target = fs::read_link(&source_path)?;\n #[cfg(unix)]\n std::os::unix::fs::symlink(target, &dest_path)?;\n #[cfg(windows)]\n {\n if metadata.is_dir() {\n std::os::windows::fs::symlink_dir(target, &dest_path)?;\n } else {\n std::os::windows::fs::symlink_file(target, &dest_path)?;\n }\n }\n } else {\n fs::copy(&source_path, &dest_path)?;\n }\n }\n Ok(())\n}\n\nfn rewrite_skill_name(content: &str, name: &str) -> String {\n if let Some(after_start) = content.strip_prefix(\"---\\n\") {\n if let Some(end) = after_start.find(\"\\n---\") {\n let mut lines = after_start[..end]\n .lines()\n .map(|line| {\n if line.trim_start().starts_with(\"name:\") {\n format!(\"name: {name}\")\n } else {\n line.to_string()\n }\n })\n .collect::<Vec<_>>();\n if !lines\n .iter()\n .any(|line| line.trim_start().starts_with(\"name:\"))\n {\n lines.insert(0, format!(\"name: {name}\"));\n }\n return format!(\"---\\n{}\\n---{}\", lines.join(\"\\n\"), &after_start[end..]);\n }\n }\n\n format!(\"---\\nname: {name}\\n---\\n\\n{content}\")\n}\n\nfn allocate_plan_path(root: &Path, stem: &str) -> PathBuf {\n let candidate = root.join(format!(\"{stem}.md\"));\n if !candidate.exists() {\n return candidate;\n }\n\n let mut index = 2usize;\n loop {\n let next = root.join(format!(\"{stem}-{index}.md\"));\n if !next.exists() {\n return next;\n }\n index += 1;\n }\n}\n\nfn derive_plan_title(body: &str) -> String {\n for raw_line in body.lines() {\n let line = raw_line.trim();\n if line.is_empty() {\n continue;\n }\n if let Some(rest) = line.strip_prefix('#') {\n let cleaned = rest.trim().trim_start_matches('#').trim();\n if !cleaned.is_empty() {\n return cleaned.to_string();\n }\n }\n return line.to_string();\n }\n \"Plan\".to_string()\n}\n\nfn append_session_footer(body: &str, session_id: Option<&str>) -> String {\n let trimmed = body.trim_end();\n let Some(session_id) = session_id.map(str::trim).filter(|value| !value.is_empty()) else {\n return trimmed.to_string();\n };\n let footer = format!(\"Made from {} Codex session.\", session_id);\n if trimmed.ends_with(&footer) {\n return trimmed.to_string();\n }\n format!(\"{trimmed}\\n\\n{footer}\")\n}\n\nfn unix_now() -> u64 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0)\n}\n\nfn runtime_token(target_path: &Path, query: &str) -> String {\n let mut hasher = Sha256::new();\n hasher.update(target_path.to_string_lossy().as_bytes());\n hasher.update(b\"\\n\");\n hasher.update(query.as_bytes());\n hasher.update(b\"\\n\");\n hasher.update(std::process::id().to_string().as_bytes());\n hasher.update(b\"\\n\");\n hasher.update(unix_now().to_string().as_bytes());\n let digest = format!(\"{:x}\", hasher.finalize());\n digest[..12.min(digest.len())].to_string()\n}\n\nfn plan_skill_name(token: &str) -> String {\n format!(\"{RUNTIME_PREFIX}plan-{token}\")\n}\n\nfn build_plan_skill_markdown(skill_name: &str) -> String {\n format!(\n r#\"---\nname: {skill_name}\ndescription: Write the finished markdown plan for this task into `~/plan` using `f codex runtime write-plan`. Use only for the current task.\npolicy:\n allow_implicit_invocation: false\n---\n\n# Flow Runtime Plan Writer\n\nUse this only when the user asks to write, save, or document a plan.\n\n## Command\n\nWrite the plan with:\n\n```bash\ncat <<'EOF' | f codex runtime write-plan --title \"<short title>\"\n<markdown plan body>\nEOF\n```\n\nThe command prints the absolute path after writing.\n\n## Hard rules\n\n- write the finished plan to `~/plan`\n- keep the chat response short\n- end with the absolute path on its own line\n- do not leave the plan only in chat when the user explicitly asked to write it\n\"#\n )\n}\n\nfn looks_like_plan_request(query: &str) -> bool {\n let normalized = query.to_ascii_lowercase();\n [\n \"write plan\",\n \"save this plan\",\n \"save the plan\",\n \"document the plan\",\n \"put the plan in ~/plan\",\n \"write this up as a plan\",\n ]\n .iter()\n .any(|needle| normalized.contains(needle))\n}\n\npub fn discover_external_skills(\n _target_path: &Path,\n codex_cfg: &config::CodexConfig,\n) -> Result<Vec<CodexExternalSkill>> {\n let mut out = Vec::new();\n for source in configured_skill_sources(codex_cfg) {\n out.extend(discover_source_skills(&source)?);\n }\n out.sort_by(|a, b| a.name.cmp(&b.name));\n Ok(out)\n}\n\npub fn dashboard_snapshot(\n target_path: &Path,\n codex_cfg: &config::CodexConfig,\n recent_limit: usize,\n) -> Result<CodexSkillsDashboardSnapshot> {\n let target_display = target_path.display().to_string();\n let mut sources = Vec::new();\n for source in configured_skill_sources(codex_cfg) {\n let skills = discover_source_skills(&source)?;\n sources.push(CodexSkillSourceSnapshot {\n name: source.name,\n path: config::expand_path(&source.path).display().to_string(),\n enabled: source.enabled.unwrap_or(true),\n skill_count: skills.len(),\n skills,\n });\n }\n sources.sort_by(|a, b| a.name.cmp(&b.name));\n\n let installed_skills = discover_installed_skills()?;\n let catalog = build_skill_catalog(&sources, &installed_skills);\n let runtime_states = load_runtime_states()?;\n let runtime_states_for_target = runtime_states\n .iter()\n .filter(|state| state.target_path == target_display)\n .count();\n let recent_runtime_states = runtime_states\n .into_iter()\n .take(recent_limit)\n .map(|state| CodexRuntimeStateSnapshot {\n token: state.token,\n created_at_unix: state.created_at_unix,\n target_path: state.target_path,\n query: state.query,\n skills: state\n .skills\n .into_iter()\n .map(|skill| skill.original_name.unwrap_or(skill.name))\n .collect(),\n })\n .collect();\n\n Ok(CodexSkillsDashboardSnapshot {\n target_path: target_display,\n sources,\n installed_skills,\n catalog,\n recent_runtime_states,\n runtime_states_for_target,\n })\n}\n\nfn discover_installed_skills() -> Result<Vec<CodexInstalledSkillSnapshot>> {\n let root = codex_global_skill_root();\n if !root.is_dir() {\n return Ok(Vec::new());\n }\n\n let mut installed = Vec::new();\n for entry in fs::read_dir(&root)? {\n let entry = entry?;\n let skill_dir = entry.path();\n if !skill_dir.is_dir() {\n continue;\n }\n let skill_file = skill_dir.join(\"SKILL.md\");\n if !skill_file.is_file() {\n continue;\n }\n let raw = fs::read_to_string(&skill_file)\n .with_context(|| format!(\"failed to read {}\", skill_file.display()))?;\n let name = parse_frontmatter_field(&raw, \"name\")\n .filter(|value| !value.is_empty())\n .unwrap_or_else(|| entry.file_name().to_string_lossy().to_string());\n let description = parse_frontmatter_field(&raw, \"description\").unwrap_or_default();\n let category = classify_skill_category(&name, &description).to_string();\n installed.push(CodexInstalledSkillSnapshot {\n runtime_managed: name.starts_with(RUNTIME_PREFIX),\n name,\n path: skill_dir.display().to_string(),\n description: description.clone(),\n category,\n });\n }\n installed.sort_by(|a, b| a.name.cmp(&b.name));\n Ok(installed)\n}\n\nfn build_skill_catalog(\n sources: &[CodexSkillSourceSnapshot],\n installed_skills: &[CodexInstalledSkillSnapshot],\n) -> Vec<CodexSkillCatalogEntry> {\n let mut merged = BTreeMap::<String, CodexSkillCatalogEntry>::new();\n\n for source in sources {\n for skill in &source.skills {\n let key = skill.name.to_ascii_lowercase();\n let entry = merged.entry(key).or_insert_with(|| CodexSkillCatalogEntry {\n name: skill.name.clone(),\n description: skill.description.clone(),\n category: skill.category.clone(),\n path: skill.path.clone(),\n sources: Vec::new(),\n installed: false,\n runtime_managed: false,\n estimated_chars: Some(skill.estimated_chars),\n });\n if entry.description.is_empty() && !skill.description.is_empty() {\n entry.description = skill.description.clone();\n }\n if entry.path.is_empty() {\n entry.path = skill.path.clone();\n }\n if entry.category == \"reference\" && skill.category != \"reference\" {\n entry.category = skill.category.clone();\n }\n if !entry.sources.iter().any(|value| value == &source.name) {\n entry.sources.push(source.name.clone());\n }\n entry.estimated_chars = entry.estimated_chars.or(Some(skill.estimated_chars));\n }\n }\n\n for skill in installed_skills {\n let key = skill.name.to_ascii_lowercase();\n let entry = merged.entry(key).or_insert_with(|| CodexSkillCatalogEntry {\n name: skill.name.clone(),\n description: skill.description.clone(),\n category: skill.category.clone(),\n path: skill.path.clone(),\n sources: vec![\"global\".to_string()],\n installed: true,\n runtime_managed: skill.runtime_managed,\n estimated_chars: None,\n });\n entry.installed = true;\n entry.runtime_managed |= skill.runtime_managed;\n if entry.description.is_empty() && !skill.description.is_empty() {\n entry.description = skill.description.clone();\n }\n if entry.path.is_empty() {\n entry.path = skill.path.clone();\n }\n if entry.category == \"reference\" && skill.category != \"reference\" {\n entry.category = skill.category.clone();\n }\n if !entry.sources.iter().any(|value| value == \"global\") {\n entry.sources.push(\"global\".to_string());\n }\n }\n\n let mut catalog = merged.into_values().collect::<Vec<_>>();\n for entry in &mut catalog {\n entry.sources.sort();\n entry.sources.dedup();\n entry.category = classify_skill_category(&entry.name, &entry.description).to_string();\n }\n catalog.sort_by(|a, b| a.name.cmp(&b.name));\n catalog\n}\n\npub fn format_external_skills(skills: &[CodexExternalSkill]) -> String {\n if skills.is_empty() {\n return \"No external Codex skill sources discovered.\".to_string();\n }\n\n let mut lines = vec![\"# codex skill-source\".to_string()];\n for skill in skills {\n lines.push(format!(\n \"- {} [{}] {} chars\",\n skill.name, skill.source_name, skill.estimated_chars\n ));\n if !skill.description.is_empty() {\n lines.push(format!(\" {}\", skill.description));\n }\n }\n lines.join(\"\\n\")\n}\n\npub fn sync_external_skills(\n target_path: &Path,\n codex_cfg: &config::CodexConfig,\n selected_skills: &[String],\n force: bool,\n) -> Result<usize> {\n let discovered = discover_external_skills(target_path, codex_cfg)?;\n let selected = selected_skills\n .iter()\n .map(|value| value.trim().to_ascii_lowercase())\n .filter(|value| !value.is_empty())\n .collect::<Vec<_>>();\n let root = codex_global_skill_root();\n fs::create_dir_all(&root)?;\n\n let mut installed = 0usize;\n for skill in discovered {\n if !selected.is_empty()\n && !selected\n .iter()\n .any(|value| value == &skill.name.to_ascii_lowercase())\n {\n continue;\n }\n let dest = root.join(&skill.name);\n if dest.exists() {\n if !force {\n continue;\n }\n fs::remove_dir_all(&dest)\n .with_context(|| format!(\"failed to replace {}\", dest.display()))?;\n }\n copy_dir_recursive(Path::new(&skill.path), &dest)?;\n installed += 1;\n }\n Ok(installed)\n}\n\npub fn prepare_runtime_activation(\n target_path: &Path,\n query: &str,\n enabled: bool,\n codex_cfg: &config::CodexConfig,\n) -> Result<Option<CodexRuntimeActivation>> {\n if !enabled {\n return Ok(None);\n }\n\n let token = runtime_token(target_path, query);\n let state_path = runtime_states_dir()?.join(format!(\"{token}.json\"));\n let skills_root = runtime_skills_dir()?.join(&token);\n fs::create_dir_all(&skills_root)?;\n let scorecard = codex_skill_eval::load_scorecard(target_path)?;\n\n let mut candidates = Vec::new();\n if looks_like_plan_request(query) {\n let skill_name = plan_skill_name(&token);\n let skill_dir = skills_root.join(&skill_name);\n let markdown = build_plan_skill_markdown(&skill_name);\n fs::create_dir_all(&skill_dir)?;\n fs::write(skill_dir.join(\"SKILL.md\"), &markdown)?;\n let scorecard_score = scorecard\n .as_ref()\n .and_then(|value| {\n value\n .skills\n .iter()\n .find(|skill| skill.name == \"plan_write\")\n .map(|skill| skill.score)\n })\n .unwrap_or(0.0);\n let score = 2.5 + scorecard_score / 100.0 - markdown.chars().count() as f64 / 5000.0;\n candidates.push(RuntimeSkillCandidate {\n score,\n skill: CodexRuntimeSkill {\n name: skill_name,\n kind: \"plan_write\".to_string(),\n path: skill_dir.display().to_string(),\n trigger: \"write plan\".to_string(),\n source: Some(\"flow\".to_string()),\n original_name: Some(\"plan_write\".to_string()),\n estimated_chars: Some(markdown.chars().count()),\n match_reason: Some(\"query explicitly asked to write or save a plan\".to_string()),\n },\n source_dir: None,\n });\n }\n\n for external in discover_external_skills(target_path, codex_cfg)? {\n let match_score = match_external_skill(query, &external);\n if match_score < 0.55 {\n continue;\n }\n let scorecard_score = scorecard\n .as_ref()\n .and_then(|value| {\n value\n .skills\n .iter()\n .find(|skill| skill.name == external.name)\n .map(|skill| skill.score)\n })\n .unwrap_or(0.0);\n let runtime_name = format!(\n \"{RUNTIME_PREFIX}ext-{}-{}-{}\",\n slugify(&external.source_name),\n slugify(&external.name),\n token\n );\n let score =\n match_score * 2.0 + scorecard_score / 100.0 - external.estimated_chars as f64 / 6000.0;\n candidates.push(RuntimeSkillCandidate {\n score,\n skill: CodexRuntimeSkill {\n name: runtime_name,\n kind: \"external\".to_string(),\n path: skills_root\n .join(format!(\n \"{}-{}\",\n slugify(&external.source_name),\n slugify(&external.name)\n ))\n .display()\n .to_string(),\n trigger: external.name.clone(),\n source: Some(external.source_name.clone()),\n original_name: Some(external.name.clone()),\n estimated_chars: Some(external.estimated_chars),\n match_reason: describe_external_skill_match(query, &external),\n },\n source_dir: Some(PathBuf::from(&external.path)),\n });\n }\n\n if candidates.is_empty() {\n return Ok(None);\n }\n\n candidates.sort_by(|a, b| {\n b.score\n .partial_cmp(&a.score)\n .unwrap_or(std::cmp::Ordering::Equal)\n });\n\n let mut total_chars = 0usize;\n let mut selected = Vec::new();\n for candidate in candidates {\n let estimated = candidate.skill.estimated_chars.unwrap_or(0);\n if !selected.is_empty() && total_chars + estimated > 8000 {\n continue;\n }\n total_chars += estimated;\n selected.push(candidate);\n if selected.len() >= 2 {\n break;\n }\n }\n\n let mut skills = Vec::new();\n for candidate in selected {\n if let Some(source_dir) = candidate.source_dir.as_ref() {\n let materialized_dir = skills_root.join(format!(\n \"{}-{}\",\n slugify(candidate.skill.source.as_deref().unwrap_or(\"external\")),\n slugify(\n candidate\n .skill\n .original_name\n .as_deref()\n .unwrap_or(candidate.skill.name.as_str())\n )\n ));\n copy_dir_recursive(source_dir, &materialized_dir)?;\n let skill_file = materialized_dir.join(\"SKILL.md\");\n let raw = fs::read_to_string(&skill_file)\n .with_context(|| format!(\"failed to read {}\", skill_file.display()))?;\n fs::write(&skill_file, rewrite_skill_name(&raw, &candidate.skill.name))\n .with_context(|| format!(\"failed to rewrite {}\", skill_file.display()))?;\n let mut skill = candidate.skill.clone();\n skill.path = materialized_dir.display().to_string();\n skills.push(skill);\n } else {\n skills.push(candidate.skill);\n }\n }\n\n let state = CodexRuntimeState {\n version: RUNTIME_VERSION,\n token,\n created_at_unix: unix_now(),\n target_path: target_path.display().to_string(),\n query: query.to_string(),\n skills: skills.clone(),\n };\n fs::write(&state_path, serde_json::to_vec_pretty(&state)?)?;\n\n Ok(Some(CodexRuntimeActivation { state_path, skills }))\n}\n\npub fn load_runtime_states() -> Result<Vec<CodexRuntimeState>> {\n let mut states = Vec::new();\n for dir in runtime_roots().into_iter().map(|root| root.join(\"states\")) {\n if !dir.exists() {\n continue;\n }\n for entry in fs::read_dir(&dir)? {\n let entry = entry?;\n let path = entry.path();\n if path.extension().and_then(|value| value.to_str()) != Some(\"json\") {\n continue;\n }\n let Ok(raw) = fs::read(&path) else {\n continue;\n };\n let Ok(state) = serde_json::from_slice::<CodexRuntimeState>(&raw) else {\n continue;\n };\n states.push(state);\n }\n }\n states.sort_by(|a, b| b.created_at_unix.cmp(&a.created_at_unix));\n states.dedup_by(|a, b| a.token == b.token);\n Ok(states)\n}\n\npub fn clear_runtime_states() -> Result<usize> {\n let mut removed = 0usize;\n for root in runtime_roots() {\n let states_dir = root.join(\"states\");\n if states_dir.exists() {\n for entry in fs::read_dir(&states_dir)? {\n let entry = entry?;\n let path = entry.path();\n if path.is_file() {\n fs::remove_file(&path)?;\n removed += 1;\n }\n }\n }\n\n let skills_dir = root.join(\"skills\");\n if skills_dir.exists() {\n fs::remove_dir_all(&skills_dir)?;\n }\n }\n\n let user_root = agents_skill_root();\n if user_root.exists() {\n for entry in fs::read_dir(&user_root)? {\n let entry = entry?;\n let path = entry.path();\n let Some(name) = path.file_name().and_then(|value| value.to_str()) else {\n continue;\n };\n if !name.starts_with(RUNTIME_PREFIX) {\n continue;\n }\n let meta = fs::symlink_metadata(&path)?;\n if meta.file_type().is_symlink() || meta.is_file() {\n fs::remove_file(&path)?;\n } else if meta.is_dir() {\n fs::remove_dir_all(&path)?;\n }\n }\n }\n\n Ok(removed)\n}\n\npub fn format_runtime_states(states: &[CodexRuntimeState]) -> String {\n if states.is_empty() {\n return \"No Flow-managed Codex runtime skills.\".to_string();\n }\n\n let mut lines = vec![\"# codex runtime\".to_string()];\n for state in states {\n lines.push(format!(\"- token: {}\", state.token));\n lines.push(format!(\" target: {}\", state.target_path));\n lines.push(format!(\" query: {}\", state.query));\n lines.push(format!(\n \" skills: {}\",\n state\n .skills\n .iter()\n .map(|skill| {\n skill\n .original_name\n .as_deref()\n .unwrap_or(skill.name.as_str())\n })\n .collect::<Vec<_>>()\n .join(\", \")\n ));\n }\n lines.join(\"\\n\")\n}\n\nfn load_runtime_state_from_env() -> Option<CodexRuntimeState> {\n let raw_path = env::var(\"FLOW_CODEX_RUNTIME_STATE_PATH\")\n .ok()\n .or_else(|| env::var(\"FLOW_CODEX_RUNTIME_STATE\").ok())?;\n let path = PathBuf::from(raw_path);\n let raw = fs::read(path).ok()?;\n serde_json::from_slice::<CodexRuntimeState>(&raw).ok()\n}\n\npub fn write_plan_from_stdin(\n title: Option<&str>,\n stem: Option<&str>,\n dir: Option<&str>,\n source_session: Option<&str>,\n) -> Result<PathBuf> {\n let mut body = String::new();\n io::stdin()\n .read_to_string(&mut body)\n .context(\"failed to read plan body from stdin\")?;\n if body.trim().is_empty() {\n bail!(\"plan body is empty\");\n }\n\n let root = dir\n .map(PathBuf::from)\n .or_else(|| {\n env::var_os(\"HOME\")\n .map(PathBuf::from)\n .map(|home| home.join(\"plan\"))\n })\n .unwrap_or_else(|| PathBuf::from(\"./plan\"));\n fs::create_dir_all(&root)?;\n\n let resolved_title = title\n .map(str::trim)\n .filter(|value| !value.is_empty())\n .map(ToOwned::to_owned)\n .unwrap_or_else(|| derive_plan_title(&body));\n let mut resolved_stem = stem\n .map(str::trim)\n .filter(|value| !value.is_empty())\n .map(ToOwned::to_owned)\n .unwrap_or_else(|| slugify(&resolved_title));\n if !resolved_stem.ends_with(\"-plan\") {\n resolved_stem.push_str(\"-plan\");\n }\n\n let session = source_session\n .map(str::trim)\n .filter(|value| !value.is_empty())\n .map(ToOwned::to_owned)\n .or_else(|| {\n env::var(\"CODEX_THREAD_ID\")\n .ok()\n .map(|value| value.trim().to_string())\n .filter(|value| !value.is_empty())\n });\n\n let path = allocate_plan_path(&root, &resolved_stem);\n let final_body = append_session_footer(&body, session.as_deref());\n fs::write(&path, final_body + \"\\n\")?;\n if let Some(runtime_state) = load_runtime_state_from_env() {\n let _ = codex_skill_eval::log_outcome(&codex_skill_eval::CodexSkillOutcomeEvent {\n version: 1,\n recorded_at_unix: unix_now(),\n runtime_token: Some(runtime_state.token.clone()),\n session_id: session.clone(),\n target_path: Some(runtime_state.target_path.clone()),\n kind: \"plan_written\".to_string(),\n skill_names: runtime_state\n .skills\n .iter()\n .map(|skill| {\n skill\n .original_name\n .clone()\n .unwrap_or_else(|| skill.name.clone())\n })\n .collect(),\n artifact_path: Some(path.display().to_string()),\n success: 1.0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n service_name: None,\n });\n let mut activity_event = activity_log::ActivityEvent::done(\"plan.write\", resolved_title);\n activity_event.runtime_token = Some(runtime_state.token.clone());\n activity_event.target_path = Some(runtime_state.target_path.clone());\n activity_event.artifact_path = Some(path.display().to_string());\n activity_event.source = Some(\"codex-runtime\".to_string());\n let _ = activity_log::append_daily_event(activity_event);\n }\n Ok(path)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use tempfile::tempdir;\n\n #[test]\n fn plan_request_detection_stays_specific() {\n assert!(looks_like_plan_request(\"write plan\"));\n assert!(looks_like_plan_request(\"Please document the plan\"));\n assert!(!looks_like_plan_request(\"document this feature\"));\n assert!(!looks_like_plan_request(\"planning support cleanup\"));\n }\n\n #[test]\n fn runtime_prompt_prelude_is_human_readable() {\n let activation = CodexRuntimeActivation {\n state_path: PathBuf::from(\"/tmp/runtime.json\"),\n skills: vec![CodexRuntimeSkill {\n name: \"flow-runtime-plan-abc\".to_string(),\n kind: \"plan_write\".to_string(),\n path: \"/tmp/skill\".to_string(),\n trigger: \"write plan\".to_string(),\n source: Some(\"flow\".to_string()),\n original_name: Some(\"plan_write\".to_string()),\n estimated_chars: Some(120),\n match_reason: Some(\"query explicitly asked to write or save a plan\".to_string()),\n }],\n };\n\n assert_eq!(\n activation.inject_into_prompt(\"write plan\"),\n \"[Active Flow skills: plan_write]\\n\\nwrite plan\"\n );\n }\n\n #[test]\n fn session_footer_is_added_once() {\n let once = append_session_footer(\"# Plan\", Some(\"019c\"));\n let twice = append_session_footer(&once, Some(\"019c\"));\n assert_eq!(once, twice);\n assert!(once.ends_with(\"Made from 019c Codex session.\"));\n }\n\n #[test]\n fn discover_external_skills_supports_nested_repo_layout() {\n let temp = tempdir().expect(\"tempdir\");\n let source_root = temp.path().join(\"vercel-skills\");\n let skill_dir = source_root.join(\"skills\").join(\"find-skills\");\n fs::create_dir_all(&skill_dir).expect(\"create nested skill dir\");\n fs::write(\n skill_dir.join(\"SKILL.md\"),\n \"---\\nname: find-skills\\ndescription: Find repo skills.\\n---\\n\",\n )\n .expect(\"write skill\");\n\n let cfg = config::CodexConfig {\n skill_sources: vec![config::CodexSkillSourceConfig {\n name: \"nested\".to_string(),\n path: source_root.display().to_string(),\n enabled: Some(true),\n }],\n ..Default::default()\n };\n\n let skills = discover_external_skills(temp.path(), &cfg).expect(\"discover nested skills\");\n assert_eq!(skills.len(), 1);\n assert_eq!(skills[0].name, \"find-skills\");\n assert_eq!(skills[0].source_name, \"nested\");\n assert_eq!(skills[0].category, \"reference\");\n }\n\n #[test]\n fn discover_external_skills_supports_flat_repo_layout() {\n let temp = tempdir().expect(\"tempdir\");\n let source_root = temp.path().join(\"dimillian-skills\");\n let skill_dir = source_root.join(\"react-component-performance\");\n fs::create_dir_all(&skill_dir).expect(\"create flat skill dir\");\n fs::write(\n skill_dir.join(\"SKILL.md\"),\n \"---\\nname: react-component-performance\\ndescription: Optimize React renders.\\n---\\n\",\n )\n .expect(\"write skill\");\n\n let cfg = config::CodexConfig {\n skill_sources: vec![config::CodexSkillSourceConfig {\n name: \"flat\".to_string(),\n path: source_root.display().to_string(),\n enabled: Some(true),\n }],\n ..Default::default()\n };\n\n let skills = discover_external_skills(temp.path(), &cfg).expect(\"discover flat skills\");\n assert_eq!(skills.len(), 1);\n assert_eq!(skills[0].name, \"react-component-performance\");\n assert_eq!(skills[0].source_name, \"flat\");\n assert_eq!(skills[0].category, \"reference\");\n }\n\n #[test]\n fn classify_skill_category_prefers_verification_for_driver_skills() {\n assert_eq!(\n classify_skill_category(\n \"signup-flow-driver\",\n \"Runs signup verification in a headless browser\"\n ),\n \"verification\"\n );\n }\n\n #[test]\n fn describe_external_skill_match_reports_name_phrase_hits() {\n let skill = CodexExternalSkill {\n source_name: \"vercel\".to_string(),\n name: \"github\".to_string(),\n path: \"/tmp/vercel/github\".to_string(),\n description: \"Interact with GitHub from the CLI\".to_string(),\n estimated_chars: 120,\n category: \"workflow\".to_string(),\n };\n assert_eq!(\n describe_external_skill_match(\n \"check https://github.com/fl2024008/prometheus/pull/2922\",\n &skill\n )\n .as_deref(),\n Some(\"matched skill name phrase `github`\")\n );\n }\n\n #[test]\n fn build_skill_catalog_merges_source_and_global_install() {\n let sources = vec![CodexSkillSourceSnapshot {\n name: \"vercel\".to_string(),\n path: \"/tmp/vercel\".to_string(),\n enabled: true,\n skill_count: 1,\n skills: vec![CodexExternalSkill {\n source_name: \"vercel\".to_string(),\n name: \"github\".to_string(),\n path: \"/tmp/vercel/github\".to_string(),\n description: \"Interact with GitHub from the CLI\".to_string(),\n estimated_chars: 120,\n category: \"workflow\".to_string(),\n }],\n }];\n let installed = vec![CodexInstalledSkillSnapshot {\n name: \"github\".to_string(),\n path: \"/tmp/global/github\".to_string(),\n description: \"Interact with GitHub from the CLI\".to_string(),\n runtime_managed: false,\n category: \"workflow\".to_string(),\n }];\n\n let catalog = build_skill_catalog(&sources, &installed);\n assert_eq!(catalog.len(), 1);\n assert_eq!(catalog[0].name, \"github\");\n assert!(catalog[0].installed);\n assert_eq!(\n catalog[0].sources,\n vec![\"global\".to_string(), \"vercel\".to_string()]\n );\n }\n}\n" }, { "path": "src/codex_skill_eval.rs", "content": "use std::collections::HashMap;\nuse std::fs::{self, File, OpenOptions};\nuse std::io::{Read, Seek, SeekFrom, Write};\nuse std::path::{Path, PathBuf};\nuse std::time::{SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result};\nuse serde::{Deserialize, Serialize};\nuse sha2::{Digest, Sha256};\n\nuse crate::{codex_memory, codex_text, config};\n\nconst SKILL_EVAL_VERSION: u32 = 1;\nconst SKILL_EVAL_REVERSE_SCAN_CHUNK_BYTES: usize = 16 * 1024;\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexSkillEvalEvent {\n pub version: u32,\n pub recorded_at_unix: u64,\n pub mode: String,\n pub action: String,\n pub route: String,\n pub target_path: String,\n pub launch_path: String,\n pub query: String,\n #[serde(default)]\n pub session_id: Option<String>,\n pub runtime_token: Option<String>,\n pub runtime_skills: Vec<String>,\n pub prompt_context_budget_chars: usize,\n pub prompt_chars: usize,\n pub injected_context_chars: usize,\n pub reference_count: usize,\n #[serde(default)]\n pub trace_id: Option<String>,\n #[serde(default)]\n pub span_id: Option<String>,\n #[serde(default)]\n pub parent_span_id: Option<String>,\n #[serde(default)]\n pub workflow_kind: Option<String>,\n #[serde(default)]\n pub service_name: Option<String>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexSkillScore {\n pub name: String,\n pub sample_size: usize,\n pub outcome_samples: usize,\n pub pass_rate: f64,\n pub avg_affinity: f64,\n pub baseline_affinity: f64,\n pub normalized_gain: f64,\n pub avg_context_chars: f64,\n pub score: f64,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexSkillOutcomeEvent {\n pub version: u32,\n pub recorded_at_unix: u64,\n pub runtime_token: Option<String>,\n #[serde(default)]\n pub session_id: Option<String>,\n pub target_path: Option<String>,\n pub kind: String,\n pub skill_names: Vec<String>,\n pub artifact_path: Option<String>,\n pub success: f64,\n #[serde(default)]\n pub trace_id: Option<String>,\n #[serde(default)]\n pub span_id: Option<String>,\n #[serde(default)]\n pub parent_span_id: Option<String>,\n #[serde(default)]\n pub service_name: Option<String>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexSkillScorecard {\n pub version: u32,\n pub generated_at_unix: u64,\n pub target_path: String,\n pub samples: usize,\n pub skills: Vec<CodexSkillScore>,\n}\n\n#[derive(Default)]\nstruct SkillAggregate {\n count: usize,\n outcome_count: usize,\n success_sum: f64,\n total_affinity_used: f64,\n total_affinity_all: f64,\n total_context_chars: usize,\n}\n\nfn unix_now() -> u64 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0)\n}\n\nfn skill_eval_root() -> Result<PathBuf> {\n Ok(config::ensure_global_state_dir()?\n .join(\"codex\")\n .join(\"skill-eval\"))\n}\n\nfn skill_eval_roots() -> Vec<PathBuf> {\n config::global_state_dir_candidates()\n .into_iter()\n .map(|root| root.join(\"codex\").join(\"skill-eval\"))\n .collect()\n}\n\nfn load_events_from_paths(\n paths: Vec<PathBuf>,\n target_path: Option<&Path>,\n limit: usize,\n) -> Result<Vec<CodexSkillEvalEvent>> {\n let mut events = Vec::new();\n for path in paths {\n if !path.exists() {\n continue;\n }\n let path_ref = path.as_path();\n let _ = visit_lines_reverse(path_ref, limit, |line| {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n return None::<CodexSkillEvalEvent>;\n }\n let mut event = serde_json::from_str::<CodexSkillEvalEvent>(trimmed).ok()?;\n event.query = codex_text::sanitize_codex_query_text(&event.query)?;\n if let Some(filter) = target_path\n && !path_matches(&event, filter)\n {\n return None;\n }\n Some(event)\n })?\n .map(|mut loaded| events.append(&mut loaded));\n }\n\n events.sort_by(|a, b| b.recorded_at_unix.cmp(&a.recorded_at_unix));\n if events.len() > limit {\n events.truncate(limit);\n }\n Ok(events)\n}\n\nfn load_outcomes_from_paths(\n paths: Vec<PathBuf>,\n target_path: Option<&Path>,\n limit: usize,\n) -> Result<Vec<CodexSkillOutcomeEvent>> {\n let mut outcomes = Vec::new();\n for path in paths {\n if !path.exists() {\n continue;\n }\n let path_ref = path.as_path();\n let _ = visit_lines_reverse(path_ref, limit, |line| {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n return None::<CodexSkillOutcomeEvent>;\n }\n let outcome = serde_json::from_str::<CodexSkillOutcomeEvent>(trimmed).ok()?;\n if let Some(filter) = target_path {\n let Some(target) = outcome.target_path.as_deref() else {\n return None;\n };\n let filter = filter.display().to_string();\n if target != filter && !target.starts_with(&(filter + \"/\")) {\n return None;\n }\n }\n Some(outcome)\n })?\n .map(|mut loaded| outcomes.append(&mut loaded));\n }\n\n outcomes.sort_by(|a, b| b.recorded_at_unix.cmp(&a.recorded_at_unix));\n if outcomes.len() > limit {\n outcomes.truncate(limit);\n }\n Ok(outcomes)\n}\n\nfn events_path() -> Result<PathBuf> {\n let root = skill_eval_root()?;\n fs::create_dir_all(&root)?;\n Ok(root.join(\"events.jsonl\"))\n}\n\npub fn events_log_path() -> Result<PathBuf> {\n events_path()\n}\n\nfn outcomes_path() -> Result<PathBuf> {\n let root = skill_eval_root()?;\n fs::create_dir_all(&root)?;\n Ok(root.join(\"outcomes.jsonl\"))\n}\n\npub fn outcomes_log_path() -> Result<PathBuf> {\n outcomes_path()\n}\n\nfn scorecards_dir() -> Result<PathBuf> {\n let dir = skill_eval_root()?.join(\"scorecards\");\n fs::create_dir_all(&dir)?;\n Ok(dir)\n}\n\nfn scorecard_key(target_path: &Path) -> String {\n let mut hasher = Sha256::new();\n hasher.update(target_path.display().to_string().as_bytes());\n let digest = format!(\"{:x}\", hasher.finalize());\n digest[..12.min(digest.len())].to_string()\n}\n\nfn scorecard_path(target_path: &Path) -> Result<PathBuf> {\n Ok(scorecards_dir()?.join(format!(\"{}.json\", scorecard_key(target_path))))\n}\n\nfn tokenize_words(value: &str) -> Vec<String> {\n value\n .split(|ch: char| !ch.is_ascii_alphanumeric())\n .filter(|part| !part.is_empty())\n .map(|part| part.to_ascii_lowercase())\n .filter(|part| {\n part.len() >= 4\n && !matches!(\n part.as_str(),\n \"flow\"\n | \"runtime\"\n | \"skill\"\n | \"skills\"\n | \"this\"\n | \"that\"\n | \"with\"\n | \"from\"\n | \"into\"\n | \"write\"\n | \"using\"\n | \"codex\"\n | \"session\"\n | \"query\"\n | \"prompt\"\n | \"plan\"\n )\n })\n .collect()\n}\n\nfn affinity_for_skill(skill_name: &str, query: &str) -> f64 {\n let query_lower = query.to_ascii_lowercase();\n let skill_words = tokenize_words(skill_name);\n if skill_words.is_empty() {\n return 0.0;\n }\n\n let phrase = skill_words.join(\" \");\n if !phrase.is_empty() && query_lower.contains(&phrase) {\n return 1.0;\n }\n\n let hits = skill_words\n .iter()\n .filter(|word| query_lower.contains(word.as_str()))\n .count();\n hits as f64 / skill_words.len() as f64\n}\n\nfn calculate_normalized_gain(p_with: f64, p_without: f64) -> f64 {\n if p_without >= 1.0 {\n return if p_with >= 1.0 { 0.0 } else { -1.0 };\n }\n (p_with - p_without) / (1.0 - p_without)\n}\n\nfn path_matches(event: &CodexSkillEvalEvent, target_path: &Path) -> bool {\n let target = target_path.display().to_string();\n event.target_path == target\n || event.launch_path == target\n || event.target_path.starts_with(&(target.clone() + \"/\"))\n || event.launch_path.starts_with(&(target + \"/\"))\n}\n\npub fn log_event(event: &CodexSkillEvalEvent) -> Result<()> {\n let mut sanitized = event.clone();\n let Some(query) = codex_text::sanitize_codex_query_text(&sanitized.query) else {\n return Ok(());\n };\n sanitized.query = query;\n let path = events_path()?;\n let mut file = OpenOptions::new()\n .create(true)\n .append(true)\n .open(&path)\n .with_context(|| format!(\"failed to open {}\", path.display()))?;\n serde_json::to_writer(&mut file, &sanitized)\n .context(\"failed to encode codex skill-eval event\")?;\n file.write_all(b\"\\n\")\n .context(\"failed to terminate codex skill-eval event\")?;\n let _ = codex_memory::mirror_skill_eval_event(&sanitized);\n Ok(())\n}\n\npub fn log_outcome(outcome: &CodexSkillOutcomeEvent) -> Result<()> {\n let path = outcomes_path()?;\n let mut file = OpenOptions::new()\n .create(true)\n .append(true)\n .open(&path)\n .with_context(|| format!(\"failed to open {}\", path.display()))?;\n serde_json::to_writer(&mut file, outcome)\n .context(\"failed to encode codex skill-eval outcome\")?;\n file.write_all(b\"\\n\")\n .context(\"failed to terminate codex skill-eval outcome\")?;\n let _ = codex_memory::mirror_skill_outcome_event(outcome);\n Ok(())\n}\n\npub fn event_count() -> usize {\n load_events(None, usize::MAX)\n .map(|events| events.len())\n .unwrap_or(0)\n}\n\npub fn outcome_count() -> usize {\n load_outcomes(None, usize::MAX)\n .map(|outcomes| outcomes.len())\n .unwrap_or(0)\n}\n\npub fn load_events(target_path: Option<&Path>, limit: usize) -> Result<Vec<CodexSkillEvalEvent>> {\n load_events_from_paths(\n skill_eval_roots()\n .into_iter()\n .map(|root| root.join(\"events.jsonl\"))\n .collect(),\n target_path,\n limit,\n )\n}\n\nfn collect_recent_targets(\n events: Vec<CodexSkillEvalEvent>,\n max_targets: usize,\n within_hours: u64,\n) -> Vec<PathBuf> {\n let mut seen = std::collections::BTreeSet::new();\n let mut out = Vec::new();\n let cutoff = unix_now().saturating_sub(within_hours.saturating_mul(3600));\n for event in events {\n if event.recorded_at_unix < cutoff {\n continue;\n }\n if event.target_path.trim().is_empty() {\n continue;\n }\n let path = PathBuf::from(&event.target_path);\n if !path.exists() {\n continue;\n }\n if seen.insert(event.target_path.clone()) {\n out.push(path);\n if out.len() >= max_targets {\n break;\n }\n }\n }\n out\n}\n\npub fn recent_targets(limit: usize, max_targets: usize, within_hours: u64) -> Result<Vec<PathBuf>> {\n Ok(collect_recent_targets(\n load_events(None, limit)?,\n max_targets,\n within_hours,\n ))\n}\n\npub fn load_outcomes(\n target_path: Option<&Path>,\n limit: usize,\n) -> Result<Vec<CodexSkillOutcomeEvent>> {\n load_outcomes_from_paths(\n skill_eval_roots()\n .into_iter()\n .map(|root| root.join(\"outcomes.jsonl\"))\n .collect(),\n target_path,\n limit,\n )\n}\n\npub fn rebuild_scorecard(target_path: &Path, limit: usize) -> Result<CodexSkillScorecard> {\n let events = load_events(Some(target_path), limit)?;\n let outcomes = load_outcomes(Some(target_path), limit)?;\n let scorecard = build_scorecard(target_path, events, outcomes);\n let path = scorecard_path(target_path)?;\n fs::write(&path, serde_json::to_vec_pretty(&scorecard)?)\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(scorecard)\n}\n\nfn build_scorecard(\n target_path: &Path,\n events: Vec<CodexSkillEvalEvent>,\n outcomes: Vec<CodexSkillOutcomeEvent>,\n) -> CodexSkillScorecard {\n let outcomes_by_token = outcomes\n .iter()\n .filter_map(|outcome| {\n outcome\n .runtime_token\n .as_deref()\n .map(|token| (token.to_string(), outcome))\n })\n .fold(\n HashMap::<String, Vec<&CodexSkillOutcomeEvent>>::new(),\n |mut acc, (token, outcome)| {\n acc.entry(token).or_default().push(outcome);\n acc\n },\n );\n let outcomes_by_session = outcomes\n .iter()\n .filter_map(|outcome| {\n outcome\n .session_id\n .as_deref()\n .map(|session_id| (session_id.to_string(), outcome))\n })\n .fold(\n HashMap::<String, Vec<&CodexSkillOutcomeEvent>>::new(),\n |mut acc, (session_id, outcome)| {\n acc.entry(session_id).or_default().push(outcome);\n acc\n },\n );\n let known_skills = events\n .iter()\n .flat_map(|event| event.runtime_skills.iter().cloned())\n .collect::<std::collections::BTreeSet<_>>();\n let mut aggregates = known_skills\n .iter()\n .map(|name| (name.clone(), SkillAggregate::default()))\n .collect::<HashMap<_, _>>();\n\n for event in &events {\n let query = event.query.trim();\n if query.is_empty() {\n continue;\n }\n let used = event\n .runtime_skills\n .iter()\n .cloned()\n .collect::<std::collections::HashSet<_>>();\n for skill_name in &known_skills {\n let affinity = affinity_for_skill(skill_name, query);\n let entry = aggregates.entry(skill_name.clone()).or_default();\n entry.total_affinity_all += affinity;\n if used.contains(skill_name) {\n entry.count += 1;\n entry.total_affinity_used += affinity;\n entry.total_context_chars += event.injected_context_chars;\n let matched = event\n .runtime_token\n .as_deref()\n .and_then(|token| outcomes_by_token.get(token))\n .or_else(|| {\n event\n .session_id\n .as_deref()\n .and_then(|session_id| outcomes_by_session.get(session_id))\n });\n if let Some(matched) = matched {\n let best_success = matched\n .iter()\n .filter(|outcome| {\n outcome.skill_names.is_empty()\n || outcome.skill_names.iter().any(|name| name == skill_name)\n })\n .map(|outcome| outcome.success)\n .fold(0.0f64, f64::max);\n entry.outcome_count += 1;\n entry.success_sum += best_success;\n }\n }\n }\n }\n\n let total_events = events.len().max(1) as f64;\n let baseline_pass_rate = {\n let mut success = 0.0f64;\n let mut samples = 0usize;\n for event in &events {\n let matched = event\n .runtime_token\n .as_deref()\n .and_then(|token| outcomes_by_token.get(token))\n .or_else(|| {\n event\n .session_id\n .as_deref()\n .and_then(|session_id| outcomes_by_session.get(session_id))\n });\n let Some(matched) = matched else {\n continue;\n };\n let best = matched\n .iter()\n .map(|outcome| outcome.success)\n .fold(0.0, f64::max);\n success += best;\n samples += 1;\n }\n if samples == 0 {\n 0.0\n } else {\n success / samples as f64\n }\n };\n let mut skills = aggregates\n .into_iter()\n .filter_map(|(name, agg)| {\n if agg.count == 0 {\n return None;\n }\n let avg_affinity = agg.total_affinity_used / agg.count as f64;\n let baseline_affinity = agg.total_affinity_all / total_events;\n let pass_rate = if agg.outcome_count == 0 {\n 0.0\n } else {\n agg.success_sum / agg.outcome_count as f64\n };\n let normalized_gain = if agg.outcome_count > 0 {\n calculate_normalized_gain(pass_rate, baseline_pass_rate)\n } else {\n calculate_normalized_gain(avg_affinity, baseline_affinity)\n };\n let avg_context_chars = agg.total_context_chars as f64 / agg.count as f64;\n let score = if agg.outcome_count > 0 {\n (normalized_gain * 100.0) + (pass_rate * 25.0) + (agg.count.min(20) as f64 / 4.0)\n - (avg_context_chars / 500.0)\n } else {\n (normalized_gain * 100.0) + (agg.count.min(20) as f64 / 4.0)\n - (avg_context_chars / 500.0)\n };\n Some(CodexSkillScore {\n name,\n sample_size: agg.count,\n outcome_samples: agg.outcome_count,\n pass_rate,\n avg_affinity,\n baseline_affinity,\n normalized_gain,\n avg_context_chars,\n score,\n })\n })\n .collect::<Vec<_>>();\n skills.sort_by(|a, b| {\n b.score\n .partial_cmp(&a.score)\n .unwrap_or(std::cmp::Ordering::Equal)\n });\n\n let scorecard = CodexSkillScorecard {\n version: SKILL_EVAL_VERSION,\n generated_at_unix: unix_now(),\n target_path: target_path.display().to_string(),\n samples: events.len(),\n skills,\n };\n scorecard\n}\n\npub fn load_scorecard(target_path: &Path) -> Result<Option<CodexSkillScorecard>> {\n for root in skill_eval_roots() {\n let path = root\n .join(\"scorecards\")\n .join(format!(\"{}.json\", scorecard_key(target_path)));\n if !path.exists() {\n continue;\n }\n let raw = fs::read(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let scorecard = serde_json::from_slice::<CodexSkillScorecard>(&raw)\n .with_context(|| format!(\"failed to decode {}\", path.display()))?;\n return Ok(Some(scorecard));\n }\n Ok(None)\n}\n\nfn visit_lines_reverse<T, F>(\n path: &Path,\n max_items: usize,\n mut on_line: F,\n) -> Result<Option<Vec<T>>>\nwhere\n F: FnMut(&str) -> Option<T>,\n{\n if max_items == 0 {\n return Ok(Some(Vec::new()));\n }\n\n let mut file =\n File::open(path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let mut pos = file.seek(SeekFrom::End(0))?;\n if pos == 0 {\n return Ok(None);\n }\n\n let mut chunk = vec![0u8; SKILL_EVAL_REVERSE_SCAN_CHUNK_BYTES];\n let mut carry = Vec::new();\n let mut values = Vec::new();\n\n while pos > 0 && values.len() < max_items {\n let read_len = usize::try_from(pos.min(chunk.len() as u64)).unwrap_or(chunk.len());\n pos -= read_len as u64;\n file.seek(SeekFrom::Start(pos))?;\n file.read_exact(&mut chunk[..read_len])\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n\n let buf = &chunk[..read_len];\n let mut end = read_len;\n while let Some(idx) = buf[..end].iter().rposition(|&byte| byte == b'\\n') {\n if let Some(value) =\n process_reverse_line_segment(&buf[idx + 1..end], &mut carry, &mut on_line)\n {\n values.push(value);\n if values.len() >= max_items {\n return Ok(Some(values));\n }\n }\n end = idx;\n }\n\n if end > 0 {\n let mut combined = Vec::with_capacity(end + carry.len());\n combined.extend_from_slice(&buf[..end]);\n combined.extend_from_slice(&carry);\n carry = combined;\n }\n }\n\n if values.len() < max_items\n && !carry.is_empty()\n && let Ok(line) = std::str::from_utf8(&carry)\n && let Some(value) = on_line(line.trim_end_matches('\\r'))\n {\n values.push(value);\n }\n\n if values.is_empty() {\n Ok(None)\n } else {\n Ok(Some(values))\n }\n}\n\nfn process_reverse_line_segment<T, F>(\n segment: &[u8],\n carry: &mut Vec<u8>,\n on_line: &mut F,\n) -> Option<T>\nwhere\n F: FnMut(&str) -> Option<T>,\n{\n if carry.is_empty() {\n let line = std::str::from_utf8(segment).ok()?;\n return on_line(line.trim_end_matches('\\r'));\n }\n\n let suffix = std::mem::take(carry);\n let mut line_bytes = Vec::with_capacity(segment.len() + suffix.len());\n line_bytes.extend_from_slice(segment);\n line_bytes.extend_from_slice(&suffix);\n let line = std::str::from_utf8(&line_bytes).ok()?;\n on_line(line.trim_end_matches('\\r'))\n}\n\npub fn score_for_skill(target_path: &Path, name: &str) -> Option<f64> {\n load_scorecard(target_path)\n .ok()\n .flatten()\n .and_then(|scorecard| {\n scorecard\n .skills\n .into_iter()\n .find(|skill| skill.name == name)\n .map(|skill| skill.score)\n })\n}\n\npub fn format_scorecard(scorecard: &CodexSkillScorecard) -> String {\n if scorecard.skills.is_empty() {\n return format!(\n \"# codex skill-eval\\n\\\ntarget: {}\\n\\\nsamples: {}\\n\\\nskills: 0\",\n scorecard.target_path, scorecard.samples\n );\n }\n\n let mut lines = vec![\n \"# codex skill-eval\".to_string(),\n format!(\"target: {}\", scorecard.target_path),\n format!(\"samples: {}\", scorecard.samples),\n ];\n for skill in &scorecard.skills {\n lines.push(format!(\n \"- {} | score {:.2} | gain {:.3} | samples {} | outcomes {} | pass {:.2} | ctx {:.0} chars\",\n skill.name,\n skill.score,\n skill.normalized_gain,\n skill.sample_size,\n skill.outcome_samples,\n skill.pass_rate,\n skill.avg_context_chars\n ));\n }\n lines.join(\"\\n\")\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn normalized_gain_behaves_like_skillgrade_formula() {\n let gain = calculate_normalized_gain(0.8, 0.5);\n assert!((gain - 0.6).abs() < 0.0001);\n }\n\n #[test]\n fn affinity_prefers_phrase_matches() {\n assert!(\n affinity_for_skill(\"find-skills\", \"please find skills for react\")\n >= affinity_for_skill(\"find-skills\", \"please help with react\")\n );\n }\n\n #[test]\n fn load_events_reads_both_state_roots() {\n let dir = tempfile::tempdir().expect(\"tempdir\");\n let legacy_path = dir.path().join(\"legacy\");\n let current_path = dir.path().join(\"current\");\n fs::create_dir_all(&legacy_path).expect(\"legacy dir\");\n fs::create_dir_all(¤t_path).expect(\"current dir\");\n\n let event = CodexSkillEvalEvent {\n version: 1,\n recorded_at_unix: 1,\n mode: \"resolve\".to_string(),\n action: \"new\".to_string(),\n route: \"new-plain\".to_string(),\n target_path: \"/tmp/repo\".to_string(),\n launch_path: \"/tmp/repo\".to_string(),\n query: \"write plan\".to_string(),\n session_id: None,\n runtime_token: Some(\"tok\".to_string()),\n runtime_skills: vec![\"plan_write\".to_string()],\n prompt_context_budget_chars: 400,\n prompt_chars: 100,\n injected_context_chars: 30,\n reference_count: 0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n workflow_kind: None,\n service_name: None,\n };\n fs::write(\n legacy_path.join(\"events.jsonl\"),\n serde_json::to_string(&event).expect(\"encode\") + \"\\n\",\n )\n .expect(\"legacy events\");\n fs::write(\n current_path.join(\"events.jsonl\"),\n serde_json::to_string(&CodexSkillEvalEvent {\n recorded_at_unix: 2,\n ..event.clone()\n })\n .expect(\"encode\")\n + \"\\n\",\n )\n .expect(\"current events\");\n\n let loaded = load_events_from_paths(\n vec![\n legacy_path.join(\"events.jsonl\"),\n current_path.join(\"events.jsonl\"),\n ],\n None,\n 10,\n )\n .expect(\"load\");\n assert_eq!(loaded.len(), 2);\n assert_eq!(loaded[0].recorded_at_unix, 2);\n }\n\n #[test]\n fn load_events_sanitizes_contextual_queries() {\n let dir = tempfile::tempdir().expect(\"tempdir\");\n let path = dir.path().join(\"events.jsonl\");\n let event = CodexSkillEvalEvent {\n version: 1,\n recorded_at_unix: 1,\n mode: \"quick-launch\".to_string(),\n action: \"resume\".to_string(),\n route: \"quick-launch-hydrated\".to_string(),\n target_path: \"/tmp/repo\".to_string(),\n launch_path: \"/tmp/repo\".to_string(),\n query: \"# AGENTS.md instructions for /tmp\\n\\n<INSTRUCTIONS>\\nbody\\n</INSTRUCTIONS>\\n<environment_context>\\n<cwd>/tmp</cwd>\\n</environment_context>\\nwrite plan\".to_string(),\n session_id: Some(\"sess-1\".to_string()),\n runtime_token: None,\n runtime_skills: Vec::new(),\n prompt_context_budget_chars: 0,\n prompt_chars: 10,\n injected_context_chars: 0,\n reference_count: 0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n workflow_kind: None,\n service_name: None,\n };\n fs::write(&path, serde_json::to_string(&event).expect(\"encode\") + \"\\n\").expect(\"write\");\n\n let loaded = load_events_from_paths(vec![path], None, 10).expect(\"load\");\n assert_eq!(loaded.len(), 1);\n assert_eq!(loaded[0].query, \"write plan\");\n }\n\n #[test]\n fn resolve_events_contribute_outcome_samples() {\n let target = Path::new(\"/tmp/repo\");\n let scorecard = build_scorecard(\n target,\n vec![CodexSkillEvalEvent {\n version: 1,\n recorded_at_unix: 1,\n mode: \"resolve\".to_string(),\n action: \"new\".to_string(),\n route: \"new-plain\".to_string(),\n target_path: target.display().to_string(),\n launch_path: target.display().to_string(),\n query: \"write plan\".to_string(),\n session_id: None,\n runtime_token: Some(\"tok\".to_string()),\n runtime_skills: vec![\"plan_write\".to_string()],\n prompt_context_budget_chars: 400,\n prompt_chars: 100,\n injected_context_chars: 30,\n reference_count: 0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n workflow_kind: None,\n service_name: None,\n }],\n vec![CodexSkillOutcomeEvent {\n version: 1,\n recorded_at_unix: 2,\n runtime_token: Some(\"tok\".to_string()),\n session_id: None,\n target_path: Some(target.display().to_string()),\n kind: \"plan_written\".to_string(),\n skill_names: vec![\"plan_write\".to_string()],\n artifact_path: Some(\"/tmp/repo/plan.md\".to_string()),\n success: 1.0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n service_name: None,\n }],\n );\n\n assert_eq!(scorecard.samples, 1);\n assert_eq!(scorecard.skills.len(), 1);\n assert_eq!(scorecard.skills[0].name, \"plan_write\");\n assert_eq!(scorecard.skills[0].outcome_samples, 1);\n assert_eq!(scorecard.skills[0].pass_rate, 1.0);\n }\n\n #[test]\n fn session_linked_events_contribute_baseline_outcomes() {\n let target = Path::new(\"/tmp/repo\");\n let scorecard = build_scorecard(\n target,\n vec![CodexSkillEvalEvent {\n version: 1,\n recorded_at_unix: 1,\n mode: \"quick-launch\".to_string(),\n action: \"resume\".to_string(),\n route: \"quick-launch-hydrated\".to_string(),\n target_path: target.display().to_string(),\n launch_path: target.display().to_string(),\n query: \"write plan\".to_string(),\n session_id: Some(\"sess-1\".to_string()),\n runtime_token: None,\n runtime_skills: vec![\"plan_write\".to_string()],\n prompt_context_budget_chars: 0,\n prompt_chars: 10,\n injected_context_chars: 0,\n reference_count: 0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n workflow_kind: None,\n service_name: None,\n }],\n vec![CodexSkillOutcomeEvent {\n version: 1,\n recorded_at_unix: 2,\n runtime_token: None,\n session_id: Some(\"sess-1\".to_string()),\n target_path: Some(target.display().to_string()),\n kind: \"plan_written\".to_string(),\n skill_names: vec![\"plan_write\".to_string()],\n artifact_path: Some(\"/tmp/repo/plan.md\".to_string()),\n success: 1.0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n service_name: None,\n }],\n );\n\n assert_eq!(scorecard.skills.len(), 1);\n assert_eq!(scorecard.skills[0].outcome_samples, 1);\n assert_eq!(scorecard.skills[0].pass_rate, 1.0);\n }\n\n #[test]\n fn recent_targets_filters_old_missing_and_excess_targets() {\n let dir = tempfile::tempdir().expect(\"tempdir\");\n let repo_a = dir.path().join(\"repo-a\");\n let repo_b = dir.path().join(\"repo-b\");\n fs::create_dir_all(&repo_a).expect(\"repo a\");\n fs::create_dir_all(&repo_b).expect(\"repo b\");\n let now = unix_now();\n\n let targets = collect_recent_targets(\n vec![\n CodexSkillEvalEvent {\n version: 1,\n recorded_at_unix: now,\n mode: \"resolve\".to_string(),\n action: \"new\".to_string(),\n route: \"new-plain\".to_string(),\n target_path: repo_a.display().to_string(),\n launch_path: repo_a.display().to_string(),\n query: \"write plan\".to_string(),\n session_id: None,\n runtime_token: Some(\"a\".to_string()),\n runtime_skills: vec![\"plan_write\".to_string()],\n prompt_context_budget_chars: 400,\n prompt_chars: 100,\n injected_context_chars: 30,\n reference_count: 0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n workflow_kind: None,\n service_name: None,\n },\n CodexSkillEvalEvent {\n version: 1,\n recorded_at_unix: now.saturating_sub(60),\n mode: \"resolve\".to_string(),\n action: \"new\".to_string(),\n route: \"new-plain\".to_string(),\n target_path: repo_b.display().to_string(),\n launch_path: repo_b.display().to_string(),\n query: \"find skills\".to_string(),\n session_id: None,\n runtime_token: Some(\"b\".to_string()),\n runtime_skills: vec![\"find-skills\".to_string()],\n prompt_context_budget_chars: 400,\n prompt_chars: 100,\n injected_context_chars: 30,\n reference_count: 0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n workflow_kind: None,\n service_name: None,\n },\n CodexSkillEvalEvent {\n version: 1,\n recorded_at_unix: now.saturating_sub(60 * 60 * 24 * 10),\n mode: \"resolve\".to_string(),\n action: \"new\".to_string(),\n route: \"new-plain\".to_string(),\n target_path: dir.path().join(\"missing\").display().to_string(),\n launch_path: dir.path().join(\"missing\").display().to_string(),\n query: \"old\".to_string(),\n session_id: None,\n runtime_token: Some(\"c\".to_string()),\n runtime_skills: vec![\"plan_write\".to_string()],\n prompt_context_budget_chars: 400,\n prompt_chars: 100,\n injected_context_chars: 30,\n reference_count: 0,\n trace_id: None,\n span_id: None,\n parent_span_id: None,\n workflow_kind: None,\n service_name: None,\n },\n ],\n 1,\n 24,\n );\n\n assert_eq!(targets, vec![repo_a]);\n }\n}\n" }, { "path": "src/codex_telemetry.rs", "content": "use std::collections::hash_map::DefaultHasher;\nuse std::fs::{self, File};\nuse std::hash::{Hash, Hasher};\nuse std::io::{BufRead, BufReader, Seek, SeekFrom};\nuse std::path::{Path, PathBuf};\nuse std::time::{SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result};\nuse reqwest::blocking::Client;\nuse seq_everruns_bridge::maple::{\n MapleExporterConfig, MapleIngestTarget, MapleSpan, MapleTraceExporter,\n};\nuse serde::{Deserialize, Serialize};\n\nuse crate::codex_skill_eval::{self, CodexSkillEvalEvent, CodexSkillOutcomeEvent};\nuse crate::config;\nuse crate::env as flow_env;\n\nconst CODEX_MAPLE_DEFAULT_SERVICE_NAME: &str = \"flow-codex\";\nconst CODEX_MAPLE_DEFAULT_SCOPE_NAME: &str = \"flow.codex\";\nconst CODEX_MAPLE_DEFAULT_ENV: &str = \"local\";\nconst CODEX_MAPLE_DEFAULT_QUEUE_CAPACITY: usize = 1024;\nconst CODEX_MAPLE_DEFAULT_MAX_BATCH_SIZE: usize = 64;\nconst CODEX_MAPLE_DEFAULT_FLUSH_INTERVAL_MS: u64 = 100;\nconst CODEX_MAPLE_DEFAULT_CONNECT_TIMEOUT_MS: u64 = 400;\nconst CODEX_MAPLE_DEFAULT_REQUEST_TIMEOUT_MS: u64 = 800;\nconst DEFAULT_MAPLE_MCP_ENDPOINT: &str = \"https://api.maple.dev/mcp\";\n\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\n#[serde(rename_all = \"camelCase\")]\nstruct CodexTelemetryExportState {\n version: u32,\n events_offset: u64,\n outcomes_offset: u64,\n events_exported: u64,\n outcomes_exported: u64,\n last_exported_at_unix: Option<u64>,\n}\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexTelemetryStatus {\n pub enabled: bool,\n pub configured_targets: usize,\n pub service_name: String,\n pub scope_name: String,\n pub state_path: String,\n pub events_path: String,\n pub outcomes_path: String,\n pub events_offset: u64,\n pub outcomes_offset: u64,\n pub events_exported: u64,\n pub outcomes_exported: u64,\n pub last_exported_at_unix: Option<u64>,\n}\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexTelemetryFlushSummary {\n pub enabled: bool,\n pub configured_targets: usize,\n pub events_seen: usize,\n pub outcomes_seen: usize,\n pub events_exported: usize,\n pub outcomes_exported: usize,\n pub state_path: String,\n pub last_exported_at_unix: Option<u64>,\n}\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexTraceStatus {\n pub enabled: bool,\n pub endpoint: String,\n pub token_source: String,\n pub tools_list_ok: bool,\n pub tools_count: usize,\n pub read_probe_ok: bool,\n pub read_probe_error: Option<String>,\n}\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexTraceInspectResult {\n pub trace_id: String,\n pub endpoint: String,\n pub token_source: String,\n pub flushed: bool,\n pub result: Option<serde_json::Value>,\n pub read_error: Option<String>,\n}\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct CodexCurrentSessionTrace {\n pub trace_id: String,\n pub span_id: Option<String>,\n pub parent_span_id: Option<String>,\n pub workflow_kind: Option<String>,\n pub service_name: Option<String>,\n pub flushed: bool,\n pub endpoint: String,\n pub token_source: String,\n pub result: Option<serde_json::Value>,\n pub read_error: Option<String>,\n}\n\n#[derive(Debug, Clone)]\nstruct MapleReadConfig {\n endpoint: String,\n token: String,\n token_source: String,\n connect_timeout_ms: u64,\n request_timeout_ms: u64,\n}\n\nfn unix_now() -> u64 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0)\n}\n\nfn env_non_empty(key: &str) -> Option<String> {\n std::env::var(key)\n .ok()\n .map(|value| value.trim().to_string())\n .filter(|value| !value.is_empty())\n}\n\nfn telemetry_env_keys() -> Vec<String> {\n [\n \"FLOW_CODEX_MAPLE_LOCAL_ENDPOINT\",\n \"FLOW_CODEX_MAPLE_LOCAL_INGEST_KEY\",\n \"FLOW_CODEX_MAPLE_HOSTED_ENDPOINT\",\n \"FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY\",\n \"FLOW_CODEX_MAPLE_TRACES_ENDPOINTS\",\n \"FLOW_CODEX_MAPLE_INGEST_KEYS\",\n \"FLOW_CODEX_MAPLE_SERVICE_NAME\",\n \"FLOW_CODEX_MAPLE_SERVICE_VERSION\",\n \"FLOW_CODEX_MAPLE_SCOPE_NAME\",\n \"FLOW_CODEX_MAPLE_ENV\",\n \"FLOW_CODEX_MAPLE_QUEUE_CAPACITY\",\n \"FLOW_CODEX_MAPLE_MAX_BATCH_SIZE\",\n \"FLOW_CODEX_MAPLE_FLUSH_INTERVAL_MS\",\n \"FLOW_CODEX_MAPLE_CONNECT_TIMEOUT_MS\",\n \"FLOW_CODEX_MAPLE_REQUEST_TIMEOUT_MS\",\n \"MAPLE_API_TOKEN\",\n \"MAPLE_MCP_URL\",\n ]\n .into_iter()\n .map(str::to_string)\n .collect()\n}\n\nfn maple_target_env_keys() -> &'static [&'static str] {\n &[\n \"FLOW_CODEX_MAPLE_LOCAL_ENDPOINT\",\n \"FLOW_CODEX_MAPLE_LOCAL_INGEST_KEY\",\n \"FLOW_CODEX_MAPLE_HOSTED_ENDPOINT\",\n \"FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY\",\n \"FLOW_CODEX_MAPLE_TRACES_ENDPOINTS\",\n \"FLOW_CODEX_MAPLE_INGEST_KEYS\",\n ]\n}\n\nfn shell_has_explicit_maple_target_env() -> bool {\n maple_target_env_keys()\n .iter()\n .any(|key| env_non_empty(key).is_some())\n}\n\nfn env_non_empty_with_store(\n key: &str,\n personal_env: &mut Option<Option<std::collections::HashMap<String, String>>>,\n) -> Option<String> {\n if let Some(value) = env_non_empty(key) {\n return Some(value);\n }\n if personal_env.is_none() {\n *personal_env = Some(flow_env::fetch_local_personal_env_vars(&telemetry_env_keys()).ok());\n }\n personal_env\n .as_ref()\n .and_then(|cached| cached.as_ref())\n .and_then(|values| values.get(key))\n .map(|value| value.trim().to_string())\n .filter(|value| !value.is_empty())\n}\n\nfn telemetry_state_path() -> Result<PathBuf> {\n let root = config::ensure_global_state_dir()?.join(\"codex\");\n fs::create_dir_all(&root)?;\n Ok(root.join(\"telemetry-export-state.json\"))\n}\n\nfn load_state() -> Result<CodexTelemetryExportState> {\n let path = telemetry_state_path()?;\n if !path.exists() {\n return Ok(CodexTelemetryExportState {\n version: 1,\n ..Default::default()\n });\n }\n let raw = fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n let mut state: CodexTelemetryExportState =\n serde_json::from_str(&raw).with_context(|| format!(\"failed to parse {}\", path.display()))?;\n if state.version == 0 {\n state.version = 1;\n }\n Ok(state)\n}\n\nfn save_state(state: &CodexTelemetryExportState) -> Result<()> {\n let path = telemetry_state_path()?;\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n fs::write(\n &path,\n serde_json::to_vec_pretty(state).context(\"failed to encode telemetry state\")?,\n )\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(())\n}\n\nfn parse_maple_exporter_config_from_env() -> Result<Option<MapleExporterConfig>> {\n let allow_store_fallback = !shell_has_explicit_maple_target_env();\n let mut personal_env = if allow_store_fallback {\n None\n } else {\n Some(None)\n };\n let mut targets = Vec::new();\n\n match (\n env_non_empty_with_store(\"FLOW_CODEX_MAPLE_LOCAL_ENDPOINT\", &mut personal_env),\n env_non_empty_with_store(\"FLOW_CODEX_MAPLE_LOCAL_INGEST_KEY\", &mut personal_env),\n ) {\n (Some(endpoint), Some(key)) => targets.push(MapleIngestTarget {\n traces_endpoint: endpoint,\n ingest_key: key,\n }),\n (None, None) => {}\n _ => anyhow::bail!(\"FLOW_CODEX_MAPLE_LOCAL_ENDPOINT and FLOW_CODEX_MAPLE_LOCAL_INGEST_KEY must both be set\"),\n }\n\n match (\n env_non_empty_with_store(\"FLOW_CODEX_MAPLE_HOSTED_ENDPOINT\", &mut personal_env),\n env_non_empty_with_store(\"FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY\", &mut personal_env),\n ) {\n (Some(endpoint), Some(key)) => targets.push(MapleIngestTarget {\n traces_endpoint: endpoint,\n ingest_key: key,\n }),\n (None, None) => {}\n _ => anyhow::bail!(\"FLOW_CODEX_MAPLE_HOSTED_ENDPOINT and FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY must both be set\"),\n }\n\n let csv_endpoints = env_non_empty_with_store(\"FLOW_CODEX_MAPLE_TRACES_ENDPOINTS\", &mut personal_env)\n .map(|raw| {\n raw.split(',')\n .map(|value| value.trim().to_string())\n .filter(|value| !value.is_empty())\n .collect::<Vec<_>>()\n })\n .unwrap_or_default();\n let csv_keys = env_non_empty_with_store(\"FLOW_CODEX_MAPLE_INGEST_KEYS\", &mut personal_env)\n .map(|raw| {\n raw.split(',')\n .map(|value| value.trim().to_string())\n .filter(|value| !value.is_empty())\n .collect::<Vec<_>>()\n })\n .unwrap_or_default();\n if !csv_endpoints.is_empty() || !csv_keys.is_empty() {\n if csv_endpoints.len() != csv_keys.len() {\n anyhow::bail!(\n \"FLOW_CODEX_MAPLE_TRACES_ENDPOINTS count ({}) does not match FLOW_CODEX_MAPLE_INGEST_KEYS count ({})\",\n csv_endpoints.len(),\n csv_keys.len()\n );\n }\n for (endpoint, key) in csv_endpoints.into_iter().zip(csv_keys.into_iter()) {\n targets.push(MapleIngestTarget {\n traces_endpoint: endpoint,\n ingest_key: key,\n });\n }\n }\n\n if targets.is_empty() {\n return Ok(None);\n }\n\n targets.dedup_by(|a, b| {\n a.traces_endpoint == b.traces_endpoint && a.ingest_key == b.ingest_key\n });\n\n Ok(Some(MapleExporterConfig {\n service_name: env_non_empty(\"FLOW_CODEX_MAPLE_SERVICE_NAME\")\n .unwrap_or_else(|| CODEX_MAPLE_DEFAULT_SERVICE_NAME.to_string()),\n service_version: env_non_empty(\"FLOW_CODEX_MAPLE_SERVICE_VERSION\"),\n deployment_environment: env_non_empty(\"FLOW_CODEX_MAPLE_ENV\")\n .unwrap_or_else(|| CODEX_MAPLE_DEFAULT_ENV.to_string()),\n scope_name: env_non_empty(\"FLOW_CODEX_MAPLE_SCOPE_NAME\")\n .unwrap_or_else(|| CODEX_MAPLE_DEFAULT_SCOPE_NAME.to_string()),\n queue_capacity: env_non_empty(\"FLOW_CODEX_MAPLE_QUEUE_CAPACITY\")\n .and_then(|value| value.parse::<usize>().ok())\n .unwrap_or(CODEX_MAPLE_DEFAULT_QUEUE_CAPACITY)\n .max(1),\n max_batch_size: env_non_empty(\"FLOW_CODEX_MAPLE_MAX_BATCH_SIZE\")\n .and_then(|value| value.parse::<usize>().ok())\n .unwrap_or(CODEX_MAPLE_DEFAULT_MAX_BATCH_SIZE)\n .max(1),\n flush_interval: std::time::Duration::from_millis(\n env_non_empty(\"FLOW_CODEX_MAPLE_FLUSH_INTERVAL_MS\")\n .and_then(|value| value.parse::<u64>().ok())\n .unwrap_or(CODEX_MAPLE_DEFAULT_FLUSH_INTERVAL_MS),\n ),\n connect_timeout: std::time::Duration::from_millis(\n env_non_empty(\"FLOW_CODEX_MAPLE_CONNECT_TIMEOUT_MS\")\n .and_then(|value| value.parse::<u64>().ok())\n .unwrap_or(CODEX_MAPLE_DEFAULT_CONNECT_TIMEOUT_MS),\n ),\n request_timeout: std::time::Duration::from_millis(\n env_non_empty(\"FLOW_CODEX_MAPLE_REQUEST_TIMEOUT_MS\")\n .and_then(|value| value.parse::<u64>().ok())\n .unwrap_or(CODEX_MAPLE_DEFAULT_REQUEST_TIMEOUT_MS),\n ),\n targets,\n }))\n}\n\nfn parse_maple_read_config_from_env() -> Result<Option<MapleReadConfig>> {\n let allow_store_fallback = env_non_empty(\"MAPLE_API_TOKEN\").is_none()\n && env_non_empty(\"FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY\").is_none();\n let mut personal_env = if allow_store_fallback {\n None\n } else {\n Some(None)\n };\n let shell_token = env_non_empty(\"MAPLE_API_TOKEN\")\n .map(|value| (value, \"shell\".to_string()))\n .or_else(|| {\n env_non_empty(\"FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY\")\n .map(|value| (value, \"shell-ingest-key\".to_string()))\n });\n let store_token = env_non_empty_with_store(\"MAPLE_API_TOKEN\", &mut personal_env)\n .map(|value| (value, \"flow-personal-env\".to_string()))\n .or_else(|| {\n env_non_empty_with_store(\"FLOW_CODEX_MAPLE_HOSTED_INGEST_KEY\", &mut personal_env)\n .map(|value| (value, \"flow-personal-ingest-key\".to_string()))\n });\n let token = shell_token.or(store_token);\n let endpoint = env_non_empty_with_store(\"MAPLE_MCP_URL\", &mut personal_env)\n .unwrap_or_else(|| DEFAULT_MAPLE_MCP_ENDPOINT.to_string());\n let Some((token, token_source)) = token else {\n return Ok(None);\n };\n Ok(Some(MapleReadConfig {\n endpoint,\n token,\n token_source,\n connect_timeout_ms: env_non_empty(\"FLOW_CODEX_MAPLE_CONNECT_TIMEOUT_MS\")\n .and_then(|value| value.parse::<u64>().ok())\n .unwrap_or(CODEX_MAPLE_DEFAULT_CONNECT_TIMEOUT_MS),\n request_timeout_ms: env_non_empty(\"FLOW_CODEX_MAPLE_REQUEST_TIMEOUT_MS\")\n .and_then(|value| value.parse::<u64>().ok())\n .unwrap_or(CODEX_MAPLE_DEFAULT_REQUEST_TIMEOUT_MS),\n }))\n}\n\nfn maple_json_rpc_request(\n config: &MapleReadConfig,\n method: &str,\n params: serde_json::Value,\n) -> Result<serde_json::Value> {\n let client = Client::builder()\n .connect_timeout(std::time::Duration::from_millis(config.connect_timeout_ms))\n .timeout(std::time::Duration::from_millis(config.request_timeout_ms))\n .build()\n .context(\"failed to build Maple MCP client\")?;\n let request = serde_json::json!({\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": method,\n \"params\": params,\n });\n let response = client\n .post(&config.endpoint)\n .bearer_auth(&config.token)\n .json(&request)\n .send()\n .with_context(|| format!(\"failed to reach Maple MCP at {}\", config.endpoint))?;\n let status = response.status();\n let payload: serde_json::Value = response\n .json()\n .context(\"failed to parse Maple MCP response JSON\")?;\n if !status.is_success() {\n anyhow::bail!(\n \"Maple MCP request failed ({}): {}\",\n status,\n serde_json::to_string(&payload).unwrap_or_else(|_| \"unparseable error body\".to_string())\n );\n }\n let envelope = if let Some(items) = payload.as_array() {\n items.first().cloned().unwrap_or(serde_json::Value::Null)\n } else {\n payload\n };\n if let Some(error) = envelope.get(\"error\") {\n let code = error\n .get(\"code\")\n .and_then(serde_json::Value::as_i64)\n .unwrap_or(-1);\n let message = error\n .get(\"message\")\n .and_then(serde_json::Value::as_str)\n .unwrap_or(\"unknown Maple MCP error\");\n anyhow::bail!(\"Maple MCP error {code}: {message}\");\n }\n envelope\n .get(\"result\")\n .cloned()\n .ok_or_else(|| anyhow::anyhow!(\"Maple MCP response did not include a result payload\"))\n}\n\nfn maple_tool_result_error(result: &serde_json::Value) -> Option<String> {\n if result.get(\"isError\").and_then(|value| value.as_bool()) != Some(true) {\n return None;\n }\n result\n .get(\"content\")\n .and_then(|value| value.as_array())\n .and_then(|items| items.first())\n .and_then(|item| item.get(\"text\"))\n .and_then(|value| value.as_str())\n .map(|value| value.trim().to_string())\n .filter(|value| !value.is_empty())\n .or_else(|| Some(\"Maple tool returned an unspecified error\".to_string()))\n}\n\nfn maple_call_tool(\n config: &MapleReadConfig,\n name: &str,\n arguments: serde_json::Value,\n) -> Result<serde_json::Value> {\n let result = maple_json_rpc_request(\n config,\n \"tools/call\",\n serde_json::json!({\n \"name\": name,\n \"arguments\": arguments,\n }),\n )?;\n if let Some(error) = maple_tool_result_error(&result) {\n anyhow::bail!(\"{error}\");\n }\n Ok(result)\n}\n\npub fn status() -> Result<CodexTelemetryStatus> {\n let config = parse_maple_exporter_config_from_env()?;\n let state = load_state()?;\n let state_path = telemetry_state_path()?;\n let events_path = codex_skill_eval::events_log_path()?;\n let outcomes_path = codex_skill_eval::outcomes_log_path()?;\n\n Ok(CodexTelemetryStatus {\n enabled: config.is_some(),\n configured_targets: config.as_ref().map(|value| value.targets.len()).unwrap_or(0),\n service_name: config\n .as_ref()\n .map(|value| value.service_name.clone())\n .unwrap_or_else(|| CODEX_MAPLE_DEFAULT_SERVICE_NAME.to_string()),\n scope_name: config\n .as_ref()\n .map(|value| value.scope_name.clone())\n .unwrap_or_else(|| CODEX_MAPLE_DEFAULT_SCOPE_NAME.to_string()),\n state_path: state_path.display().to_string(),\n events_path: events_path.display().to_string(),\n outcomes_path: outcomes_path.display().to_string(),\n events_offset: state.events_offset,\n outcomes_offset: state.outcomes_offset,\n events_exported: state.events_exported,\n outcomes_exported: state.outcomes_exported,\n last_exported_at_unix: state.last_exported_at_unix,\n })\n}\n\npub fn trace_status() -> Result<CodexTraceStatus> {\n let Some(config) = parse_maple_read_config_from_env()? else {\n return Ok(CodexTraceStatus {\n enabled: false,\n endpoint: DEFAULT_MAPLE_MCP_ENDPOINT.to_string(),\n token_source: \"missing\".to_string(),\n tools_list_ok: false,\n tools_count: 0,\n read_probe_ok: false,\n read_probe_error: Some(\"MAPLE_API_TOKEN is not configured\".to_string()),\n });\n };\n let list_result = maple_json_rpc_request(&config, \"tools/list\", serde_json::json!({}))?;\n let tools = list_result\n .get(\"tools\")\n .and_then(|value| value.as_array())\n .cloned()\n .unwrap_or_default();\n let read_probe = maple_json_rpc_request(\n &config,\n \"tools/call\",\n serde_json::json!({\n \"name\": \"system_health\",\n \"arguments\": {},\n }),\n );\n Ok(CodexTraceStatus {\n enabled: true,\n endpoint: config.endpoint,\n token_source: config.token_source,\n tools_list_ok: true,\n tools_count: tools.len(),\n read_probe_ok: read_probe\n .as_ref()\n .ok()\n .and_then(maple_tool_result_error)\n .is_none(),\n read_probe_error: match read_probe {\n Ok(value) => maple_tool_result_error(&value),\n Err(error) => Some(error.to_string()),\n },\n })\n}\n\npub fn inspect_trace(trace_id: &str, flush_first: bool) -> Result<CodexTraceInspectResult> {\n let Some(config) = parse_maple_read_config_from_env()? else {\n anyhow::bail!(\"MAPLE_API_TOKEN is not configured\");\n };\n let flushed = if flush_first {\n let _ = flush(64);\n true\n } else {\n false\n };\n let result = maple_call_tool(\n &config,\n \"inspect_trace\",\n serde_json::json!({\n \"trace_id\": trace_id,\n }),\n );\n let (result, read_error) = match result {\n Ok(result) => (Some(result), None),\n Err(error) => (None, Some(error.to_string())),\n };\n Ok(CodexTraceInspectResult {\n trace_id: trace_id.to_string(),\n endpoint: config.endpoint,\n token_source: config.token_source,\n flushed,\n result,\n read_error,\n })\n}\n\npub fn inspect_current_session_trace(flush_first: bool) -> Result<CodexCurrentSessionTrace> {\n let trace_id = env_non_empty(\"FLOW_TRACE_ID\").ok_or_else(|| {\n anyhow::anyhow!(\n \"FLOW_TRACE_ID is not set; start or resume the Codex session through Flow (`j`, `k`, or `f codex ...`)\"\n )\n })?;\n let span_id = env_non_empty(\"FLOW_SPAN_ID\");\n let parent_span_id = env_non_empty(\"FLOW_PARENT_SPAN_ID\");\n let workflow_kind = env_non_empty(\"FLOW_WORKFLOW_KIND\");\n let service_name = env_non_empty(\"FLOW_TRACE_SERVICE_NAME\");\n let inspected = inspect_trace(&trace_id, flush_first)?;\n Ok(CodexCurrentSessionTrace {\n trace_id,\n span_id,\n parent_span_id,\n workflow_kind,\n service_name,\n flushed: inspected.flushed,\n endpoint: inspected.endpoint,\n token_source: inspected.token_source,\n result: inspected.result,\n read_error: inspected.read_error,\n })\n}\n\nfn stable_hex_id(parts: &[&str], width: usize) -> String {\n let mut out = String::new();\n let needed = width.div_ceil(16);\n for seed in 0..needed {\n let mut hasher = DefaultHasher::new();\n seed.hash(&mut hasher);\n for part in parts {\n part.hash(&mut hasher);\n }\n out.push_str(&format!(\"{:016x}\", hasher.finish()));\n }\n out.truncate(width);\n out\n}\n\nfn redact_id(value: Option<&str>) -> String {\n value\n .filter(|candidate| !candidate.trim().is_empty())\n .map(|candidate| stable_hex_id(&[candidate], 16))\n .unwrap_or_else(|| \"none\".to_string())\n}\n\nfn repo_name(path: &str) -> String {\n Path::new(path)\n .file_name()\n .and_then(|value| value.to_str())\n .filter(|value| !value.is_empty())\n .unwrap_or(\"unknown\")\n .to_string()\n}\n\nfn path_hash(path: &str) -> String {\n stable_hex_id(&[path], 16)\n}\n\nfn artifact_name(path: Option<&str>) -> String {\n path.and_then(|value| Path::new(value).file_name())\n .and_then(|value| value.to_str())\n .filter(|value| !value.is_empty())\n .unwrap_or(\"none\")\n .to_string()\n}\n\nfn event_span(event: &CodexSkillEvalEvent) -> MapleSpan {\n let session_seed = event\n .session_id\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n .unwrap_or(event.target_path.as_str());\n let event_seed = format!(\n \"eval:{}:{}:{}:{}\",\n event.recorded_at_unix, event.mode, event.route, event.action\n );\n let start_time_unix_nano = event.recorded_at_unix.saturating_mul(1_000_000_000);\n let end_time_unix_nano = start_time_unix_nano.saturating_add(1_000_000);\n MapleSpan {\n trace_id: event\n .trace_id\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n .map(|value| value.to_string())\n .unwrap_or_else(|| stable_hex_id(&[session_seed], 32)),\n span_id: event\n .span_id\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n .map(|value| value.to_string())\n .unwrap_or_else(|| stable_hex_id(&[session_seed, &event_seed], 16)),\n parent_span_id: event.parent_span_id.clone().unwrap_or_default(),\n name: event\n .workflow_kind\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n .map(|value| format!(\"flow.codex.{value}\"))\n .unwrap_or_else(|| \"flow.codex.launch\".to_string()),\n kind: 1,\n start_time_unix_nano,\n end_time_unix_nano,\n status_code: 1,\n status_message: None,\n attributes: vec![\n (\"event.kind\".to_string(), \"codex_skill_eval\".to_string()),\n (\"mode\".to_string(), event.mode.clone()),\n (\"action\".to_string(), event.action.clone()),\n (\"route\".to_string(), event.route.clone()),\n (\"target.repo\".to_string(), repo_name(&event.target_path)),\n (\"target.path_hash\".to_string(), path_hash(&event.target_path)),\n (\"launch.path_hash\".to_string(), path_hash(&event.launch_path)),\n (\"session.hash\".to_string(), redact_id(event.session_id.as_deref())),\n (\n \"runtime.skill_count\".to_string(),\n event.runtime_skills.len().to_string(),\n ),\n (\n \"trace.workflow_kind\".to_string(),\n event\n .workflow_kind\n .clone()\n .unwrap_or_else(|| \"launch\".to_string()),\n ),\n (\n \"trace.service_name\".to_string(),\n event\n .service_name\n .clone()\n .unwrap_or_else(|| CODEX_MAPLE_DEFAULT_SERVICE_NAME.to_string()),\n ),\n (\n \"runtime.skills\".to_string(),\n if event.runtime_skills.is_empty() {\n \"none\".to_string()\n } else {\n event.runtime_skills.join(\",\")\n },\n ),\n (\n \"prompt.context_budget_chars\".to_string(),\n event.prompt_context_budget_chars.to_string(),\n ),\n (\"prompt.chars\".to_string(), event.prompt_chars.to_string()),\n (\n \"prompt.injected_context_chars\".to_string(),\n event.injected_context_chars.to_string(),\n ),\n (\n \"prompt.reference_count\".to_string(),\n event.reference_count.to_string(),\n ),\n ],\n }\n}\n\nfn outcome_span(outcome: &CodexSkillOutcomeEvent) -> MapleSpan {\n let target_seed = outcome\n .target_path\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n .unwrap_or(\"unknown-target\");\n let outcome_seed = format!(\n \"outcome:{}:{}:{:.3}\",\n outcome.recorded_at_unix, outcome.kind, outcome.success\n );\n let start_time_unix_nano = outcome.recorded_at_unix.saturating_mul(1_000_000_000);\n let end_time_unix_nano = start_time_unix_nano.saturating_add(1_000_000);\n MapleSpan {\n trace_id: outcome\n .trace_id\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n .map(|value| value.to_string())\n .unwrap_or_else(|| {\n stable_hex_id(\n &[outcome.session_id.as_deref().unwrap_or(target_seed), \"outcome\"],\n 32,\n )\n }),\n span_id: outcome\n .span_id\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n .map(|value| value.to_string())\n .unwrap_or_else(|| stable_hex_id(&[target_seed, &outcome_seed], 16)),\n parent_span_id: outcome.parent_span_id.clone().unwrap_or_default(),\n name: outcome\n .service_name\n .as_deref()\n .filter(|value| !value.trim().is_empty())\n .map(|_| \"flow.codex.outcome\".to_string())\n .unwrap_or_else(|| \"flow.codex.outcome\".to_string()),\n kind: 1,\n start_time_unix_nano,\n end_time_unix_nano,\n status_code: if outcome.success >= 0.5 { 1 } else { 2 },\n status_message: None,\n attributes: vec![\n (\"event.kind\".to_string(), \"codex_skill_outcome\".to_string()),\n (\"kind\".to_string(), outcome.kind.clone()),\n (\"success\".to_string(), format!(\"{:.3}\", outcome.success)),\n (\n \"skill_names\".to_string(),\n if outcome.skill_names.is_empty() {\n \"none\".to_string()\n } else {\n outcome.skill_names.join(\",\")\n },\n ),\n (\n \"session.hash\".to_string(),\n redact_id(outcome.session_id.as_deref()),\n ),\n (\n \"target.repo\".to_string(),\n outcome\n .target_path\n .as_deref()\n .map(repo_name)\n .unwrap_or_else(|| \"unknown\".to_string()),\n ),\n (\n \"target.path_hash\".to_string(),\n outcome\n .target_path\n .as_deref()\n .map(path_hash)\n .unwrap_or_else(|| \"none\".to_string()),\n ),\n (\n \"artifact.name\".to_string(),\n artifact_name(outcome.artifact_path.as_deref()),\n ),\n (\n \"artifact.hash\".to_string(),\n outcome\n .artifact_path\n .as_deref()\n .map(path_hash)\n .unwrap_or_else(|| \"none\".to_string()),\n ),\n (\n \"trace.service_name\".to_string(),\n outcome\n .service_name\n .clone()\n .unwrap_or_else(|| CODEX_MAPLE_DEFAULT_SERVICE_NAME.to_string()),\n ),\n ],\n }\n}\n\nfn export_lines<T, F, E>(\n path: &Path,\n offset: &mut u64,\n remaining: &mut usize,\n mut parse_line: F,\n mut emit: E,\n) -> Result<(usize, usize)>\nwhere\n F: FnMut(&str) -> Option<T>,\n E: FnMut(T),\n{\n if *remaining == 0 || !path.exists() {\n return Ok((0, 0));\n }\n let metadata =\n fs::metadata(path).with_context(|| format!(\"failed to stat {}\", path.display()))?;\n if *offset > metadata.len() {\n *offset = 0;\n }\n\n let mut file =\n File::open(path).with_context(|| format!(\"failed to open {}\", path.display()))?;\n file.seek(SeekFrom::Start(*offset))\n .with_context(|| format!(\"failed to seek {}\", path.display()))?;\n let mut reader = BufReader::new(file);\n let mut line = String::new();\n let mut seen = 0usize;\n let mut exported = 0usize;\n\n while *remaining > 0 {\n line.clear();\n let bytes = reader\n .read_line(&mut line)\n .with_context(|| format!(\"failed reading {}\", path.display()))?;\n if bytes == 0 {\n break;\n }\n *offset = (*offset).saturating_add(bytes as u64);\n let trimmed = line.trim();\n if trimmed.is_empty() {\n continue;\n }\n seen += 1;\n if let Some(item) = parse_line(trimmed) {\n emit(item);\n exported += 1;\n }\n *remaining = remaining.saturating_sub(1);\n }\n\n Ok((seen, exported))\n}\n\npub fn flush(limit: usize) -> Result<CodexTelemetryFlushSummary> {\n let config = parse_maple_exporter_config_from_env()?;\n let state_path = telemetry_state_path()?;\n let Some(config) = config else {\n return Ok(CodexTelemetryFlushSummary {\n enabled: false,\n configured_targets: 0,\n events_seen: 0,\n outcomes_seen: 0,\n events_exported: 0,\n outcomes_exported: 0,\n state_path: state_path.display().to_string(),\n last_exported_at_unix: None,\n });\n };\n\n let exporter = MapleTraceExporter::new(config.clone());\n let mut state = load_state()?;\n let events_path = codex_skill_eval::events_log_path()?;\n let outcomes_path = codex_skill_eval::outcomes_log_path()?;\n let mut remaining = limit.max(1);\n\n let (events_seen, events_exported) = export_lines(\n &events_path,\n &mut state.events_offset,\n &mut remaining,\n |line| serde_json::from_str::<CodexSkillEvalEvent>(line).ok(),\n |event| exporter.emit_span(event_span(&event)),\n )?;\n let (outcomes_seen, outcomes_exported) = export_lines(\n &outcomes_path,\n &mut state.outcomes_offset,\n &mut remaining,\n |line| serde_json::from_str::<CodexSkillOutcomeEvent>(line).ok(),\n |outcome| exporter.emit_span(outcome_span(&outcome)),\n )?;\n\n if events_seen > 0 || outcomes_seen > 0 {\n state.version = 1;\n state.events_exported = state.events_exported.saturating_add(events_exported as u64);\n state.outcomes_exported = state\n .outcomes_exported\n .saturating_add(outcomes_exported as u64);\n if events_exported > 0 || outcomes_exported > 0 {\n state.last_exported_at_unix = Some(unix_now());\n }\n save_state(&state)?;\n }\n\n Ok(CodexTelemetryFlushSummary {\n enabled: true,\n configured_targets: config.targets.len(),\n events_seen,\n outcomes_seen,\n events_exported,\n outcomes_exported,\n state_path: state_path.display().to_string(),\n last_exported_at_unix: state.last_exported_at_unix,\n })\n}\n\npub fn maybe_flush(limit: usize) -> Result<usize> {\n let summary = flush(limit)?;\n Ok(summary.events_exported + summary.outcomes_exported)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn repo_name_uses_leaf_directory() {\n assert_eq!(repo_name(\"/Users/test/code/flow\"), \"flow\");\n assert_eq!(repo_name(\"flow\"), \"flow\");\n }\n\n #[test]\n fn redact_id_is_stable_and_short() {\n let first = redact_id(Some(\"session-123\"));\n let second = redact_id(Some(\"session-123\"));\n assert_eq!(first, second);\n assert_eq!(first.len(), 16);\n }\n}\n" }, { "path": "src/codex_text.rs", "content": "fn strip_tagged_block(text: &str, open_tag: &str, close_tag: &str) -> String {\n let mut result = text.to_string();\n while let Some(start) = result.find(open_tag) {\n if let Some(end) = result[start..].find(close_tag) {\n let end_pos = start + end + close_tag.len();\n result = format!(\"{}{}\", &result[..start], &result[end_pos..]);\n } else {\n result = result[..start].to_string();\n break;\n }\n }\n result\n}\n\nfn strip_system_reminders(text: &str) -> String {\n strip_tagged_block(text, \"<system-reminder>\", \"</system-reminder>\")\n .trim()\n .to_string()\n}\n\nfn strip_agents_instruction_block(text: &str) -> String {\n let mut result = text.to_string();\n loop {\n let agents_start = result\n .find(\"# AGENTS.md instructions for \")\n .or_else(|| result.find(\"# agents.md instructions for \"));\n let Some(start) = agents_start else {\n break;\n };\n\n if let Some(end) = result[start..].find(\"</INSTRUCTIONS>\") {\n let end_pos = start + end + \"</INSTRUCTIONS>\".len();\n result = format!(\"{}{}\", &result[..start], &result[end_pos..]);\n } else {\n result = result[..start].to_string();\n break;\n }\n }\n result\n}\n\nfn truncate_before_heading(text: &str, heading: &str) -> String {\n let mut offset = 0usize;\n for line in text.lines() {\n if line.trim_start().starts_with(heading) {\n return text[..offset].trim().to_string();\n }\n offset += line.len();\n if offset < text.len() {\n offset += 1;\n }\n }\n text.trim().to_string()\n}\n\nfn collapse_blank_lines(text: &str) -> String {\n let mut out = String::new();\n let mut saw_blank = false;\n\n for line in text.lines() {\n let trimmed = line.trim_end();\n if trimmed.trim().is_empty() {\n if saw_blank || out.is_empty() {\n continue;\n }\n saw_blank = true;\n out.push('\\n');\n continue;\n }\n\n if !out.is_empty() && !out.ends_with('\\n') {\n out.push('\\n');\n }\n out.push_str(trimmed);\n out.push('\\n');\n saw_blank = false;\n }\n\n out.trim().to_string()\n}\n\npub(crate) fn sanitize_codex_memory_rollout_text(text: &str) -> Option<String> {\n let mut cleaned = strip_system_reminders(text);\n cleaned = strip_agents_instruction_block(&cleaned);\n cleaned = strip_tagged_block(&cleaned, \"<skill>\", \"</skill>\");\n cleaned = collapse_blank_lines(&cleaned);\n\n let trimmed = cleaned.trim();\n if trimmed.is_empty() {\n return None;\n }\n Some(trimmed.to_string())\n}\n\npub(crate) fn sanitize_codex_query_text(text: &str) -> Option<String> {\n let mut cleaned = sanitize_codex_memory_rollout_text(text)?;\n cleaned = strip_tagged_block(&cleaned, \"<environment_context>\", \"</environment_context>\");\n cleaned = strip_tagged_block(\n &cleaned,\n \"<permissions instructions>\",\n \"</permissions instructions>\",\n );\n cleaned = strip_tagged_block(&cleaned, \"<collaboration_mode>\", \"</collaboration_mode>\");\n cleaned = strip_tagged_block(\n &cleaned,\n \"<subagent_notification>\",\n \"</subagent_notification>\",\n );\n cleaned = truncate_before_heading(&cleaned, \"Workflow context:\");\n cleaned = truncate_before_heading(&cleaned, \"Start by checking:\");\n cleaned = truncate_before_heading(&cleaned, \"Designer stack notes:\");\n cleaned = collapse_blank_lines(&cleaned);\n\n let trimmed = cleaned.trim();\n if trimmed.is_empty()\n || trimmed.starts_with(\"<environment_context>\")\n || trimmed.starts_with(\"<INSTRUCTIONS>\")\n || trimmed.starts_with(\"# AGENTS.md instructions\")\n || trimmed.starts_with(\"# agents.md instructions\")\n {\n return None;\n }\n Some(trimmed.to_string())\n}\n\n#[cfg(test)]\nmod tests {\n use super::{sanitize_codex_memory_rollout_text, sanitize_codex_query_text};\n\n #[test]\n fn rollout_sanitizer_drops_agents_and_skills_but_keeps_environment() {\n let text = concat!(\n \"# AGENTS.md instructions for /tmp\\n\\n\",\n \"<INSTRUCTIONS>\\nbody\\n</INSTRUCTIONS>\\n\",\n \"<environment_context>\\n<cwd>/tmp</cwd>\\n</environment_context>\\n\",\n \"<skill>\\n<name>demo</name>\\nbody\\n</skill>\\n\",\n \"<subagent_notification>{\\\"agent_id\\\":\\\"a\\\",\\\"status\\\":\\\"completed\\\"}</subagent_notification>\\n\"\n );\n\n let cleaned = sanitize_codex_memory_rollout_text(text).expect(\"cleaned\");\n assert!(!cleaned.contains(\"AGENTS.md\"));\n assert!(!cleaned.contains(\"<skill>\"));\n assert!(cleaned.contains(\"<environment_context>\"));\n assert!(cleaned.contains(\"<subagent_notification>\"));\n }\n\n #[test]\n fn query_sanitizer_keeps_only_real_user_intent() {\n let text = concat!(\n \"# AGENTS.md instructions for /tmp\\n\\n\",\n \"<INSTRUCTIONS>\\nbody\\n</INSTRUCTIONS>\\n\",\n \"<environment_context>\\n<cwd>/tmp</cwd>\\n</environment_context>\\n\",\n \"write plan for rollout\\n\\n\",\n \"Workflow context:\\n- Repo: ~/code/example\\n\"\n );\n\n assert_eq!(\n sanitize_codex_query_text(text).as_deref(),\n Some(\"write plan for rollout\")\n );\n }\n\n #[test]\n fn query_sanitizer_drops_context_only_messages() {\n let text = concat!(\n \"# AGENTS.md instructions for /tmp\\n\\n\",\n \"<INSTRUCTIONS>\\nbody\\n</INSTRUCTIONS>\\n\",\n \"<environment_context>\\n<cwd>/tmp</cwd>\\n</environment_context>\\n\"\n );\n\n assert_eq!(sanitize_codex_query_text(text), None);\n }\n}\n" }, { "path": "src/codexd.rs", "content": "use std::fs::{self, OpenOptions};\nuse std::io::{BufRead, BufReader, Write};\n#[cfg(unix)]\nuse std::os::fd::AsRawFd;\nuse std::os::unix::net::{UnixListener, UnixStream};\nuse std::path::{Path, PathBuf};\nuse std::thread;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result, bail};\nuse serde::{Deserialize, Serialize};\n\nuse crate::{ai, config, daemon, supervisor};\n\nconst CODEXD_NAME: &str = \"codexd\";\n\n#[cfg(unix)]\n#[derive(Debug)]\nstruct FileLockGuard {\n fd: std::os::fd::RawFd,\n}\n\n#[cfg(unix)]\nimpl Drop for FileLockGuard {\n fn drop(&mut self) {\n let _ = unsafe { libc::flock(self.fd, libc::LOCK_UN) };\n }\n}\n\n#[derive(Debug, Serialize, Deserialize)]\n#[serde(tag = \"type\", rename_all = \"snake_case\")]\nenum CodexdRequest {\n Ping,\n Recent {\n target_path: String,\n exact_cwd: bool,\n limit: usize,\n query: Option<String>,\n },\n SessionHint {\n session_hint: String,\n limit: usize,\n },\n Find {\n target_path: Option<String>,\n exact_cwd: bool,\n query: String,\n limit: usize,\n },\n}\n\n#[derive(Debug, Serialize, Deserialize)]\nstruct CodexdResponse {\n ok: bool,\n message: Option<String>,\n #[serde(default)]\n rows: Vec<ai::CodexRecoverRow>,\n}\n\npub fn builtin_daemon_config() -> Result<config::DaemonConfig> {\n let exe = std::env::current_exe().context(\"failed to resolve current executable for codexd\")?;\n Ok(config::DaemonConfig {\n name: CODEXD_NAME.to_string(),\n binary: exe.display().to_string(),\n command: Some(\"codex\".to_string()),\n args: vec![\n \"daemon\".to_string(),\n \"serve\".to_string(),\n \"--socket\".to_string(),\n socket_path()?.display().to_string(),\n ],\n health_url: None,\n health_socket: Some(socket_path()?.display().to_string()),\n port: None,\n host: None,\n working_dir: None,\n env: Default::default(),\n autostart: false,\n autostop: false,\n boot: false,\n restart: Some(config::DaemonRestartPolicy::Always),\n retry: None,\n ready_delay: Some(100),\n ready_output: None,\n description: Some(\"Flow-managed Codex query daemon\".to_string()),\n })\n}\n\npub fn socket_path() -> Result<PathBuf> {\n Ok(config::ensure_global_state_dir()?.join(\"codexd.sock\"))\n}\n\nfn lock_path() -> Result<PathBuf> {\n Ok(config::ensure_global_state_dir()?.join(\"codexd.lock\"))\n}\n\n#[cfg(unix)]\nfn acquire_process_lock(file: &std::fs::File) -> Result<FileLockGuard> {\n let fd = file.as_raw_fd();\n let status = unsafe { libc::flock(fd, libc::LOCK_EX | libc::LOCK_NB) };\n if status == 0 {\n return Ok(FileLockGuard { fd });\n }\n let err = std::io::Error::last_os_error();\n let raw = err.raw_os_error();\n if raw == Some(libc::EWOULDBLOCK) || raw == Some(libc::EAGAIN) {\n bail!(\"codexd already holds {}\", lock_path()?.display());\n }\n Err(err).context(\"failed to lock codexd process lock\")\n}\n\n#[cfg(not(unix))]\nfn acquire_process_lock(_file: &std::fs::File) -> Result<()> {\n Ok(())\n}\n\npub fn ping() -> Result<()> {\n let response = send_request(&CodexdRequest::Ping)?;\n if response.ok {\n Ok(())\n } else {\n bail!(\n \"{}\",\n response\n .message\n .unwrap_or_else(|| \"codexd ping failed\".to_string())\n )\n }\n}\n\npub fn is_running() -> bool {\n ping().is_ok()\n}\n\npub fn ensure_running() -> Result<()> {\n if is_running() {\n return Ok(());\n }\n supervisor::ensure_daemon_running(CODEXD_NAME, None, false)\n}\n\npub fn start() -> Result<()> {\n supervisor::ensure_daemon_running(CODEXD_NAME, None, true)\n}\n\npub fn stop() -> Result<()> {\n supervisor::stop_daemon_managed(CODEXD_NAME, None, true)\n}\n\npub fn status() -> Result<()> {\n daemon::show_status_for_with_path(CODEXD_NAME, None)\n}\n\npub fn serve(socket_override: Option<&Path>) -> Result<()> {\n let socket = socket_override.map(PathBuf::from).unwrap_or(socket_path()?);\n if let Some(parent) = socket.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n let lock_path = lock_path()?;\n let mut lock_file = OpenOptions::new()\n .create(true)\n .read(true)\n .write(true)\n .open(&lock_path)\n .with_context(|| format!(\"failed to open {}\", lock_path.display()))?;\n let _process_lock = acquire_process_lock(&lock_file)?;\n lock_file\n .set_len(0)\n .with_context(|| format!(\"failed to reset {}\", lock_path.display()))?;\n writeln!(lock_file, \"{}\", std::process::id())\n .with_context(|| format!(\"failed to write {}\", lock_path.display()))?;\n lock_file\n .flush()\n .with_context(|| format!(\"failed to flush {}\", lock_path.display()))?;\n if socket.exists() {\n fs::remove_file(&socket)\n .with_context(|| format!(\"failed to remove stale socket {}\", socket.display()))?;\n }\n\n let listener = UnixListener::bind(&socket)\n .with_context(|| format!(\"failed to bind codexd socket {}\", socket.display()))?;\n\n start_background_maintenance_loop();\n\n loop {\n let (stream, _) = match listener.accept() {\n Ok(stream) => stream,\n Err(err) => {\n eprintln!(\"WARN codexd accept failed: {err}\");\n continue;\n }\n };\n if let Err(err) = handle_client(stream) {\n eprintln!(\"WARN codexd request failed: {err:#}\");\n }\n }\n}\n\nfn background_poll_secs() -> u64 {\n std::env::var(\"FLOW_CODEXD_BACKGROUND_POLL_SECS\")\n .ok()\n .and_then(|value| value.parse::<u64>().ok())\n .map(|value| value.clamp(5, 300))\n .unwrap_or(20)\n}\n\nfn start_background_maintenance_loop() {\n let poll_secs = background_poll_secs();\n let _ = thread::Builder::new()\n .name(\"flow-codexd-maint\".to_string())\n .spawn(move || {\n loop {\n if let Err(err) = ai::run_codex_background_maintenance() {\n eprintln!(\"WARN codexd maintenance failed: {err:#}\");\n }\n if let Err(err) = ai::maybe_run_codex_learning_refresh() {\n eprintln!(\"WARN codexd learning refresh failed: {err:#}\");\n }\n if let Err(err) = ai::maybe_run_codex_telemetry_export(200) {\n eprintln!(\"WARN codexd telemetry export failed: {err:#}\");\n }\n thread::sleep(Duration::from_secs(poll_secs));\n }\n });\n}\n\npub(crate) fn query_recent(\n target_path: &Path,\n exact_cwd: bool,\n limit: usize,\n query: Option<&str>,\n) -> Result<Vec<ai::CodexRecoverRow>> {\n ensure_running()?;\n let response = send_request(&CodexdRequest::Recent {\n target_path: target_path.display().to_string(),\n exact_cwd,\n limit,\n query: query.map(str::to_string),\n })?;\n if response.ok {\n Ok(response.rows)\n } else {\n bail!(\n \"{}\",\n response\n .message\n .unwrap_or_else(|| \"codexd recent query failed\".to_string())\n )\n }\n}\n\npub(crate) fn query_session_hint(\n session_hint: &str,\n limit: usize,\n) -> Result<Vec<ai::CodexRecoverRow>> {\n ensure_running()?;\n let response = send_request(&CodexdRequest::SessionHint {\n session_hint: session_hint.to_string(),\n limit,\n })?;\n if response.ok {\n Ok(response.rows)\n } else {\n bail!(\n \"{}\",\n response\n .message\n .unwrap_or_else(|| \"codexd session hint query failed\".to_string())\n )\n }\n}\n\npub(crate) fn query_find(\n target_path: Option<&Path>,\n exact_cwd: bool,\n query: &str,\n limit: usize,\n) -> Result<Vec<ai::CodexRecoverRow>> {\n ensure_running()?;\n let response = send_request(&CodexdRequest::Find {\n target_path: target_path.map(|path| path.display().to_string()),\n exact_cwd,\n query: query.to_string(),\n limit,\n })?;\n if response.ok {\n Ok(response.rows)\n } else {\n bail!(\n \"{}\",\n response\n .message\n .unwrap_or_else(|| \"codexd find query failed\".to_string())\n )\n }\n}\n\nfn send_request(request: &CodexdRequest) -> Result<CodexdResponse> {\n let mut stream =\n UnixStream::connect(socket_path()?).context(\"failed to connect to codexd socket\")?;\n let payload = serde_json::to_string(request).context(\"failed to encode codexd request\")?;\n stream\n .write_all(payload.as_bytes())\n .context(\"failed to write codexd request\")?;\n stream\n .write_all(b\"\\n\")\n .context(\"failed to terminate codexd request\")?;\n stream.flush().context(\"failed to flush codexd request\")?;\n\n let mut reader = BufReader::new(stream);\n let mut line = Vec::with_capacity(1024);\n reader\n .read_until(b'\\n', &mut line)\n .context(\"failed to read codexd response\")?;\n let trimmed = trim_ascii_whitespace(&line);\n if trimmed.is_empty() {\n bail!(\"codexd returned an empty response\");\n }\n serde_json::from_slice(trimmed).context(\"failed to decode codexd response\")\n}\n\nfn handle_client(stream: UnixStream) -> Result<()> {\n let mut reader = BufReader::new(&stream);\n let mut line = Vec::with_capacity(1024);\n reader.read_until(b'\\n', &mut line)?;\n let trimmed = trim_ascii_whitespace(&line);\n if trimmed.is_empty() {\n return Ok(());\n }\n\n let request: CodexdRequest =\n serde_json::from_slice(trimmed).context(\"failed to decode codexd request\")?;\n let response = handle_request(request);\n\n let mut writer = &stream;\n let payload = serde_json::to_string(&response).context(\"failed to encode codexd response\")?;\n writer.write_all(payload.as_bytes())?;\n writer.write_all(b\"\\n\")?;\n writer.flush()?;\n Ok(())\n}\n\nfn handle_request(request: CodexdRequest) -> CodexdResponse {\n match request {\n CodexdRequest::Ping => CodexdResponse {\n ok: true,\n message: Some(\"pong\".to_string()),\n rows: vec![],\n },\n CodexdRequest::Recent {\n target_path,\n exact_cwd,\n limit,\n query,\n } => match ai::read_recent_codex_threads_local(\n Path::new(&target_path),\n exact_cwd,\n limit,\n query.as_deref(),\n ) {\n Ok(rows) => CodexdResponse {\n ok: true,\n message: None,\n rows,\n },\n Err(err) => CodexdResponse {\n ok: false,\n message: Some(format!(\"{err:#}\")),\n rows: vec![],\n },\n },\n CodexdRequest::SessionHint {\n session_hint,\n limit,\n } => match ai::read_codex_threads_by_session_hint_local(&session_hint, limit) {\n Ok(rows) => CodexdResponse {\n ok: true,\n message: None,\n rows,\n },\n Err(err) => CodexdResponse {\n ok: false,\n message: Some(format!(\"{err:#}\")),\n rows: vec![],\n },\n },\n CodexdRequest::Find {\n target_path,\n exact_cwd,\n query,\n limit,\n } => match ai::search_codex_threads_for_find_local(\n target_path.as_deref().map(Path::new),\n exact_cwd,\n &query,\n limit,\n ) {\n Ok(rows) => CodexdResponse {\n ok: true,\n message: None,\n rows,\n },\n Err(err) => CodexdResponse {\n ok: false,\n message: Some(format!(\"{err:#}\")),\n rows: vec![],\n },\n },\n }\n}\n\n#[inline]\nfn trim_ascii_whitespace(bytes: &[u8]) -> &[u8] {\n let mut start = 0usize;\n let mut end = bytes.len();\n while start < end && bytes[start].is_ascii_whitespace() {\n start += 1;\n }\n while end > start && bytes[end - 1].is_ascii_whitespace() {\n end -= 1;\n }\n &bytes[start..end]\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use tempfile::tempdir;\n\n #[test]\n fn builtin_daemon_config_uses_socket_health() {\n let cfg = builtin_daemon_config().expect(\"builtin codexd config\");\n let socket = socket_path().expect(\"codexd socket\");\n\n assert_eq!(cfg.name, CODEXD_NAME);\n assert_eq!(cfg.command.as_deref(), Some(\"codex\"));\n assert_eq!(\n cfg.effective_health_socket().as_deref(),\n Some(socket.as_path())\n );\n let expected_label = format!(\"unix:{}\", socket.display());\n assert_eq!(\n cfg.health_target_label().as_deref(),\n Some(expected_label.as_str())\n );\n assert!(\n cfg.args\n .windows(2)\n .any(|window| window == [\"daemon\", \"serve\"])\n );\n }\n\n #[cfg(unix)]\n #[test]\n fn process_lock_rejects_second_holder() {\n let temp = tempdir().expect(\"tempdir\");\n let path = temp.path().join(\"codexd.lock\");\n let first = OpenOptions::new()\n .create(true)\n .read(true)\n .write(true)\n .open(&path)\n .expect(\"first lock file\");\n let _guard = acquire_process_lock(&first).expect(\"first lock\");\n\n let second = OpenOptions::new()\n .create(true)\n .read(true)\n .write(true)\n .open(&path)\n .expect(\"second lock file\");\n let err = acquire_process_lock(&second).expect_err(\"second lock should fail\");\n assert!(format!(\"{err:#}\").contains(\"codexd already holds\"));\n }\n}\n" }, { "path": "src/commit.rs", "content": "//! AI-powered git commit command using OpenAI.\n\nuse std::cell::RefCell;\nuse std::collections::{HashMap, HashSet, hash_map::DefaultHasher};\nuse std::env;\nuse std::fs;\nuse std::hash::{Hash, Hasher};\nuse std::io::{self, IsTerminal, Read, Seek, SeekFrom, Write};\nuse std::net::IpAddr;\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\nuse std::time::{Duration, Instant};\n\nuse anyhow::{Context, Result, anyhow, bail};\nuse clap::ValueEnum;\nuse flow_commit_scan::scan_diff_for_secrets;\nuse regex::Regex;\nuse reqwest::StatusCode;\nuse reqwest::blocking::Client;\nuse serde::de::DeserializeOwned;\nuse serde::{Deserialize, Serialize};\nuse serde_json::json;\nuse sha1::{Digest, Sha1};\nuse tempfile::{Builder as TempBuilder, NamedTempFile, TempDir};\nuse tracing::{debug, info};\nuse uuid::Uuid;\n\nuse crate::ai;\nuse crate::cli::{CommitQueueAction, CommitQueueCommand, DaemonAction, PrOpts};\nuse crate::config;\nuse crate::daemon;\nuse crate::env as flow_env;\nuse crate::features;\nuse crate::git_guard;\nuse crate::gitignore_policy;\nuse crate::hub;\nuse crate::notify;\nuse crate::setup;\nuse crate::skills;\nuse crate::supervisor;\nuse crate::todo;\nuse crate::undo;\nuse crate::vcs;\n\nconst MODEL: &str = \"gpt-4.1-nano\";\nconst MAX_DIFF_CHARS: usize = 12_000;\nconst HUB_HOST: IpAddr = IpAddr::V4(std::net::Ipv4Addr::new(127, 0, 0, 1));\nconst HUB_PORT: u16 = 9050;\nconst DEFAULT_OPENROUTER_REVIEW_MODEL: &str = \"arcee-ai/trinity-large-preview:free\";\nconst DEFAULT_OPENCODE_MODEL: &str = \"opencode/minimax-m2.1-free\";\nconst DEFAULT_RISE_MODEL: &str = \"zai:glm-4.7\";\nconst DEFAULT_GLM5_RISE_MODEL: &str = \"zai:glm-5\";\n\n/// Patterns for files that likely contain secrets and shouldn't be committed.\nconst SENSITIVE_PATTERNS: &[&str] = &[\n \".env\",\n \".env.local\",\n \".env.production\",\n \".env.development\",\n \".env.staging\",\n \".env.host\",\n \"credentials.json\",\n \"secrets.json\",\n \"service-account.json\",\n \".pem\",\n \".key\",\n \".p12\",\n \".pfx\",\n \".keystore\",\n \"id_rsa\",\n \"id_ed25519\",\n \"id_ecdsa\",\n \"id_dsa\",\n \".npmrc\",\n \".pypirc\",\n \".netrc\",\n \"htpasswd\",\n \".htpasswd\",\n \"shadow\",\n \"passwd\",\n];\n\nconst SYSTEM_PROMPT: &str = \"You are an expert software engineer who writes clear, concise git commit messages. Use imperative mood, keep the subject line under 72 characters, and include an optional body with bullet points if helpful. Never wrap the message in quotes. Never include secrets, credentials, or file contents from .env files, environment variables, keys, or other sensitive data—even if they appear in the diff.\";\n\n#[derive(Copy, Clone, Debug, ValueEnum)]\npub enum ReviewModelArg {\n /// Use Claude Opus 1 for review.\n ClaudeOpus,\n /// Use Codex high-capacity review (gpt-5.1-codex-max).\n CodexHigh,\n /// Use Codex mini review model (gpt-5.1-codex-mini).\n CodexMini,\n}\n\n#[derive(Copy, Clone, Debug)]\npub struct CommitQueueMode {\n pub enabled: bool,\n pub override_flag: Option<bool>,\n pub open_review: bool,\n}\n\nimpl CommitQueueMode {\n pub fn with_open_review(mut self, open_review: bool) -> Self {\n self.open_review = open_review;\n self\n }\n}\n\n#[derive(Copy, Clone, Debug, Default)]\npub struct CommitGateOverrides {\n pub skip_quality: bool,\n pub skip_docs: bool,\n pub skip_tests: bool,\n}\n\n#[derive(Clone, Debug)]\nstruct CommitTestingPolicy {\n mode: String,\n runner: String,\n bun_repo_strict: bool,\n require_related_tests: bool,\n ai_scratch_test_dir: String,\n run_ai_scratch_tests: bool,\n allow_ai_scratch_to_satisfy_gate: bool,\n max_local_gate_seconds: u64,\n}\n\n#[derive(Clone, Debug, Default)]\nstruct CommitSkillGatePolicy {\n mode: String,\n required: Vec<String>,\n min_version: HashMap<String, u32>,\n}\n\n#[derive(Clone, Debug, Default)]\nstruct SkillGateReport {\n pass: bool,\n mode: String,\n override_flag: Option<String>,\n required_skills: Vec<String>,\n missing_skills: Vec<String>,\n version_failures: Vec<String>,\n loaded_versions: HashMap<String, u32>,\n}\n\nimpl ReviewModelArg {\n fn as_arg(&self) -> &'static str {\n match self {\n ReviewModelArg::ClaudeOpus => \"claude-opus\",\n ReviewModelArg::CodexHigh => \"codex-high\",\n ReviewModelArg::CodexMini => \"codex-mini\",\n }\n }\n}\n\n#[derive(Copy, Clone, Debug)]\npub enum CodexModel {\n High,\n Mini,\n}\n\nimpl CodexModel {\n fn as_codex_arg(&self) -> &'static str {\n match self {\n CodexModel::High => \"gpt-5.1-codex-max\",\n CodexModel::Mini => \"gpt-5.1-codex-mini\",\n }\n }\n}\n\n#[derive(Copy, Clone, Debug)]\npub enum ClaudeModel {\n Sonnet,\n Opus,\n}\n\nimpl ClaudeModel {\n fn as_claude_arg(&self) -> &'static str {\n match self {\n ClaudeModel::Sonnet => \"claude-sonnet-4-20250514\",\n ClaudeModel::Opus => \"claude-opus-1\",\n }\n }\n}\n\n#[derive(Clone, Debug)]\npub enum ReviewSelection {\n Codex(CodexModel),\n Claude(ClaudeModel),\n Opencode { model: String },\n Rise { model: String },\n Kimi { model: Option<String> },\n OpenRouter { model: String },\n}\n\nimpl ReviewSelection {\n fn is_codex(&self) -> bool {\n matches!(self, ReviewSelection::Codex(_))\n }\n\n fn is_openrouter(&self) -> bool {\n matches!(self, ReviewSelection::OpenRouter { .. })\n }\n\n fn review_model_arg(&self) -> Option<ReviewModelArg> {\n match self {\n ReviewSelection::Codex(CodexModel::High) => Some(ReviewModelArg::CodexHigh),\n ReviewSelection::Codex(CodexModel::Mini) => Some(ReviewModelArg::CodexMini),\n ReviewSelection::Claude(ClaudeModel::Opus) => Some(ReviewModelArg::ClaudeOpus),\n ReviewSelection::Claude(ClaudeModel::Sonnet) => None,\n ReviewSelection::Opencode { .. } => None,\n ReviewSelection::Rise { .. } => None,\n ReviewSelection::Kimi { .. } => None,\n ReviewSelection::OpenRouter { .. } => None,\n }\n }\n\n fn model_label(&self) -> String {\n match self {\n ReviewSelection::Codex(model) => model.as_codex_arg().to_string(),\n ReviewSelection::Claude(model) => model.as_claude_arg().to_string(),\n ReviewSelection::Opencode { model } => model.clone(),\n ReviewSelection::Rise { model } => format!(\"rise:{}\", model),\n ReviewSelection::Kimi { model } => match model.as_deref() {\n Some(model) if !model.trim().is_empty() => format!(\"kimi:{}\", model),\n _ => \"kimi\".to_string(),\n },\n ReviewSelection::OpenRouter { model } => openrouter_model_label(model),\n }\n }\n}\n\nfn review_tool_label(selection: &ReviewSelection) -> &'static str {\n match selection {\n ReviewSelection::Claude(_) => \"Claude\",\n ReviewSelection::Codex(_) => \"Codex\",\n ReviewSelection::Opencode { .. } => \"opencode\",\n ReviewSelection::OpenRouter { .. } => \"OpenRouter\",\n ReviewSelection::Rise { .. } => \"Rise AI\",\n ReviewSelection::Kimi { .. } => \"Kimi\",\n }\n}\n\n/// Check staged files for potentially sensitive content and warn the user.\n/// Returns list of sensitive files found.\nfn check_sensitive_files(repo_root: &Path) -> Vec<String> {\n let output = Command::new(\"git\")\n .args([\"diff\", \"--cached\", \"--name-only\"])\n .current_dir(repo_root)\n .output();\n\n let Ok(output) = output else {\n return Vec::new();\n };\n\n if !output.status.success() {\n return Vec::new();\n }\n\n let files = String::from_utf8_lossy(&output.stdout);\n let mut sensitive = Vec::new();\n\n for file in files.lines() {\n let file_lower = file.to_lowercase();\n let file_name = Path::new(file)\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(file)\n .to_lowercase();\n\n // Check for .env files, but allow .env.example and .env.sample (safe templates)\n if file_name.starts_with(\".env\") {\n if file_name.ends_with(\".example\") || file_name.ends_with(\".sample\") {\n continue;\n }\n sensitive.push(file.to_string());\n continue;\n }\n\n for pattern in SENSITIVE_PATTERNS {\n let pattern_lower = pattern.to_lowercase();\n // Check if filename matches or ends with pattern\n if file_name == pattern_lower\n || file_name.ends_with(&pattern_lower)\n || file_lower.contains(&format!(\"/{}\", pattern_lower))\n {\n sensitive.push(file.to_string());\n break;\n }\n }\n }\n\n sensitive\n}\n\n/// Warn about sensitive files and optionally abort.\nfn warn_sensitive_files(files: &[String]) -> Result<()> {\n if files.is_empty() {\n return Ok(());\n }\n\n if env::var(\"FLOW_ALLOW_SENSITIVE_COMMIT\").ok().as_deref() == Some(\"1\") {\n return Ok(());\n }\n\n println!(\"\\n⚠️ Warning: Potentially sensitive files detected:\");\n for file in files {\n println!(\" - {}\", file);\n }\n println!();\n println!(\"These files may contain secrets. Consider:\");\n println!(\" - Adding them to .gitignore\");\n println!(\" - Using `git reset HEAD <file>` to unstage\");\n println!();\n\n bail!(\"Refusing to commit sensitive files. Set FLOW_ALLOW_SENSITIVE_COMMIT=1 to override.\")\n}\n\n/// Warn about secrets found in diff and optionally abort.\nfn warn_secrets_in_diff(\n repo_root: &Path,\n findings: &[(String, usize, String, String)],\n) -> Result<()> {\n if findings.is_empty() {\n return Ok(());\n }\n\n if env::var(\"FLOW_ALLOW_SECRET_COMMIT\").ok().as_deref() == Some(\"1\") {\n println!(\n \"\\n⚠️ Warning: Potential secrets detected but FLOW_ALLOW_SECRET_COMMIT=1, continuing...\"\n );\n return Ok(());\n }\n\n println!();\n print_secret_findings(\"🔐 Potential secrets detected in staged changes:\", findings);\n println!();\n println!(\"If these are false positives (examples, placeholders, tests), you can:\");\n println!(\" - Set FLOW_ALLOW_SECRET_COMMIT=1 to override for this commit\");\n println!(\n \" - Mark the line with '# flow:secret:ignore' (or add it on the line above to ignore the next line)\"\n );\n println!(\" - Use placeholder values like 'xxx' for example secrets\");\n println!(\" - Re-stage files if you recently edited them: git add <file>\");\n println!();\n\n let mut unstaged_files: Vec<&str> = Vec::new();\n for (file, _, _, _) in findings {\n if has_unstaged_changes(repo_root, file) {\n unstaged_files.push(file);\n }\n }\n\n if !unstaged_files.is_empty() {\n println!(\"ℹ️ Staged content differs from working tree for:\");\n for file in &unstaged_files {\n println!(\" - {}\", file);\n }\n println!(\" Re-run: git add <file> to update the staged diff.\");\n println!();\n }\n\n let agent_name =\n env::var(\"FLOW_FIX_COMMIT_AGENT\").unwrap_or_else(|_| \"fix-f-commit\".to_string());\n let agent_enabled = agent_name.trim().to_lowercase() != \"off\";\n let hive_available = which::which(\"hive\").is_ok();\n let ai_available = which::which(\"ai\").is_ok();\n let interactive = io::stdin().is_terminal();\n let mut current_findings = findings.to_vec();\n\n let rescan_after_fix = |findings: &mut Vec<(String, usize, String, String)>| -> Result<()> {\n git_run_in(repo_root, &[\"add\", \".\"])?;\n ensure_no_internal_staged(repo_root)?;\n ensure_no_unwanted_staged(repo_root)?;\n gitignore_policy::enforce_staged_policy(repo_root)?;\n *findings = scan_diff_for_secrets(repo_root);\n Ok(())\n };\n\n if interactive && agent_enabled && hive_available {\n let task = build_fix_f_commit_task(¤t_findings);\n println!(\"Running fix-f-commit agent (hive)...\");\n if let Err(err) = run_fix_f_commit_agent(repo_root, &agent_name, &task) {\n eprintln!(\"⚠ Failed to run fix-f-commit agent: {err}\");\n eprintln!(\n \" Create the agent at ~/.config/flow/agents/fix-f-commit.md or ~/.hive/agents/fix-f-commit/spec.md\"\n );\n eprintln!();\n }\n rescan_after_fix(&mut current_findings)?;\n if current_findings.is_empty() {\n if prompt_yes_no_default_yes(\n \"Secret scan is clean after auto-fix. Continue with commit?\",\n )? {\n return Ok(());\n }\n bail!(\"Commit aborted after auto-fix. Review changes and retry.\");\n }\n } else if !agent_enabled {\n eprintln!(\"ℹ️ fix-f-commit agent disabled via FLOW_FIX_COMMIT_AGENT=off\");\n } else if !hive_available {\n eprintln!(\"ℹ️ hive not found; skipping fix-f-commit agent\");\n }\n\n if interactive && !current_findings.is_empty() && ai_available {\n if prompt_yes_no_default_yes(\"Run auto-fix with ai?\")? {\n let task = build_fix_f_commit_task(¤t_findings);\n println!(\"Running auto-fix with ai...\");\n if let Err(err) = run_fix_f_commit_ai(repo_root, &task) {\n eprintln!(\"⚠ Failed to run ai auto-fix: {err}\");\n }\n rescan_after_fix(&mut current_findings)?;\n if current_findings.is_empty() {\n if prompt_yes_no_default_yes(\n \"Secret scan is clean after auto-fix. Continue with commit?\",\n )? {\n return Ok(());\n }\n bail!(\"Commit aborted after auto-fix. Review changes and retry.\");\n }\n }\n }\n\n if current_findings != findings {\n print_secret_findings(\n \"🔐 Potential secrets still detected in staged changes:\",\n ¤t_findings,\n );\n println!();\n }\n\n let task = build_fix_f_commit_task(¤t_findings);\n if !task.trim().is_empty() {\n eprintln!(\"Suggested prompt (copy/paste into your model):\");\n eprintln!(\"────────────────────────────────────────\");\n eprintln!(\"{}\", task);\n eprintln!(\"────────────────────────────────────────\");\n }\n\n bail!(\"Refusing to commit potential secrets. Review the findings above.\")\n}\n\nfn should_run_sync_for_secret_fixes(repo_root: &Path) -> Result<bool> {\n if !io::stdin().is_terminal() {\n return Ok(false);\n }\n if env::var(\"FLOW_ALLOW_SECRET_COMMIT\").ok().as_deref() == Some(\"1\") {\n return Ok(false);\n }\n\n let agent_name =\n env::var(\"FLOW_FIX_COMMIT_AGENT\").unwrap_or_else(|_| \"fix-f-commit\".to_string());\n let hive_enabled = agent_name.trim().to_lowercase() != \"off\" && which::which(\"hive\").is_ok();\n let ai_available = which::which(\"ai\").is_ok();\n if !hive_enabled && !ai_available {\n return Ok(false);\n }\n\n git_run(&[\"add\", \".\"])?;\n ensure_no_internal_staged(repo_root)?;\n ensure_no_unwanted_staged(repo_root)?;\n gitignore_policy::enforce_staged_policy(repo_root)?;\n\n Ok(!scan_diff_for_secrets(repo_root).is_empty())\n}\n\nfn run_fix_f_commit_agent(repo_root: &Path, agent: &str, task: &str) -> Result<()> {\n if which::which(\"hive\").is_err() {\n bail!(\"hive not found in PATH\");\n }\n\n let mut cmd = Command::new(\"hive\");\n cmd.args([\"agent\", &agent, task])\n .current_dir(repo_root)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .envs(resolve_hive_env());\n\n let status = cmd.status().context(\"failed to run hive agent\")?;\n\n if !status.success() {\n bail!(\"hive agent '{}' failed\", agent);\n }\n\n Ok(())\n}\n\nfn run_fix_f_commit_ai(repo_root: &Path, task: &str) -> Result<()> {\n if which::which(\"ai\").is_err() {\n bail!(\"ai not found in PATH\");\n }\n\n let status = Command::new(\"ai\")\n .args([\"--prompt\", task])\n .current_dir(repo_root)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run ai\")?;\n\n if !status.success() {\n bail!(\"ai auto-fix failed\");\n }\n\n Ok(())\n}\n\nfn build_fix_f_commit_task(findings: &[(String, usize, String, String)]) -> String {\n let mut summary = String::new();\n for (file, line, pattern, matched) in findings {\n summary.push_str(&format!(\n \"- {}:{} — {} ({})\\n\",\n file, line, pattern, matched\n ));\n }\n\n let task = format!(\n \"Fix f commit secret detection.\\n\\n\\\nFindings:\\n{summary}\\n\\\nPlease remove or mask real secrets, replace with placeholders if needed, \\\nand update .gitignore or docs/examples so the commit passes the secret scan. \\\nIf the match is a false positive, prefer marking the flagged line with `flow:secret:ignore` (for example: `# flow:secret:ignore`). \\\nIf you must keep the pattern but want it to pass the scanner, use 'xxx' placeholders.\\n\\\nAfter fixing, restage changes.\"\n );\n\n sanitize_hive_task(&task)\n}\n\nfn print_secret_findings(header: &str, findings: &[(String, usize, String, String)]) {\n println!(\"{}\", header);\n for (file, line, pattern, matched) in findings {\n println!(\" {}:{} - {} ({})\", file, line, pattern, matched);\n }\n}\n\nfn has_unstaged_changes(repo_root: &Path, file: &str) -> bool {\n let output = Command::new(\"git\")\n .args([\"diff\", \"--name-only\", \"--\", file])\n .current_dir(repo_root)\n .output();\n\n let Ok(output) = output else {\n return false;\n };\n if !output.status.success() {\n return false;\n }\n\n let output = String::from_utf8_lossy(&output.stdout);\n output.lines().any(|line| line.trim() == file)\n}\n\nfn sanitize_hive_task(task: &str) -> String {\n let mut cleaned = String::with_capacity(task.len());\n for ch in task.chars() {\n match ch {\n '\"' => cleaned.push('\\''),\n '\\n' | '\\r' | '\\t' => cleaned.push(' '),\n _ => cleaned.push(ch),\n }\n }\n cleaned\n}\n\nfn resolve_hive_env() -> Vec<(String, String)> {\n let mut vars = Vec::new();\n\n if std::env::var(\"CEREBRAS_API_KEY\")\n .map(|v| v.trim().is_empty())\n .unwrap_or(true)\n {\n if is_local_env_backend() {\n if let Ok(store) =\n crate::env::fetch_personal_env_vars(&[\"CEREBRAS_API_KEY\".to_string()])\n {\n if let Some(value) = store.get(\"CEREBRAS_API_KEY\") {\n if !value.trim().is_empty() {\n vars.push((\"CEREBRAS_API_KEY\".to_string(), value.to_string()));\n }\n }\n }\n }\n }\n\n vars\n}\n\n/// Threshold for \"large\" file changes (lines added + removed).\nconst LARGE_DIFF_THRESHOLD: usize = 500;\n\n/// Check for files with unusually large diffs.\n/// Returns list of (filename, lines_changed) for files over threshold.\nfn check_large_diffs(repo_root: &Path) -> Vec<(String, usize)> {\n let output = Command::new(\"git\")\n .args([\"diff\", \"--cached\", \"--numstat\"])\n .current_dir(repo_root)\n .output();\n\n let Ok(output) = output else {\n return Vec::new();\n };\n\n if !output.status.success() {\n return Vec::new();\n }\n\n let stats = String::from_utf8_lossy(&output.stdout);\n let mut large_files = Vec::new();\n\n for line in stats.lines() {\n let parts: Vec<&str> = line.split('\\t').collect();\n if parts.len() >= 3 {\n // Format: added<tab>removed<tab>filename\n // Binary files show \"-\" for added/removed\n let added: usize = parts[0].parse().unwrap_or(0);\n let removed: usize = parts[1].parse().unwrap_or(0);\n let filename = parts[2].to_string();\n let total = added + removed;\n\n if total >= LARGE_DIFF_THRESHOLD {\n large_files.push((filename, total));\n }\n }\n }\n\n // Sort by size descending\n large_files.sort_by(|a, b| b.1.cmp(&a.1));\n large_files\n}\n\n/// Warn about files with large diffs.\nfn warn_large_diffs(files: &[(String, usize)]) -> Result<()> {\n if files.is_empty() {\n return Ok(());\n }\n\n println!(\n \"⚠️ Warning: Files with large diffs ({}+ lines):\",\n LARGE_DIFF_THRESHOLD\n );\n for (file, lines) in files {\n println!(\" - {} ({} lines)\", file, lines);\n }\n println!();\n println!(\"These might be generated/lock files. Consider:\");\n println!(\" - Adding them to .gitignore if generated\");\n println!(\" - Using `git reset HEAD <file>` to unstage\");\n println!();\n\n Ok(())\n}\n\n/// Check TypeScript config for review settings first, then fall back to commit settings.\npub fn resolve_review_selection_from_config() -> Option<ReviewSelection> {\n let ts_config = config::load_ts_config()?;\n let flow_config = ts_config.flow?;\n\n // Check review config first (takes precedence)\n let (tool, model) = if let Some(ref review_config) = flow_config.review {\n if let Some(ref tool) = review_config.tool {\n (tool.as_str(), review_config.model.clone())\n } else if let Some(ref commit_config) = flow_config.commit {\n // Fall back to commit config\n (commit_config.tool.as_deref()?, commit_config.model.clone())\n } else {\n return None;\n }\n } else if let Some(ref commit_config) = flow_config.commit {\n // No review config, use commit config\n (commit_config.tool.as_deref()?, commit_config.model.clone())\n } else {\n return None;\n };\n\n match tool {\n \"opencode\" => {\n let model = model.unwrap_or_else(|| DEFAULT_OPENCODE_MODEL.to_string());\n Some(ReviewSelection::Opencode { model })\n }\n \"openrouter\" => {\n let model = model.unwrap_or_else(|| DEFAULT_OPENROUTER_REVIEW_MODEL.to_string());\n Some(ReviewSelection::OpenRouter { model })\n }\n \"rise\" => {\n let model = model.unwrap_or_else(|| DEFAULT_RISE_MODEL.to_string());\n Some(ReviewSelection::Rise { model })\n }\n \"glm5\" | \"glm-5\" | \"glm\" => {\n let model = model.unwrap_or_else(|| DEFAULT_GLM5_RISE_MODEL.to_string());\n Some(ReviewSelection::Rise { model })\n }\n \"kimi\" => Some(ReviewSelection::Kimi { model }),\n \"claude\" => {\n let model_enum = match model.as_deref() {\n Some(\"opus\") | Some(\"claude-opus\") => ClaudeModel::Opus,\n _ => ClaudeModel::Sonnet,\n };\n Some(ReviewSelection::Claude(model_enum))\n }\n \"codex\" => {\n let model_enum = match model.as_deref() {\n Some(\"mini\") | Some(\"codex-mini\") => CodexModel::Mini,\n _ => CodexModel::High,\n };\n Some(ReviewSelection::Codex(model_enum))\n }\n _ => None,\n }\n}\n\npub fn resolve_review_selection(\n use_claude: bool,\n override_model: Option<ReviewModelArg>,\n) -> ReviewSelection {\n // Check TypeScript config first\n if let Some(selection) = resolve_review_selection_from_config() {\n return selection;\n }\n\n if let Some(model) = override_model {\n return match model {\n ReviewModelArg::ClaudeOpus => ReviewSelection::Claude(ClaudeModel::Opus),\n ReviewModelArg::CodexHigh => ReviewSelection::Codex(CodexModel::High),\n ReviewModelArg::CodexMini => ReviewSelection::Codex(CodexModel::Mini),\n };\n }\n\n if use_claude {\n ReviewSelection::Claude(ClaudeModel::Sonnet)\n } else {\n ReviewSelection::Codex(CodexModel::High)\n }\n}\n\n/// New default: Claude is default, --codex flag to use Codex\npub fn resolve_review_selection_v2(\n use_codex: bool,\n override_model: Option<ReviewModelArg>,\n) -> ReviewSelection {\n // Check TypeScript config first\n if let Some(selection) = resolve_review_selection_from_config() {\n return selection;\n }\n\n if let Some(model) = override_model {\n return match model {\n ReviewModelArg::ClaudeOpus => ReviewSelection::Claude(ClaudeModel::Opus),\n ReviewModelArg::CodexHigh => ReviewSelection::Codex(CodexModel::High),\n ReviewModelArg::CodexMini => ReviewSelection::Codex(CodexModel::Mini),\n };\n }\n\n if use_codex {\n ReviewSelection::Codex(CodexModel::High)\n } else {\n // Default: Claude Sonnet\n ReviewSelection::Claude(ClaudeModel::Sonnet)\n }\n}\n\nfn parse_boolish(value: &str) -> Option<bool> {\n match value.trim().to_ascii_lowercase().as_str() {\n \"1\" | \"true\" | \"yes\" | \"on\" => Some(true),\n \"0\" | \"false\" | \"no\" | \"off\" => Some(false),\n _ => None,\n }\n}\n\nfn load_ts_commit_config() -> Option<config::TsCommitConfig> {\n config::load_ts_config()\n .and_then(|cfg| cfg.flow)\n .and_then(|flow| flow.commit)\n}\n\nfn load_local_commit_config(repo_root: &Path) -> Option<config::CommitConfig> {\n let local = repo_root.join(\"flow.toml\");\n if !local.exists() {\n return None;\n }\n config::load(&local).ok().and_then(|cfg| cfg.commit)\n}\n\nfn load_global_commit_config() -> Option<config::CommitConfig> {\n let global = config::default_config_path();\n if !global.exists() {\n return None;\n }\n config::load(&global).ok().and_then(|cfg| cfg.commit)\n}\n\npub fn commit_quick_default_enabled() -> bool {\n if let Ok(value) = env::var(\"FLOW_COMMIT_QUICK_DEFAULT\") {\n if let Some(parsed) = parse_boolish(&value) {\n return parsed;\n }\n }\n\n if let Some(ts) = load_ts_commit_config() {\n if let Some(enabled) = ts.quick_default {\n return enabled;\n }\n }\n\n let repo_root = git_root_or_cwd();\n if let Some(local) = load_local_commit_config(&repo_root) {\n if let Some(enabled) = local.quick_default {\n return enabled;\n }\n }\n\n if let Some(global) = load_global_commit_config() {\n if let Some(enabled) = global.quick_default {\n return enabled;\n }\n }\n\n true\n}\n\nfn commit_review_fail_open_enabled(repo_root: &Path) -> bool {\n if let Ok(value) = env::var(\"FLOW_COMMIT_REVIEW_FAIL_OPEN\") {\n if let Some(parsed) = parse_boolish(&value) {\n return parsed;\n }\n }\n\n if let Some(ts) = load_ts_commit_config() {\n if let Some(enabled) = ts.review_fail_open {\n return enabled;\n }\n }\n if let Some(local) = load_local_commit_config(repo_root) {\n if let Some(enabled) = local.review_fail_open {\n return enabled;\n }\n }\n if let Some(global) = load_global_commit_config() {\n if let Some(enabled) = global.review_fail_open {\n return enabled;\n }\n }\n\n true\n}\n\nfn commit_message_fail_open_enabled(repo_root: &Path) -> bool {\n if let Ok(value) = env::var(\"FLOW_COMMIT_MESSAGE_FAIL_OPEN\") {\n if let Some(parsed) = parse_boolish(&value) {\n return parsed;\n }\n }\n\n if let Some(ts) = load_ts_commit_config() {\n if let Some(enabled) = ts.message_fail_open {\n return enabled;\n }\n }\n if let Some(local) = load_local_commit_config(repo_root) {\n if let Some(enabled) = local.message_fail_open {\n return enabled;\n }\n }\n if let Some(global) = load_global_commit_config() {\n if let Some(enabled) = global.message_fail_open {\n return enabled;\n }\n }\n\n true\n}\n\nfn parse_review_selection_spec(spec: &str) -> Option<ReviewSelection> {\n let trimmed = spec.trim();\n if trimmed.is_empty() {\n return None;\n }\n let lower = trimmed.to_ascii_lowercase();\n if lower == \"codex\" || lower == \"codex-high\" {\n return Some(ReviewSelection::Codex(CodexModel::High));\n }\n if lower == \"codex-mini\" || lower == \"codex:mini\" || lower == \"codex-mini-review\" {\n return Some(ReviewSelection::Codex(CodexModel::Mini));\n }\n if lower == \"claude\" || lower == \"claude-sonnet\" {\n return Some(ReviewSelection::Claude(ClaudeModel::Sonnet));\n }\n if lower == \"claude-opus\" || lower == \"claude:opus\" {\n return Some(ReviewSelection::Claude(ClaudeModel::Opus));\n }\n if lower == \"kimi\" {\n return Some(ReviewSelection::Kimi { model: None });\n }\n if let Some(model) = trimmed\n .strip_prefix(\"openrouter:\")\n .or_else(|| trimmed.strip_prefix(\"openrouter/\"))\n {\n let model = if model.trim().is_empty() {\n DEFAULT_OPENROUTER_REVIEW_MODEL.to_string()\n } else {\n model.trim().to_string()\n };\n return Some(ReviewSelection::OpenRouter { model });\n }\n if lower == \"openrouter\" {\n return Some(ReviewSelection::OpenRouter {\n model: DEFAULT_OPENROUTER_REVIEW_MODEL.to_string(),\n });\n }\n if let Some(model) = trimmed\n .strip_prefix(\"rise:\")\n .or_else(|| trimmed.strip_prefix(\"rise/\"))\n {\n let model = if model.trim().is_empty() {\n DEFAULT_RISE_MODEL.to_string()\n } else {\n model.trim().to_string()\n };\n return Some(ReviewSelection::Rise { model });\n }\n if lower == \"rise\" {\n return Some(ReviewSelection::Rise {\n model: DEFAULT_RISE_MODEL.to_string(),\n });\n }\n if lower == \"glm5\" || lower == \"glm-5\" || lower == \"glm\" {\n return Some(ReviewSelection::Rise {\n model: DEFAULT_GLM5_RISE_MODEL.to_string(),\n });\n }\n if let Some(model) = trimmed\n .strip_prefix(\"glm5:\")\n .or_else(|| trimmed.strip_prefix(\"glm5/\"))\n .or_else(|| trimmed.strip_prefix(\"glm-5:\"))\n .or_else(|| trimmed.strip_prefix(\"glm-5/\"))\n {\n let model = if model.trim().is_empty() {\n DEFAULT_GLM5_RISE_MODEL.to_string()\n } else {\n model.trim().to_string()\n };\n return Some(ReviewSelection::Rise { model });\n }\n if let Some(model) = trimmed\n .strip_prefix(\"opencode:\")\n .or_else(|| trimmed.strip_prefix(\"opencode/\"))\n {\n let model = if model.trim().is_empty() {\n DEFAULT_OPENCODE_MODEL.to_string()\n } else {\n model.trim().to_string()\n };\n return Some(ReviewSelection::Opencode { model });\n }\n if lower == \"opencode\" {\n return Some(ReviewSelection::Opencode {\n model: DEFAULT_OPENCODE_MODEL.to_string(),\n });\n }\n None\n}\n\nfn commit_review_fallback_specs(repo_root: &Path) -> Vec<String> {\n if let Ok(raw) = env::var(\"FLOW_COMMIT_REVIEW_FALLBACKS\") {\n let parsed = raw\n .split([',', '\\n'])\n .map(|v| v.trim().to_string())\n .filter(|v| !v.is_empty())\n .collect::<Vec<_>>();\n if !parsed.is_empty() {\n return parsed;\n }\n }\n\n if let Some(ts) = load_ts_commit_config() {\n if let Some(v) = ts.review_fallbacks {\n let parsed = v\n .into_iter()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n .collect::<Vec<_>>();\n if !parsed.is_empty() {\n return parsed;\n }\n }\n }\n if let Some(local) = load_local_commit_config(repo_root) {\n if let Some(v) = local.review_fallbacks {\n let parsed = v\n .into_iter()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n .collect::<Vec<_>>();\n if !parsed.is_empty() {\n return parsed;\n }\n }\n }\n if let Some(global) = load_global_commit_config() {\n if let Some(v) = global.review_fallbacks {\n let parsed = v\n .into_iter()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n .collect::<Vec<_>>();\n if !parsed.is_empty() {\n return parsed;\n }\n }\n }\n\n vec![\n \"openrouter\".to_string(),\n \"claude\".to_string(),\n \"codex-high\".to_string(),\n ]\n}\n\nfn review_attempts_for_selection(\n repo_root: &Path,\n primary: &ReviewSelection,\n prefer_codex_over_openrouter: bool,\n) -> Vec<ReviewSelection> {\n let mut attempts: Vec<ReviewSelection> = Vec::new();\n if prefer_codex_over_openrouter {\n attempts.push(ReviewSelection::Codex(CodexModel::High));\n }\n attempts.push(primary.clone());\n\n for spec in commit_review_fallback_specs(repo_root) {\n if let Some(selection) = parse_review_selection_spec(&spec) {\n attempts.push(selection);\n }\n }\n\n let mut seen = HashSet::new();\n let mut deduped = Vec::new();\n for attempt in attempts {\n let key = attempt.model_label();\n if seen.insert(key) {\n deduped.push(attempt);\n }\n }\n deduped\n}\n\n#[derive(Debug, Clone)]\nenum CommitMessageSelection {\n Kimi { model: Option<String> },\n Claude,\n Opencode { model: String },\n OpenRouter { model: String },\n Rise { model: String },\n Remote,\n OpenAi,\n Heuristic,\n}\n\nimpl CommitMessageSelection {\n fn key(&self) -> String {\n match self {\n CommitMessageSelection::Kimi { model } => match model.as_deref() {\n Some(model) if !model.trim().is_empty() => format!(\"kimi:{}\", model.trim()),\n _ => \"kimi\".to_string(),\n },\n CommitMessageSelection::Claude => \"claude\".to_string(),\n CommitMessageSelection::Opencode { model } => format!(\"opencode:{}\", model.trim()),\n CommitMessageSelection::OpenRouter { model } => {\n format!(\"openrouter:{}\", openrouter_model_id(model))\n }\n CommitMessageSelection::Rise { model } => format!(\"rise:{}\", model.trim()),\n CommitMessageSelection::Remote => \"remote\".to_string(),\n CommitMessageSelection::OpenAi => \"openai\".to_string(),\n CommitMessageSelection::Heuristic => \"heuristic\".to_string(),\n }\n }\n\n fn label(&self) -> String {\n match self {\n CommitMessageSelection::Kimi { .. } => \"Kimi\".to_string(),\n CommitMessageSelection::Claude => \"Claude\".to_string(),\n CommitMessageSelection::Opencode { .. } => \"opencode\".to_string(),\n CommitMessageSelection::OpenRouter { .. } => \"OpenRouter\".to_string(),\n CommitMessageSelection::Rise { .. } => \"Rise\".to_string(),\n CommitMessageSelection::Remote => \"myflow\".to_string(),\n CommitMessageSelection::OpenAi => \"OpenAI\".to_string(),\n CommitMessageSelection::Heuristic => \"deterministic fallback\".to_string(),\n }\n }\n}\n\nfn parse_commit_message_selection_spec(spec: &str) -> Option<CommitMessageSelection> {\n let trimmed = spec.trim();\n if trimmed.is_empty() {\n return None;\n }\n\n let lower = trimmed.to_ascii_lowercase();\n if lower == \"remote\" || lower == \"myflow\" || lower == \"flow\" {\n return Some(CommitMessageSelection::Remote);\n }\n if lower == \"openai\" {\n return Some(CommitMessageSelection::OpenAi);\n }\n if lower == \"heuristic\" || lower == \"fallback\" || lower == \"local\" {\n return Some(CommitMessageSelection::Heuristic);\n }\n if lower == \"claude\" {\n return Some(CommitMessageSelection::Claude);\n }\n if lower == \"kimi\" {\n return Some(CommitMessageSelection::Kimi { model: None });\n }\n\n if let Some(model) = trimmed\n .strip_prefix(\"kimi:\")\n .or_else(|| trimmed.strip_prefix(\"kimi/\"))\n {\n let model = model.trim();\n return Some(CommitMessageSelection::Kimi {\n model: if model.is_empty() {\n None\n } else {\n Some(model.to_string())\n },\n });\n }\n\n if let Some(model) = trimmed\n .strip_prefix(\"openrouter:\")\n .or_else(|| trimmed.strip_prefix(\"openrouter/\"))\n {\n let model = if model.trim().is_empty() {\n DEFAULT_OPENROUTER_REVIEW_MODEL.to_string()\n } else {\n model.trim().to_string()\n };\n return Some(CommitMessageSelection::OpenRouter { model });\n }\n if lower == \"openrouter\" {\n return Some(CommitMessageSelection::OpenRouter {\n model: DEFAULT_OPENROUTER_REVIEW_MODEL.to_string(),\n });\n }\n\n if let Some(model) = trimmed\n .strip_prefix(\"opencode:\")\n .or_else(|| trimmed.strip_prefix(\"opencode/\"))\n {\n let model = if model.trim().is_empty() {\n DEFAULT_OPENCODE_MODEL.to_string()\n } else {\n model.trim().to_string()\n };\n return Some(CommitMessageSelection::Opencode { model });\n }\n if lower == \"opencode\" {\n return Some(CommitMessageSelection::Opencode {\n model: DEFAULT_OPENCODE_MODEL.to_string(),\n });\n }\n\n if let Some(model) = trimmed\n .strip_prefix(\"rise:\")\n .or_else(|| trimmed.strip_prefix(\"rise/\"))\n {\n let model = if model.trim().is_empty() {\n DEFAULT_RISE_MODEL.to_string()\n } else {\n model.trim().to_string()\n };\n return Some(CommitMessageSelection::Rise { model });\n }\n if lower == \"rise\" {\n return Some(CommitMessageSelection::Rise {\n model: DEFAULT_RISE_MODEL.to_string(),\n });\n }\n if lower == \"glm5\" || lower == \"glm-5\" || lower == \"glm\" {\n return Some(CommitMessageSelection::Rise {\n model: DEFAULT_GLM5_RISE_MODEL.to_string(),\n });\n }\n if let Some(model) = trimmed\n .strip_prefix(\"glm5:\")\n .or_else(|| trimmed.strip_prefix(\"glm5/\"))\n .or_else(|| trimmed.strip_prefix(\"glm-5:\"))\n .or_else(|| trimmed.strip_prefix(\"glm-5/\"))\n {\n let model = if model.trim().is_empty() {\n DEFAULT_GLM5_RISE_MODEL.to_string()\n } else {\n model.trim().to_string()\n };\n return Some(CommitMessageSelection::Rise { model });\n }\n\n None\n}\n\nfn parse_commit_message_selection_with_model(\n tool: &str,\n model: Option<String>,\n) -> Option<CommitMessageSelection> {\n let tool_trimmed = tool.trim();\n if tool_trimmed.is_empty() {\n return None;\n }\n let model_trimmed = model.and_then(|m| {\n let trimmed = m.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n }\n });\n\n match tool_trimmed.to_ascii_lowercase().as_str() {\n \"kimi\" => Some(CommitMessageSelection::Kimi {\n model: model_trimmed,\n }),\n \"claude\" => Some(CommitMessageSelection::Claude),\n \"openrouter\" => Some(CommitMessageSelection::OpenRouter {\n model: model_trimmed.unwrap_or_else(|| DEFAULT_OPENROUTER_REVIEW_MODEL.to_string()),\n }),\n \"opencode\" => Some(CommitMessageSelection::Opencode {\n model: model_trimmed.unwrap_or_else(|| DEFAULT_OPENCODE_MODEL.to_string()),\n }),\n \"rise\" => Some(CommitMessageSelection::Rise {\n model: model_trimmed.unwrap_or_else(|| DEFAULT_RISE_MODEL.to_string()),\n }),\n \"glm5\" | \"glm-5\" | \"glm\" => Some(CommitMessageSelection::Rise {\n model: model_trimmed.unwrap_or_else(|| DEFAULT_GLM5_RISE_MODEL.to_string()),\n }),\n \"remote\" | \"myflow\" | \"flow\" => Some(CommitMessageSelection::Remote),\n \"openai\" => Some(CommitMessageSelection::OpenAi),\n \"heuristic\" | \"fallback\" | \"local\" => Some(CommitMessageSelection::Heuristic),\n _ => parse_commit_message_selection_spec(tool_trimmed),\n }\n}\n\nfn commit_message_fallback_specs(repo_root: &Path) -> Vec<String> {\n if let Ok(raw) = env::var(\"FLOW_COMMIT_MESSAGE_FALLBACKS\") {\n let parsed = raw\n .split([',', '\\n'])\n .map(|v| v.trim().to_string())\n .filter(|v| !v.is_empty())\n .collect::<Vec<_>>();\n if !parsed.is_empty() {\n return parsed;\n }\n }\n\n if let Some(ts) = load_ts_commit_config() {\n if let Some(v) = ts.message_fallbacks {\n let parsed = v\n .into_iter()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n .collect::<Vec<_>>();\n if !parsed.is_empty() {\n return parsed;\n }\n }\n }\n if let Some(local) = load_local_commit_config(repo_root) {\n if let Some(v) = local.message_fallbacks {\n let parsed = v\n .into_iter()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n .collect::<Vec<_>>();\n if !parsed.is_empty() {\n return parsed;\n }\n }\n }\n if let Some(global) = load_global_commit_config() {\n if let Some(v) = global.message_fallbacks {\n let parsed = v\n .into_iter()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n .collect::<Vec<_>>();\n if !parsed.is_empty() {\n return parsed;\n }\n }\n }\n\n vec![\n \"remote\".to_string(),\n \"openai\".to_string(),\n \"openrouter\".to_string(),\n ]\n}\n\nfn review_selection_to_message_selection(\n review_selection: &ReviewSelection,\n) -> Option<CommitMessageSelection> {\n match review_selection {\n ReviewSelection::Claude(_) => Some(CommitMessageSelection::Claude),\n ReviewSelection::Opencode { model } => Some(CommitMessageSelection::Opencode {\n model: model.clone(),\n }),\n ReviewSelection::OpenRouter { model } => Some(CommitMessageSelection::OpenRouter {\n model: model.clone(),\n }),\n ReviewSelection::Rise { model } => Some(CommitMessageSelection::Rise {\n model: model.clone(),\n }),\n ReviewSelection::Kimi { model } => Some(CommitMessageSelection::Kimi {\n model: model.clone(),\n }),\n ReviewSelection::Codex(_) => None,\n }\n}\n\nfn commit_message_attempts(\n repo_root: &Path,\n review_selection: Option<&ReviewSelection>,\n override_selection: Option<&CommitMessageSelection>,\n) -> Vec<CommitMessageSelection> {\n let mut attempts: Vec<CommitMessageSelection> = Vec::new();\n\n if let Some(selection) = override_selection {\n attempts.push(selection.clone());\n } else if let Some(review_selection) = review_selection {\n if let Some(selection) = review_selection_to_message_selection(review_selection) {\n attempts.push(selection);\n }\n }\n\n for spec in commit_message_fallback_specs(repo_root) {\n if let Some(selection) = parse_commit_message_selection_spec(&spec) {\n attempts.push(selection);\n }\n }\n\n let mut seen = HashSet::new();\n let mut deduped = Vec::new();\n for attempt in attempts {\n let key = attempt.key();\n if seen.insert(key) {\n deduped.push(attempt);\n }\n }\n deduped\n}\n\n#[derive(Debug, Deserialize)]\nstruct ReviewJson {\n issues_found: bool,\n #[serde(default)]\n issues: Vec<String>,\n #[serde(default)]\n summary: Option<String>,\n #[serde(default)]\n future_tasks: Vec<String>,\n #[serde(default)]\n quality: Option<QualityResult>,\n}\n\n#[derive(Debug, Serialize)]\nstruct RemoteReviewRequest {\n diff: String,\n context: Option<String>,\n model: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n review_instructions: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct RemoteReviewResponse {\n output: String,\n #[serde(default)]\n stderr: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct RemoteCommitMessageResponse {\n message: String,\n}\n\n#[derive(Debug)]\nstruct ReviewResult {\n issues_found: bool,\n issues: Vec<String>,\n summary: Option<String>,\n future_tasks: Vec<String>,\n timed_out: bool,\n quality: Option<QualityResult>,\n}\n\n#[derive(Debug, Clone, Deserialize)]\n#[allow(dead_code)]\npub(crate) struct QualityResult {\n pub(crate) features_touched: Vec<FeatureTouched>,\n pub(crate) new_features: Vec<NewFeature>,\n pub(crate) test_coverage: String,\n pub(crate) doc_coverage: String,\n pub(crate) gate_pass: bool,\n pub(crate) gate_failures: Vec<String>,\n}\n\n#[derive(Debug, Clone, Deserialize)]\n#[allow(dead_code)]\npub(crate) struct FeatureTouched {\n pub(crate) name: String,\n pub(crate) action: String,\n pub(crate) description: String,\n pub(crate) files_changed: Vec<String>,\n pub(crate) has_tests: bool,\n pub(crate) test_files: Vec<String>,\n pub(crate) doc_current: bool,\n}\n\n#[derive(Debug, Clone, Deserialize)]\n#[allow(dead_code)]\npub(crate) struct NewFeature {\n pub(crate) name: String,\n pub(crate) description: String,\n pub(crate) files: Vec<String>,\n pub(crate) doc_content: String,\n}\n\n#[derive(Debug)]\nstruct StagedSnapshot {\n patch_path: Option<std::path::PathBuf>,\n}\n\n#[derive(Debug, Serialize)]\nstruct UnhashCommitMetadata {\n repo: String,\n repo_root: String,\n branch: String,\n created_at: String,\n commit_message: String,\n author_message: Option<String>,\n include_context: bool,\n context_chars: Option<usize>,\n review_model: Option<String>,\n review_instructions: Option<String>,\n review_issues: Vec<String>,\n review_summary: Option<String>,\n review_future_tasks: Vec<String>,\n review_timed_out: bool,\n gitedit_session_hash: Option<String>,\n session_count: usize,\n}\n\n#[derive(Debug, Serialize)]\nstruct UnhashReviewPayload {\n issues_found: bool,\n issues: Vec<String>,\n summary: Option<String>,\n future_tasks: Vec<String>,\n timed_out: bool,\n model: Option<String>,\n reviewer: Option<String>,\n}\n\n#[derive(Debug, Serialize)]\nstruct ChatRequest {\n model: String,\n messages: Vec<Message>,\n temperature: f32,\n}\n\n#[derive(Debug, Serialize)]\nstruct Message {\n role: String,\n content: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ChatResponse {\n choices: Vec<Choice>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct Choice {\n message: Option<ResponseMessage>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ResponseMessage {\n content: String,\n}\n\nfn parse_rise_output(text: &str) -> Result<String> {\n let trimmed = text.trim();\n if trimmed.is_empty() {\n bail!(\"Rise daemon returned empty response\");\n }\n\n if let Ok(value) = serde_json::from_str::<serde_json::Value>(trimmed) {\n if let Some(err) = value.get(\"error\") {\n let code = err\n .get(\"code\")\n .and_then(|v| v.as_str())\n .unwrap_or(\"unknown\");\n let message = err\n .get(\"message\")\n .and_then(|v| v.as_str())\n .unwrap_or(\"unknown error\");\n bail!(\"Rise daemon error: {} ({})\", message, code);\n }\n }\n\n if let Ok(response) = serde_json::from_str::<ChatResponse>(text) {\n if let Some(output) = response\n .choices\n .first()\n .and_then(|c| c.message.as_ref())\n .map(|m| m.content.clone())\n {\n if !output.trim().is_empty() {\n return Ok(output);\n }\n }\n }\n\n if let Ok(value) = serde_json::from_str::<serde_json::Value>(text) {\n if let Some(content) = value\n .get(\"assistant\")\n .and_then(|v| v.as_str())\n .map(|s| s.to_string())\n {\n if !content.trim().is_empty() {\n return Ok(content);\n }\n }\n\n if let Some(content) = value\n .pointer(\"/choices/0/message/content\")\n .and_then(|v| v.as_str())\n .map(|s| s.to_string())\n {\n if !content.trim().is_empty() {\n return Ok(content);\n }\n }\n }\n\n Ok(trimmed.to_string())\n}\n\nfn is_rise_auth_error(text: &str) -> bool {\n let trimmed = text.trim();\n trimmed.contains(\"Authorization Token Missing\")\n || trimmed.contains(\"\\\"code\\\":\\\"1001\\\"\")\n || trimmed.contains(\"\\\"code\\\":1001\")\n}\n\nfn rise_provider_from_model(model: &str) -> Option<String> {\n let trimmed = model.trim();\n if trimmed.is_empty() {\n return None;\n }\n let stripped = trimmed.strip_prefix(\"rise:\").unwrap_or(trimmed);\n let provider = stripped.split(':').next().unwrap_or(\"\").trim();\n if provider.is_empty() {\n return None;\n }\n Some(provider.to_ascii_lowercase())\n}\n\nfn rise_provider_env_key(provider: &str) -> Option<&'static str> {\n match provider {\n \"zai\" => Some(\"ZAI_API_KEY\"),\n \"xai\" => Some(\"XAI_API_KEY\"),\n \"cerebras\" => Some(\"CEREBRAS_API_KEY\"),\n \"deepseek\" => Some(\"DEEPSEEK_API_KEY\"),\n \"openai\" => Some(\"OPENAI_API_KEY\"),\n _ => None,\n }\n}\n\nfn is_local_env_backend() -> bool {\n if let Some(backend) = crate::config::preferred_env_backend() {\n return backend.eq_ignore_ascii_case(\"local\");\n }\n\n match std::env::var(\"FLOW_ENV_BACKEND\")\n .ok()\n .map(|v| v.to_ascii_lowercase())\n .as_deref()\n {\n Some(\"local\") => true,\n Some(\"cloud\") | Some(\"remote\") => false,\n _ => std::env::var(\"FLOW_ENV_LOCAL\")\n .ok()\n .map(|v| {\n let v = v.to_ascii_lowercase();\n v == \"1\" || v == \"true\" || v == \"yes\"\n })\n .unwrap_or(false),\n }\n}\n\nfn rise_auth_error_message(model: &str) -> String {\n let Some(provider) = rise_provider_from_model(model) else {\n return \"Rise daemon error: Authorization Token Missing (1001).\".to_string();\n };\n let Some(env_key) = rise_provider_env_key(&provider) else {\n return format!(\n \"Rise daemon error: Authorization Token Missing (1001). Missing auth for provider '{}'.\",\n provider\n );\n };\n\n let has_env = std::env::var(env_key)\n .map(|v| !v.trim().is_empty())\n .unwrap_or(false);\n let has_store = if is_local_env_backend() {\n crate::env::fetch_personal_env_vars(&[env_key.to_string()])\n .ok()\n .and_then(|vars| vars.get(env_key).cloned())\n .map(|v| !v.trim().is_empty())\n .unwrap_or(false)\n } else {\n false\n };\n\n let mut message = format!(\n \"Rise daemon error: Authorization Token Missing (1001). Missing {} for provider '{}'.\",\n env_key, provider\n );\n if has_store || has_env {\n message.push_str(\" Restart the Rise daemon so it picks up the key.\");\n } else {\n message.push_str(&format!(\n \" Set it in Flow env store: f env set --personal {}=... then restart the Rise daemon.\",\n env_key\n ));\n }\n message\n}\n\nfn rise_url() -> String {\n std::env::var(\"ZERG_AI_URL\")\n .or_else(|_| std::env::var(\"FLOW_RISE_URL\"))\n .or_else(|_| std::env::var(\"RISE_URL\"))\n .unwrap_or_else(|_| \"http://localhost:7654/v1/chat/completions\".to_string())\n}\n\nfn rise_health_url(rise_url: &str) -> Option<String> {\n let trimmed = rise_url.trim_end_matches('/');\n let idx = trimmed.find(\"/v1/\")?;\n Some(format!(\"{}/health\", &trimmed[..idx]))\n}\n\nfn wait_for_rise_ready(client: &Client, rise_url: &str) {\n let Some(health_url) = rise_health_url(rise_url) else {\n return;\n };\n for _ in 0..12 {\n match client.get(&health_url).send() {\n Ok(resp) if resp.status().is_success() => return,\n _ => std::thread::sleep(Duration::from_millis(350)),\n }\n }\n}\n\nfn try_start_rise_daemon() -> Result<()> {\n let action = DaemonAction::Start {\n name: \"rise\".to_string(),\n };\n if supervisor::try_handle_daemon_action(&action, None)? {\n return Ok(());\n }\n daemon::start_daemon_with_path(\"rise\", None)\n}\n\nfn try_restart_rise_daemon() -> Result<()> {\n let action = DaemonAction::Restart {\n name: \"rise\".to_string(),\n };\n if supervisor::try_handle_daemon_action(&action, None)? {\n return Ok(());\n }\n daemon::stop_daemon_with_path(\"rise\", None).ok();\n daemon::start_daemon_with_path(\"rise\", None)\n}\n\nfn send_rise_request_text(\n client: &Client,\n rise_url: &str,\n body: &ChatRequest,\n model: &str,\n) -> Result<String> {\n let resp = send_rise_request(client, rise_url, body)?;\n if !resp.status().is_success() {\n let error_text = resp.text().unwrap_or_else(|_| \"unknown error\".to_string());\n if is_rise_auth_error(&error_text) {\n info!(\"Rise auth error; attempting daemon restart...\");\n if let Err(err) = try_restart_rise_daemon() {\n bail!(\n \"{} (restart failed: {})\",\n rise_auth_error_message(model),\n err\n );\n }\n std::thread::sleep(Duration::from_millis(500));\n wait_for_rise_ready(client, rise_url);\n let resp = send_rise_request(client, rise_url, body)?;\n if !resp.status().is_success() {\n let error_text = resp.text().unwrap_or_else(|_| \"unknown error\".to_string());\n bail!(\"Rise daemon error: {}\", error_text);\n }\n let text = resp.text().context(\"failed to read Rise response\")?;\n if is_rise_auth_error(&text) {\n bail!(rise_auth_error_message(model));\n }\n return Ok(text);\n }\n bail!(\"Rise daemon error: {}\", error_text);\n }\n\n let text = resp.text().context(\"failed to read Rise response\")?;\n if is_rise_auth_error(&text) {\n info!(\"Rise auth error; attempting daemon restart...\");\n if let Err(err) = try_restart_rise_daemon() {\n bail!(\n \"{} (restart failed: {})\",\n rise_auth_error_message(model),\n err\n );\n }\n std::thread::sleep(Duration::from_millis(500));\n wait_for_rise_ready(client, rise_url);\n let resp = send_rise_request(client, rise_url, body)?;\n if !resp.status().is_success() {\n let error_text = resp.text().unwrap_or_else(|_| \"unknown error\".to_string());\n bail!(\"Rise daemon error: {}\", error_text);\n }\n let text = resp.text().context(\"failed to read Rise response\")?;\n if is_rise_auth_error(&text) {\n bail!(rise_auth_error_message(model));\n }\n return Ok(text);\n }\n\n Ok(text)\n}\n\nfn send_rise_request(\n client: &Client,\n rise_url: &str,\n body: &ChatRequest,\n) -> Result<reqwest::blocking::Response> {\n match client.post(rise_url).json(body).send() {\n Ok(resp) => Ok(resp),\n Err(err) => {\n if err.is_connect() {\n info!(\"Rise daemon unreachable; attempting auto-start...\");\n if let Err(start_err) = try_start_rise_daemon() {\n return Err(err).with_context(|| {\n format!(\n \"failed to reach Rise daemon at {}. Auto-start failed: {}\",\n rise_url, start_err\n )\n });\n }\n std::thread::sleep(Duration::from_millis(500));\n wait_for_rise_ready(client, rise_url);\n return client.post(rise_url).json(body).send().with_context(|| {\n format!(\n \"failed to reach Rise daemon at {} after auto-start. Start with: f rise\",\n rise_url\n )\n });\n }\n\n Err(err).with_context(|| {\n format!(\n \"failed to reach Rise daemon at {}. Start with: f rise\",\n rise_url\n )\n })\n }\n }\n}\n\n/// Dry run: show the context that would be passed to Codex without committing.\npub fn dry_run_context() -> Result<()> {\n println!(\"Dry run: showing context that would be passed to Codex\\n\");\n\n // Ensure we're in a git repo\n ensure_git_repo()?;\n\n // Show checkpoint info\n let cwd = std::env::current_dir()?;\n let checkpoints = ai::load_checkpoints(&cwd).unwrap_or_default();\n println!(\"────────────────────────────────────────\");\n println!(\"COMMIT CHECKPOINT\");\n println!(\"────────────────────────────────────────\");\n if let Some(ref checkpoint) = checkpoints.last_commit {\n println!(\"Last commit: {}\", checkpoint.timestamp);\n if let Some(ref ts) = checkpoint.last_entry_timestamp {\n println!(\"Last entry included: {}\", ts);\n }\n if let Some(ref sid) = checkpoint.session_id {\n println!(\"Session: {}...\", &sid[..8.min(sid.len())]);\n }\n } else {\n println!(\"No previous checkpoint (first commit with context)\");\n }\n\n // Get diff\n let diff = git_capture(&[\"diff\", \"--cached\"]).or_else(|_| git_capture(&[\"diff\"]))?;\n\n if diff.trim().is_empty() {\n println!(\"\\nNo changes to show (no staged or unstaged diff)\");\n println!(\"\\nTrying to show what would be staged with 'git add .'...\");\n git_run(&[\"add\", \"--dry-run\", \".\"])?;\n }\n\n // Get AI session context since checkpoint\n println!(\"\\n────────────────────────────────────────\");\n println!(\"AI SESSION CONTEXT (since checkpoint)\");\n println!(\"────────────────────────────────────────\");\n\n match ai::get_context_since_checkpoint() {\n Ok(Some(context)) => {\n println!(\n \"Context length: {} chars, {} lines\\n\",\n context.len(),\n context.lines().count()\n );\n println!(\"{}\", context);\n }\n Ok(None) => {\n println!(\"No new AI session context since last checkpoint.\");\n println!(\"\\nThis could mean:\");\n println!(\" - No exchanges since last commit\");\n println!(\" - No Claude Code or Codex session in this project\");\n }\n Err(e) => {\n println!(\"Error getting context: {}\", e);\n }\n }\n\n println!(\"────────────────────────────────────────\");\n println!(\"\\nDiff that would be reviewed:\");\n println!(\"────────────────────────────────────────\");\n\n let (diff_for_prompt, truncated) = truncate_diff(&diff);\n println!(\"{}\", diff_for_prompt);\n\n if truncated {\n println!(\"\\n[Diff truncated to {} chars]\", MAX_DIFF_CHARS);\n }\n\n println!(\"────────────────────────────────────────\");\n\n Ok(())\n}\n\n/// Run the commit workflow: stage, generate message, commit, push.\n/// If hub is running, delegates to it for async execution.\npub fn run(\n push: bool,\n queue: CommitQueueMode,\n include_unhash: bool,\n stage_paths: &[String],\n) -> Result<()> {\n let _git_capture_cache_scope = GitCaptureCacheScope::begin();\n\n // Check if hub is running - if so, delegate\n if hub::hub_healthy(HUB_HOST, HUB_PORT) {\n ensure_git_repo()?;\n let repo_root = git_root_or_cwd();\n ensure_commit_setup(&repo_root)?;\n git_guard::ensure_clean_for_commit(&repo_root)?;\n if should_run_sync_for_secret_fixes(&repo_root)? {\n return run_sync(push, queue, include_unhash, stage_paths);\n }\n return delegate_to_hub(push, queue, include_unhash, stage_paths);\n }\n\n run_sync(push, queue, include_unhash, stage_paths)\n}\n\nfn save_commit_checkpoint_for_repo(repo_root: &Path) {\n let now = chrono::Utc::now().to_rfc3339();\n let (session_id, last_ts) =\n match ai::get_last_entry_timestamp_for_path(&repo_root.to_path_buf()) {\n Ok(Some((session_id, last_ts))) => (Some(session_id), Some(last_ts)),\n Ok(None) => (None, Some(now.clone())),\n Err(err) => {\n debug!(\n \"failed to resolve latest session timestamp for checkpoint: {}\",\n err\n );\n (None, Some(now.clone()))\n }\n };\n let checkpoint = ai::CommitCheckpoint {\n timestamp: now,\n session_id,\n last_entry_timestamp: last_ts,\n };\n if let Err(err) = ai::save_checkpoint(&repo_root.to_path_buf(), checkpoint) {\n debug!(\"failed to save commit checkpoint: {}\", err);\n }\n}\n\nfn git_commit_timestamp_iso(repo_root: &Path, rev: &str) -> Option<String> {\n git_capture_in(repo_root, &[\"show\", \"-s\", \"--format=%cI\", rev])\n .ok()\n .map(|ts| ts.trim().to_string())\n .filter(|ts| !ts.is_empty())\n}\n\n#[derive(Debug, Clone)]\nstruct MyflowSessionWindow {\n mode: String,\n since_ts: Option<String>,\n until_ts: Option<String>,\n collected_at: String,\n}\n\nimpl MyflowSessionWindow {\n fn new(mode: &str, since_ts: Option<String>, until_ts: Option<String>) -> Self {\n Self {\n mode: mode.to_string(),\n since_ts,\n until_ts,\n collected_at: chrono::Utc::now().to_rfc3339(),\n }\n }\n}\n\nfn collect_sync_sessions_for_commit_with_window(\n repo_root: &Path,\n) -> (Vec<ai::GitEditSessionData>, MyflowSessionWindow) {\n let until_ts = git_commit_timestamp_iso(repo_root, \"HEAD\");\n let since_ts = git_commit_timestamp_iso(repo_root, \"HEAD~1\");\n\n if until_ts.is_some() {\n match ai::get_sessions_for_gitedit_between(\n &repo_root.to_path_buf(),\n since_ts.as_deref(),\n until_ts.as_deref(),\n ) {\n Ok(sessions) => {\n return (\n sessions,\n MyflowSessionWindow::new(\"commit_window\", since_ts, until_ts),\n );\n }\n Err(err) => {\n debug!(\n \"failed to collect AI sessions in commit timestamp window (since={:?}, until={:?}): {}\",\n since_ts, until_ts, err\n );\n }\n }\n }\n\n match ai::get_sessions_for_gitedit(&repo_root.to_path_buf()) {\n Ok(sessions) => (\n sessions,\n MyflowSessionWindow::new(\"checkpoint_fallback\", since_ts, until_ts),\n ),\n Err(err) => {\n debug!(\n \"failed to collect AI sessions using checkpoint fallback: {}\",\n err\n );\n (\n Vec::new(),\n MyflowSessionWindow::new(\"checkpoint_fallback\", since_ts, until_ts),\n )\n }\n }\n}\n\nfn collect_sync_sessions_for_pending_commit_with_window(\n repo_root: &Path,\n) -> (Vec<ai::GitEditSessionData>, MyflowSessionWindow) {\n // commit-with-check calls this before creating the new commit; use HEAD as the lower\n // bound and include everything after it so current-cycle AI exchanges are not dropped.\n let since_ts = git_commit_timestamp_iso(repo_root, \"HEAD\");\n\n if since_ts.is_some() {\n match ai::get_sessions_for_gitedit_between(\n &repo_root.to_path_buf(),\n since_ts.as_deref(),\n None,\n ) {\n Ok(sessions) => {\n return (\n sessions,\n MyflowSessionWindow::new(\"pending_window\", since_ts, None),\n );\n }\n Err(err) => {\n debug!(\n \"failed to collect AI sessions for pending commit window (since={:?}): {}\",\n since_ts, err\n );\n }\n }\n }\n\n match ai::get_sessions_for_gitedit(&repo_root.to_path_buf()) {\n Ok(sessions) => (\n sessions,\n MyflowSessionWindow::new(\"checkpoint_fallback\", since_ts, None),\n ),\n Err(err) => {\n debug!(\n \"failed to collect AI sessions using checkpoint fallback: {}\",\n err\n );\n (\n Vec::new(),\n MyflowSessionWindow::new(\"checkpoint_fallback\", since_ts, None),\n )\n }\n }\n}\n\n/// Run commit synchronously (called directly or by hub).\npub fn run_sync(\n push: bool,\n queue: CommitQueueMode,\n include_unhash: bool,\n stage_paths: &[String],\n) -> Result<()> {\n let _git_capture_cache_scope = GitCaptureCacheScope::begin();\n\n let queue_enabled = queue.enabled;\n let push = push && !queue_enabled;\n info!(\n push = push,\n queue = queue_enabled,\n \"starting commit workflow\"\n );\n\n // Ensure we're in a git repo\n ensure_git_repo()?;\n debug!(\"verified git repository\");\n let repo_root = git_root_or_cwd();\n warn_if_commit_invoked_from_subdir(&repo_root);\n ensure_commit_setup(&repo_root)?;\n git_guard::ensure_clean_for_commit(&repo_root)?;\n\n let commit_message_override = resolve_commit_message_override(&repo_root);\n debug!(\n has_override = commit_message_override.is_some(),\n \"resolved commit message override\"\n );\n\n stage_changes_for_commit(&repo_root, stage_paths)?;\n debug!(paths = stage_paths.len(), \"staged changes\");\n ensure_no_internal_staged(&repo_root)?;\n ensure_no_unwanted_staged(&repo_root)?;\n gitignore_policy::enforce_staged_policy(&repo_root)?;\n\n // Check for sensitive files before proceeding\n let sensitive_files = check_sensitive_files(&repo_root);\n warn_sensitive_files(&sensitive_files)?;\n\n // Scan diff content for hardcoded secrets\n let secret_findings = scan_diff_for_secrets(&repo_root);\n warn_secrets_in_diff(&repo_root, &secret_findings)?;\n\n // Check for files with large diffs\n let large_diffs = check_large_diffs(&repo_root);\n warn_large_diffs(&large_diffs)?;\n\n // Get diff\n let diff = git_capture_in(&repo_root, &[\"diff\", \"--cached\"])?;\n if diff.trim().is_empty() {\n println!(\"\\nnotify: No staged changes to commit\");\n print_pending_queue_review_hint(&repo_root);\n bail!(\"No staged changes to commit\");\n }\n debug!(diff_len = diff.len(), \"got cached diff\");\n\n // Get status\n let status = git_capture_in(&repo_root, &[\"status\", \"--short\"]).unwrap_or_default();\n debug!(status_lines = status.lines().count(), \"got git status\");\n\n // Truncate diff if needed\n let (diff_for_prompt, truncated) = truncate_diff(&diff);\n debug!(\n truncated = truncated,\n prompt_len = diff_for_prompt.len(),\n \"prepared diff for prompt\"\n );\n\n // Generate commit message\n print!(\"Generating commit message... \");\n io::stdout().flush()?;\n let mut message = generate_commit_message_with_fallbacks(\n &repo_root,\n None,\n commit_message_override.as_ref(),\n &diff_for_prompt,\n &status,\n truncated,\n )?;\n println!(\"done\\n\");\n debug!(message_len = message.len(), \"got commit message\");\n\n if include_unhash && unhash_capture_enabled() {\n if let Some(unhash_hash) = capture_unhash_bundle(\n &repo_root,\n &diff,\n Some(&status),\n None,\n None,\n None,\n None,\n None,\n None,\n None,\n &message,\n None,\n false,\n ) {\n message = format!(\"{}\\n\\nunhash.sh/{}\", message, unhash_hash);\n }\n }\n\n // Show the message\n println!(\"Commit message:\");\n println!(\"────────────────────────────────────────\");\n println!(\"{}\", message);\n println!(\"────────────────────────────────────────\\n\");\n\n // Commit\n let paragraphs = split_paragraphs(&message);\n debug!(\n paragraphs = paragraphs.len(),\n \"split message into paragraphs\"\n );\n let mut args = vec![\"commit\"];\n for p in ¶graphs {\n args.push(\"-m\");\n args.push(p);\n }\n git_run(&args)?;\n println!(\"✓ Committed\");\n info!(\"created commit\");\n\n log_commit_event_for_repo(&repo_root, &message, \"commit\", None, None);\n\n if queue_enabled {\n match queue_commit_for_review(&repo_root, &message, None, None, None, Vec::new()) {\n Ok(sha) => {\n print_queue_instructions(&repo_root, &sha);\n if queue.open_review {\n open_review_in_rise(&repo_root, &sha);\n }\n }\n Err(err) => println!(\"⚠ Failed to queue commit for review: {}\", err),\n }\n }\n\n // Push if requested\n let mut pushed = false;\n if push {\n let push_remote = config::preferred_git_remote_for_repo(&repo_root);\n let push_branch = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string())\n .trim()\n .to_string();\n print!(\"Pushing... \");\n io::stdout().flush()?;\n\n match git_push_try(&push_remote, &push_branch) {\n PushResult::Success => {\n println!(\"done\");\n info!(\"pushed to remote\");\n pushed = true;\n }\n PushResult::NoRemoteRepo => {\n println!(\"skipped (no remote repo)\");\n info!(\"skipped push - remote repo does not exist\");\n }\n PushResult::RemoteAhead => {\n // Push failed, likely remote has new commits\n println!(\"failed (remote ahead)\");\n print!(\"Pulling with rebase... \");\n io::stdout().flush()?;\n\n match git_pull_rebase_try(&push_remote, &push_branch) {\n Ok(_) => {\n println!(\"done\");\n print!(\"Pushing... \");\n io::stdout().flush()?;\n git_push_run(&push_remote, &push_branch)?;\n println!(\"done\");\n info!(\"pulled and pushed to remote\");\n pushed = true;\n }\n Err(_) => {\n println!(\"conflict!\");\n println!();\n println!(\"Rebase conflict detected. Resolve manually:\");\n println!(\" 1. Fix conflicts in the listed files\");\n println!(\" 2. git add <files>\");\n println!(\" 3. git rebase --continue\");\n println!(\" 4. git push\");\n println!();\n println!(\"Or abort with: git rebase --abort\");\n bail!(\"Rebase conflict - manual resolution required\");\n }\n }\n }\n }\n }\n\n // Record undo action\n record_undo_action(&repo_root, pushed, Some(&message));\n\n // Sync mirrors with AI sessions since previous checkpoint.\n let cwd = std::env::current_dir().unwrap_or_default();\n let sync_gitedit = gitedit_globally_enabled() && gitedit_mirror_enabled_for_commit(&repo_root);\n let sync_myflow = myflow_mirror_enabled(&repo_root);\n let (sync_sessions, sync_window) = if sync_gitedit || sync_myflow {\n let (sessions, window) = collect_sync_sessions_for_commit_with_window(&repo_root);\n (sessions, Some(window))\n } else {\n (Vec::new(), None)\n };\n if sync_gitedit {\n sync_to_gitedit(&cwd, \"commit\", &sync_sessions, None, None);\n }\n if sync_myflow {\n sync_to_myflow(\n &repo_root,\n \"commit\",\n &sync_sessions,\n sync_window.as_ref(),\n None,\n None,\n );\n }\n save_commit_checkpoint_for_repo(&repo_root);\n\n Ok(())\n}\n\n/// Run a fast commit with the provided message (no AI review).\npub fn run_fast(\n message: &str,\n push: bool,\n queue: CommitQueueMode,\n include_unhash: bool,\n stage_paths: &[String],\n) -> Result<()> {\n let queue_enabled = queue.enabled;\n let push = push && !queue_enabled;\n ensure_git_repo()?;\n let repo_root = git_root_or_cwd();\n warn_if_commit_invoked_from_subdir(&repo_root);\n ensure_commit_setup(&repo_root)?;\n git_guard::ensure_clean_for_commit(&repo_root)?;\n\n // Run pre-commit fixers if configured (fast lint/format)\n if let Ok(fixed) = run_fixers(&repo_root) {\n if fixed {\n println!();\n }\n }\n\n stage_changes_for_commit(&repo_root, stage_paths)?;\n ensure_no_internal_staged(&repo_root)?;\n ensure_no_unwanted_staged(&repo_root)?;\n gitignore_policy::enforce_staged_policy(&repo_root)?;\n\n // Check for sensitive files before proceeding\n let cwd = std::env::current_dir()?;\n let sensitive_files = check_sensitive_files(&cwd);\n warn_sensitive_files(&sensitive_files)?;\n\n // Scan diff content for hardcoded secrets\n let secret_findings = scan_diff_for_secrets(&cwd);\n warn_secrets_in_diff(&repo_root, &secret_findings)?;\n\n // Ensure we actually have changes\n let diff = git_capture(&[\"diff\", \"--cached\"])?;\n if diff.trim().is_empty() {\n println!(\"\\nnotify: No staged changes to commit\");\n print_pending_queue_review_hint(&repo_root);\n bail!(\"No staged changes to commit\");\n }\n\n let status = git_capture(&[\"status\", \"--short\"]).unwrap_or_default();\n let mut full_message = message.to_string();\n\n if include_unhash && unhash_capture_enabled() {\n if let Some(unhash_hash) = capture_unhash_bundle(\n &repo_root,\n &diff,\n Some(&status),\n None,\n None,\n None,\n None,\n None,\n None,\n None,\n &full_message,\n None,\n false,\n ) {\n full_message = format!(\"{}\\n\\nunhash.sh/{}\", full_message, unhash_hash);\n }\n }\n\n ensure_no_unwanted_staged(&repo_root)?;\n gitignore_policy::enforce_staged_policy(&repo_root)?;\n\n // Commit\n git_run(&[\"commit\", \"-m\", &full_message])?;\n println!(\"✓ Committed\");\n\n log_commit_event_for_repo(&repo_root, &full_message, \"commit\", None, None);\n\n if queue_enabled {\n match queue_commit_for_review(&repo_root, &full_message, None, None, None, Vec::new()) {\n Ok(sha) => {\n print_queue_instructions(&repo_root, &sha);\n if queue.open_review {\n open_review_in_rise(&repo_root, &sha);\n }\n }\n Err(err) => println!(\"⚠ Failed to queue commit for review: {}\", err),\n }\n }\n\n // Push if requested\n let mut pushed = false;\n if push {\n let push_remote = config::preferred_git_remote_for_repo(&repo_root);\n let push_branch = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string())\n .trim()\n .to_string();\n print!(\"Pushing... \");\n io::stdout().flush()?;\n\n match git_push_try(&push_remote, &push_branch) {\n PushResult::Success => {\n println!(\"done\");\n pushed = true;\n }\n PushResult::NoRemoteRepo => {\n println!(\"skipped (no remote repo)\");\n }\n PushResult::RemoteAhead => {\n println!(\"failed (remote ahead)\");\n print!(\"Pulling with rebase... \");\n io::stdout().flush()?;\n\n match git_pull_rebase_try(&push_remote, &push_branch) {\n Ok(_) => {\n println!(\"done\");\n print!(\"Pushing... \");\n io::stdout().flush()?;\n git_push_run(&push_remote, &push_branch)?;\n println!(\"done\");\n pushed = true;\n }\n Err(_) => {\n println!(\"conflict!\");\n println!();\n println!(\"Rebase conflict detected. Resolve manually:\");\n println!(\" 1. Fix conflicts in the listed files\");\n println!(\" 2. git add <files>\");\n println!(\" 3. git rebase --continue\");\n println!(\" 4. git push\");\n println!();\n println!(\"Or abort with: git rebase --abort\");\n bail!(\"Rebase conflict - manual resolution required\");\n }\n }\n }\n }\n }\n\n // Record undo action\n record_undo_action(&repo_root, pushed, Some(&full_message));\n\n let sync_gitedit = gitedit_globally_enabled() && gitedit_mirror_enabled();\n let sync_myflow = myflow_mirror_enabled(&repo_root);\n let (sync_sessions, sync_window) = if sync_gitedit || sync_myflow {\n let (sessions, window) = collect_sync_sessions_for_commit_with_window(&repo_root);\n (sessions, Some(window))\n } else {\n (Vec::new(), None)\n };\n if sync_gitedit {\n sync_to_gitedit(&cwd, \"commit\", &sync_sessions, None, None);\n }\n if sync_myflow {\n sync_to_myflow(\n &repo_root,\n \"commit\",\n &sync_sessions,\n sync_window.as_ref(),\n None,\n None,\n );\n }\n save_commit_checkpoint_for_repo(&repo_root);\n\n Ok(())\n}\n\n/// Commit immediately and trigger Codex queue review in the background.\n/// This gives a fast \"commit now\" UX while preserving deep review asynchronously.\npub fn run_quick_then_async_review(\n push: bool,\n queue: CommitQueueMode,\n include_unhash: bool,\n stage_paths: &[String],\n fast_message: Option<&str>,\n) -> Result<()> {\n let explicit_no_queue = queue.override_flag == Some(false);\n\n if let Some(message) = fast_message {\n run_fast(message, push, queue, include_unhash, stage_paths)?;\n } else {\n run_sync(push, queue, include_unhash, stage_paths)?;\n }\n\n if explicit_no_queue {\n println!(\"Skipped async Codex review because --no-queue was requested.\");\n return Ok(());\n }\n\n let repo_root = git_root_or_cwd();\n let commit_sha = git_capture_in(&repo_root, &[\"rev-parse\", \"--verify\", \"HEAD\"])?\n .trim()\n .to_string();\n if commit_sha.is_empty() {\n bail!(\"failed to resolve HEAD commit after quick commit\");\n }\n\n ensure_commit_queued_for_async_review(&repo_root, &commit_sha)?;\n\n match spawn_async_queue_review(&repo_root, &commit_sha) {\n Ok(()) => {\n println!(\n \"Started async Codex review for {} (running in background).\",\n short_sha(&commit_sha)\n );\n println!(\n \" Check status: f commit-queue show {}\",\n short_sha(&commit_sha)\n );\n }\n Err(err) => {\n println!(\"⚠️ Failed to start async review automatically: {}\", err);\n println!(\n \" Run manually: f commit-queue review {}\",\n short_sha(&commit_sha)\n );\n }\n }\n\n Ok(())\n}\n\nfn ensure_commit_queued_for_async_review(repo_root: &Path, commit_sha: &str) -> Result<()> {\n if resolve_commit_queue_entry(repo_root, commit_sha).is_ok() {\n return Ok(());\n }\n\n let entry = queue_existing_commit_for_approval(repo_root, commit_sha, false)?;\n println!(\"Queued {} for async review.\", short_sha(&entry.commit_sha));\n Ok(())\n}\n\nfn spawn_async_queue_review(repo_root: &Path, commit_sha: &str) -> Result<()> {\n let flow_bin = std::env::current_exe().unwrap_or_else(|_| PathBuf::from(\"f\"));\n\n let mut cmd = Command::new(flow_bin);\n cmd.current_dir(repo_root)\n .arg(\"commit-queue\")\n .arg(\"review\")\n .arg(commit_sha)\n .stdin(Stdio::null())\n .stdout(Stdio::null())\n .stderr(Stdio::null());\n\n cmd.spawn()\n .context(\"failed to spawn background queue review\")?;\n Ok(())\n}\n\n/// Run commit with code review: stage, review with Codex or Claude, generate message, commit, push.\n/// If hub is running, delegates to it for async execution.\npub fn run_with_check(\n push: bool,\n include_context: bool,\n review_selection: ReviewSelection,\n author_message: Option<&str>,\n max_tokens: usize,\n queue: CommitQueueMode,\n include_unhash: bool,\n stage_paths: &[String],\n gate_overrides: CommitGateOverrides,\n) -> Result<()> {\n let _git_capture_cache_scope = GitCaptureCacheScope::begin();\n\n if commit_with_check_async_enabled() && hub::hub_healthy(HUB_HOST, HUB_PORT) {\n ensure_git_repo()?;\n let repo_root = git_root_or_cwd();\n ensure_commit_setup(&repo_root)?;\n git_guard::ensure_clean_for_commit(&repo_root)?;\n if should_run_sync_for_secret_fixes(&repo_root)? {\n return run_with_check_sync(\n push,\n include_context,\n review_selection,\n author_message,\n max_tokens,\n false,\n queue,\n include_unhash,\n stage_paths,\n gate_overrides,\n );\n }\n return delegate_to_hub_with_check(\n \"commitWithCheck\",\n push,\n include_context,\n review_selection,\n author_message,\n max_tokens,\n queue,\n include_unhash,\n stage_paths,\n gate_overrides,\n );\n }\n\n run_with_check_sync(\n push,\n include_context,\n review_selection,\n author_message,\n max_tokens,\n false,\n queue,\n include_unhash,\n stage_paths,\n gate_overrides,\n )\n}\n\n/// Run commitWithCheck, honoring the global gitedit setting for sync/hash.\npub fn run_with_check_with_gitedit(\n push: bool,\n include_context: bool,\n review_selection: ReviewSelection,\n author_message: Option<&str>,\n max_tokens: usize,\n queue: CommitQueueMode,\n include_unhash: bool,\n stage_paths: &[String],\n gate_overrides: CommitGateOverrides,\n) -> Result<()> {\n let _git_capture_cache_scope = GitCaptureCacheScope::begin();\n\n let force_gitedit = gitedit_globally_enabled();\n if commit_with_check_async_enabled() && hub::hub_healthy(HUB_HOST, HUB_PORT) {\n ensure_git_repo()?;\n let repo_root = git_root_or_cwd();\n ensure_commit_setup(&repo_root)?;\n git_guard::ensure_clean_for_commit(&repo_root)?;\n if should_run_sync_for_secret_fixes(&repo_root)? {\n return run_with_check_sync(\n push,\n include_context,\n review_selection,\n author_message,\n max_tokens,\n force_gitedit,\n queue,\n include_unhash,\n stage_paths,\n gate_overrides,\n );\n }\n return delegate_to_hub_with_check(\n \"commit\", // CLI command name\n push,\n include_context,\n review_selection,\n author_message,\n max_tokens,\n queue,\n include_unhash,\n stage_paths,\n gate_overrides,\n );\n }\n\n run_with_check_sync(\n push,\n include_context,\n review_selection,\n author_message,\n max_tokens,\n force_gitedit,\n queue,\n include_unhash,\n stage_paths,\n gate_overrides,\n )\n}\n\nfn commit_with_check_async_enabled() -> bool {\n // Check TypeScript config first\n if let Some(ts_config) = config::load_ts_config() {\n if let Some(flow) = ts_config.flow {\n if let Some(commit) = flow.commit {\n if let Some(async_enabled) = commit.async_enabled {\n return async_enabled;\n }\n }\n }\n }\n\n let repo_root = git_root_or_cwd();\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n return cfg.options.commit_with_check_async.unwrap_or(true);\n }\n return true;\n }\n\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n return cfg.options.commit_with_check_async.unwrap_or(true);\n }\n }\n\n true\n}\n\nfn commit_with_check_use_repo_root() -> bool {\n let repo_root = git_root_or_cwd();\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n return cfg.options.commit_with_check_use_repo_root.unwrap_or(true);\n }\n return true;\n }\n\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n return cfg.options.commit_with_check_use_repo_root.unwrap_or(true);\n }\n }\n\n true\n}\n\nfn resolve_commit_with_check_root() -> Result<std::path::PathBuf> {\n if !commit_with_check_use_repo_root() {\n return std::env::current_dir().context(\"failed to get current directory\");\n }\n\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"--show-toplevel\"])\n .output()\n .context(\"failed to run git rev-parse --show-toplevel\")?;\n\n if !output.status.success() {\n bail!(\"failed to resolve git repo root\");\n }\n\n let root = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if root.is_empty() {\n bail!(\"git repo root was empty\");\n }\n\n Ok(std::path::PathBuf::from(root))\n}\n\nconst DEFAULT_COMMIT_WITH_CHECK_TIMEOUT_SECS: u64 = 300;\nconst MAX_COMMIT_WITH_CHECK_TIMEOUT_SECS: u64 = 3600;\nconst DEFAULT_COMMIT_WITH_CHECK_REVIEW_RETRIES: u32 = 2;\nconst MAX_COMMIT_WITH_CHECK_REVIEW_RETRIES: u32 = 5;\nconst DEFAULT_COMMIT_WITH_CHECK_RETRY_BACKOFF_SECS: u64 = 3;\n\nfn commit_with_check_timeout_from_env() -> Option<u64> {\n for key in [\n \"FLOW_COMMIT_WITH_CHECK_TIMEOUT_SECS\",\n \"FLOW_COMMIT_TIMEOUT_SECS\",\n ] {\n if let Ok(value) = env::var(key) {\n if let Ok(parsed) = value.trim().parse::<u64>() {\n if parsed > 0 {\n return Some(parsed.min(MAX_COMMIT_WITH_CHECK_TIMEOUT_SECS));\n }\n }\n }\n }\n None\n}\n\nfn commit_with_check_timeout_secs() -> u64 {\n if let Some(timeout) = commit_with_check_timeout_from_env() {\n return timeout;\n }\n\n let repo_root = git_root_or_cwd();\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n return cfg\n .options\n .commit_with_check_timeout_secs\n .unwrap_or(DEFAULT_COMMIT_WITH_CHECK_TIMEOUT_SECS)\n .clamp(1, MAX_COMMIT_WITH_CHECK_TIMEOUT_SECS);\n }\n return DEFAULT_COMMIT_WITH_CHECK_TIMEOUT_SECS;\n }\n\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n return cfg\n .options\n .commit_with_check_timeout_secs\n .unwrap_or(DEFAULT_COMMIT_WITH_CHECK_TIMEOUT_SECS)\n .clamp(1, MAX_COMMIT_WITH_CHECK_TIMEOUT_SECS);\n }\n }\n\n DEFAULT_COMMIT_WITH_CHECK_TIMEOUT_SECS\n}\n\nfn commit_with_check_review_retries() -> u32 {\n for key in [\n \"FLOW_COMMIT_WITH_CHECK_REVIEW_RETRIES\",\n \"FLOW_COMMIT_REVIEW_RETRIES\",\n ] {\n if let Ok(value) = env::var(key) {\n if let Ok(parsed) = value.trim().parse::<u32>() {\n return parsed.min(MAX_COMMIT_WITH_CHECK_REVIEW_RETRIES);\n }\n }\n }\n\n let repo_root = git_root_or_cwd();\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n return cfg\n .options\n .commit_with_check_review_retries\n .unwrap_or(DEFAULT_COMMIT_WITH_CHECK_REVIEW_RETRIES)\n .min(MAX_COMMIT_WITH_CHECK_REVIEW_RETRIES);\n }\n return DEFAULT_COMMIT_WITH_CHECK_REVIEW_RETRIES;\n }\n\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n return cfg\n .options\n .commit_with_check_review_retries\n .unwrap_or(DEFAULT_COMMIT_WITH_CHECK_REVIEW_RETRIES)\n .min(MAX_COMMIT_WITH_CHECK_REVIEW_RETRIES);\n }\n }\n\n DEFAULT_COMMIT_WITH_CHECK_REVIEW_RETRIES\n}\n\nfn commit_with_check_retry_backoff_secs(attempt: u32) -> u64 {\n let mut base = DEFAULT_COMMIT_WITH_CHECK_RETRY_BACKOFF_SECS;\n if let Ok(value) = env::var(\"FLOW_COMMIT_WITH_CHECK_RETRY_BACKOFF_SECS\") {\n if let Ok(parsed) = value.trim().parse::<u64>() {\n if parsed > 0 {\n base = parsed.min(60);\n }\n }\n }\n base.saturating_mul(attempt as u64).min(120)\n}\n\nfn commit_with_check_review_url() -> Option<String> {\n if let Ok(url) = env::var(\"FLOW_REVIEW_URL\") {\n let trimmed = url.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n }\n }\n\n let repo_root = git_root_or_cwd();\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(url) = cfg.options.commit_with_check_review_url {\n let trimmed = url.trim().to_string();\n if !trimmed.is_empty() {\n return Some(trimmed);\n }\n }\n }\n }\n\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n if let Some(url) = cfg.options.commit_with_check_review_url {\n let trimmed = url.trim().to_string();\n if !trimmed.is_empty() {\n return Some(trimmed);\n }\n }\n }\n }\n\n if let Ok(Some(_token)) = crate::env::load_ai_auth_token() {\n if let Ok(api_url) = crate::env::load_ai_api_url() {\n let trimmed = api_url.trim().trim_end_matches('/').to_string();\n if !trimmed.is_empty() {\n return Some(format!(\"{}/api/ai\", trimmed));\n }\n }\n }\n\n None\n}\n\nfn commit_with_check_review_token() -> Option<String> {\n if let Ok(token) = env::var(\"FLOW_REVIEW_TOKEN\") {\n let trimmed = token.trim().to_string();\n if !trimmed.is_empty() {\n return Some(trimmed);\n }\n }\n\n let repo_root = git_root_or_cwd();\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(token) = cfg.options.commit_with_check_review_token {\n let trimmed = token.trim().to_string();\n if !trimmed.is_empty() {\n return Some(trimmed);\n }\n }\n }\n }\n\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n if let Some(token) = cfg.options.commit_with_check_review_token {\n let trimmed = token.trim().to_string();\n if !trimmed.is_empty() {\n return Some(trimmed);\n }\n }\n }\n }\n\n if let Ok(Some(token)) = crate::env::load_ai_auth_token() {\n let trimmed = token.trim().to_string();\n if !trimmed.is_empty() {\n return Some(trimmed);\n }\n }\n\n None\n}\n\npub fn resolve_commit_queue_mode(cli_queue: bool, cli_no_queue: bool) -> CommitQueueMode {\n if cli_no_queue {\n return CommitQueueMode {\n enabled: false,\n override_flag: Some(false),\n open_review: false,\n };\n }\n if cli_queue {\n return CommitQueueMode {\n enabled: true,\n override_flag: Some(true),\n open_review: false,\n };\n }\n\n CommitQueueMode {\n enabled: commit_queue_enabled_from_config(),\n override_flag: None,\n open_review: false,\n }\n}\n\nfn commit_queue_enabled_from_config() -> bool {\n if let Some(ts_config) = config::load_ts_config() {\n if let Some(flow) = ts_config.flow {\n if let Some(commit) = flow.commit {\n if let Some(queue_enabled) = commit.queue {\n return queue_enabled;\n }\n }\n }\n }\n\n let repo_root = git_root_or_cwd();\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(commit) = cfg.commit {\n if let Some(queue_enabled) = commit.queue {\n return queue_enabled;\n }\n }\n }\n }\n\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n if let Some(commit) = cfg.commit {\n if let Some(queue_enabled) = commit.queue {\n return queue_enabled;\n }\n }\n }\n }\n\n true\n}\n\nfn commit_queue_on_issues_enabled(repo_root: &Path) -> bool {\n if let Some(ts_config) = config::load_ts_config() {\n if let Some(flow) = ts_config.flow {\n if let Some(commit) = flow.commit {\n if let Some(queue_on_issues) = commit.queue_on_issues {\n return queue_on_issues;\n }\n }\n }\n }\n\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(commit) = cfg.commit {\n if let Some(queue_on_issues) = commit.queue_on_issues {\n return queue_on_issues;\n }\n }\n }\n }\n\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n if let Some(commit) = cfg.commit {\n if let Some(queue_on_issues) = commit.queue_on_issues {\n return queue_on_issues;\n }\n }\n }\n }\n\n false\n}\n\nfn prompt_yes_no(message: &str) -> Result<bool> {\n print!(\"{} [y/N]: \", message);\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n Ok(answer == \"y\" || answer == \"yes\")\n}\n\nfn prompt_yes_no_default_yes(message: &str) -> Result<bool> {\n if !io::stdin().is_terminal() {\n return Ok(false);\n }\n print!(\"{} [Y/n]: \", message);\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n if answer.is_empty() {\n return Ok(true);\n }\n Ok(answer == \"y\" || answer == \"yes\")\n}\n\nfn resolve_commit_testing_policy(repo_root: &Path) -> CommitTestingPolicy {\n let cfg = config::load_or_default(repo_root.join(\"flow.toml\"));\n let maybe_testing = cfg.commit.and_then(|commit| commit.testing);\n let Some(testing) = maybe_testing else {\n if is_bun_repo_layout(repo_root) {\n return CommitTestingPolicy {\n mode: \"warn\".to_string(),\n runner: \"bun\".to_string(),\n bun_repo_strict: true,\n require_related_tests: true,\n ai_scratch_test_dir: \".ai/test\".to_string(),\n run_ai_scratch_tests: true,\n allow_ai_scratch_to_satisfy_gate: false,\n max_local_gate_seconds: 15,\n };\n }\n return CommitTestingPolicy {\n mode: \"off\".to_string(),\n runner: \"bun\".to_string(),\n bun_repo_strict: true,\n require_related_tests: true,\n ai_scratch_test_dir: \".ai/test\".to_string(),\n run_ai_scratch_tests: true,\n allow_ai_scratch_to_satisfy_gate: false,\n max_local_gate_seconds: 15,\n };\n };\n\n let mode = testing\n .mode\n .unwrap_or_else(|| \"warn\".to_string())\n .to_ascii_lowercase();\n let mode = match mode.as_str() {\n \"warn\" | \"block\" | \"off\" => mode,\n _ => \"warn\".to_string(),\n };\n\n CommitTestingPolicy {\n mode,\n runner: testing\n .runner\n .unwrap_or_else(|| \"bun\".to_string())\n .to_ascii_lowercase(),\n bun_repo_strict: testing.bun_repo_strict.unwrap_or(true),\n require_related_tests: testing.require_related_tests.unwrap_or(true),\n ai_scratch_test_dir: testing\n .ai_scratch_test_dir\n .unwrap_or_else(|| \".ai/test\".to_string()),\n run_ai_scratch_tests: testing.run_ai_scratch_tests.unwrap_or(true),\n allow_ai_scratch_to_satisfy_gate: testing.allow_ai_scratch_to_satisfy_gate.unwrap_or(false),\n max_local_gate_seconds: testing.max_local_gate_seconds.unwrap_or(15),\n }\n}\n\nfn resolve_commit_skill_gate_policy(repo_root: &Path) -> CommitSkillGatePolicy {\n let cfg = config::load_or_default(repo_root.join(\"flow.toml\"));\n let Some(skill_gate) = cfg.commit.and_then(|commit| commit.skill_gate) else {\n return CommitSkillGatePolicy {\n mode: \"off\".to_string(),\n required: Vec::new(),\n min_version: HashMap::new(),\n };\n };\n\n let mut required = skill_gate.required;\n required.retain(|name| !name.trim().is_empty());\n required.sort();\n required.dedup();\n\n let default_mode = if required.is_empty() { \"off\" } else { \"warn\" };\n let mode = skill_gate\n .mode\n .unwrap_or_else(|| default_mode.to_string())\n .to_ascii_lowercase();\n let mode = match mode.as_str() {\n \"warn\" | \"block\" | \"off\" => mode,\n _ => default_mode.to_string(),\n };\n\n CommitSkillGatePolicy {\n mode,\n required,\n min_version: skill_gate.min_version.unwrap_or_default(),\n }\n}\n\nfn run_required_skill_gate(\n repo_root: &Path,\n gate_overrides: CommitGateOverrides,\n) -> Result<SkillGateReport> {\n if gate_overrides.skip_quality {\n return Ok(SkillGateReport {\n pass: true,\n mode: \"off\".to_string(),\n override_flag: Some(\"skip-quality\".to_string()),\n ..SkillGateReport::default()\n });\n }\n\n let policy = resolve_commit_skill_gate_policy(repo_root);\n if policy.mode == \"off\" || policy.required.is_empty() {\n return Ok(SkillGateReport {\n pass: true,\n mode: policy.mode,\n required_skills: policy.required,\n ..SkillGateReport::default()\n });\n }\n\n let mut report = SkillGateReport {\n pass: true,\n mode: policy.mode.clone(),\n override_flag: None,\n required_skills: policy.required.clone(),\n missing_skills: Vec::new(),\n version_failures: Vec::new(),\n loaded_versions: HashMap::new(),\n };\n\n for skill_name in &policy.required {\n let skill_content = skills::read_skill_content_at(repo_root, skill_name)?;\n if skill_content.is_none() {\n report.missing_skills.push(skill_name.clone());\n continue;\n }\n\n if let Some(required_version) = policy.min_version.get(skill_name) {\n let local_version = skills::read_skill_version_at(repo_root, skill_name)?;\n match local_version {\n Some(version) => {\n report.loaded_versions.insert(skill_name.clone(), version);\n if version < *required_version {\n report.version_failures.push(format!(\n \"{} has version {}, requires >= {}\",\n skill_name, version, required_version\n ));\n }\n }\n None => {\n report.version_failures.push(format!(\n \"{} is missing frontmatter version (requires >= {})\",\n skill_name, required_version\n ));\n }\n }\n } else if let Some(version) = skills::read_skill_version_at(repo_root, skill_name)? {\n report.loaded_versions.insert(skill_name.clone(), version);\n }\n }\n\n report.pass = report.missing_skills.is_empty() && report.version_failures.is_empty();\n if !report.pass {\n for missing in &report.missing_skills {\n eprintln!(\n \" skills: required skill '{}' is missing in .ai/skills/\",\n missing\n );\n }\n for failure in &report.version_failures {\n eprintln!(\" skills: {}\", failure);\n }\n if policy.mode == \"block\" {\n bail!(\"Commit blocked by required skill gate\");\n }\n eprintln!(\" skills: warning only (mode=warn)\");\n }\n\n Ok(report)\n}\n\nfn build_required_skills_prompt_context(\n repo_root: &Path,\n skill_report: &SkillGateReport,\n) -> String {\n if skill_report.required_skills.is_empty() {\n return String::new();\n }\n\n let mut sections = Vec::new();\n for skill_name in &skill_report.required_skills {\n if let Ok(Some(content)) = skills::read_skill_content_at(repo_root, skill_name) {\n sections.push(format!(\"## Skill: {}\\n{}\", skill_name, content));\n }\n }\n if sections.is_empty() {\n return String::new();\n }\n format!(\n \"\\nRequired workflow skills for this repo. Follow these constraints while reviewing and generating output:\\n\\n{}\\n\",\n sections.join(\"\\n\\n\")\n )\n}\n\nfn combine_review_instructions(\n custom: Option<&str>,\n required_skill_context: &str,\n) -> Option<String> {\n let mut parts = Vec::new();\n if let Some(custom) = custom {\n if !custom.trim().is_empty() {\n parts.push(custom.trim().to_string());\n }\n }\n if !required_skill_context.trim().is_empty() {\n parts.push(required_skill_context.trim().to_string());\n }\n if parts.is_empty() {\n None\n } else {\n Some(parts.join(\"\\n\\n\"))\n }\n}\n\n// ---------------------------------------------------------------------------\n// Invariant gate: check staged diff against [invariants] from flow.toml\n// ---------------------------------------------------------------------------\n\n#[derive(Debug, Default)]\nstruct InvariantFinding {\n severity: String, // \"critical\" | \"warning\" | \"note\"\n category: String, // \"forbidden\" | \"deps\" | \"files\" | \"terminology\"\n message: String,\n file: Option<String>,\n}\n\n#[derive(Debug, Default)]\nstruct InvariantGateReport {\n findings: Vec<InvariantFinding>,\n}\n\nimpl InvariantGateReport {\n /// Build prompt context from findings + invariants for AI review injection.\n fn to_prompt_context(&self, inv: &config::InvariantsConfig) -> String {\n let mut parts = Vec::new();\n\n // Always inject invariants into prompt even if no findings.\n if let Some(style) = inv.architecture_style.as_deref() {\n parts.push(format!(\"Architecture: {}\", style));\n }\n if !inv.non_negotiable.is_empty() {\n parts.push(format!(\n \"Non-negotiable rules:\\n{}\",\n inv.non_negotiable\n .iter()\n .map(|r| format!(\"- {}\", r))\n .collect::<Vec<_>>()\n .join(\"\\n\")\n ));\n }\n if !inv.terminology.is_empty() {\n let terms: Vec<String> = inv\n .terminology\n .iter()\n .map(|(k, v)| format!(\"- {}: {}\", k, v))\n .collect();\n parts.push(format!(\n \"Terminology (do not rename):\\n{}\",\n terms.join(\"\\n\")\n ));\n }\n\n if !self.findings.is_empty() {\n let finding_lines: Vec<String> = self\n .findings\n .iter()\n .map(|f| {\n let loc = f.file.as_deref().unwrap_or(\"(repo)\");\n format!(\" [{}] {} — {}\", f.severity, loc, f.message)\n })\n .collect();\n parts.push(format!(\n \"Invariant findings on staged files:\\n{}\",\n finding_lines.join(\"\\n\")\n ));\n }\n\n if parts.is_empty() {\n return String::new();\n }\n format!(\n \"\\n## Project Invariants (enforced by flow)\\n\\n{}\\n\",\n parts.join(\"\\n\\n\")\n )\n }\n}\n\nfn resolve_invariants_config(repo_root: &Path) -> Option<config::InvariantsConfig> {\n let cfg = config::load_or_default(repo_root.join(\"flow.toml\"));\n cfg.invariants\n}\n\nfn run_invariant_gate(\n repo_root: &Path,\n diff: &str,\n changed_files: &[String],\n gate_overrides: CommitGateOverrides,\n) -> Result<InvariantGateReport> {\n if gate_overrides.skip_quality {\n return Ok(InvariantGateReport {\n findings: Vec::new(),\n });\n }\n\n let Some(inv) = resolve_invariants_config(repo_root) else {\n return Ok(InvariantGateReport {\n findings: Vec::new(),\n });\n };\n\n let mode = inv.mode.as_deref().unwrap_or(\"warn\").to_ascii_lowercase();\n if mode == \"off\" {\n return Ok(InvariantGateReport {\n findings: Vec::new(),\n });\n }\n\n let mut findings: Vec<InvariantFinding> = Vec::new();\n\n // 1. Forbidden patterns in diff content.\n let skip_files = [\"flow.toml\"];\n for pattern in &inv.forbidden {\n let pat_lower = pattern.to_lowercase();\n let mut current_file: Option<String> = None;\n let mut skip_current = false;\n for line in diff.lines() {\n if let Some(file) = line.strip_prefix(\"+++ b/\") {\n let file = file.trim().trim_matches('\"');\n current_file = Some(file.to_string());\n skip_current = skip_files.iter().any(|s| file.ends_with(s));\n continue;\n }\n if current_file\n .as_deref()\n .is_some_and(|f| f.trim().trim_matches('\"').ends_with(\"flow.toml\"))\n {\n continue;\n }\n if skip_current {\n continue;\n }\n // Only check added lines (lines starting with +, excluding +++ header).\n if !line.starts_with('+') || line.starts_with(\"+++\") {\n continue;\n }\n if line.to_lowercase().contains(&pat_lower) {\n findings.push(InvariantFinding {\n severity: \"warning\".to_string(),\n category: \"forbidden\".to_string(),\n message: format!(\"Forbidden pattern '{}' in added line\", pattern),\n file: current_file.clone(),\n });\n break; // One finding per pattern is enough.\n }\n }\n }\n\n // 2. Dependency policy: check package.json changes for unapproved deps.\n if let Some(deps_config) = &inv.deps {\n let policy = deps_config.policy.as_deref().unwrap_or(\"approval_required\");\n if policy == \"approval_required\" && !deps_config.approved.is_empty() {\n for file in changed_files {\n if file.ends_with(\"package.json\") {\n let full = repo_root.join(file);\n if let Ok(contents) = fs::read_to_string(&full) {\n check_unapproved_deps(\n &contents,\n &deps_config.approved,\n file,\n &mut findings,\n );\n }\n }\n }\n }\n }\n\n // 3. File size limits.\n if let Some(files_config) = &inv.files {\n if let Some(max_lines) = files_config.max_lines {\n for file in changed_files {\n let full = repo_root.join(file);\n if let Ok(contents) = fs::read_to_string(&full) {\n let line_count = contents.lines().count() as u32;\n if line_count > max_lines {\n findings.push(InvariantFinding {\n severity: \"warning\".to_string(),\n category: \"files\".to_string(),\n message: format!(\"File has {} lines (max {})\", line_count, max_lines),\n file: Some(file.clone()),\n });\n }\n }\n }\n }\n }\n\n let has_blocking = findings\n .iter()\n .any(|f| f.severity == \"critical\" || f.severity == \"warning\");\n\n // Print findings.\n if !findings.is_empty() {\n eprintln!();\n eprintln!(\" invariants: {} finding(s)\", findings.len());\n for f in &findings {\n let loc = f.file.as_deref().unwrap_or(\"(diff)\");\n eprintln!(\n \" [{}:{}] {} — {}\",\n f.severity, f.category, loc, f.message\n );\n }\n }\n\n let pass = !has_blocking;\n if !pass && mode == \"block\" {\n bail!(\n \"Commit blocked by invariant gate ({} finding(s))\",\n findings.len()\n );\n }\n if !pass {\n eprintln!(\" invariants: warning only (mode=warn)\");\n }\n\n Ok(InvariantGateReport { findings })\n}\n\n/// Check a package.json for dependencies not on the approved list.\nfn check_unapproved_deps(\n package_json: &str,\n approved: &[String],\n file_path: &str,\n findings: &mut Vec<InvariantFinding>,\n) {\n let Ok(parsed) = serde_json::from_str::<serde_json::Value>(package_json) else {\n return;\n };\n\n let dep_sections = [\"dependencies\", \"devDependencies\", \"peerDependencies\"];\n for section in &dep_sections {\n if let Some(deps) = parsed.get(section).and_then(|v| v.as_object()) {\n for dep_name in deps.keys() {\n if !approved.iter().any(|a| a == dep_name) {\n findings.push(InvariantFinding {\n severity: \"warning\".to_string(),\n category: \"deps\".to_string(),\n message: format!(\n \"'{}' in {} is not on the approved list\",\n dep_name, section\n ),\n file: Some(file_path.to_string()),\n });\n }\n }\n }\n }\n}\n\nfn is_bun_repo_layout(repo_root: &Path) -> bool {\n if repo_root.join(\"build.zig\").exists() && repo_root.join(\"src/bun.js\").exists() {\n return true;\n }\n let agents_file = repo_root.join(\"AGENTS.md\");\n if let Ok(contents) = fs::read_to_string(agents_file) {\n return contents.contains(\"This is the Bun repository\");\n }\n false\n}\n\nfn looks_like_source_file_for_test_gate(path: &str) -> bool {\n let normalized = path.replace('\\\\', \"/\");\n let ext = Path::new(&normalized)\n .extension()\n .and_then(|s| s.to_str())\n .unwrap_or(\"\")\n .to_ascii_lowercase();\n matches!(\n ext.as_str(),\n \"js\" | \"jsx\" | \"ts\" | \"tsx\" | \"mjs\" | \"cjs\" | \"rs\"\n )\n}\n\nfn is_test_file_path(path: &str) -> bool {\n let normalized = path.replace('\\\\', \"/\").to_ascii_lowercase();\n normalized.contains(\"/__tests__/\")\n || normalized.ends_with(\".test.js\")\n || normalized.ends_with(\".test.jsx\")\n || normalized.ends_with(\".test.ts\")\n || normalized.ends_with(\".test.tsx\")\n || normalized.ends_with(\".spec.js\")\n || normalized.ends_with(\".spec.jsx\")\n || normalized.ends_with(\".spec.ts\")\n || normalized.ends_with(\".spec.tsx\")\n || normalized.ends_with(\"_test.rs\")\n}\n\nfn normalize_rel_path(path: &Path) -> String {\n path.to_string_lossy().replace('\\\\', \"/\")\n}\n\nfn normalize_dir_path(path: &str) -> String {\n let mut normalized = path.replace('\\\\', \"/\");\n while normalized.starts_with(\"./\") {\n normalized = normalized.trim_start_matches(\"./\").to_string();\n }\n normalized.trim_end_matches('/').to_string()\n}\n\nfn path_is_within_dir(path: &str, dir: &str) -> bool {\n let normalized_path = normalize_dir_path(path);\n let normalized_dir = normalize_dir_path(dir);\n if normalized_dir.is_empty() {\n return false;\n }\n normalized_path == normalized_dir || normalized_path.starts_with(&(normalized_dir + \"/\"))\n}\n\nfn find_ai_scratch_tests(repo_root: &Path, scratch_dir: &str) -> Vec<String> {\n let scratch_dir = normalize_dir_path(scratch_dir);\n if scratch_dir.is_empty() {\n return Vec::new();\n }\n\n let scratch_root = repo_root.join(&scratch_dir);\n if !scratch_root.is_dir() {\n return Vec::new();\n }\n\n let mut out = HashSet::new();\n let mut stack = vec![scratch_root];\n while let Some(dir) = stack.pop() {\n let Ok(entries) = fs::read_dir(&dir) else {\n continue;\n };\n for entry in entries.flatten() {\n let path = entry.path();\n if path.is_dir() {\n stack.push(path);\n continue;\n }\n if !path.is_file() {\n continue;\n }\n let Ok(rel) = path.strip_prefix(repo_root) else {\n continue;\n };\n let rel = normalize_rel_path(rel);\n if is_test_file_path(&rel) {\n out.insert(rel);\n }\n }\n }\n\n let mut tests: Vec<String> = out.into_iter().collect();\n tests.sort();\n tests\n}\n\nfn collect_candidate_js_test_paths(rel_path: &Path) -> Vec<PathBuf> {\n const JS_EXTS: &[&str] = &[\"ts\", \"tsx\", \"js\", \"jsx\", \"mjs\", \"cjs\"];\n let mut out = Vec::new();\n let parent = rel_path.parent().unwrap_or_else(|| Path::new(\"\"));\n let stem = rel_path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n if stem.is_empty() {\n return out;\n }\n\n let base_no_ext = parent.join(stem);\n for ext in JS_EXTS {\n let mut same_dir_test = base_no_ext.clone();\n same_dir_test.set_extension(format!(\"test.{}\", ext));\n out.push(same_dir_test);\n\n let mut same_dir_spec = base_no_ext.clone();\n same_dir_spec.set_extension(format!(\"spec.{}\", ext));\n out.push(same_dir_spec);\n\n let mut in_test_dir = PathBuf::from(\"test\").join(&base_no_ext);\n in_test_dir.set_extension(format!(\"test.{}\", ext));\n out.push(in_test_dir);\n\n let mut in_tests_dir = PathBuf::from(\"tests\").join(&base_no_ext);\n in_tests_dir.set_extension(format!(\"test.{}\", ext));\n out.push(in_tests_dir);\n }\n\n let tests_dir = parent.join(\"__tests__\");\n if let Some(file_name) = rel_path.file_name() {\n out.push(tests_dir.join(file_name));\n }\n\n out\n}\n\nfn collect_candidate_rust_test_paths(rel_path: &Path) -> Vec<PathBuf> {\n let mut out = Vec::new();\n let parent = rel_path.parent().unwrap_or_else(|| Path::new(\"\"));\n let stem = rel_path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"\");\n if stem.is_empty() {\n return out;\n }\n\n out.push(parent.join(format!(\"{}_test.rs\", stem)));\n out.push(PathBuf::from(\"tests\").join(format!(\"{}.rs\", stem)));\n out.push(PathBuf::from(\"tests\").join(format!(\"{}_test.rs\", stem)));\n\n let mut tests_rel = PathBuf::from(\"tests\").join(rel_path);\n tests_rel.set_extension(\"rs\");\n out.push(tests_rel);\n\n out\n}\n\nfn find_related_tests(\n repo_root: &Path,\n changed_files: &[String],\n ai_scratch_test_dir: &str,\n) -> Vec<String> {\n let mut tests = HashSet::new();\n for changed in changed_files {\n let normalized = changed.replace('\\\\', \"/\");\n if path_is_within_dir(&normalized, ai_scratch_test_dir) {\n continue;\n }\n if is_test_file_path(&normalized) {\n tests.insert(normalized);\n continue;\n }\n if !looks_like_source_file_for_test_gate(&normalized) {\n continue;\n }\n\n let rel = Path::new(&normalized);\n let ext = rel\n .extension()\n .and_then(|s| s.to_str())\n .unwrap_or(\"\")\n .to_ascii_lowercase();\n let candidates = if ext == \"rs\" {\n collect_candidate_rust_test_paths(rel)\n } else {\n collect_candidate_js_test_paths(rel)\n };\n\n for candidate in candidates {\n if repo_root.join(&candidate).is_file() {\n let candidate = normalize_rel_path(&candidate);\n if !path_is_within_dir(&candidate, ai_scratch_test_dir) {\n tests.insert(candidate);\n }\n }\n }\n }\n\n let mut out: Vec<String> = tests.into_iter().collect();\n out.sort();\n out\n}\n\nfn find_non_bun_test_tasks(repo_root: &Path, strict_bun_repo: bool) -> Vec<String> {\n let config_path = repo_root.join(\"flow.toml\");\n if !config_path.exists() {\n return Vec::new();\n }\n let cfg = match config::load(&config_path) {\n Ok(cfg) => cfg,\n Err(_) => return Vec::new(),\n };\n\n let mut violations = Vec::new();\n for task in cfg.tasks {\n let name = task.name.to_ascii_lowercase();\n let cmd = task.command.to_ascii_lowercase();\n let looks_like_test_task = name.contains(\"test\")\n || cmd.starts_with(\"test \")\n || cmd.contains(\" test \")\n || cmd.contains(\"bun test\")\n || cmd.contains(\"bun bd test\");\n if !looks_like_test_task {\n continue;\n }\n\n if !cmd.contains(\"bun \") {\n violations.push(format!(\n \"task '{}' must use bun: {}\",\n task.name, task.command\n ));\n continue;\n }\n\n if strict_bun_repo && !cmd.contains(\"bun bd test\") {\n violations.push(format!(\n \"task '{}' must use `bun bd test` in Bun repo: {}\",\n task.name, task.command\n ));\n }\n }\n\n violations\n}\n\nfn apply_testing_gate_failure(mode: &str, message: &str) -> Result<()> {\n eprintln!(\" testing: {}\", message);\n if mode == \"block\" {\n bail!(\"Commit blocked by testing gate\");\n }\n eprintln!(\" testing: warning only (mode=warn)\");\n Ok(())\n}\n\nfn run_pre_commit_test_gate(\n repo_root: &Path,\n changed_files: &[String],\n gate_overrides: CommitGateOverrides,\n) -> Result<()> {\n if gate_overrides.skip_quality || gate_overrides.skip_tests {\n if gate_overrides.skip_tests {\n println!(\"Skipping test gate due to --skip-tests\");\n }\n return Ok(());\n }\n\n let policy = resolve_commit_testing_policy(repo_root);\n if policy.mode == \"off\" {\n return Ok(());\n }\n if policy.runner != \"bun\" {\n return apply_testing_gate_failure(\n &policy.mode,\n &format!(\n \"unsupported test runner '{}'; only bun is currently supported\",\n policy.runner\n ),\n );\n }\n\n let strict_bun_repo = policy.bun_repo_strict && is_bun_repo_layout(repo_root);\n let task_violations = find_non_bun_test_tasks(repo_root, strict_bun_repo);\n if !task_violations.is_empty() {\n return apply_testing_gate_failure(\n &policy.mode,\n &format!(\n \"flow.toml test tasks are not Bun-compliant:\\n {}\",\n task_violations.join(\"\\n \")\n ),\n );\n }\n\n let has_source_changes = changed_files\n .iter()\n .any(|p| looks_like_source_file_for_test_gate(p) && !is_test_file_path(p));\n if !has_source_changes {\n return Ok(());\n }\n\n let related_tests = find_related_tests(repo_root, changed_files, &policy.ai_scratch_test_dir);\n let run_bun_tests = |tests: &[String], label: &str| -> Result<()> {\n let mut args: Vec<String> = Vec::new();\n if strict_bun_repo {\n args.push(\"bd\".to_string());\n args.push(\"test\".to_string());\n } else {\n args.push(\"test\".to_string());\n }\n args.extend(tests.iter().cloned());\n\n println!();\n println!(\"Running local test gate (bun) for {}...\", label);\n println!(\"Command: bun {}\", args.join(\" \"));\n\n let started_at = Instant::now();\n let status = match Command::new(\"bun\")\n .args(args.iter().map(|s| s.as_str()))\n .current_dir(repo_root)\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n {\n Ok(status) => status,\n Err(err) => {\n return apply_testing_gate_failure(\n &policy.mode,\n &format!(\"failed to execute bun test gate: {}\", err),\n );\n }\n };\n let elapsed = started_at.elapsed();\n\n if elapsed > Duration::from_secs(policy.max_local_gate_seconds) {\n eprintln!(\n \" testing: local gate exceeded target budget ({}s > {}s)\",\n elapsed.as_secs(),\n policy.max_local_gate_seconds\n );\n }\n\n if !status.success() {\n return apply_testing_gate_failure(\n &policy.mode,\n &format!(\"bun tests failed for {} (exit status: {})\", label, status),\n );\n }\n\n Ok(())\n };\n\n if related_tests.is_empty() {\n if policy.run_ai_scratch_tests {\n let scratch_tests = find_ai_scratch_tests(repo_root, &policy.ai_scratch_test_dir);\n if !scratch_tests.is_empty() {\n run_bun_tests(&scratch_tests, \"AI scratch tests\")?;\n println!(\n \"✓ AI scratch tests passed ({} test file{})\",\n scratch_tests.len(),\n if scratch_tests.len() == 1 { \"\" } else { \"s\" }\n );\n\n if policy.allow_ai_scratch_to_satisfy_gate {\n println!(\n \"✓ Test gate satisfied by AI scratch tests ({})\",\n policy.ai_scratch_test_dir\n );\n return Ok(());\n }\n }\n }\n\n if policy.require_related_tests {\n return apply_testing_gate_failure(\n &policy.mode,\n &format!(\n \"no related tracked test files detected for staged source changes (AI scratch dir: {}; set commit.testing.allow_ai_scratch_to_satisfy_gate=true to allow scratch-only satisfaction)\",\n policy.ai_scratch_test_dir\n ),\n );\n }\n return Ok(());\n }\n\n run_bun_tests(&related_tests, \"related tracked tests\")?;\n\n println!(\n \"✓ Test gate passed ({} related tracked test file{})\",\n related_tests.len(),\n if related_tests.len() == 1 { \"\" } else { \"s\" }\n );\n Ok(())\n}\n\nfn is_doc_gate_failure(message: &str) -> bool {\n let m = message.to_ascii_lowercase();\n m.contains(\"doc\") || m.contains(\"documentation\")\n}\n\nfn is_test_gate_failure(message: &str) -> bool {\n let m = message.to_ascii_lowercase();\n m.contains(\"test\") || m.contains(\"coverage\")\n}\n\nfn run_review_attempt(\n selection: &ReviewSelection,\n diff: &str,\n session_context: Option<&str>,\n review_instructions: Option<&str>,\n repo_root: &Path,\n) -> Result<(ReviewResult, &'static str, String)> {\n match selection {\n ReviewSelection::Claude(model) => Ok((\n run_claude_review(\n diff,\n session_context,\n review_instructions,\n repo_root,\n *model,\n )?,\n \"claude\",\n model.as_claude_arg().to_string(),\n )),\n ReviewSelection::Codex(model) => Ok((\n run_codex_review(\n diff,\n session_context,\n review_instructions,\n repo_root,\n *model,\n )?,\n \"codex\",\n model.as_codex_arg().to_string(),\n )),\n ReviewSelection::Opencode { model } => Ok((\n run_opencode_review(diff, session_context, review_instructions, repo_root, model)?,\n \"opencode\",\n model.clone(),\n )),\n ReviewSelection::OpenRouter { model } => Ok((\n run_openrouter_review(diff, session_context, review_instructions, repo_root, model)?,\n \"openrouter\",\n openrouter_model_label(model),\n )),\n ReviewSelection::Rise { model } => Ok((\n run_rise_review(diff, session_context, review_instructions, repo_root, model)?,\n \"rise\",\n format!(\"rise:{}\", model),\n )),\n ReviewSelection::Kimi { model } => Ok((\n run_kimi_review(\n diff,\n session_context,\n review_instructions,\n repo_root,\n model.as_deref(),\n )?,\n \"kimi\",\n match model.as_deref() {\n Some(model) if !model.trim().is_empty() => format!(\"kimi:{}\", model),\n _ => \"kimi\".to_string(),\n },\n )),\n }\n}\n\n/// Run commit with code review synchronously (called directly or by hub).\n/// If `include_context` is true, AI session context is passed for better understanding.\n/// `review_selection` determines whether Claude or Codex runs and which model is used.\n/// If `author_message` is provided, it's appended to the commit message.\npub fn run_with_check_sync(\n push: bool,\n include_context: bool,\n review_selection: ReviewSelection,\n author_message: Option<&str>,\n max_tokens: usize,\n force_gitedit: bool,\n queue: CommitQueueMode,\n include_unhash: bool,\n stage_paths: &[String],\n gate_overrides: CommitGateOverrides,\n) -> Result<()> {\n let _git_capture_cache_scope = GitCaptureCacheScope::begin();\n\n let push_requested = push;\n let mut queue_enabled = queue.enabled;\n let prefer_codex_over_openrouter =\n review_selection.is_openrouter() && openrouter_review_should_use_codex();\n // Convert tokens to chars (roughly 4 chars per token)\n let max_context = max_tokens * 4;\n info!(\n push = push_requested && !queue_enabled,\n queue = queue_enabled,\n include_context = include_context,\n review_model = if prefer_codex_over_openrouter {\n CodexModel::High.as_codex_arg().to_string()\n } else {\n review_selection.model_label()\n },\n max_tokens = max_tokens,\n \"starting commit with check workflow\"\n );\n\n // Ensure we're in a git repo\n ensure_git_repo()?;\n\n let repo_root = resolve_commit_with_check_root()?;\n warn_if_commit_invoked_from_subdir(&repo_root);\n ensure_commit_setup(&repo_root)?;\n git_guard::ensure_clean_for_commit(&repo_root)?;\n\n // Capture current staged changes so we can restore if we cancel.\n let staged_snapshot = capture_staged_snapshot_in(&repo_root)?;\n\n // Run pre-commit fixers if configured\n if let Ok(fixed) = run_fixers(&repo_root) {\n if fixed {\n println!();\n }\n }\n\n stage_changes_for_commit(&repo_root, stage_paths)?;\n ensure_no_internal_staged(&repo_root)?;\n gitignore_policy::enforce_staged_policy(&repo_root)?;\n\n // Check for sensitive files before proceeding\n let sensitive_files = check_sensitive_files(&repo_root);\n warn_sensitive_files(&sensitive_files)?;\n\n // Scan diff content for hardcoded secrets\n let secret_findings = scan_diff_for_secrets(&repo_root);\n warn_secrets_in_diff(&repo_root, &secret_findings)?;\n\n // Check for files with large diffs\n let large_diffs = check_large_diffs(&repo_root);\n warn_large_diffs(&large_diffs)?;\n\n // Get diff\n let diff = git_capture_in(&repo_root, &[\"diff\", \"--cached\"])?;\n if diff.trim().is_empty() {\n println!(\"\\nnotify: No staged changes to commit\");\n print_pending_queue_review_hint(&repo_root);\n bail!(\"No staged changes to commit\");\n }\n let changed_files = changed_files_from_diff(&diff);\n\n // Enforce required workflow skills before review.\n let skill_gate_report = run_required_skill_gate(&repo_root, gate_overrides)?;\n\n // Fast feedback loop: run impacted tests with Bun before AI review.\n run_pre_commit_test_gate(&repo_root, &changed_files, gate_overrides)?;\n\n // Enforce project invariants (forbidden patterns, dep policy, file size).\n let invariant_report = run_invariant_gate(&repo_root, &diff, &changed_files, gate_overrides)?;\n\n // Get AI session context since last checkpoint (if enabled)\n let session_context = if include_context {\n ai::get_context_since_checkpoint_for_path(&repo_root)\n .ok()\n .flatten()\n .map(|context| truncate_context(&context, max_context))\n } else {\n None\n };\n if let Some(context) = session_context.as_ref() {\n let line_count = context.lines().count();\n println!(\n \"Using AI session context ({} chars, {} lines) since last checkpoint\",\n context.len(),\n line_count\n );\n if should_show_review_context() {\n println!(\"--- AI session context ---\");\n println!(\"{}\", context);\n println!(\"--- End AI session context ---\");\n }\n }\n\n // Merge [commit] review instructions with required skill + invariant instructions.\n let custom_review_instructions = get_review_instructions(&repo_root);\n let required_skill_context =\n build_required_skills_prompt_context(&repo_root, &skill_gate_report);\n let invariant_context = resolve_invariants_config(&repo_root)\n .map(|inv| invariant_report.to_prompt_context(&inv))\n .unwrap_or_default();\n let combined_extra = format!(\"{}{}\", required_skill_context, invariant_context);\n let review_instructions =\n combine_review_instructions(custom_review_instructions.as_deref(), &combined_extra);\n\n // Run code review with configured fallbacks.\n let review_attempts =\n review_attempts_for_selection(&repo_root, &review_selection, prefer_codex_over_openrouter);\n let primary_review_attempt = review_attempts\n .first()\n .cloned()\n .unwrap_or_else(|| review_selection.clone());\n\n println!(\n \"\\nRunning {} review...\",\n review_tool_label(&primary_review_attempt)\n );\n println!(\"Model: {}\", primary_review_attempt.model_label());\n if session_context.is_some() {\n println!(\"(with AI session context)\");\n }\n if custom_review_instructions.is_some()\n || !required_skill_context.is_empty()\n || !invariant_context.trim().is_empty()\n {\n println!(\"(with custom review instructions)\");\n }\n println!(\"────────────────────────────────────────\");\n\n let mut review_reviewer_label = \"codex\";\n let mut review_model_label = primary_review_attempt.model_label();\n let mut review_selection_used = primary_review_attempt.clone();\n let mut review_failures: Vec<String> = Vec::new();\n let mut review_result: Option<ReviewResult> = None;\n\n for (idx, attempt) in review_attempts.iter().enumerate() {\n if idx > 0 {\n println!(\"────────────────────────────────────────\");\n println!(\n \"Retrying review with fallback: {} ({})\",\n review_tool_label(attempt),\n attempt.model_label()\n );\n println!(\"────────────────────────────────────────\");\n }\n\n match run_review_attempt(\n attempt,\n &diff,\n session_context.as_deref(),\n review_instructions.as_deref(),\n &repo_root,\n ) {\n Ok((review, reviewer_label, model_label)) => {\n review_reviewer_label = reviewer_label;\n review_model_label = model_label;\n review_selection_used = attempt.clone();\n review_result = Some(review);\n break;\n }\n Err(err) => {\n let error_message = format!(\n \"{} ({}) failed: {}\",\n review_tool_label(attempt),\n attempt.model_label(),\n err\n );\n review_failures.push(error_message.clone());\n if idx + 1 < review_attempts.len() {\n println!(\"⚠ {}. Trying next fallback...\", error_message);\n }\n }\n }\n }\n\n let mut review_failed_open = false;\n let review = if let Some(review) = review_result {\n review\n } else if commit_review_fail_open_enabled(&repo_root) {\n review_failed_open = true;\n println!(\n \"⚠ Review failed across all attempts; continuing because commit.review_fail_open = true.\"\n );\n if let Some(last_error) = review_failures.last() {\n println!(\"Last review error: {}\", last_error);\n }\n ReviewResult {\n issues_found: false,\n issues: Vec::new(),\n summary: Some(format!(\n \"Review unavailable; commit proceeded in fail-open mode after {} failed attempt(s).\",\n review_failures.len()\n )),\n future_tasks: Vec::new(),\n timed_out: true,\n quality: None,\n }\n } else {\n restore_staged_snapshot_in(&repo_root, &staged_snapshot)?;\n if review_failures.is_empty() {\n bail!(\"review failed: no review attempts were available\");\n }\n bail!(\"review failed:\\n {}\", review_failures.join(\"\\n \"));\n };\n\n println!(\"────────────────────────────────────────\\n\");\n\n // Log review result for async tracking\n let context_chars = session_context.as_ref().map(|c| c.len()).unwrap_or(0);\n ai::log_review_result(\n &repo_root,\n review.issues_found,\n &review.issues,\n context_chars,\n 0, // TODO: track actual review time\n );\n\n if review.timed_out {\n if review_failed_open {\n println!(\"⚠ Review unavailable after fallback attempts, proceeding anyway\");\n } else {\n println!(\n \"⚠ Review timed out after {}s, proceeding anyway\",\n commit_with_check_timeout_secs()\n );\n }\n }\n\n // Show review results (informational only, never blocks)\n if review.issues_found {\n if let Some(summary) = review.summary.as_ref() {\n if !summary.trim().is_empty() {\n println!(\"Summary: {}\", summary.trim());\n println!();\n }\n }\n if !review.issues.is_empty() {\n println!(\"Issues found:\");\n for issue in &review.issues {\n println!(\"- {}\", issue);\n }\n println!();\n\n // Send notification for critical issues (secrets, security)\n let critical_issues: Vec<_> = review\n .issues\n .iter()\n .filter(|i| {\n let lower = i.to_lowercase();\n lower.contains(\"secret\")\n || lower.contains(\".env\")\n || lower.contains(\"credential\")\n || lower.contains(\"api key\")\n || lower.contains(\"password\")\n || lower.contains(\"token\")\n || lower.contains(\"security\")\n || lower.contains(\"vulnerability\")\n })\n .collect();\n\n if !critical_issues.is_empty() {\n let alert_msg = format!(\n \"⚠️ Review found {} critical issue(s): {}\",\n critical_issues.len(),\n critical_issues\n .iter()\n .map(|s| s.as_str())\n .collect::<Vec<_>>()\n .join(\"; \")\n );\n // Truncate if too long\n let alert_msg = if alert_msg.len() > 200 {\n format!(\"{}...\", &alert_msg[..200])\n } else {\n alert_msg\n };\n let _ = notify::send_warning(&alert_msg);\n // Also try to POST to cloud\n send_to_cloud(&repo_root, &review.issues, review.summary.as_deref());\n }\n }\n println!(\"Proceeding with commit...\");\n } else if !review.timed_out {\n if let Some(summary) = review.summary.as_ref() {\n if !summary.trim().is_empty() {\n println!(\"Summary: {}\", summary.trim());\n println!();\n }\n }\n println!(\"✓ Review passed\");\n }\n\n // ── Quality gate check ─────────────────────────────────────────\n if gate_overrides.skip_quality {\n println!(\"Skipping quality gates due to --skip-quality\");\n } else if let Some(ref quality) = review.quality {\n let quality_config = config::load_or_default(repo_root.join(\"flow.toml\"))\n .commit\n .and_then(|c| c.quality)\n .unwrap_or_default();\n let mode = quality_config.mode.as_deref().unwrap_or(\"warn\");\n\n let mut gate_failures: Vec<String> = quality.gate_failures.clone();\n if gate_overrides.skip_docs {\n gate_failures.retain(|failure| !is_doc_gate_failure(failure));\n }\n if gate_overrides.skip_tests {\n gate_failures.retain(|failure| !is_test_gate_failure(failure));\n }\n\n if !gate_failures.is_empty() && mode != \"off\" {\n println!();\n for failure in &gate_failures {\n eprintln!(\" quality: {}\", failure);\n }\n\n if mode == \"block\" {\n eprintln!(\"\\nCommit blocked by quality gates.\");\n eprintln!(\"Fix the issues above, or override with: f commit --skip-quality\");\n restore_staged_snapshot_in(&repo_root, &staged_snapshot)?;\n bail!(\"Quality gate blocked commit\");\n } else {\n eprintln!(\"\\nQuality warnings above. Proceeding with commit.\");\n }\n }\n\n // Auto-generate/update feature docs if enabled\n let auto_docs = quality_config.auto_generate_docs.unwrap_or(true);\n if auto_docs && mode != \"off\" && !gate_overrides.skip_docs {\n let commit_sha_preview = git_capture_in(&repo_root, &[\"rev-parse\", \"--short\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string())\n .trim()\n .to_string();\n\n match features::apply_quality_results(&repo_root, quality, &commit_sha_preview) {\n Ok(actions) => {\n for action in &actions {\n println!(\" feature docs: {}\", action);\n }\n // Stage .ai/features/ changes\n if !actions.is_empty() {\n let _ = std::process::Command::new(\"git\")\n .args([\"add\", \".ai/features/\"])\n .current_dir(&repo_root)\n .output();\n }\n }\n Err(e) => {\n eprintln!(\" warning: failed to update feature docs: {}\", e);\n }\n }\n }\n }\n\n if queue_enabled && queue.override_flag.is_none() && commit_queue_on_issues_enabled(&repo_root)\n {\n if review.issues_found || review.timed_out {\n println!(\"ℹ️ Review found issues; keeping commit queued for approval.\");\n } else {\n println!(\"ℹ️ Review passed; skipping queue because commit.queue_on_issues = true.\");\n queue_enabled = false;\n }\n }\n\n let push = push_requested && !queue_enabled;\n\n let review_run_id = flow_review_run_id(\n &repo_root,\n &diff,\n &review_model_label,\n review_reviewer_label,\n );\n\n // Continue with normal commit flow\n let commit_message_override = resolve_commit_message_override(&repo_root);\n\n // Get status\n let status = git_capture_in(&repo_root, &[\"status\", \"--short\"]).unwrap_or_default();\n\n // Truncate diff if needed\n let (diff_for_prompt, truncated) = truncate_diff(&diff);\n\n // Generate commit message based on the review tool\n print!(\"Generating commit message... \");\n io::stdout().flush()?;\n let message = generate_commit_message_with_fallbacks(\n &repo_root,\n Some(&review_selection_used),\n commit_message_override.as_ref(),\n &diff_for_prompt,\n &status,\n truncated,\n )?;\n println!(\"done\\n\");\n\n // Best-effort: write a private review record into repo-local beads history for later triage.\n // This is written into `.beads/.br_history` inside the current repository.\n if let Err(err) = write_beads_commit_review_record(\n &repo_root,\n review_reviewer_label,\n &review_model_label,\n &review,\n Some(&message),\n ) {\n debug!(\n \"failed to write commit review record to repo-local beads: {}\",\n err\n );\n }\n\n let mut gitedit_sessions: Vec<ai::GitEditSessionData> = Vec::new();\n let mut gitedit_session_hash: Option<String> = None;\n\n let gitedit_mirror_enabled = if force_gitedit {\n gitedit_mirror_enabled_for_commit(&repo_root)\n } else {\n gitedit_mirror_enabled_for_commit_with_check(&repo_root)\n };\n let gitedit_enabled = gitedit_globally_enabled() && gitedit_mirror_enabled;\n let unhash_enabled = include_unhash && unhash_capture_enabled();\n let mut unhash_sessions: Vec<ai::GitEditSessionData> = Vec::new();\n let mut pending_sync_window: Option<MyflowSessionWindow> = None;\n\n if gitedit_enabled || unhash_enabled {\n let (sessions, window) = collect_sync_sessions_for_pending_commit_with_window(&repo_root);\n pending_sync_window = Some(window);\n if !sessions.is_empty() {\n if gitedit_enabled {\n if let Some((owner, repo)) = get_gitedit_project(&repo_root) {\n gitedit_session_hash = gitedit_sessions_hash(&owner, &repo, &sessions);\n }\n gitedit_sessions = sessions.clone();\n }\n if unhash_enabled {\n unhash_sessions = sessions;\n }\n }\n }\n\n // Append author note if provided\n let mut full_message = if let Some(note) = author_message {\n format!(\"{}\\n\\nauthor: {}\", message, note)\n } else {\n message\n };\n\n if let Some(hash) = gitedit_session_hash.as_deref() {\n full_message = format!(\"{}\\n\\ngitedit.dev/{}\", full_message, hash);\n }\n\n if unhash_enabled {\n if let Some(unhash_hash) = capture_unhash_bundle(\n &repo_root,\n &diff,\n Some(&status),\n Some(&review),\n Some(&review_model_label),\n Some(review_reviewer_label),\n review_instructions.as_deref(),\n session_context.as_deref(),\n Some(&unhash_sessions),\n gitedit_session_hash.as_deref(),\n &full_message,\n author_message,\n include_context,\n ) {\n full_message = format!(\"{}\\n\\nunhash.sh/{}\", full_message, unhash_hash);\n }\n }\n\n // Show the message\n println!(\"Commit message:\");\n println!(\"────────────────────────────────────────\");\n println!(\"{}\", full_message);\n println!(\"────────────────────────────────────────\\n\");\n\n // Check if docs need updating (reminder for AI assistant)\n let docs_dir = repo_root.join(\".ai/docs\");\n if docs_dir.exists() {\n let has_new_commands = diff.contains(\"pub enum Commands\")\n || diff.contains(\"Subcommand\")\n || diff.contains(\"#[command(\");\n let has_new_features = diff.contains(\"pub fn run\")\n || diff.contains(\"pub async fn\")\n || diff.lines().any(|l| l.starts_with(\"+pub mod\"));\n\n if has_new_commands || has_new_features {\n println!(\"📝 Docs may need updating (.ai/docs/)\");\n }\n }\n\n ensure_no_internal_staged(&repo_root)?;\n ensure_no_unwanted_staged(&repo_root)?;\n gitignore_policy::enforce_staged_policy(&repo_root)?;\n\n // Commit\n let paragraphs = split_paragraphs(&full_message);\n let mut args = vec![\"commit\"];\n for p in ¶graphs {\n args.push(\"-m\");\n args.push(p);\n }\n git_run(&args)?;\n println!(\"✓ Committed\");\n\n if let Ok(commit_sha) = git_capture_in(&repo_root, &[\"rev-parse\", \"HEAD\"]) {\n let branch = git_capture_in(&repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string());\n ai::log_commit_review(\n &repo_root,\n commit_sha.trim(),\n branch.trim(),\n &full_message,\n &review_model_label,\n review_reviewer_label,\n review.issues_found,\n &review.issues,\n review.summary.as_deref(),\n review.timed_out,\n context_chars,\n );\n } else {\n debug!(\"failed to capture commit SHA for review log\");\n }\n\n let review_summary = ai::CommitReviewSummary {\n model: review_model_label.clone(),\n reviewer: review_reviewer_label.to_string(),\n issues_found: review.issues_found,\n issues: review.issues.clone(),\n summary: review.summary.clone(),\n timed_out: review.timed_out,\n };\n let context_len = if context_chars > 0 {\n Some(context_chars)\n } else {\n None\n };\n log_commit_event_for_repo(\n &repo_root,\n &full_message,\n \"commitWithCheck\",\n Some(review_summary),\n context_len,\n );\n\n // Record review issues as project-scoped todos so they cannot be ignored.\n // This is best-effort: never block commits on todo persistence.\n let mut review_todo_ids: Vec<String> = Vec::new();\n let committed_sha = git_capture_in(&repo_root, &[\"rev-parse\", \"HEAD\"])\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty());\n if let Some(commit_sha) = committed_sha.as_deref() {\n if !env_flag(\"FLOW_REVIEW_ISSUES_TODOS_DISABLE\") {\n if review.issues_found && !review.issues.is_empty() {\n match todo::record_review_issues_as_todos(\n &repo_root,\n commit_sha,\n &review.issues,\n review.summary.as_deref(),\n &review_model_label,\n ) {\n Ok(ids) => {\n if !ids.is_empty() {\n println!(\"Added {} review issue todo(s) to .ai/todos\", ids.len());\n }\n review_todo_ids.extend(ids);\n }\n Err(err) => println!(\"⚠ Failed to record review issues as todos: {}\", err),\n }\n }\n\n if review.timed_out {\n let issue = format!(\n \"Re-run review: review timed out for commit {}\",\n short_sha(commit_sha)\n );\n match todo::record_review_issues_as_todos(\n &repo_root,\n commit_sha,\n &vec![issue],\n review.summary.as_deref(),\n &review_model_label,\n ) {\n Ok(ids) => {\n if !ids.is_empty() {\n println!(\"Added {} review todo(s) to .ai/todos\", ids.len());\n }\n review_todo_ids.extend(ids);\n }\n Err(err) => println!(\"⚠ Failed to record review timeout todo: {}\", err),\n }\n }\n }\n }\n\n // Record review outputs as ephemeral beads in beads_rust\n record_review_outputs_to_beads_rust(\n &repo_root,\n &review,\n review_reviewer_label,\n &review_model_label,\n committed_sha.as_deref(),\n &review_run_id,\n );\n\n let review_report_path = match write_commit_review_markdown_report(\n &repo_root,\n &review,\n review_reviewer_label,\n &review_model_label,\n committed_sha.as_deref(),\n &full_message,\n &review_run_id,\n &review_todo_ids,\n ) {\n Ok(path) => Some(path),\n Err(err) => {\n println!(\"⚠ Failed to write review report: {}\", err);\n None\n }\n };\n\n if queue_enabled {\n match queue_commit_for_review(\n &repo_root,\n &full_message,\n Some(&review),\n Some(&review_model_label),\n Some(review_reviewer_label),\n review_todo_ids,\n ) {\n Ok(sha) => {\n print_queue_instructions(&repo_root, &sha);\n if queue.open_review {\n open_review_in_rise(&repo_root, &sha);\n }\n }\n Err(err) => println!(\"⚠ Failed to queue commit for review: {}\", err),\n }\n }\n\n // Push if requested\n let mut pushed = false;\n if push {\n let push_remote = config::preferred_git_remote_for_repo(&repo_root);\n let push_branch = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string())\n .trim()\n .to_string();\n print!(\"Pushing... \");\n io::stdout().flush()?;\n\n match git_push_try(&push_remote, &push_branch) {\n PushResult::Success => {\n println!(\"done\");\n pushed = true;\n }\n PushResult::NoRemoteRepo => {\n println!(\"skipped (no remote repo)\");\n }\n PushResult::RemoteAhead => {\n println!(\"failed (remote ahead)\");\n print!(\"Pulling with rebase... \");\n io::stdout().flush()?;\n\n match git_pull_rebase_try(&push_remote, &push_branch) {\n Ok(_) => {\n println!(\"done\");\n print!(\"Pushing... \");\n io::stdout().flush()?;\n git_push_run(&push_remote, &push_branch)?;\n println!(\"done\");\n pushed = true;\n }\n Err(_) => {\n println!(\"conflict!\");\n println!();\n println!(\"Rebase conflict detected. Resolve manually:\");\n println!(\" 1. Fix conflicts in the listed files\");\n println!(\" 2. git add <files>\");\n println!(\" 3. git rebase --continue\");\n println!(\" 4. git push\");\n println!();\n println!(\"Or abort with: git rebase --abort\");\n println!(\"\\nnotify: Rebase conflict - manual resolution required\");\n bail!(\"Rebase conflict - manual resolution required\");\n }\n }\n }\n }\n }\n\n // Record undo action (use full_message which contains the commit message)\n record_undo_action(&repo_root, pushed, Some(&full_message));\n\n cleanup_staged_snapshot(&staged_snapshot);\n\n // Advance checkpoint for all commit paths so syncs only include new exchanges.\n save_commit_checkpoint_for_repo(&repo_root);\n\n // Sync to gitedit if enabled\n let should_sync = if force_gitedit {\n gitedit_enabled\n } else {\n push && gitedit_enabled\n };\n\n if should_sync {\n // Build review data for gitedit\n let review_data = GitEditReviewData {\n diff: Some(diff.clone()),\n issues_found: review.issues_found,\n issues: review.issues.clone(),\n summary: review.summary.clone(),\n reviewer: Some(review_reviewer_label.to_string()),\n };\n\n sync_to_gitedit(\n &repo_root,\n \"commit_with_check\",\n &gitedit_sessions,\n gitedit_session_hash.as_deref(),\n Some(&review_data),\n );\n\n // Also sync to myflow if enabled\n if myflow_mirror_enabled(&repo_root) {\n sync_to_myflow(\n &repo_root,\n \"commit_with_check\",\n &gitedit_sessions,\n pending_sync_window.as_ref(),\n Some(&review_data),\n Some(&skill_gate_report),\n );\n }\n } else if myflow_mirror_enabled(&repo_root) {\n // myflow sync even when gitedit sync is skipped\n let review_data = GitEditReviewData {\n diff: Some(diff.clone()),\n issues_found: review.issues_found,\n issues: review.issues.clone(),\n summary: review.summary.clone(),\n reviewer: Some(review_reviewer_label.to_string()),\n };\n // Get AI sessions for myflow even if gitedit didn't collect them\n let (myflow_sessions, myflow_window) =\n collect_sync_sessions_for_commit_with_window(&repo_root);\n sync_to_myflow(\n &repo_root,\n \"commit_with_check\",\n &myflow_sessions,\n Some(&myflow_window),\n Some(&review_data),\n Some(&skill_gate_report),\n );\n }\n\n if let Some(path) = review_report_path.as_ref() {\n println!(\"Review report: {}\", path.display());\n println!(\"Run: f fix {}\", path.display());\n }\n\n Ok(())\n}\n\n/// Write a JSON-RPC message to a writer (newline-delimited).\nfn codex_write_msg(writer: &mut dyn Write, msg: &serde_json::Value) -> Result<()> {\n let mut line = serde_json::to_string(msg)?;\n line.push('\\n');\n writer.write_all(line.as_bytes())?;\n writer.flush()?;\n Ok(())\n}\n\nenum CodexAppServerEvent {\n Line(String),\n ReadError(String),\n Closed,\n}\n\nenum CodexReadOutcome {\n Message(serde_json::Value),\n TimedOut,\n}\n\nfn codex_read_next_message(\n rx: &std::sync::mpsc::Receiver<CodexAppServerEvent>,\n deadline: std::time::Instant,\n) -> Result<CodexReadOutcome> {\n use std::cmp;\n use std::sync::mpsc::RecvTimeoutError;\n use std::time::Instant;\n\n loop {\n let now = Instant::now();\n if now >= deadline {\n return Ok(CodexReadOutcome::TimedOut);\n }\n\n let wait = cmp::min(\n Duration::from_millis(250),\n deadline.saturating_duration_since(now),\n );\n match rx.recv_timeout(wait) {\n Ok(CodexAppServerEvent::Line(line)) => {\n if line.trim().is_empty() {\n continue;\n }\n let msg: serde_json::Value = serde_json::from_str(&line)\n .with_context(|| format!(\"invalid JSON from codex: {}\", line))?;\n return Ok(CodexReadOutcome::Message(msg));\n }\n Ok(CodexAppServerEvent::ReadError(err)) => bail!(\"failed to read from codex: {}\", err),\n Ok(CodexAppServerEvent::Closed) => bail!(\"codex app-server closed stdout unexpectedly\"),\n Err(RecvTimeoutError::Timeout) => continue,\n Err(RecvTimeoutError::Disconnected) => bail!(\"codex app-server reader disconnected\"),\n }\n }\n}\n\n/// Read lines until a JSON-RPC response with the expected id arrives.\nfn codex_read_response(\n rx: &std::sync::mpsc::Receiver<CodexAppServerEvent>,\n expected_id: u64,\n deadline: std::time::Instant,\n) -> Result<serde_json::Value> {\n loop {\n let msg = match codex_read_next_message(rx, deadline)? {\n CodexReadOutcome::Message(msg) => msg,\n CodexReadOutcome::TimedOut => bail!(\"codex app-server response timed out\"),\n };\n if msg.get(\"id\").and_then(|id| id.as_u64()) == Some(expected_id) {\n if let Some(err) = msg.get(\"error\") {\n bail!(\n \"codex error: {}\",\n err.get(\"message\")\n .and_then(|m| m.as_str())\n .unwrap_or(\"unknown error\")\n );\n }\n return Ok(msg);\n }\n }\n}\n\nfn codex_read_response_with_notifications<F>(\n rx: &std::sync::mpsc::Receiver<CodexAppServerEvent>,\n expected_id: u64,\n deadline: std::time::Instant,\n mut on_notification: F,\n) -> Result<serde_json::Value>\nwhere\n F: FnMut(&serde_json::Value),\n{\n loop {\n let msg = match codex_read_next_message(rx, deadline)? {\n CodexReadOutcome::Message(msg) => msg,\n CodexReadOutcome::TimedOut => bail!(\"codex app-server response timed out\"),\n };\n\n if msg.get(\"method\").is_some() && msg.get(\"id\").is_none() {\n on_notification(&msg);\n }\n\n if msg.get(\"id\").and_then(|id| id.as_u64()) == Some(expected_id) {\n if let Some(err) = msg.get(\"error\") {\n bail!(\n \"codex error: {}\",\n err.get(\"message\")\n .and_then(|m| m.as_str())\n .unwrap_or(\"unknown error\")\n );\n }\n return Ok(msg);\n }\n }\n}\n\nfn openrouter_review_should_use_codex() -> bool {\n // Default: true (use Codex /review when available) to improve commit-check quality.\n // Allow opt-out for cases where the user explicitly wants OpenRouter.\n match env::var(\"FLOW_OPENROUTER_REVIEW_USE_CODEX\") {\n Ok(v) if v.trim() == \"0\" || v.trim().eq_ignore_ascii_case(\"false\") => false,\n _ => true,\n }\n}\n\nfn beads_rust_history_dir(repo_root: &Path) -> PathBuf {\n repo_root\n .join(\".beads\")\n .join(\".br_history\")\n .join(\"flow_commit_reviews\")\n}\n\nfn beads_rust_beads_dir(repo_root: &Path) -> PathBuf {\n repo_root.join(\".beads\")\n}\n\nfn flow_commit_reports_dir() -> Option<PathBuf> {\n if let Ok(value) = env::var(\"FLOW_COMMIT_REPORT_DIR\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Some(PathBuf::from(trimmed));\n }\n }\n dirs::home_dir().map(|home| home.join(\".flow\").join(\"commits\"))\n}\n\nfn write_commit_review_markdown_report(\n repo_root: &Path,\n review: &ReviewResult,\n reviewer: &str,\n model_label: &str,\n committed_sha: Option<&str>,\n commit_message: &str,\n review_run_id: &str,\n review_todo_ids: &[String],\n) -> Result<PathBuf> {\n let Some(report_dir) = flow_commit_reports_dir() else {\n bail!(\"could not resolve commit report directory\");\n };\n fs::create_dir_all(&report_dir)?;\n\n let project_name = flow_project_name(repo_root);\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string())\n .trim()\n .to_string();\n let sha_short = committed_sha.map(short_sha).unwrap_or(\"unknown\");\n let stamp = chrono::Utc::now().format(\"%Y%m%d_%H%M%S\").to_string();\n let file_name = format!(\n \"{}-{}-{}-{}.md\",\n safe_label_value(&project_name),\n safe_label_value(&branch),\n sha_short,\n stamp\n );\n let path = report_dir.join(file_name);\n\n let mut md = String::new();\n md.push_str(\"# Flow Commit Review\\n\\n\");\n md.push_str(\"- Generated: \");\n md.push_str(&chrono::Utc::now().to_rfc3339());\n md.push_str(\"\\n- Project: \");\n md.push_str(&project_name);\n md.push_str(\"\\n- Repo Root: \");\n md.push_str(&repo_root.display().to_string());\n md.push_str(\"\\n- Branch: \");\n md.push_str(&branch);\n md.push_str(\"\\n- Commit: \");\n md.push_str(sha_short);\n md.push_str(\"\\n- Reviewer: \");\n md.push_str(reviewer);\n md.push_str(\"\\n- Model: \");\n md.push_str(model_label);\n md.push_str(\"\\n- Review Run ID: \");\n md.push_str(review_run_id);\n md.push_str(\"\\n- Timed Out: \");\n md.push_str(if review.timed_out { \"yes\" } else { \"no\" });\n md.push_str(\"\\n\\n## Commit Message\\n\\n```text\\n\");\n md.push_str(commit_message.trim());\n md.push_str(\"\\n```\\n\");\n\n if let Some(summary) = review\n .summary\n .as_deref()\n .map(str::trim)\n .filter(|s| !s.is_empty())\n {\n md.push_str(\"\\n## Summary\\n\\n\");\n md.push_str(summary);\n md.push('\\n');\n }\n\n md.push_str(\"\\n## Issues\\n\\n\");\n if review.issues.is_empty() {\n md.push_str(\"0. (none)\\n\");\n } else {\n for (idx, issue) in review.issues.iter().enumerate() {\n md.push_str(&(idx + 1).to_string());\n md.push_str(\". \");\n md.push_str(issue.trim());\n md.push('\\n');\n }\n }\n\n md.push_str(\"\\n## Future Tasks\\n\\n\");\n if review.future_tasks.is_empty() {\n md.push_str(\"0. (none)\\n\");\n } else {\n for (idx, task) in review.future_tasks.iter().enumerate() {\n md.push_str(&(idx + 1).to_string());\n md.push_str(\". \");\n md.push_str(task.trim());\n md.push('\\n');\n }\n }\n\n if !review_todo_ids.is_empty() {\n md.push_str(\"\\n## Todo IDs\\n\\n\");\n for todo_id in review_todo_ids {\n md.push_str(\"- \");\n md.push_str(todo_id.trim());\n md.push('\\n');\n }\n }\n\n md.push_str(\"\\n## Next Step\\n\\n```bash\\nf fix \");\n md.push_str(&path.display().to_string());\n md.push_str(\"\\n```\\n\");\n\n fs::write(&path, md).with_context(|| format!(\"write {}\", path.display()))?;\n Ok(path)\n}\n\nfn write_beads_commit_review_record(\n repo_root: &Path,\n reviewer: &str,\n model_label: &str,\n review: &ReviewResult,\n commit_message: Option<&str>,\n) -> Result<()> {\n #[derive(Serialize)]\n struct BeadsCommitReviewRecord<'a> {\n timestamp: String,\n repo_root: String,\n repo_name: String,\n branch: String,\n reviewer: &'a str,\n model: &'a str,\n issues_found: bool,\n issues: Vec<String>,\n future_tasks: Vec<String>,\n summary: Option<String>,\n commit_message: Option<String>,\n }\n\n let dir = beads_rust_history_dir(repo_root);\n fs::create_dir_all(&dir).with_context(|| format!(\"create {}\", dir.display()))?;\n\n let repo_name = repo_root\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(\"repo\")\n .to_string();\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string())\n .trim()\n .to_string();\n let ts = chrono::Utc::now().to_rfc3339();\n let stamp = chrono::Utc::now().format(\"%Y%m%d_%H%M%S\").to_string();\n let safe_repo = repo_name\n .chars()\n .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })\n .collect::<String>();\n let safe_branch = branch\n .chars()\n .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })\n .collect::<String>();\n\n let path = dir.join(format!(\n \"review.{}.{}.{}.json\",\n stamp, safe_repo, safe_branch\n ));\n\n let record = BeadsCommitReviewRecord {\n timestamp: ts,\n repo_root: repo_root.display().to_string(),\n repo_name,\n branch,\n reviewer,\n model: model_label,\n issues_found: review.issues_found,\n issues: review.issues.clone(),\n future_tasks: review.future_tasks.clone(),\n summary: review.summary.clone(),\n commit_message: commit_message.map(|s| s.to_string()),\n };\n let json = serde_json::to_string_pretty(&record)?;\n fs::write(&path, json)?;\n Ok(())\n}\n\n/// Run Codex app-server `review/start` to review staged changes.\n///\n/// Spawns `codex app-server` over stdio JSON-RPC, sends initialize handshake,\n/// creates a thread, and uses the built-in `review/start` method which is\n/// optimized for code review (structured findings, confidence scores, etc.).\nfn run_codex_review(\n _diff: &str,\n session_context: Option<&str>,\n review_instructions: Option<&str>,\n workdir: &std::path::Path,\n model: CodexModel,\n) -> Result<ReviewResult> {\n let max_attempts = commit_with_check_review_retries() + 1; // retries + initial attempt\n let mut last_timeout_secs = 0u64;\n\n for attempt in 1..=max_attempts {\n match run_codex_review_once(_diff, session_context, review_instructions, workdir, model) {\n Ok(result) if result.timed_out && attempt < max_attempts => {\n last_timeout_secs = commit_with_check_timeout_secs();\n let backoff_secs = commit_with_check_retry_backoff_secs(attempt);\n println!(\n \"⚠ Review timed out after {}s, retrying ({}/{}) in {}s...\",\n last_timeout_secs, attempt, max_attempts, backoff_secs\n );\n std::thread::sleep(Duration::from_secs(backoff_secs));\n continue;\n }\n other => return other,\n }\n }\n\n // Should not reach here, but just in case\n Ok(ReviewResult {\n issues_found: false,\n issues: Vec::new(),\n summary: Some(format!(\n \"Codex review timed out after {}s (exhausted {} attempts)\",\n last_timeout_secs, max_attempts\n )),\n future_tasks: Vec::new(),\n timed_out: true,\n quality: None,\n })\n}\n\nfn run_codex_review_once(\n _diff: &str,\n session_context: Option<&str>,\n review_instructions: Option<&str>,\n workdir: &std::path::Path,\n model: CodexModel,\n) -> Result<ReviewResult> {\n use std::io::{BufRead, BufReader};\n use std::sync::mpsc;\n use std::time::Instant;\n\n let timeout = Duration::from_secs(commit_with_check_timeout_secs());\n\n let mut developer_instructions = String::new();\n if let Some(instructions) = review_instructions {\n if !instructions.trim().is_empty() {\n developer_instructions.push_str(\"Additional review instructions:\\n\");\n developer_instructions.push_str(instructions.trim());\n developer_instructions.push_str(\"\\n\\n\");\n }\n }\n if let Some(ctx) = session_context {\n if !ctx.trim().is_empty() {\n developer_instructions.push_str(\"Context:\\n\");\n developer_instructions.push_str(ctx.trim());\n developer_instructions.push_str(\"\\n\\n\");\n }\n }\n\n let codex_bin = configured_codex_bin_for_workdir(workdir);\n\n // Spawn codex app-server (JSON-RPC over stdio)\n let mut child = Command::new(&codex_bin)\n .arg(\"app-server\")\n .current_dir(workdir)\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .stderr(Stdio::piped())\n .spawn()\n .context(\"failed to run codex app-server - is codex installed?\")?;\n\n let mut stdin = child.stdin.take().context(\"missing stdin\")?;\n let stdout = child.stdout.take().context(\"missing stdout\")?;\n let (line_tx, line_rx) = mpsc::channel::<CodexAppServerEvent>();\n let reader_handle = std::thread::spawn(move || {\n let reader = BufReader::new(stdout);\n for line in reader.lines() {\n match line {\n Ok(line) => {\n if line_tx.send(CodexAppServerEvent::Line(line)).is_err() {\n return;\n }\n }\n Err(err) => {\n let _ = line_tx.send(CodexAppServerEvent::ReadError(err.to_string()));\n return;\n }\n }\n }\n let _ = line_tx.send(CodexAppServerEvent::Closed);\n });\n let handshake_deadline = Instant::now() + Duration::from_secs(15);\n\n // Step 1: Initialize handshake\n codex_write_msg(\n &mut stdin,\n &json!({\n \"id\": 1,\n \"method\": \"initialize\",\n \"params\": {\n \"clientInfo\": { \"name\": \"flow\", \"title\": \"Flow CLI\", \"version\": \"0.1.0\" },\n \"capabilities\": { \"experimentalApi\": true }\n }\n }),\n )?;\n let _init_resp = codex_read_response(&line_rx, 1, handshake_deadline)\n .context(\"codex app-server did not respond to initialize\")?;\n\n // Step 2: Send initialized notification\n codex_write_msg(&mut stdin, &json!({ \"method\": \"initialized\" }))?;\n\n // Step 3: Start a thread\n let op_deadline = Instant::now() + timeout;\n codex_write_msg(\n &mut stdin,\n &json!({\n \"id\": 2,\n \"method\": \"thread/start\",\n \"params\": {\n \"cwd\": workdir.to_string_lossy(),\n \"approvalPolicy\": \"never\",\n \"sandbox\": \"read-only\",\n \"model\": model.as_codex_arg(),\n \"developerInstructions\": if developer_instructions.trim().is_empty() { serde_json::Value::Null } else { json!(developer_instructions.trim()) }\n }\n }),\n )?;\n let thread_resp = codex_read_response(&line_rx, 2, op_deadline)?;\n let thread_id = thread_resp\n .pointer(\"/result/threadId\")\n .or_else(|| thread_resp.pointer(\"/result/thread/id\"))\n .and_then(|v| v.as_str())\n .context(\"failed to get threadId from codex\")?\n .to_string();\n\n // Step 4: Start review using review/start with appropriate target\n let target = json!({ \"type\": \"uncommittedChanges\" });\n\n codex_write_msg(\n &mut stdin,\n &json!({\n \"id\": 3,\n \"method\": \"review/start\",\n \"params\": {\n \"threadId\": thread_id,\n \"target\": target,\n \"delivery\": \"inline\"\n }\n }),\n )?;\n let _review_resp = codex_read_response(&line_rx, 3, op_deadline)?;\n\n // Step 5: Collect streaming events until we see the ExitedReviewMode item.\n let mut review_text: Option<String> = None;\n let mut timed_out = false;\n let review_start = Instant::now();\n let hard_cap = Duration::from_secs(commit_with_check_timeout_secs().saturating_mul(3));\n let hard_deadline = review_start + hard_cap;\n let mut idle_deadline = review_start + timeout;\n\n loop {\n let next_deadline = std::cmp::min(idle_deadline, hard_deadline);\n let msg = match codex_read_next_message(&line_rx, next_deadline)? {\n CodexReadOutcome::Message(msg) => msg,\n CodexReadOutcome::TimedOut => {\n timed_out = true;\n break;\n }\n };\n idle_deadline = Instant::now() + timeout;\n let method = msg.get(\"method\").and_then(|m| m.as_str()).unwrap_or(\"\");\n match method {\n \"item/completed\" => {\n let thread_id_msg = msg.pointer(\"/params/threadId\").and_then(|v| v.as_str());\n if thread_id_msg != Some(thread_id.as_str()) {\n continue;\n }\n let item_type = msg.pointer(\"/params/item/type\").and_then(|v| v.as_str());\n if item_type == Some(\"exitedReviewMode\") {\n if let Some(text) = msg.pointer(\"/params/item/review\").and_then(|v| v.as_str())\n {\n review_text = Some(text.to_string());\n break;\n }\n }\n }\n \"review/completed\" => {\n let thread_id_msg = msg.pointer(\"/params/threadId\").and_then(|v| v.as_str());\n if thread_id_msg != Some(thread_id.as_str()) {\n continue;\n }\n if let Some(text) = msg\n .pointer(\"/params/review\")\n .or_else(|| msg.pointer(\"/params/item/review\"))\n .and_then(|v| v.as_str())\n {\n review_text = Some(text.to_string());\n break;\n }\n }\n _ => {}\n }\n }\n\n let review_text = review_text.unwrap_or_default();\n\n if timed_out {\n // Best-effort cleanup\n let _ = codex_write_msg(\n &mut stdin,\n &json!({\n \"id\": 4,\n \"method\": \"thread/archive\",\n \"params\": { \"threadId\": thread_id }\n }),\n );\n drop(stdin);\n let _ = child.kill();\n let _ = child.wait();\n let _ = reader_handle.join();\n\n return Ok(ReviewResult {\n issues_found: false,\n issues: Vec::new(),\n summary: Some(format!(\n \"Codex review timed out after {}s\",\n review_start.elapsed().as_secs()\n )),\n future_tasks: Vec::new(),\n timed_out: true,\n quality: None,\n });\n }\n\n let result = review_text.trim().to_string();\n if !result.is_empty() {\n println!(\"{}\", result);\n }\n\n // Codex review output is plain text. Convert it into the structured JSON\n // format expected by the rest of Flow via a small follow-up turn.\n let mut json_output = String::new();\n let conversion_deadline = Instant::now() + Duration::from_secs(60);\n let conversion_prompt = format!(\n \"Convert the following code review into JSON ONLY with this exact schema: \\\n{{\\\"issues_found\\\": true/false, \\\"issues\\\": [\\\"...\\\"], \\\"summary\\\": \\\"...\\\", \\\"future_tasks\\\": [\\\"...\\\"]}}.\\n\\\nRules:\\n\\\n- Put concrete, actionable problems in issues (include file paths/line hints when present).\\n\\\n- future_tasks are optional follow-up improvements (max 3), not duplicates of issues.\\n\\\n- If review contains no concrete issues, set issues_found=false and issues=[].\\n\\\nReview:\\n{}\",\n result\n );\n\n codex_write_msg(\n &mut stdin,\n &json!({\n \"id\": 5,\n \"method\": \"turn/start\",\n \"params\": {\n \"threadId\": thread_id,\n \"cwd\": workdir.to_string_lossy(),\n \"approvalPolicy\": \"never\",\n \"sandboxPolicy\": { \"type\": \"readOnly\" },\n \"input\": [{ \"type\": \"text\", \"text\": conversion_prompt }]\n }\n }),\n )?;\n let _turn_resp =\n codex_read_response_with_notifications(&line_rx, 5, conversion_deadline, |msg| {\n let method = msg.get(\"method\").and_then(|m| m.as_str()).unwrap_or(\"\");\n if method != \"item/agentMessage/delta\" {\n return;\n }\n let thread_id_msg = msg.pointer(\"/params/threadId\").and_then(|v| v.as_str());\n if thread_id_msg != Some(thread_id.as_str()) {\n return;\n }\n if let Some(delta) = msg.pointer(\"/params/delta\").and_then(|v| v.as_str()) {\n json_output.push_str(delta);\n }\n })?;\n\n // Now stream until turn/completed for this thread, collecting agent deltas.\n loop {\n let msg = match codex_read_next_message(&line_rx, conversion_deadline)? {\n CodexReadOutcome::Message(msg) => msg,\n CodexReadOutcome::TimedOut => break,\n };\n let method = msg.get(\"method\").and_then(|m| m.as_str()).unwrap_or(\"\");\n match method {\n \"item/agentMessage/delta\" => {\n let thread_id_msg = msg.pointer(\"/params/threadId\").and_then(|v| v.as_str());\n if thread_id_msg != Some(thread_id.as_str()) {\n continue;\n }\n if let Some(delta) = msg.pointer(\"/params/delta\").and_then(|v| v.as_str()) {\n json_output.push_str(delta);\n }\n }\n \"turn/completed\" => {\n let thread_id_msg = msg.pointer(\"/params/threadId\").and_then(|v| v.as_str());\n if thread_id_msg == Some(thread_id.as_str()) {\n break;\n }\n }\n _ => {}\n }\n }\n\n let json_output = json_output.trim().to_string();\n let mut review_json = parse_review_json(&json_output);\n let future_tasks = review_json\n .as_ref()\n .map(|parsed| normalize_future_tasks(&parsed.future_tasks))\n .unwrap_or_default();\n let summary = review_json.as_ref().and_then(|r| r.summary.clone());\n let quality = review_json.as_mut().and_then(|r| r.quality.take());\n let (issues_found, issues) = if let Some(ref parsed) = review_json {\n (parsed.issues_found, parsed.issues.clone())\n } else if result.is_empty() {\n (false, Vec::new())\n } else {\n // Fallback: parse bullet items from Codex's rendered review text.\n let mut issues = Vec::new();\n for line in result.lines() {\n let trimmed = line.trim_start();\n if let Some(rest) = trimmed.strip_prefix(\"- \") {\n let t = rest.trim();\n if !t.is_empty() {\n issues.push(t.to_string());\n }\n }\n }\n (!issues.is_empty(), issues)\n };\n\n // Cleanup: archive thread and kill process\n let _ = codex_write_msg(\n &mut stdin,\n &json!({\n \"id\": 4,\n \"method\": \"thread/archive\",\n \"params\": { \"threadId\": thread_id }\n }),\n );\n drop(stdin);\n let _ = child.kill();\n let _ = child.wait();\n let _ = reader_handle.join();\n\n Ok(ReviewResult {\n issues_found,\n issues,\n summary,\n future_tasks,\n timed_out: false,\n quality,\n })\n}\n\npub(crate) fn configured_codex_bin_for_workdir(workdir: &Path) -> String {\n if let Ok(value) = env::var(\"CODEX_BIN\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return normalize_codex_bin_value(trimmed);\n }\n }\n\n let mut roots: Vec<PathBuf> = vec![workdir.to_path_buf()];\n if let Ok(repo_root) = git_capture_in(workdir, &[\"rev-parse\", \"--show-toplevel\"]) {\n let trimmed = repo_root.trim();\n if !trimmed.is_empty() {\n let root = PathBuf::from(trimmed);\n if !roots.iter().any(|r| r == &root) {\n roots.push(root);\n }\n }\n }\n\n for root in roots {\n let cfg_path = root.join(\"flow.toml\");\n if !cfg_path.exists() {\n continue;\n }\n if let Ok(cfg) = config::load(&cfg_path) {\n if let Some(bin) = cfg.options.codex_bin {\n let trimmed = bin.trim();\n if !trimmed.is_empty() {\n return normalize_codex_bin_value(trimmed);\n }\n }\n }\n }\n\n let global_cfg = config::default_config_path();\n if global_cfg.exists() {\n if let Ok(cfg) = config::load(&global_cfg) {\n if let Some(bin) = cfg.options.codex_bin {\n let trimmed = bin.trim();\n if !trimmed.is_empty() {\n return normalize_codex_bin_value(trimmed);\n }\n }\n }\n }\n\n \"codex\".to_string()\n}\n\nfn normalize_codex_bin_value(raw: &str) -> String {\n let trimmed = raw.trim();\n if trimmed.is_empty() {\n return String::new();\n }\n\n if trimmed.starts_with('~')\n || trimmed.starts_with('$')\n || trimmed.starts_with('.')\n || trimmed.starts_with('/')\n || trimmed.contains(std::path::MAIN_SEPARATOR)\n {\n return config::expand_path(trimmed).to_string_lossy().into_owned();\n }\n\n trimmed.to_string()\n}\n\nfn normalize_review_url(url: &str) -> String {\n let trimmed = url.trim().trim_end_matches('/');\n if trimmed.ends_with(\"/review\") {\n trimmed.to_string()\n } else {\n format!(\"{}/review\", trimmed)\n }\n}\n\nfn run_remote_claude_review(\n diff: &str,\n session_context: Option<&str>,\n review_instructions: Option<&str>,\n model: ClaudeModel,\n) -> Result<ReviewResult> {\n let url = match commit_with_check_review_url() {\n Some(url) => url,\n None => bail!(\"remote review URL not configured\"),\n };\n\n let review_url = normalize_review_url(&url);\n let payload = RemoteReviewRequest {\n diff: diff.to_string(),\n context: session_context.map(|value| value.to_string()),\n model: model.as_claude_arg().to_string(),\n review_instructions: review_instructions.map(|v| v.to_string()),\n };\n\n let client = crate::http_client::blocking_with_timeout(Duration::from_secs(\n commit_with_check_timeout_secs(),\n ))\n .context(\"failed to create HTTP client for remote review\")?;\n\n let mut request = client.post(&review_url).json(&payload);\n if let Some(token) = commit_with_check_review_token() {\n request = request.bearer_auth(token);\n }\n\n let response = request\n .send()\n .context(\"failed to send remote review request\")?;\n\n if !response.status().is_success() {\n if response.status() == StatusCode::UNAUTHORIZED {\n bail!(\"remote review unauthorized. Run `f auth` to login.\");\n }\n if response.status() == StatusCode::PAYMENT_REQUIRED {\n bail!(\"remote review requires an active subscription. Visit myflow to subscribe.\");\n }\n bail!(\"remote review failed: HTTP {}\", response.status());\n }\n\n let payload: RemoteReviewResponse = response\n .json()\n .context(\"failed to parse remote review response\")?;\n\n if !payload.stderr.trim().is_empty() {\n debug!(stderr = payload.stderr.as_str(), \"remote claude stderr\");\n }\n\n let result = payload.output;\n let mut review_json = parse_review_json(&result);\n let future_tasks = review_json\n .as_ref()\n .map(|parsed| normalize_future_tasks(&parsed.future_tasks))\n .unwrap_or_default();\n let summary = review_json.as_ref().and_then(|r| r.summary.clone());\n let quality = review_json.as_mut().and_then(|r| r.quality.take());\n let (issues_found, issues) = if let Some(ref parsed) = review_json {\n if let Some(summary) = parsed.summary.as_ref() {\n debug!(summary = summary.as_str(), \"remote claude review summary\");\n }\n (parsed.issues_found, parsed.issues.clone())\n } else if result.trim().is_empty() {\n (false, Vec::new())\n } else {\n debug!(\n review_output = result.as_str(),\n \"remote claude review output\"\n );\n let lowered = result.to_lowercase();\n let has_issues = lowered.contains(\"bug\")\n || lowered.contains(\"issue\")\n || lowered.contains(\"problem\")\n || lowered.contains(\"error\")\n || lowered.contains(\"vulnerability\")\n || lowered.contains(\"performance issue\")\n || lowered.contains(\"memory leak\");\n (has_issues, Vec::new())\n };\n\n Ok(ReviewResult {\n issues_found,\n issues,\n summary,\n future_tasks,\n timed_out: false,\n quality,\n })\n}\n\n/// Run Claude Code SDK to review staged changes for bugs and performance issues.\nfn run_claude_review(\n diff: &str,\n session_context: Option<&str>,\n review_instructions: Option<&str>,\n workdir: &std::path::Path,\n model: ClaudeModel,\n) -> Result<ReviewResult> {\n if commit_with_check_review_url().is_some() {\n match run_remote_claude_review(diff, session_context, review_instructions, model) {\n Ok(review) => return Ok(review),\n Err(err) => {\n println!(\"⚠ Remote review failed: {}\", err);\n println!(\" Falling back to local Claude review...\");\n }\n }\n }\n\n let local_review = (|| -> Result<ReviewResult> {\n use std::io::{BufRead, BufReader};\n use std::sync::mpsc;\n use std::time::Instant;\n\n let (diff_for_prompt, _truncated) = truncate_diff(diff);\n\n // Build compact review prompt optimized for speed/cost\n let mut prompt = String::from(\n \"Review diff for bugs, security, perf issues. Return JSON: {\\\"issues_found\\\":bool,\\\"issues\\\":[\\\"...\\\"],\\\"summary\\\":\\\"...\\\",\\\"future_tasks\\\":[\\\"...\\\"]}. future_tasks are optional follow-up improvements or optimizations (max 3), actionable, and not duplicates of issues; use [] if none.\\n\",\n );\n\n // Add quality assessment instructions if quality gates are enabled\n let quality_config = config::load_or_default(workdir.join(\"flow.toml\"))\n .commit\n .and_then(|c| c.quality)\n .unwrap_or_default();\n let quality_mode = quality_config.mode.as_deref().unwrap_or(\"warn\");\n if quality_mode != \"off\" {\n prompt.push_str(\n \"\\nAdditionally, analyze the diff for quality assessment. Add a \\\"quality\\\" object to your JSON response:\\n\\\n {\\\"quality\\\":{\\\"features_touched\\\":[{\\\"name\\\":\\\"kebab-name\\\",\\\"action\\\":\\\"added|modified|fixed\\\",\\\"description\\\":\\\"one sentence\\\",\\\"files_changed\\\":[\\\"...\\\"],\\\"has_tests\\\":bool,\\\"test_files\\\":[\\\"...\\\"],\\\"doc_current\\\":bool}],\\\n \\\"new_features\\\":[{\\\"name\\\":\\\"kebab-name\\\",\\\"description\\\":\\\"one sentence\\\",\\\"files\\\":[\\\"...\\\"],\\\"doc_content\\\":\\\"# Title\\\\n\\\\nDescription...\\\"}],\\\n \\\"test_coverage\\\":\\\"full|partial|none\\\",\\\"doc_coverage\\\":\\\"full|partial|none\\\",\\\"gate_pass\\\":bool,\\\"gate_failures\\\":[\\\"...\\\"]}}\\n\\\n A \\\"feature\\\" = a user-visible capability, API endpoint, or CLI command. Name features in kebab-case. \\\n gate_pass is false if new features lack tests or docs. gate_failures lists specific reasons.\\n\",\n );\n // Add features context (existing documented features) if available\n let features_ctx = crate::features::features_context_for_review(\n workdir,\n &changed_files_from_diff(diff),\n );\n if !features_ctx.is_empty() {\n prompt.push_str(&features_ctx);\n }\n }\n\n // Add custom review instructions if provided\n if let Some(instructions) = review_instructions {\n prompt.push_str(&format!(\n \"\\nAdditional review instructions:\\n{}\\n\",\n instructions\n ));\n }\n\n // Add session context if provided\n if let Some(context) = session_context {\n prompt.push_str(&format!(\"\\nContext:\\n{}\\n\", context));\n }\n\n prompt.push_str(&format!(\"```diff\\n{}\\n```\", diff_for_prompt));\n\n // Use claude CLI with print mode, piping prompt via stdin to avoid arg length limits\n let model_arg = model.as_claude_arg();\n\n let mut child = Command::new(\"claude\")\n .args([\"-p\", \"--model\", model_arg])\n .current_dir(workdir)\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .stderr(Stdio::piped())\n .spawn()\n .context(\"failed to run claude - is Claude Code SDK installed?\")?;\n\n // Write prompt to stdin and explicitly close it\n {\n let mut stdin = child.stdin.take().context(\"failed to get stdin\")?;\n stdin\n .write_all(prompt.as_bytes())\n .context(\"failed to write prompt to claude stdin\")?;\n stdin.flush().context(\"failed to flush stdin\")?;\n drop(stdin); // Explicitly close stdin to signal EOF\n }\n\n let stdout = child.stdout.take().unwrap();\n let stderr = child.stderr.take().unwrap();\n let (tx, rx) = mpsc::channel();\n let start = Instant::now();\n\n let tx_stdout = tx.clone();\n let reader_handle = std::thread::spawn(move || {\n let reader = BufReader::new(stdout);\n for line in reader.lines().flatten() {\n let _ = tx_stdout.send(ReviewEvent::Line(line));\n }\n let _ = tx_stdout.send(ReviewEvent::StdoutDone);\n });\n\n let tx_stderr = tx.clone();\n let stderr_handle = std::thread::spawn(move || {\n let reader = BufReader::new(stderr);\n for line in reader.lines().flatten() {\n let _ = tx_stderr.send(ReviewEvent::StderrLine(line));\n }\n let _ = tx_stderr.send(ReviewEvent::StderrDone);\n });\n\n let mut output_lines = Vec::new();\n let mut stderr_lines = Vec::new();\n let mut last_progress = Instant::now();\n let timeout = Duration::from_secs(commit_with_check_timeout_secs());\n let mut deadline = Instant::now() + timeout;\n let mut timed_out = false;\n let mut done_count = 0;\n loop {\n match rx.recv_timeout(Duration::from_secs(2)) {\n Ok(ReviewEvent::Line(line)) => {\n println!(\"{}\", line);\n output_lines.push(line);\n last_progress = Instant::now();\n }\n Ok(ReviewEvent::StderrLine(line)) => {\n if !line.trim().is_empty() {\n println!(\"claude: {}\", line);\n }\n stderr_lines.push(line);\n }\n Ok(ReviewEvent::StdoutDone) | Ok(ReviewEvent::StderrDone) => {\n done_count += 1;\n if done_count >= 2 {\n break;\n }\n }\n Err(mpsc::RecvTimeoutError::Timeout) => {\n if last_progress.elapsed() >= Duration::from_secs(10) {\n println!(\n \"Waiting on Claude review... ({}s elapsed, no output yet)\",\n start.elapsed().as_secs()\n );\n last_progress = Instant::now();\n }\n if Instant::now() >= deadline {\n if prompt_yes_no(\n \"Claude review is taking longer than expected. Keep waiting?\",\n )? {\n deadline = Instant::now() + timeout;\n } else {\n timed_out = true;\n let _ = child.kill();\n break;\n }\n }\n }\n Err(mpsc::RecvTimeoutError::Disconnected) => break,\n }\n }\n\n let _ = reader_handle.join();\n let _ = stderr_handle.join();\n let status = child.wait()?;\n let stderr_output = stderr_lines.join(\"\\n\");\n\n if timed_out {\n if !stderr_output.trim().is_empty() {\n println!(\"{}\", stderr_output.trim_end());\n }\n return Ok(ReviewResult {\n issues_found: false,\n issues: Vec::new(),\n summary: Some(format!(\n \"Claude review timed out after {}s\",\n timeout.as_secs()\n )),\n future_tasks: Vec::new(),\n timed_out: true,\n quality: None,\n });\n }\n\n if !status.success() {\n if !stderr_output.trim().is_empty() {\n println!(\"{}\", stderr_output.trim_end());\n }\n println!(\"\\nnotify: Claude review failed\");\n bail!(\"Claude review failed\");\n }\n\n let result = output_lines.join(\"\\n\");\n\n let mut review_json = parse_review_json(&result);\n let future_tasks = review_json\n .as_ref()\n .map(|parsed| normalize_future_tasks(&parsed.future_tasks))\n .unwrap_or_default();\n let summary = review_json.as_ref().and_then(|r| r.summary.clone());\n let quality = review_json.as_mut().and_then(|r| r.quality.take());\n let (issues_found, issues) = if let Some(ref parsed) = review_json {\n if let Some(summary) = parsed.summary.as_ref() {\n debug!(summary = summary.as_str(), \"claude review summary\");\n }\n (parsed.issues_found, parsed.issues.clone())\n } else if result.trim().is_empty() {\n (false, Vec::new())\n } else {\n debug!(review_output = result.as_str(), \"claude review output\");\n let lowered = result.to_lowercase();\n let has_issues = lowered.contains(\"bug\")\n || lowered.contains(\"issue\")\n || lowered.contains(\"problem\")\n || lowered.contains(\"error\")\n || lowered.contains(\"vulnerability\")\n || lowered.contains(\"performance issue\")\n || lowered.contains(\"memory leak\");\n (has_issues, Vec::new())\n };\n\n Ok(ReviewResult {\n issues_found,\n issues,\n summary,\n future_tasks,\n timed_out: false,\n quality,\n })\n })();\n\n match local_review {\n Ok(review) => Ok(review),\n Err(err) => {\n println!(\"⚠ Local Claude review failed: {}\", err);\n println!(\" Proceeding without review.\");\n Ok(ReviewResult {\n issues_found: false,\n issues: Vec::new(),\n summary: Some(format!(\"Claude review failed: {}\", err)),\n future_tasks: Vec::new(),\n timed_out: false,\n quality: None,\n })\n }\n }\n}\n\n/// Run opencode to review staged changes for bugs and performance issues.\nfn run_opencode_review(\n diff: &str,\n session_context: Option<&str>,\n review_instructions: Option<&str>,\n workdir: &std::path::Path,\n model: &str,\n) -> Result<ReviewResult> {\n use std::io::{BufRead, BufReader, Write};\n\n let (diff_for_prompt, _truncated) = truncate_diff(diff);\n\n // Write diff to a temp file in the working directory to avoid /tmp permission issues\n let diff_file = workdir.join(\".flow_diff_review.tmp\");\n {\n let mut f = std::fs::File::create(&diff_file).context(\"failed to create temp diff file\")?;\n f.write_all(diff_for_prompt.as_bytes())\n .context(\"failed to write temp diff file\")?;\n }\n\n // Build review prompt - explicitly say to output to stdout only\n let mut prompt = String::from(\n \"Review the attached git diff file for bugs, security issues, and performance problems. \\\n Output ONLY a JSON object to stdout with this exact format (do not write any files): \\\n {\\\"issues_found\\\": true/false, \\\"issues\\\": [\\\"issue 1\\\", \\\"issue 2\\\"], \\\"summary\\\": \\\"brief summary\\\", \\\"future_tasks\\\": [\\\"optional follow-up\\\"]}. \\\n future_tasks are optional improvements/optimizations (max 3), actionable, and not duplicates of issues; use [] if none.\",\n );\n\n if let Some(instructions) = review_instructions {\n prompt.push_str(&format!(\n \"\\n\\nAdditional review instructions:\\n{}\",\n instructions\n ));\n }\n\n if let Some(context) = session_context {\n prompt.push_str(&format!(\"\\n\\nContext:\\n{}\", context));\n }\n\n // Run opencode with the diff as an attached file\n let mut child = Command::new(\"opencode\")\n .args([\n \"run\",\n \"--model\",\n model,\n \"-f\",\n diff_file.to_str().unwrap(),\n &prompt,\n ])\n .current_dir(workdir)\n .stdout(Stdio::piped())\n .stderr(Stdio::piped())\n .spawn()\n .context(\"failed to run opencode - is it installed?\")?;\n\n let stdout = child.stdout.take().unwrap();\n let stderr = child.stderr.take().unwrap();\n\n // Read output with timeout\n let reader = BufReader::new(stdout);\n let mut output_lines = Vec::new();\n for line in reader.lines().flatten() {\n print!(\"{}\\n\", line);\n output_lines.push(line);\n }\n\n // Also capture stderr\n let stderr_reader = BufReader::new(stderr);\n for line in stderr_reader.lines().flatten() {\n debug!(\"opencode stderr: {}\", line);\n }\n\n let status = child.wait()?;\n if !status.success() {\n debug!(\"opencode exited with non-zero status: {:?}\", status.code());\n }\n\n let output = output_lines.join(\"\\n\");\n\n // Try to parse JSON from output\n let mut review_json = parse_review_json(&output);\n let future_tasks = review_json\n .as_ref()\n .map(|json| normalize_future_tasks(&json.future_tasks))\n .unwrap_or_default();\n let summary = review_json.as_ref().and_then(|r| r.summary.clone());\n let quality = review_json.as_mut().and_then(|r| r.quality.take());\n let (issues_found, issues) = if let Some(ref json) = review_json {\n (json.issues_found, json.issues.clone())\n } else {\n // Fallback: check for issue keywords\n let lowered = output.to_lowercase();\n let has_issues = lowered.contains(\"bug\")\n || lowered.contains(\"issue\")\n || lowered.contains(\"error\")\n || lowered.contains(\"problem\")\n || lowered.contains(\"security\")\n || lowered.contains(\"vulnerability\")\n || lowered.contains(\"performance issue\")\n || lowered.contains(\"memory leak\");\n (has_issues, Vec::new())\n };\n\n // Clean up temp file\n let _ = std::fs::remove_file(&diff_file);\n\n Ok(ReviewResult {\n issues_found,\n issues,\n summary,\n future_tasks,\n timed_out: false,\n quality,\n })\n}\n\n/// Run Kimi CLI to review staged changes for bugs and performance issues.\nfn changed_files_from_diff(diff: &str) -> Vec<String> {\n let mut files = Vec::new();\n for line in diff.lines() {\n if let Some(path) = line.strip_prefix(\"+++ b/\") {\n if path != \"/dev/null\" {\n files.push(path.to_string());\n }\n }\n }\n files.sort();\n files.dedup();\n files\n}\n\nfn issue_mentions_changed_file(issue: &str, files: &[String]) -> bool {\n for file in files {\n if issue.contains(file) {\n return true;\n }\n let with_b = format!(\"b/{}\", file);\n if issue.contains(&with_b) {\n return true;\n }\n let with_dot = format!(\"./{}\", file);\n if issue.contains(&with_dot) {\n return true;\n }\n }\n false\n}\n\nfn run_kimi_review(\n diff: &str,\n session_context: Option<&str>,\n review_instructions: Option<&str>,\n _workdir: &std::path::Path,\n model: Option<&str>,\n) -> Result<ReviewResult> {\n use std::io::{BufRead, Read, Write};\n use std::sync::mpsc;\n use std::thread;\n\n let (diff_for_prompt, truncated) = truncate_diff(diff);\n\n let mut prompt = String::from(\n \"Review this git diff for bugs, security issues, and performance problems. \\\n Only report issues that are directly supported by this diff. \\\n Each issue MUST include a file path and line number from the diff, in the format: \\\n \\\"path/to/file:line - description (evidence: `exact diff line`)\\\". \\\n Output ONLY a JSON object with this exact format: \\\n {\\\"issues_found\\\": true/false, \\\"issues\\\": [\\\"issue 1\\\", \\\"issue 2\\\"], \\\"summary\\\": \\\"brief summary\\\", \\\"future_tasks\\\": [\\\"optional follow-up\\\"]}. \\\n future_tasks are optional improvements/optimizations (max 3), actionable, and not duplicates of issues; use [] if none. \\\n If you cannot find concrete issues in the diff, set issues_found=false and issues=[].\\n\\n\\\n Git diff:\\n\",\n );\n prompt.push_str(&diff_for_prompt);\n\n if truncated {\n prompt.push_str(\"\\n\\n[Diff truncated]\");\n }\n\n if let Some(instructions) = review_instructions {\n prompt.push_str(&format!(\n \"\\n\\nAdditional review instructions:\\n{}\",\n instructions\n ));\n }\n\n if let Some(context) = session_context {\n prompt.push_str(&format!(\"\\n\\nContext:\\n{}\", context));\n }\n\n info!(\n model = model.unwrap_or(\"default\"),\n prompt_len = prompt.len(),\n \"calling kimi for code review\"\n );\n\n let mut cmd = Command::new(\"kimi\");\n cmd.args([\n \"--print\",\n \"--input-format\",\n \"text\",\n \"--output-format\",\n \"stream-json\",\n ]);\n if let Some(model) = model {\n if !model.trim().is_empty() {\n cmd.args([\"--model\", model]);\n }\n }\n cmd.stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .stderr(Stdio::piped());\n\n let mut child = cmd.spawn().context(\"failed to run kimi for review\")?;\n\n if let Some(mut stdin) = child.stdin.take() {\n stdin\n .write_all(prompt.as_bytes())\n .context(\"failed to write prompt to kimi\")?;\n }\n\n let stdout = child\n .stdout\n .take()\n .context(\"failed to capture kimi stdout\")?;\n let stderr = child\n .stderr\n .take()\n .context(\"failed to capture kimi stderr\")?;\n\n let (stdout_tx, stdout_rx) = mpsc::channel::<Vec<u8>>();\n let (stderr_tx, stderr_rx) = mpsc::channel::<String>();\n\n let stdout_handle = thread::spawn(move || {\n let mut buf = Vec::new();\n let _ = std::io::BufReader::new(stdout).read_to_end(&mut buf);\n let _ = stdout_tx.send(buf);\n });\n\n let stderr_handle = thread::spawn(move || {\n let mut collected = String::new();\n let reader = std::io::BufReader::new(stderr);\n for line in reader.lines().flatten() {\n // Stream stderr (progress/errors) to console\n if !line.trim().is_empty() {\n eprintln!(\"{}\", line);\n }\n collected.push_str(&line);\n collected.push('\\n');\n }\n let _ = stderr_tx.send(collected);\n });\n\n let status = child.wait().context(\"failed to wait for kimi\")?;\n let _ = stdout_handle.join();\n let _ = stderr_handle.join();\n\n let stdout_bytes = stdout_rx.recv().unwrap_or_default();\n let stderr_text = stderr_rx.recv().unwrap_or_default();\n\n if !status.success() {\n let stdout_text = String::from_utf8_lossy(&stdout_bytes);\n let error_msg = if stderr_text.trim().is_empty() {\n stdout_text.trim()\n } else {\n stderr_text.trim()\n };\n bail!(\"kimi review failed: {}\", error_msg);\n }\n\n let stdout_text = String::from_utf8_lossy(&stdout_bytes).trim().to_string();\n if stdout_text.is_empty() {\n bail!(\"kimi returned empty output\");\n }\n\n // Parse the stream-json output from kimi\n // Format: {\"role\":\"assistant\",\"content\":[{\"type\":\"think\",\"think\":\"...\"},{\"type\":\"text\",\"text\":\"...\"}]}\n let result = extract_kimi_text_content(&stdout_text).unwrap_or_else(|| stdout_text.clone());\n if result.is_empty() {\n bail!(\"kimi returned empty review output (no text content in response)\");\n }\n\n // Try to parse JSON from output\n let mut review_json = parse_review_json(&result);\n let future_tasks = review_json\n .as_ref()\n .map(|json| normalize_future_tasks(&json.future_tasks))\n .unwrap_or_default();\n let mut summary = review_json.as_ref().and_then(|r| r.summary.clone());\n let quality = review_json.as_mut().and_then(|r| r.quality.take());\n let (mut issues_found, mut issues) = if let Some(ref json) = review_json {\n (json.issues_found, json.issues.clone())\n } else {\n let lowered = result.to_lowercase();\n let has_issues = lowered.contains(\"bug\")\n || lowered.contains(\"issue\")\n || lowered.contains(\"error\")\n || lowered.contains(\"problem\")\n || lowered.contains(\"security\")\n || lowered.contains(\"vulnerability\")\n || lowered.contains(\"performance issue\")\n || lowered.contains(\"memory leak\");\n (has_issues, Vec::new())\n };\n\n let changed_files = changed_files_from_diff(diff);\n if !issues.is_empty() && !changed_files.is_empty() {\n let before = issues.len();\n issues.retain(|issue| issue_mentions_changed_file(issue, &changed_files));\n let dropped = before.saturating_sub(issues.len());\n if dropped > 0 {\n let note = format!(\n \"Filtered {} unverified issue(s) that did not reference files in the diff.\",\n dropped\n );\n let summary = match summary.take() {\n Some(existing) if !existing.is_empty() => format!(\"{} {}\", existing, note),\n _ => note,\n };\n issues_found = !issues.is_empty();\n return Ok(ReviewResult {\n issues_found,\n issues,\n summary: Some(summary),\n future_tasks,\n timed_out: false,\n quality: quality.clone(),\n });\n }\n }\n\n if issues.is_empty() {\n issues_found = false;\n }\n\n Ok(ReviewResult {\n issues_found,\n issues,\n summary,\n future_tasks,\n timed_out: false,\n quality,\n })\n}\n\nfn run_openrouter_review(\n diff: &str,\n session_context: Option<&str>,\n review_instructions: Option<&str>,\n _workdir: &std::path::Path,\n model: &str,\n) -> Result<ReviewResult> {\n let (diff_for_prompt, truncated) = truncate_diff(diff);\n\n let mut prompt = String::from(\n \"Review this git diff for bugs, security issues, and performance problems. \\\n Only report issues that are directly supported by this diff. \\\n Each issue MUST include a file path and line number from the diff, in the format: \\\n \\\"path/to/file:line - description (evidence: `exact diff line`)\\\". \\\n Output ONLY a JSON object with this exact format: \\\n {\\\"issues_found\\\": true/false, \\\"issues\\\": [\\\"issue 1\\\", \\\"issue 2\\\"], \\\"summary\\\": \\\"brief summary\\\", \\\"future_tasks\\\": [\\\"optional follow-up\\\"]}. \\\n future_tasks are optional improvements/optimizations (max 3), actionable, and not duplicates of issues; use [] if none. \\\n If you cannot find concrete issues in the diff, set issues_found=false and issues=[].\\n\\n\\\n Git diff:\\n\",\n );\n prompt.push_str(&diff_for_prompt);\n\n if truncated {\n prompt.push_str(\"\\n\\n[Diff truncated]\");\n }\n\n if let Some(instructions) = review_instructions {\n prompt.push_str(&format!(\n \"\\n\\nAdditional review instructions:\\n{}\",\n instructions\n ));\n }\n\n if let Some(context) = session_context {\n prompt.push_str(&format!(\"\\n\\nContext:\\n{}\", context));\n }\n\n let api_key = openrouter_api_key()?;\n let model_id = openrouter_model_id(model);\n\n let client = openrouter_http_client(Duration::from_secs(120))?;\n\n let body = ChatRequest {\n model: model_id.to_string(),\n messages: vec![\n Message {\n role: \"system\".to_string(),\n content: \"You are a code reviewer. Analyze code changes for bugs, security issues, and performance problems. Output JSON only.\".to_string(),\n },\n Message {\n role: \"user\".to_string(),\n content: prompt,\n },\n ],\n temperature: 0.3,\n };\n\n info!(\n model = model_id,\n prompt_len = body.messages[1].content.len(),\n \"calling OpenRouter for code review\"\n );\n let start = std::time::Instant::now();\n\n let parsed: ChatResponse = openrouter_chat_completion_with_retry(&client, &api_key, &body)\n .context(\"OpenRouter request failed\")?;\n\n info!(\n elapsed_ms = start.elapsed().as_millis() as u64,\n \"OpenRouter responded\"\n );\n\n let output = parsed\n .choices\n .first()\n .and_then(|c| c.message.as_ref())\n .map(|m| m.content.trim().to_string())\n .unwrap_or_default();\n\n if output.is_empty() {\n bail!(\"OpenRouter returned empty review output\");\n }\n\n println!(\"{}\", output);\n\n let mut review_json = parse_review_json(&output);\n let future_tasks = review_json\n .as_ref()\n .map(|json| normalize_future_tasks(&json.future_tasks))\n .unwrap_or_default();\n let mut summary = review_json.as_ref().and_then(|r| r.summary.clone());\n let quality = review_json.as_mut().and_then(|r| r.quality.take());\n let (mut issues_found, mut issues) = if let Some(ref json) = review_json {\n (json.issues_found, json.issues.clone())\n } else {\n let lowered = output.to_lowercase();\n let has_issues = lowered.contains(\"bug\")\n || lowered.contains(\"issue\")\n || lowered.contains(\"error\")\n || lowered.contains(\"problem\")\n || lowered.contains(\"security\")\n || lowered.contains(\"vulnerability\")\n || lowered.contains(\"performance issue\")\n || lowered.contains(\"memory leak\");\n (has_issues, Vec::new())\n };\n\n let changed_files = changed_files_from_diff(diff);\n if !issues.is_empty() && !changed_files.is_empty() {\n let before = issues.len();\n issues.retain(|issue| issue_mentions_changed_file(issue, &changed_files));\n let dropped = before.saturating_sub(issues.len());\n if dropped > 0 {\n let note = format!(\n \"Filtered {} unverified issue(s) that did not reference files in the diff.\",\n dropped\n );\n let summary = match summary.take() {\n Some(existing) if !existing.is_empty() => format!(\"{} {}\", existing, note),\n _ => note,\n };\n issues_found = !issues.is_empty();\n return Ok(ReviewResult {\n issues_found,\n issues,\n summary: Some(summary),\n future_tasks,\n timed_out: false,\n quality: quality.clone(),\n });\n }\n }\n\n if issues.is_empty() {\n issues_found = false;\n }\n\n Ok(ReviewResult {\n issues_found,\n issues,\n summary,\n future_tasks,\n timed_out: false,\n quality,\n })\n}\n\nconst OPENROUTER_CHAT_URL: &str = \"https://openrouter.ai/api/v1/chat/completions\";\n\nfn openrouter_http_client(timeout: Duration) -> Result<Client> {\n Client::builder()\n .timeout(timeout)\n // OpenRouter occasionally drops pooled connections mid-body, producing\n // `unexpected EOF during chunk size line`. Disabling idle pooling makes\n // these transient failures much rarer for CLI-style, low-QPS usage.\n .pool_max_idle_per_host(0)\n .build()\n .context(\"failed to create HTTP client\")\n}\n\nfn openrouter_should_retry_error(err: &reqwest::Error) -> bool {\n if err.is_timeout() || err.is_connect() || err.is_body() {\n return true;\n }\n\n // reqwest/hyper doesn't expose a stable typed error for this; match common symptoms.\n let msg = err.to_string().to_lowercase();\n msg.contains(\"unexpected eof\")\n || msg.contains(\"chunk size line\")\n || msg.contains(\"connection closed\")\n || msg.contains(\"incomplete message\")\n}\n\nfn openrouter_retry_after(resp: &reqwest::blocking::Response) -> Option<Duration> {\n let value = resp.headers().get(\"retry-after\")?.to_str().ok()?;\n // Spec also allows HTTP-date; we only handle integer seconds.\n let secs: u64 = value.trim().parse().ok()?;\n Some(Duration::from_secs(secs))\n}\n\nfn openrouter_chat_completion_with_retry(\n client: &Client,\n api_key: &str,\n body: &ChatRequest,\n) -> Result<ChatResponse> {\n let max_attempts = 3usize;\n let mut backoff = Duration::from_millis(250);\n let mut last_err: Option<anyhow::Error> = None;\n\n for attempt in 1..=max_attempts {\n let resp = client\n .post(OPENROUTER_CHAT_URL)\n .header(\"Authorization\", format!(\"Bearer {}\", api_key))\n .header(\"HTTP-Referer\", \"https://github.com/nikitavoloboev/flow\")\n .header(\"Accept\", \"application/json\")\n .json(body)\n .send();\n\n let resp = match resp {\n Ok(resp) => resp,\n Err(err) => {\n let retry = openrouter_should_retry_error(&err) && attempt < max_attempts;\n let err = anyhow::Error::new(err).context(\"failed to call OpenRouter API\");\n if retry {\n info!(\n attempt = attempt,\n max_attempts = max_attempts,\n backoff_ms = backoff.as_millis() as u64,\n \"OpenRouter request error (transient), retrying\"\n );\n last_err = Some(err);\n std::thread::sleep(backoff);\n backoff = backoff.saturating_mul(2);\n continue;\n }\n return Err(err);\n }\n };\n\n let status = resp.status();\n let retry_after = openrouter_retry_after(&resp);\n let request_id = resp\n .headers()\n .get(\"x-request-id\")\n .and_then(|v| v.to_str().ok())\n .map(|s| s.to_string())\n .or_else(|| {\n resp.headers()\n .get(\"cf-ray\")\n .and_then(|v| v.to_str().ok())\n .map(|s| s.to_string())\n });\n\n let body_bytes = match resp.bytes() {\n Ok(bytes) => bytes,\n Err(err) => {\n let retry = openrouter_should_retry_error(&err) && attempt < max_attempts;\n let mut err =\n anyhow::Error::new(err).context(\"failed to read OpenRouter response body\");\n if let Some(rid) = request_id.as_deref() {\n err = err.context(format!(\"OpenRouter request id: {}\", rid));\n }\n if retry {\n info!(\n attempt = attempt,\n max_attempts = max_attempts,\n backoff_ms = backoff.as_millis() as u64,\n \"OpenRouter body read error (transient), retrying\"\n );\n last_err = Some(err);\n std::thread::sleep(backoff);\n backoff = backoff.saturating_mul(2);\n continue;\n }\n return Err(err);\n }\n };\n\n if !status.is_success() {\n let is_retryable_status =\n status == StatusCode::TOO_MANY_REQUESTS || status.is_server_error();\n let text = String::from_utf8_lossy(&body_bytes).trim().to_string();\n\n if is_retryable_status && attempt < max_attempts {\n let sleep_for = retry_after.unwrap_or(backoff);\n info!(\n attempt = attempt,\n max_attempts = max_attempts,\n status = %status,\n sleep_ms = sleep_for.as_millis() as u64,\n \"OpenRouter returned transient status, retrying\"\n );\n last_err = Some(anyhow::anyhow!(\"OpenRouter API error {}: {}\", status, text));\n std::thread::sleep(sleep_for);\n backoff = backoff.saturating_mul(2);\n continue;\n }\n\n let mut err = anyhow::anyhow!(\"OpenRouter API error {}: {}\", status, text);\n if let Some(rid) = request_id.as_deref() {\n err = err.context(format!(\"OpenRouter request id: {}\", rid));\n }\n return Err(err);\n }\n\n match serde_json::from_slice::<ChatResponse>(&body_bytes) {\n Ok(parsed) => return Ok(parsed),\n Err(err) => {\n let snippet = {\n let s = String::from_utf8_lossy(&body_bytes);\n let s = s.trim();\n let max = 600usize;\n if s.len() > max {\n format!(\"{}...\", &s[..max])\n } else {\n s.to_string()\n }\n };\n let mut err = anyhow::Error::new(err)\n .context(\"failed to decode OpenRouter JSON response\")\n .context(format!(\"response snippet: {}\", snippet));\n if let Some(rid) = request_id.as_deref() {\n err = err.context(format!(\"OpenRouter request id: {}\", rid));\n }\n return Err(err);\n }\n }\n }\n\n Err(last_err.unwrap_or_else(|| anyhow::anyhow!(\"OpenRouter request failed after retries\")))\n}\n\n/// Run Rise daemon to review staged changes for bugs and performance issues.\nfn run_rise_review(\n diff: &str,\n session_context: Option<&str>,\n review_instructions: Option<&str>,\n _workdir: &std::path::Path,\n model: &str,\n) -> Result<ReviewResult> {\n let (diff_for_prompt, _truncated) = truncate_diff(diff);\n\n // Build review prompt\n let mut prompt = String::from(\n \"Review this git diff for bugs, security issues, and performance problems. \\\n Output ONLY a JSON object with this exact format: \\\n {\\\"issues_found\\\": true/false, \\\"issues\\\": [\\\"issue 1\\\", \\\"issue 2\\\"], \\\"summary\\\": \\\"brief summary\\\", \\\"future_tasks\\\": [\\\"optional follow-up\\\"]}. \\\n future_tasks are optional improvements/optimizations (max 3), actionable, and not duplicates of issues; use [] if none.\\n\\n\\\n Git diff:\\n\",\n );\n prompt.push_str(&diff_for_prompt);\n\n if let Some(instructions) = review_instructions {\n prompt.push_str(&format!(\n \"\\n\\nAdditional review instructions:\\n{}\",\n instructions\n ));\n }\n\n if let Some(context) = session_context {\n prompt.push_str(&format!(\"\\n\\nContext:\\n{}\", context));\n }\n\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(120))\n .context(\"failed to create HTTP client\")?;\n\n let body = ChatRequest {\n model: model.to_string(),\n messages: vec![\n Message {\n role: \"system\".to_string(),\n content: \"You are a code reviewer. Analyze code changes for bugs, security issues, and performance problems. Output JSON only.\".to_string(),\n },\n Message {\n role: \"user\".to_string(),\n content: prompt,\n },\n ],\n temperature: 0.3,\n };\n\n info!(model = model, \"calling Rise daemon for code review\");\n let start = std::time::Instant::now();\n\n let rise_url = rise_url();\n let text = send_rise_request_text(&client, &rise_url, &body, model)?;\n\n info!(\n elapsed_ms = start.elapsed().as_millis() as u64,\n \"Rise daemon responded\"\n );\n let output = parse_rise_output(&text).context(\"failed to parse Rise response\")?;\n\n println!(\"{}\", output);\n\n // Try to parse JSON from output\n let mut review_json = parse_review_json(&output);\n let future_tasks = review_json\n .as_ref()\n .map(|json| normalize_future_tasks(&json.future_tasks))\n .unwrap_or_default();\n let summary = review_json.as_ref().and_then(|r| r.summary.clone());\n let quality = review_json.as_mut().and_then(|r| r.quality.take());\n let (issues_found, issues) = if let Some(ref json) = review_json {\n (json.issues_found, json.issues.clone())\n } else {\n // Fallback: check for issue keywords\n let lowered = output.to_lowercase();\n let has_issues = lowered.contains(\"bug\")\n || lowered.contains(\"issue\")\n || lowered.contains(\"error\")\n || lowered.contains(\"problem\")\n || lowered.contains(\"security\")\n || lowered.contains(\"vulnerability\")\n || lowered.contains(\"performance issue\")\n || lowered.contains(\"memory leak\");\n (has_issues, Vec::new())\n };\n\n Ok(ReviewResult {\n issues_found,\n issues,\n summary,\n future_tasks,\n timed_out: false,\n quality,\n })\n}\n\nfn ensure_git_repo() -> Result<()> {\n let _ = vcs::ensure_jj_repo()?;\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"--git-dir\"])\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .context(\"failed to run git\")?;\n\n if !output.success() {\n bail!(\"Not a git repository\");\n }\n Ok(())\n}\n\nfn git_root_or_cwd() -> std::path::PathBuf {\n match git_capture(&[\"rev-parse\", \"--show-toplevel\"]) {\n Ok(root) => std::path::PathBuf::from(root.trim()),\n Err(_) => std::env::current_dir().unwrap_or_default(),\n }\n}\n\nfn warn_if_commit_invoked_from_subdir(repo_root: &Path) {\n let Ok(cwd) = std::env::current_dir() else {\n return;\n };\n let cwd_norm = cwd.canonicalize().unwrap_or(cwd.clone());\n let root_norm = repo_root\n .canonicalize()\n .unwrap_or_else(|_| repo_root.to_path_buf());\n if cwd_norm == root_norm {\n return;\n }\n\n println!(\n \"warning: commit invoked from subdirectory: {}\",\n cwd.display()\n );\n println!(\n \"warning: using git repo root for commit operations: {}\",\n repo_root.display()\n );\n}\n\nfn ensure_commit_setup(repo_root: &Path) -> Result<()> {\n let ai_internal = repo_root.join(\".ai\").join(\"internal\");\n fs::create_dir_all(&ai_internal)\n .with_context(|| format!(\"failed to create {}\", ai_internal.display()))?;\n setup::add_gitignore_entry(repo_root, \".ai/internal/\")?;\n Ok(())\n}\n\nfn ensure_no_internal_staged(repo_root: &Path) -> Result<()> {\n if env::var(\"FLOW_ALLOW_INTERNAL_COMMIT\").as_deref() == Ok(\"1\") {\n return Ok(());\n }\n let staged = internal_staged_paths(repo_root);\n if staged.is_empty() {\n return Ok(());\n }\n\n println!(\"Refusing to commit internal .ai files:\");\n for path in staged {\n println!(\" - {}\", path);\n }\n println!(\"Remove these from staging or set FLOW_ALLOW_INTERNAL_COMMIT=1 to override.\");\n bail!(\"Refusing to commit internal .ai files\");\n}\n\nfn internal_staged_paths(repo_root: &Path) -> Vec<String> {\n let output = Command::new(\"git\")\n .args([\"diff\", \"--cached\", \"--name-only\"])\n .current_dir(repo_root)\n .output();\n\n let Ok(output) = output else {\n return Vec::new();\n };\n if !output.status.success() {\n return Vec::new();\n }\n\n let files = String::from_utf8_lossy(&output.stdout);\n files\n .lines()\n .filter(|path| {\n path.starts_with(\".ai/internal/\")\n || path == &\".ai/internal\"\n || (path.starts_with(\".ai/todos/\") && path.ends_with(\".bike\"))\n })\n .map(|path| path.to_string())\n .collect()\n}\n\nfn ensure_no_unwanted_staged(repo_root: &Path) -> Result<()> {\n if env::var(\"FLOW_ALLOW_UNWANTED_COMMIT\")\n .ok()\n .map(|v| {\n let v = v.to_ascii_lowercase();\n v == \"1\" || v == \"true\" || v == \"yes\"\n })\n .unwrap_or(false)\n {\n return Ok(());\n }\n\n let staged = unwanted_staged_paths(repo_root);\n if staged.is_empty() {\n return Ok(());\n }\n\n let mut ignore_entries = HashSet::new();\n let mut saw_personal_tooling = false;\n\n for (path, reason) in &staged {\n println!(\"Refusing to commit generated file: {} ({})\", path, reason);\n\n // Personal tooling entries belong in global gitignore, not project .gitignore.\n if path.starts_with(\".beads/\") || path == \".beads\" {\n saw_personal_tooling = true;\n continue;\n }\n if path == \".rise\" || path.starts_with(\".rise/\") || path.contains(\"/.rise/\") {\n saw_personal_tooling = true;\n continue;\n }\n\n if path.ends_with(\".pyc\")\n || path.contains(\"/__pycache__/\")\n || path.ends_with(\"/__pycache__\")\n {\n ignore_entries.insert(\"__pycache__/\");\n ignore_entries.insert(\"*.pyc\");\n }\n }\n\n for entry in &ignore_entries {\n let _ = setup::add_gitignore_entry(repo_root, entry);\n }\n\n for (path, _) in &staged {\n let _ = git_run_in(repo_root, &[\"reset\", \"HEAD\", \"--\", path]);\n }\n\n if !ignore_entries.is_empty() {\n println!(\"Added ignore rules for generated files and unstaged them.\");\n } else {\n println!(\"Unstaged generated files.\");\n }\n if saw_personal_tooling {\n println!(\n \"Personal tooling paths (.beads/, .rise/) should be ignored globally, not in project .gitignore.\"\n );\n println!(\"Run `f gitignore policy-init` and `f gitignore fix` to clean existing repos.\");\n }\n println!(\"Re-run `f commit` after verifying the changes.\");\n println!(\"Set FLOW_ALLOW_UNWANTED_COMMIT=1 to override.\");\n bail!(\"Refusing to commit generated files\");\n}\nfn unwanted_staged_paths(repo_root: &Path) -> Vec<(String, String)> {\n let output = Command::new(\"git\")\n .args([\"diff\", \"--cached\", \"--name-status\", \"-z\"])\n .current_dir(repo_root)\n .output();\n\n let Ok(output) = output else {\n return Vec::new();\n };\n if !output.status.success() {\n return Vec::new();\n }\n\n let mut out = Vec::new();\n let raw = String::from_utf8_lossy(&output.stdout);\n let parts: Vec<&str> = raw.split('\\0').collect();\n let mut i = 0;\n while i < parts.len() {\n let status = parts[i];\n i += 1;\n if status.is_empty() {\n continue;\n }\n let path = if status.starts_with('R') || status.starts_with('C') {\n if i + 1 >= parts.len() {\n break;\n }\n let new_path = parts[i + 1];\n i += 2;\n new_path\n } else {\n if i >= parts.len() {\n break;\n }\n let path = parts[i];\n i += 1;\n path\n };\n\n if status.starts_with('D') {\n continue;\n }\n\n if let Some(reason) = unwanted_reason(path) {\n out.push((path.to_string(), reason.to_string()));\n }\n }\n out\n}\n\nfn unwanted_reason(path: &str) -> Option<&'static str> {\n if path == \".flow/deploy-log.json\" || path.ends_with(\"/.flow/deploy-log.json\") {\n return Some(\"flow deploy state\");\n }\n if path == \".beads\" || path.starts_with(\".beads/\") || path.contains(\"/.beads/\") {\n return Some(\"beads metadata\");\n }\n if path == \".rise\" || path.starts_with(\".rise/\") || path.contains(\"/.rise/\") {\n return Some(\"rise metadata\");\n }\n if path.ends_with(\".pyc\") {\n return Some(\"python bytecode\");\n }\n if path.ends_with(\"/__pycache__\")\n || path.contains(\"/__pycache__/\")\n || path.starts_with(\"__pycache__/\")\n {\n return Some(\"python cache\");\n }\n None\n}\n\nfn log_commit_event_for_repo(\n repo_root: &Path,\n message: &str,\n command: &str,\n review: Option<ai::CommitReviewSummary>,\n context_chars: Option<usize>,\n) {\n let commit_sha = match git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"]) {\n Ok(sha) => sha,\n Err(err) => {\n debug!(\"failed to capture commit SHA for commit log: {}\", err);\n return;\n }\n };\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string());\n let author_name = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%an\"])\n .unwrap_or_else(|_| \"unknown\".to_string());\n let author_email = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%ae\"])\n .unwrap_or_else(|_| \"unknown\".to_string());\n\n ai::log_commit_event(\n &repo_root.to_path_buf(),\n commit_sha.trim(),\n branch.trim(),\n message,\n author_name.trim(),\n author_email.trim(),\n command,\n review,\n context_chars,\n );\n}\n\n/// Record an undoable commit action.\n/// Call this after a successful commit (and optionally push).\nfn record_undo_action(repo_root: &Path, pushed: bool, message: Option<&str>) {\n // Get the current HEAD (after commit)\n let after_sha = match git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"]) {\n Ok(sha) => sha.trim().to_string(),\n Err(_) => return,\n };\n\n // Get the parent commit (before commit)\n let before_sha = match git_capture_in(repo_root, &[\"rev-parse\", \"HEAD~1\"]) {\n Ok(sha) => sha.trim().to_string(),\n Err(_) => return,\n };\n\n // Get current branch\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string());\n\n let action_type = if pushed {\n undo::ActionType::CommitPush\n } else {\n undo::ActionType::Commit\n };\n let push_remote = config::preferred_git_remote_for_repo(repo_root);\n let remote_for_undo = if pushed {\n Some(push_remote.as_str())\n } else {\n None\n };\n\n if let Err(e) = undo::record_action(\n repo_root,\n action_type,\n &before_sha,\n &after_sha,\n branch.trim(),\n pushed,\n remote_for_undo,\n message,\n ) {\n debug!(\"failed to record undo action: {}\", e);\n }\n}\n\nconst COMMIT_QUEUE_DIR: &str = \".ai/internal/commit-queue\";\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct CommitQueueEntry {\n version: u8,\n created_at: String,\n repo_root: String,\n branch: String,\n commit_sha: String,\n message: String,\n review_bookmark: Option<String>,\n #[serde(default)]\n review_completed: bool,\n #[serde(default)]\n review_issues_found: bool,\n #[serde(default)]\n review_timed_out: bool,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n review_model: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n review_reviewer: Option<String>,\n #[serde(default, skip_serializing_if = \"Vec::is_empty\")]\n review_todo_ids: Vec<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pr_url: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pr_number: Option<u64>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pr_head: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pr_base: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n analysis: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n review: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n summary: Option<String>,\n #[serde(skip)]\n record_path: Option<PathBuf>,\n}\n\nconst RISE_REVIEW_DIR: &str = \".ai/internal/rise-review\";\nconst EMPTY_TREE_HASH: &str = \"4b825dc642cb6eb9a060e54bf8d69288fbee4904\";\n\n#[derive(Debug, Serialize)]\nstruct RiseReviewFileEntry {\n status: String,\n path: String,\n #[serde(skip_serializing_if = \"Option::is_none\", rename = \"originalPath\")]\n original_path: Option<String>,\n}\n\n#[derive(Debug, Serialize)]\nstruct RiseReviewSession {\n version: u8,\n #[serde(rename = \"created_at\")]\n created_at: String,\n #[serde(rename = \"repoRoot\")]\n repo_root: String,\n commit: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n parent: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n bookmark: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n branch: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n message: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n analysis: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n review: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n summary: Option<String>,\n files: Vec<RiseReviewFileEntry>,\n}\n\nfn short_sha(sha: &str) -> &str {\n if sha.len() <= 7 { sha } else { &sha[..7] }\n}\n\nfn commit_queue_dir(repo_root: &Path) -> PathBuf {\n repo_root.join(COMMIT_QUEUE_DIR)\n}\n\nfn commit_queue_entry_path(repo_root: &Path, sha: &str) -> PathBuf {\n commit_queue_dir(repo_root).join(format!(\"{}.json\", sha))\n}\n\nfn write_commit_queue_entry(repo_root: &Path, entry: &CommitQueueEntry) -> Result<PathBuf> {\n let dir = commit_queue_dir(repo_root);\n fs::create_dir_all(&dir)?;\n let payload = serde_json::to_string_pretty(entry).context(\"serialize commit queue entry\")?;\n let path = commit_queue_entry_path(repo_root, &entry.commit_sha);\n fs::write(&path, payload).context(\"write commit queue entry\")?;\n Ok(path)\n}\n\nfn format_review_body(review: &ReviewResult) -> Option<String> {\n if review.issues.is_empty() {\n return None;\n }\n let mut out = String::new();\n for issue in &review.issues {\n if !out.is_empty() {\n out.push('\\n');\n }\n out.push_str(\"- \");\n out.push_str(issue);\n }\n Some(out)\n}\n\nfn resolve_commit_parent(repo_root: &Path, commit_sha: &str) -> String {\n match git_capture_in(repo_root, &[\"rev-parse\", &format!(\"{}^\", commit_sha)]) {\n Ok(parent) => {\n let trimmed = parent.trim().to_string();\n if trimmed.is_empty() {\n EMPTY_TREE_HASH.to_string()\n } else {\n trimmed\n }\n }\n Err(_) => EMPTY_TREE_HASH.to_string(),\n }\n}\n\nfn resolve_commit_message(repo_root: &Path, entry: &CommitQueueEntry) -> Option<String> {\n if !entry.message.trim().is_empty() {\n return Some(entry.message.clone());\n }\n git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%B\", &entry.commit_sha])\n .ok()\n .map(|message| message.trim().to_string())\n .filter(|message| !message.is_empty())\n}\n\nfn resolve_review_files(repo_root: &Path, commit_sha: &str) -> Vec<RiseReviewFileEntry> {\n let output = git_capture_in(\n repo_root,\n &[\n \"diff-tree\",\n \"--root\",\n \"--no-commit-id\",\n \"--name-status\",\n \"-r\",\n \"-M\",\n commit_sha,\n ],\n );\n\n let Ok(output) = output else {\n return Vec::new();\n };\n\n output\n .lines()\n .filter_map(|line| {\n if line.trim().is_empty() {\n return None;\n }\n let mut parts = line.split('\\t');\n let status = parts.next().unwrap_or_default().trim().to_string();\n if status.starts_with('R') || status.starts_with('C') {\n let original = parts.next().unwrap_or_default().trim().to_string();\n let path = parts.next().unwrap_or_default().trim().to_string();\n if path.is_empty() {\n return None;\n }\n return Some(RiseReviewFileEntry {\n status,\n path,\n original_path: if original.is_empty() {\n None\n } else {\n Some(original)\n },\n });\n }\n let path = parts.next().unwrap_or_default().trim().to_string();\n if path.is_empty() {\n return None;\n }\n Some(RiseReviewFileEntry {\n status,\n path,\n original_path: None,\n })\n })\n .collect()\n}\n\nfn write_rise_review_session(repo_root: &Path, entry: &CommitQueueEntry) -> Result<PathBuf> {\n let review_dir = repo_root.join(RISE_REVIEW_DIR);\n fs::create_dir_all(&review_dir)\n .with_context(|| format!(\"failed to create {}\", review_dir.display()))?;\n\n let session = RiseReviewSession {\n version: 1,\n created_at: entry.created_at.clone(),\n repo_root: entry.repo_root.clone(),\n commit: entry.commit_sha.clone(),\n parent: Some(resolve_commit_parent(repo_root, &entry.commit_sha)),\n bookmark: entry.review_bookmark.clone(),\n branch: Some(entry.branch.clone()),\n message: resolve_commit_message(repo_root, entry),\n analysis: entry.analysis.clone(),\n review: entry.review.clone(),\n summary: entry.summary.clone(),\n files: resolve_review_files(repo_root, &entry.commit_sha),\n };\n\n let path = review_dir.join(format!(\"review-{}.json\", entry.commit_sha));\n let payload =\n serde_json::to_string_pretty(&session).context(\"serialize rise review session\")?;\n fs::write(&path, payload).context(\"write rise review session\")?;\n Ok(path)\n}\n\nfn rise_review_path(repo_root: &Path, commit_sha: &str) -> PathBuf {\n repo_root\n .join(RISE_REVIEW_DIR)\n .join(format!(\"review-{}.json\", commit_sha))\n}\n\nfn delete_rise_review_session(repo_root: &Path, commit_sha: &str) {\n let path = rise_review_path(repo_root, commit_sha);\n if path.exists() {\n let _ = fs::remove_file(path);\n }\n}\n\nfn git_is_ancestor(repo_root: &Path, ancestor: &str, descendant: &str) -> bool {\n Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"merge-base\", \"--is-ancestor\", ancestor, descendant])\n .status()\n .map(|status| status.success())\n .unwrap_or(false)\n}\n\nfn load_commit_queue_entries(repo_root: &Path) -> Result<Vec<CommitQueueEntry>> {\n let dir = commit_queue_dir(repo_root);\n if !dir.exists() {\n return Ok(Vec::new());\n }\n\n let mut entries = Vec::new();\n for entry in fs::read_dir(&dir).context(\"read commit queue directory\")? {\n let entry = entry?;\n let path = entry.path();\n if path.extension().and_then(|e| e.to_str()) != Some(\"json\") {\n continue;\n }\n let content = fs::read_to_string(&path).unwrap_or_default();\n match serde_json::from_str::<CommitQueueEntry>(&content) {\n Ok(mut parsed) => {\n parsed.record_path = Some(path);\n entries.push(parsed);\n }\n Err(err) => debug!(path = %path.display(), error = %err, \"invalid commit queue entry\"),\n }\n }\n entries.sort_by(|a, b| a.created_at.cmp(&b.created_at));\n Ok(entries)\n}\n\nfn resolve_commit_queue_entry(repo_root: &Path, hash: &str) -> Result<CommitQueueEntry> {\n let entries = load_commit_queue_entries(repo_root)?;\n let matches: Vec<_> = entries\n .into_iter()\n .filter(|entry| commit_queue_entry_matches(entry, hash))\n .collect();\n\n match matches.len() {\n 0 => bail!(\"No queued commit matches {}\", hash),\n 1 => Ok(matches.into_iter().next().unwrap()),\n _ => bail!(\"Multiple queued commits match {}. Use a longer hash.\", hash),\n }\n}\n\nfn resolve_git_commit_sha(repo_root: &Path, hash: &str) -> Result<String> {\n let rev = format!(\"{hash}^{{commit}}\");\n let sha = git_capture_in(repo_root, &[\"rev-parse\", \"--verify\", &rev])\n .with_context(|| format!(\"{hash} is not a valid git commit\"))?;\n let trimmed = sha.trim();\n if trimmed.is_empty() {\n bail!(\"{hash} is not a valid git commit\");\n }\n Ok(trimmed.to_string())\n}\n\nfn queue_existing_commit_for_approval(\n repo_root: &Path,\n hash: &str,\n mark_reviewed: bool,\n) -> Result<CommitQueueEntry> {\n let commit_sha = resolve_git_commit_sha(repo_root, hash)?;\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string())\n .trim()\n .to_string();\n let message = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%s\", &commit_sha])\n .unwrap_or_default()\n .trim()\n .to_string();\n let review_bookmark = create_review_bookmark(repo_root, &commit_sha, &branch).ok();\n\n let mut entry = CommitQueueEntry {\n version: 2,\n created_at: chrono::Utc::now().to_rfc3339(),\n repo_root: repo_root.display().to_string(),\n branch,\n commit_sha: commit_sha.clone(),\n message,\n review_bookmark,\n review_completed: mark_reviewed,\n review_issues_found: false,\n review_timed_out: !mark_reviewed,\n review_model: if mark_reviewed {\n Some(\"manual-codex\".to_string())\n } else {\n None\n },\n review_reviewer: if mark_reviewed {\n Some(\"codex\".to_string())\n } else {\n None\n },\n review_todo_ids: Vec::new(),\n pr_url: None,\n pr_number: None,\n pr_head: None,\n pr_base: None,\n analysis: None,\n review: None,\n summary: if mark_reviewed {\n Some(\"Manually reviewed with Codex; approved for push.\".to_string())\n } else {\n Some(\"Queued from git history without review metadata.\".to_string())\n },\n record_path: None,\n };\n\n let path = write_commit_queue_entry(repo_root, &entry)?;\n entry.record_path = Some(path);\n if let Err(err) = write_rise_review_session(repo_root, &entry) {\n debug!(\"failed to write rise review session: {}\", err);\n }\n Ok(entry)\n}\n\nfn remove_commit_queue_entry_by_entry(repo_root: &Path, entry: &CommitQueueEntry) -> Result<()> {\n if let Some(path) = entry.record_path.as_ref() {\n if path.exists() {\n fs::remove_file(path).context(\"remove commit queue entry\")?;\n }\n }\n let path = commit_queue_entry_path(repo_root, &entry.commit_sha);\n if path.exists() {\n fs::remove_file(&path).context(\"remove commit queue entry\")?;\n }\n delete_rise_review_session(repo_root, &entry.commit_sha);\n Ok(())\n}\n\nfn queue_commit_for_review(\n repo_root: &Path,\n message: &str,\n review: Option<&ReviewResult>,\n review_model: Option<&str>,\n review_reviewer: Option<&str>,\n review_todo_ids: Vec<String>,\n) -> Result<String> {\n let commit_sha = git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"])?\n .trim()\n .to_string();\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string())\n .trim()\n .to_string();\n let review_bookmark = create_review_bookmark(repo_root, &commit_sha, &branch).ok();\n let summary = review\n .and_then(|value| value.summary.clone())\n .and_then(|value| {\n let trimmed = value.trim().to_string();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed)\n }\n });\n let review_body = review.and_then(format_review_body);\n\n let entry = CommitQueueEntry {\n version: 2,\n created_at: chrono::Utc::now().to_rfc3339(),\n repo_root: repo_root.display().to_string(),\n branch,\n commit_sha: commit_sha.clone(),\n message: message.to_string(),\n review_bookmark,\n review_completed: review.is_some(),\n review_issues_found: review.map(|r| r.issues_found).unwrap_or(false),\n review_timed_out: review.map(|r| r.timed_out).unwrap_or(false),\n review_model: review_model.map(|s| s.to_string()),\n review_reviewer: review_reviewer.map(|s| s.to_string()),\n review_todo_ids,\n pr_url: None,\n pr_number: None,\n pr_head: None,\n pr_base: None,\n analysis: None,\n review: review_body,\n summary,\n record_path: None,\n };\n\n let path = write_commit_queue_entry(repo_root, &entry)?;\n let _ = path;\n if let Err(err) = write_rise_review_session(repo_root, &entry) {\n debug!(\"failed to write rise review session: {}\", err);\n }\n Ok(commit_sha)\n}\n\nfn open_review_in_rise(repo_root: &Path, commit_sha: &str) {\n // Prefer rise-app (VS Code fork) because it has the best multi-file diff UX.\n // Fall back to `rise review open` if rise-app isn't installed.\n let (cmd, args): (String, Vec<String>) = if let Ok(rise_app_path) = which::which(\"rise-app\") {\n // Ensure review file exists, then open it explicitly.\n let review_file = rise_review_path(repo_root, commit_sha);\n if !review_file.exists() {\n // Best-effort recreate; failures here shouldn't block.\n if let Ok(entry) = resolve_commit_queue_entry(repo_root, commit_sha) {\n let _ = write_rise_review_session(repo_root, &entry);\n }\n }\n\n // Some installations place the JS wrapper directly on PATH without a shebang.\n // In that case, execute it with node.\n let launch_with_node = fs::read(&rise_app_path)\n .ok()\n .and_then(|bytes| {\n bytes\n .get(0..128)\n .map(|chunk| String::from_utf8_lossy(chunk).to_string())\n })\n .map(|head| {\n !head.starts_with(\"#!\") && (head.starts_with(\"/*\") || head.starts_with(\"//\"))\n })\n .unwrap_or(false);\n\n if launch_with_node {\n (\n \"node\".to_string(),\n vec![\n rise_app_path.display().to_string(),\n \"review\".to_string(),\n \"--review-file\".to_string(),\n review_file.display().to_string(),\n ],\n )\n } else {\n (\n rise_app_path.display().to_string(),\n vec![\n \"review\".to_string(),\n \"--review-file\".to_string(),\n review_file.display().to_string(),\n ],\n )\n }\n } else if which::which(\"rise\").is_ok() {\n (\n \"rise\".to_string(),\n vec![\n \"review\".to_string(),\n \"open\".to_string(),\n \"--queue\".to_string(),\n commit_sha.to_string(),\n ],\n )\n } else {\n println!(\"Rise not found on PATH; skipping review open.\");\n return;\n };\n\n let status = Command::new(&cmd)\n .args(&args)\n .current_dir(repo_root)\n .status();\n\n match status {\n Ok(status) => {\n if !status.success() {\n println!(\"⚠ Failed to open review (exit {}).\", status);\n }\n }\n Err(err) => println!(\"⚠ Failed to run review opener: {}\", err),\n }\n}\n\npub fn open_latest_queue_review() -> Result<()> {\n ensure_git_repo()?;\n let repo_root = git_root_or_cwd();\n let _ = refresh_commit_queue(&repo_root);\n let mut entries = load_commit_queue_entries(&repo_root)?;\n if entries.is_empty() {\n bail!(\"Commit queue is empty.\");\n }\n let entry = entries.pop().unwrap();\n println!(\n \"Opening latest queued commit {} in Rise...\",\n short_sha(&entry.commit_sha)\n );\n open_review_in_rise(&repo_root, &entry.commit_sha);\n Ok(())\n}\n\nfn latest_review_report_for_commit(repo_root: &Path, commit_sha: &str) -> Option<PathBuf> {\n let report_dir = flow_commit_reports_dir()?;\n let sha_short = short_sha(commit_sha);\n let project_slug = safe_label_value(&flow_project_name(repo_root));\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string())\n .trim()\n .to_string();\n let branch_slug = safe_label_value(&branch);\n let strict_prefix = format!(\"{project_slug}-{branch_slug}-{sha_short}-\");\n\n let mut strict_matches: Vec<PathBuf> = Vec::new();\n let mut fallback_matches: Vec<PathBuf> = Vec::new();\n for entry in fs::read_dir(&report_dir).ok()? {\n let path = entry.ok()?.path();\n if path.extension().and_then(|e| e.to_str()) != Some(\"md\") {\n continue;\n }\n let Some(file_name) = path.file_name().and_then(|n| n.to_str()) else {\n continue;\n };\n if file_name.starts_with(&strict_prefix) {\n strict_matches.push(path);\n } else if file_name.contains(&format!(\"-{sha_short}-\")) {\n fallback_matches.push(path);\n }\n }\n\n strict_matches.sort_by(|a, b| a.file_name().cmp(&b.file_name()));\n fallback_matches.sort_by(|a, b| a.file_name().cmp(&b.file_name()));\n\n strict_matches.pop().or_else(|| fallback_matches.pop())\n}\n\nfn queued_review_counts_excluding(\n repo_root: &Path,\n excluded_commit_sha: &str,\n) -> Result<(usize, usize, String)> {\n let entries = load_commit_queue_entries(repo_root)?;\n let current_branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string())\n .trim()\n .to_string();\n\n let mut total_other = 0usize;\n let mut branch_other = 0usize;\n for entry in entries {\n if entry.commit_sha == excluded_commit_sha {\n continue;\n }\n total_other += 1;\n if entry.branch.trim() == current_branch {\n branch_other += 1;\n }\n }\n\n Ok((branch_other, total_other, current_branch))\n}\n\nfn print_other_queued_review_count(repo_root: &Path, commit_sha: &str) {\n let Ok((branch_other, total_other, current_branch)) =\n queued_review_counts_excluding(repo_root, commit_sha)\n else {\n return;\n };\n\n if total_other == 0 {\n println!(\"No other queued commits pending review.\");\n return;\n }\n\n println!(\n \"{} other queued commit(s) pending review ({} on current branch {}).\",\n total_other, branch_other, current_branch\n );\n}\n\nfn copy_text_to_clipboard(text: &str) -> Result<bool> {\n if std::env::var(\"FLOW_NO_CLIPBOARD\").is_ok() || !std::io::stdin().is_terminal() {\n return Ok(false);\n }\n\n #[cfg(target_os = \"macos\")]\n {\n let mut child = Command::new(\"pbcopy\")\n .stdin(Stdio::piped())\n .spawn()\n .context(\"failed to spawn pbcopy\")?;\n\n if let Some(stdin) = child.stdin.as_mut() {\n stdin.write_all(text.as_bytes())?;\n }\n\n child.wait()?;\n return Ok(true);\n }\n\n #[cfg(target_os = \"linux\")]\n {\n let result = Command::new(\"xclip\")\n .arg(\"-selection\")\n .arg(\"clipboard\")\n .stdin(Stdio::piped())\n .spawn();\n\n let mut child = match result {\n Ok(c) => c,\n Err(_) => Command::new(\"xsel\")\n .arg(\"--clipboard\")\n .arg(\"--input\")\n .stdin(Stdio::piped())\n .spawn()\n .context(\"failed to spawn xclip or xsel\")?,\n };\n\n if let Some(stdin) = child.stdin.as_mut() {\n stdin.write_all(text.as_bytes())?;\n }\n\n child.wait()?;\n return Ok(true);\n }\n\n #[cfg(not(any(target_os = \"macos\", target_os = \"linux\")))]\n {\n bail!(\"clipboard not supported on this platform\");\n }\n}\n\nfn build_review_prompt_payload(\n repo_root: &Path,\n entry: &CommitQueueEntry,\n report_path: Option<&Path>,\n) -> String {\n let (branch_other, total_other, current_branch) = queued_review_counts_excluding(\n repo_root,\n &entry.commit_sha,\n )\n .unwrap_or((0, 0, \"unknown\".to_string()));\n let mut out = String::new();\n out.push_str(\"here is commit i want you to address fully\\n\\n\");\n out.push_str(&format!(\n \"Repo: {}\\nBranch: {}\\nQueued commit: {}\",\n repo_root.display(),\n entry.branch.trim(),\n short_sha(&entry.commit_sha)\n ));\n if let Some(bookmark) = entry\n .review_bookmark\n .as_deref()\n .map(str::trim)\n .filter(|s| !s.is_empty())\n {\n out.push_str(&format!(\"\\nReview bookmark: {}\", bookmark));\n }\n out.push_str(\"\\n\\nCommands:\\n\");\n out.push_str(&format!(\n \"f commit-queue show {}\\n\",\n short_sha(&entry.commit_sha)\n ));\n out.push_str(&format!(\n \"f commit-queue approve {}\\n\",\n short_sha(&entry.commit_sha)\n ));\n out.push_str(\"f commit-queue approve --all\\n\");\n\n if let Some(path) = report_path {\n out.push_str(&format!(\"\\nReview report: {}\\n\", path.display()));\n out.push_str(&format!(\"Run: f fix {}\\n\", path.display()));\n }\n\n out.push_str(\"\\nCommit message:\\n\");\n out.push_str(\"────────────────────────────────────────\\n\");\n out.push_str(entry.message.trim_end());\n out.push_str(\"\\n────────────────────────────────────────\\n\");\n\n if let Some(summary) = entry\n .summary\n .as_deref()\n .map(str::trim)\n .filter(|s| !s.is_empty())\n {\n out.push_str(\"\\nReview summary:\\n\");\n out.push_str(summary);\n out.push('\\n');\n }\n\n if let Some(review) = entry\n .review\n .as_deref()\n .map(str::trim)\n .filter(|s| !s.is_empty())\n {\n out.push_str(\"\\nReview findings:\\n\");\n out.push_str(review);\n out.push('\\n');\n }\n\n if let Some(path) = report_path {\n if let Ok(markdown) = fs::read_to_string(path) {\n let trimmed = markdown.trim();\n if !trimmed.is_empty() {\n out.push_str(\"\\nReview report markdown:\\n\");\n out.push_str(trimmed);\n out.push('\\n');\n }\n }\n }\n\n if total_other == 0 {\n out.push_str(\"\\nOther queued commits pending review: 0\\n\");\n } else {\n out.push_str(&format!(\n \"\\nOther queued commits pending review: {} ({} on current branch {})\\n\",\n total_other, branch_other, current_branch\n ));\n }\n\n out.push_str(\"\\naddress this so we can push\\n\");\n out\n}\n\npub fn copy_review_prompt(hash: Option<&str>) -> Result<()> {\n ensure_git_repo()?;\n let repo_root = git_root_or_cwd();\n let _ = refresh_commit_queue(&repo_root);\n\n let mut entry = if let Some(hash) = hash {\n resolve_commit_queue_entry(&repo_root, hash)?\n } else {\n let mut entries = load_commit_queue_entries(&repo_root)?;\n if entries.is_empty() {\n bail!(\"Commit queue is empty.\");\n }\n entries.pop().unwrap()\n };\n let _ = refresh_queue_entry_commit(&repo_root, &mut entry);\n\n let report_path = latest_review_report_for_commit(&repo_root, &entry.commit_sha);\n let payload = build_review_prompt_payload(&repo_root, &entry, report_path.as_deref());\n\n match copy_text_to_clipboard(&payload) {\n Ok(true) => println!(\n \"Copied review prompt for {} to clipboard.\",\n short_sha(&entry.commit_sha)\n ),\n Ok(false) => {\n println!(\"Clipboard copy skipped (non-interactive shell or FLOW_NO_CLIPBOARD).\")\n }\n Err(err) => println!(\"⚠ Failed to copy review prompt to clipboard: {}\", err),\n }\n\n println!(\"────────────────────────────────────────\");\n println!(\"{}\", payload.trim_end());\n println!(\"────────────────────────────────────────\");\n Ok(())\n}\n\nfn print_queue_instructions(repo_root: &Path, commit_sha: &str) {\n println!(\"Queued commit {} for review.\", short_sha(commit_sha));\n println!(\" f commit-queue list\");\n println!(\" f commit-queue show {}\", short_sha(commit_sha));\n println!(\n \" When review passes: f commit-queue approve {}\",\n short_sha(commit_sha)\n );\n println!(\" When all pass: f commit-queue approve --all\");\n println!(\" f review copy {}\", short_sha(commit_sha));\n print_other_queued_review_count(repo_root, commit_sha);\n}\n\nfn queue_review_status_label(entry: &CommitQueueEntry) -> &'static str {\n let issues_present = entry.review_issues_found\n || entry\n .review\n .as_deref()\n .map(|s| !s.trim().is_empty())\n .unwrap_or(false);\n if entry.review_timed_out {\n \"review timed out\"\n } else if issues_present {\n \"review issues\"\n } else if entry.version >= 2 && !entry.review_completed {\n \"review pending\"\n } else {\n \"review clean\"\n }\n}\n\nfn print_pending_queue_review_hint(repo_root: &Path) {\n let mut entries = match load_commit_queue_entries(repo_root) {\n Ok(entries) => entries,\n Err(_) => return,\n };\n if entries.is_empty() {\n return;\n }\n\n for entry in &mut entries {\n let _ = refresh_queue_entry_commit(repo_root, entry);\n }\n\n let current_branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string())\n .trim()\n .to_string();\n\n let mut scoped_entries: Vec<&CommitQueueEntry> = entries\n .iter()\n .filter(|entry| entry.branch.trim() == current_branch)\n .collect();\n let scoped_to_branch = !scoped_entries.is_empty();\n if !scoped_to_branch {\n scoped_entries = entries.iter().collect();\n }\n\n println!();\n if scoped_to_branch {\n println!(\n \"Queued commits pending review on branch {}:\",\n current_branch\n );\n } else {\n println!(\"Queued commits pending review (all branches):\");\n }\n\n let max_display = 5usize;\n for entry in scoped_entries.iter().take(max_display) {\n println!(\n \" - {} {} {}\",\n short_sha(&entry.commit_sha),\n format_queue_created_at(&entry.created_at),\n queue_review_status_label(entry)\n );\n }\n if scoped_entries.len() > max_display {\n println!(\" ... and {} more\", scoped_entries.len() - max_display);\n }\n\n println!(\"Next:\");\n println!(\" f commit-queue list\");\n println!(\" f commit-queue approve --all\");\n}\n\nfn approve_all_queued_commits(\n repo_root: &Path,\n force: bool,\n allow_issues: bool,\n allow_unreviewed: bool,\n) -> Result<()> {\n git_guard::ensure_clean_for_push(repo_root)?;\n let mut entries = load_commit_queue_entries(repo_root)?;\n if entries.is_empty() {\n println!(\"No queued commits.\");\n return Ok(());\n }\n\n for entry in &mut entries {\n let _ = refresh_queue_entry_commit(repo_root, entry);\n }\n\n let current_branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string());\n let current_branch = current_branch.trim().to_string();\n\n let mut candidates = Vec::new();\n let mut skipped_branch = Vec::new();\n for entry in entries {\n if !force && entry.branch.trim() != current_branch {\n skipped_branch.push(entry);\n } else {\n candidates.push(entry);\n }\n }\n\n if candidates.is_empty() {\n if skipped_branch.is_empty() {\n println!(\"No queued commits to approve.\");\n } else {\n println!(\n \"No queued commits on branch {}. {} queued commit(s) are on other branches.\",\n current_branch,\n skipped_branch.len()\n );\n }\n return Ok(());\n }\n\n if !force {\n let mut bad_issues: Vec<String> = Vec::new();\n let mut bad_unreviewed: Vec<String> = Vec::new();\n for entry in &candidates {\n let issues_present = entry.review_issues_found\n || entry\n .review\n .as_deref()\n .map(|s| !s.trim().is_empty())\n .unwrap_or(false);\n let unreviewed =\n (entry.version >= 2 && !entry.review_completed) || entry.review_timed_out;\n if issues_present && !allow_issues {\n bad_issues.push(short_sha(&entry.commit_sha).to_string());\n }\n if unreviewed && !allow_unreviewed {\n bad_unreviewed.push(short_sha(&entry.commit_sha).to_string());\n }\n }\n\n if !bad_unreviewed.is_empty() {\n bail!(\n \"Some queued commits do not have a clean review (timed out/missing): {}. Re-run review or use --allow-unreviewed.\",\n bad_unreviewed.join(\", \")\n );\n }\n if !bad_issues.is_empty() {\n bail!(\n \"Some queued commits have review issues: {}. Fix them or use --allow-issues.\",\n bad_issues.join(\", \")\n );\n }\n }\n\n let head_sha = git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"])?;\n let head_sha = head_sha.trim().to_string();\n ensure_safe_upstream_for_commit_queue_push(repo_root, &head_sha, force)?;\n\n if git_try_in(repo_root, &[\"fetch\", \"--quiet\"]).is_ok() {\n if let Ok(counts) = git_capture_in(\n repo_root,\n &[\"rev-list\", \"--left-right\", \"--count\", \"@{u}...HEAD\"],\n ) {\n let parts: Vec<&str> = counts.split_whitespace().collect();\n if parts.len() == 2 {\n let behind = parts[0].parse::<u64>().unwrap_or(0);\n if behind > 0 && !force {\n bail!(\n \"Remote is ahead by {} commit(s). Run `f sync` or rebase, then re-approve.\",\n behind\n );\n }\n }\n }\n }\n\n let before_sha = git_capture_in(repo_root, &[\"rev-parse\", \"@{u}\"]).ok();\n let push_remote = config::preferred_git_remote_for_repo(repo_root);\n let push_branch = current_branch.trim().to_string();\n\n print!(\"Pushing... \");\n io::stdout().flush()?;\n let mut pushed = false;\n match git_push_try_in(repo_root, &push_remote, &push_branch) {\n PushResult::Success => {\n println!(\"done\");\n pushed = true;\n }\n PushResult::NoRemoteRepo => {\n println!(\"skipped (no remote repo)\");\n }\n PushResult::RemoteAhead => {\n println!(\"failed (remote ahead)\");\n print!(\"Pulling with rebase... \");\n io::stdout().flush()?;\n match git_pull_rebase_try_in(repo_root, &push_remote, &push_branch) {\n Ok(_) => {\n println!(\"done\");\n print!(\"Pushing... \");\n io::stdout().flush()?;\n git_push_run_in(repo_root, &push_remote, &push_branch)?;\n println!(\"done\");\n pushed = true;\n }\n Err(_) => {\n println!(\"conflict!\");\n println!();\n println!(\"Rebase conflict detected. Resolve manually:\");\n println!(\" 1. Fix conflicts in the listed files\");\n println!(\" 2. git add <files>\");\n println!(\" 3. git rebase --continue\");\n println!(\" 4. git push\");\n println!();\n println!(\"Or abort with: git rebase --abort\");\n bail!(\"Rebase conflict - manual resolution required\");\n }\n }\n }\n }\n\n if pushed {\n if let (Some(before_sha), Ok(after_sha)) = (\n before_sha,\n git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"]),\n ) {\n let branch = current_branch.as_str();\n let before_sha = before_sha.trim();\n let after_sha = after_sha.trim();\n let _ = undo::record_action(\n repo_root,\n undo::ActionType::Push,\n before_sha,\n after_sha,\n branch,\n true,\n Some(push_remote.as_str()),\n None,\n );\n }\n\n let head_sha = git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"]).unwrap_or_default();\n let head_sha = head_sha.trim();\n let mut approved = 0;\n let mut skipped = 0;\n\n for entry in &candidates {\n if git_is_ancestor(repo_root, &entry.commit_sha, head_sha) {\n if let Some(bookmark) = entry.review_bookmark.as_ref() {\n delete_review_bookmark(repo_root, bookmark);\n }\n remove_commit_queue_entry_by_entry(repo_root, entry)?;\n if let Ok(done) =\n todo::complete_review_timeout_todos(repo_root, &entry.review_todo_ids)\n {\n if done > 0 {\n println!(\"Auto-completed {} review follow-up todo(s).\", done);\n }\n }\n approved += 1;\n } else {\n println!(\n \"Skipped queued commit {} (not reachable from HEAD)\",\n short_sha(&entry.commit_sha)\n );\n skipped += 1;\n }\n }\n\n if !skipped_branch.is_empty() {\n println!(\n \"Skipped {} queued commit(s) on other branches.\",\n skipped_branch.len()\n );\n }\n\n println!(\n \"✓ Approved and pushed {} queued commit(s){}\",\n approved,\n if skipped > 0 { \" (some skipped)\" } else { \"\" }\n );\n }\n\n Ok(())\n}\n\nfn commit_queue_entry_matches(entry: &CommitQueueEntry, hash: &str) -> bool {\n if entry.commit_sha.starts_with(hash) {\n return true;\n }\n if let Some(path) = entry.record_path.as_ref() {\n if let Some(stem) = path.file_stem().and_then(|s| s.to_str()) {\n return stem.starts_with(hash);\n }\n }\n false\n}\n\nfn refresh_queue_entry_commit(repo_root: &Path, entry: &mut CommitQueueEntry) -> Result<bool> {\n let Some(bookmark) = entry.review_bookmark.as_deref() else {\n return Ok(false);\n };\n let Some(jj_root) = vcs::jj_root_if_exists(repo_root) else {\n return Ok(false);\n };\n let Ok(output) = jj_capture_in(\n &jj_root,\n &[\"log\", \"-r\", bookmark, \"--no-graph\", \"-T\", \"commit_id\"],\n ) else {\n return Ok(false);\n };\n let new_sha = output\n .split_whitespace()\n .next()\n .unwrap_or_default()\n .trim()\n .to_string();\n if new_sha.is_empty() || new_sha == entry.commit_sha {\n return Ok(false);\n }\n\n let old_sha = entry.commit_sha.clone();\n let old_path = entry\n .record_path\n .clone()\n .unwrap_or_else(|| commit_queue_entry_path(repo_root, &entry.commit_sha));\n entry.commit_sha = new_sha;\n let new_path = write_commit_queue_entry(repo_root, entry)?;\n if old_path != new_path && old_path.exists() {\n let _ = fs::remove_file(&old_path);\n }\n entry.record_path = Some(new_path);\n delete_rise_review_session(repo_root, &old_sha);\n if let Err(err) = write_rise_review_session(repo_root, entry) {\n debug!(\"failed to refresh rise review session: {}\", err);\n }\n Ok(true)\n}\n\nfn current_upstream_ref(repo_root: &Path) -> Option<String> {\n git_capture_in(\n repo_root,\n &[\"rev-parse\", \"--abbrev-ref\", \"--symbolic-full-name\", \"@{u}\"],\n )\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n}\n\nfn is_ephemeral_upstream_ref(upstream: &str) -> bool {\n upstream.starts_with(\"origin/jj/keep/\")\n || upstream.starts_with(\"origin/review/\")\n || upstream.contains(\"/jj/keep/\")\n || upstream.contains(\"/review/\")\n}\n\nfn find_best_pr_upstream_candidate(repo_root: &Path, head_sha: &str) -> Option<String> {\n let refs = git_capture_in(\n repo_root,\n &[\n \"for-each-ref\",\n \"--format=%(refname:short)\",\n \"refs/remotes/origin/pr/\",\n ],\n )\n .ok()?;\n\n let mut best: Option<(u64, String)> = None;\n for candidate in refs.lines().map(str::trim).filter(|s| !s.is_empty()) {\n if !git_is_ancestor(repo_root, candidate, head_sha) {\n continue;\n }\n let distance = git_capture_in(\n repo_root,\n &[\"rev-list\", \"--count\", &format!(\"{candidate}..{head_sha}\")],\n )\n .ok()\n .and_then(|s| s.trim().parse::<u64>().ok())\n .unwrap_or(u64::MAX);\n match &best {\n Some((best_distance, _)) if *best_distance <= distance => {}\n _ => best = Some((distance, candidate.to_string())),\n }\n }\n best.map(|(_, candidate)| candidate)\n}\n\nfn ensure_safe_upstream_for_commit_queue_push(\n repo_root: &Path,\n head_sha: &str,\n force: bool,\n) -> Result<()> {\n let upstream = current_upstream_ref(repo_root);\n\n if let Some(upstream) = upstream {\n if is_ephemeral_upstream_ref(&upstream) && !force {\n if let Some(candidate) = find_best_pr_upstream_candidate(repo_root, head_sha) {\n if candidate != upstream {\n println!(\n \"Upstream {} looks ephemeral. Retargeting push upstream to {}.\",\n upstream, candidate\n );\n git_run_in(repo_root, &[\"branch\", \"--set-upstream-to\", &candidate])?;\n }\n } else {\n bail!(\n \"Current upstream {} looks ephemeral and no origin/pr/* candidate was found. Set upstream explicitly to your PR branch, or re-run with --force.\",\n upstream\n );\n }\n }\n return Ok(());\n }\n\n if force {\n return Ok(());\n }\n\n if let Some(candidate) = find_best_pr_upstream_candidate(repo_root, head_sha) {\n println!(\n \"No upstream configured. Using {} as push upstream.\",\n candidate\n );\n git_run_in(repo_root, &[\"branch\", \"--set-upstream-to\", &candidate])?;\n return Ok(());\n }\n\n bail!(\n \"No upstream configured and no origin/pr/* candidate found. Set upstream to your PR branch first, then re-run.\"\n );\n}\n\npub fn commit_queue_has_entries(repo_root: &Path) -> bool {\n let dir = commit_queue_dir(repo_root);\n if !dir.exists() {\n return false;\n }\n fs::read_dir(dir)\n .map(|entries| {\n entries\n .filter_map(|entry| entry.ok())\n .any(|entry| entry.path().extension().and_then(|s| s.to_str()) == Some(\"json\"))\n })\n .unwrap_or(false)\n}\n\npub fn commit_queue_has_entries_on_branch(repo_root: &Path, branch: &str) -> bool {\n let target = branch.trim();\n if target.is_empty() {\n return commit_queue_has_entries(repo_root);\n }\n load_commit_queue_entries(repo_root)\n .map(|entries| entries.iter().any(|entry| entry.branch.trim() == target))\n .unwrap_or_else(|_| commit_queue_has_entries(repo_root))\n}\n\npub fn commit_queue_has_entries_reachable_from_head(repo_root: &Path) -> bool {\n let head = match git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"]) {\n Ok(value) => value.trim().to_string(),\n Err(_) => return commit_queue_has_entries(repo_root),\n };\n if head.is_empty() {\n return commit_queue_has_entries(repo_root);\n }\n\n load_commit_queue_entries(repo_root)\n .map(|entries| {\n entries\n .iter()\n .any(|entry| git_is_ancestor(repo_root, &entry.commit_sha, &head))\n })\n .unwrap_or_else(|_| commit_queue_has_entries(repo_root))\n}\n\npub fn refresh_commit_queue(repo_root: &Path) -> Result<usize> {\n let mut entries = load_commit_queue_entries(repo_root)?;\n let mut updated = 0;\n for entry in &mut entries {\n if refresh_queue_entry_commit(repo_root, entry)? {\n updated += 1;\n }\n }\n Ok(updated)\n}\n\nfn queued_commit_patch(repo_root: &Path, commit_sha: &str) -> Result<String> {\n git_capture_in(\n repo_root,\n &[\"show\", \"--format=\", \"--patch\", \"--no-color\", commit_sha],\n )\n}\n\nfn with_temp_worktree_for_commit<T, F>(repo_root: &Path, commit_sha: &str, f: F) -> Result<T>\nwhere\n F: FnOnce(&Path) -> Result<T>,\n{\n let tmp = TempDir::new().context(\"create temp worktree dir\")?;\n let worktree_path = tmp.path().join(\"repo\");\n let worktree_str = worktree_path.to_string_lossy().to_string();\n\n git_run_in(\n repo_root,\n &[\"worktree\", \"add\", \"--detach\", &worktree_str, commit_sha],\n )?;\n\n let result = f(&worktree_path);\n\n if let Err(err) = git_run_in(repo_root, &[\"worktree\", \"remove\", \"--force\", &worktree_str]) {\n debug!(\n worktree = %worktree_str,\n error = %err,\n \"failed to remove temp worktree for queue review\"\n );\n }\n\n result\n}\n\nfn run_codex_review_for_queued_commit(\n repo_root: &Path,\n commit_sha: &str,\n review_instructions: Option<&str>,\n) -> Result<(ReviewResult, String)> {\n let diff = queued_commit_patch(repo_root, commit_sha)?;\n let review = with_temp_worktree_for_commit(repo_root, commit_sha, |worktree| {\n let parent = git_capture_in(worktree, &[\"rev-parse\", \"HEAD^\"])\n .context(\"queued root commit review is not supported yet\")?;\n git_run_in(worktree, &[\"reset\", \"--mixed\", parent.trim()])?;\n run_codex_review(&diff, None, review_instructions, worktree, CodexModel::High)\n })?;\n Ok((review, diff))\n}\n\nfn append_unique_ids(dest: &mut Vec<String>, ids: Vec<String>) {\n let mut seen: HashSet<String> = dest.iter().cloned().collect();\n for id in ids {\n if seen.insert(id.clone()) {\n dest.push(id);\n }\n }\n}\n\nfn review_queue_entry_with_codex(\n repo_root: &Path,\n entry: &mut CommitQueueEntry,\n review_instructions: Option<&str>,\n) -> Result<()> {\n let (review, diff) =\n run_codex_review_for_queued_commit(repo_root, &entry.commit_sha, review_instructions)?;\n\n let model_label = CodexModel::High.as_codex_arg();\n let reviewer_label = \"codex\";\n\n let mut review_todo_ids = entry.review_todo_ids.clone();\n if !env_flag(\"FLOW_REVIEW_ISSUES_TODOS_DISABLE\") {\n if review.issues_found && !review.issues.is_empty() {\n let ids = todo::record_review_issues_as_todos(\n repo_root,\n &entry.commit_sha,\n &review.issues,\n review.summary.as_deref(),\n model_label,\n )?;\n append_unique_ids(&mut review_todo_ids, ids);\n }\n if review.timed_out {\n let issue = format!(\n \"Re-run review: review timed out for commit {}\",\n short_sha(&entry.commit_sha)\n );\n let ids = todo::record_review_issues_as_todos(\n repo_root,\n &entry.commit_sha,\n &vec![issue],\n review.summary.as_deref(),\n model_label,\n )?;\n append_unique_ids(&mut review_todo_ids, ids);\n } else {\n let _ = todo::complete_review_timeout_todos(repo_root, &review_todo_ids);\n }\n }\n\n let review_run_id = flow_review_run_id(repo_root, &diff, model_label, reviewer_label);\n record_review_outputs_to_beads_rust(\n repo_root,\n &review,\n reviewer_label,\n model_label,\n Some(&entry.commit_sha),\n &review_run_id,\n );\n\n entry.review_completed = true;\n entry.review_issues_found = review.issues_found;\n entry.review_timed_out = review.timed_out;\n entry.review_model = Some(model_label.to_string());\n entry.review_reviewer = Some(reviewer_label.to_string());\n entry.review_todo_ids = review_todo_ids;\n entry.review = format_review_body(&review);\n entry.summary = review.summary.as_ref().and_then(|value| {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n }\n });\n\n let path = write_commit_queue_entry(repo_root, entry)?;\n entry.record_path = Some(path);\n let _ = write_rise_review_session(repo_root, entry);\n maybe_sync_queue_review_to_mirrors(repo_root, entry, &diff, &review, reviewer_label);\n Ok(())\n}\n\n/// Mirror queued-review results to myflow/gitedit when the reviewed commit is the current HEAD.\n/// This keeps async `f commit --quick` reviews visible in mirrors without risking wrong SHA syncs\n/// when users review arbitrary queued commits from other branches.\nfn maybe_sync_queue_review_to_mirrors(\n repo_root: &Path,\n entry: &CommitQueueEntry,\n diff: &str,\n review: &ReviewResult,\n reviewer_label: &str,\n) {\n let head_sha = match git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"]) {\n Ok(sha) => sha.trim().to_string(),\n Err(err) => {\n debug!(\n error = %err,\n \"skipping queue review mirror sync: failed to resolve HEAD\"\n );\n return;\n }\n };\n if head_sha != entry.commit_sha {\n debug!(\n queue_commit = %entry.commit_sha,\n head_commit = %head_sha,\n \"skipping queue review mirror sync: reviewed commit is not HEAD\"\n );\n return;\n }\n\n let sync_gitedit = gitedit_globally_enabled() && gitedit_mirror_enabled_for_commit(repo_root);\n let sync_myflow = myflow_mirror_enabled(repo_root);\n if !sync_gitedit && !sync_myflow {\n return;\n }\n\n let (sync_sessions, sync_window) = collect_sync_sessions_for_commit_with_window(repo_root);\n let review_data = GitEditReviewData {\n diff: Some(diff.to_string()),\n issues_found: review.issues_found,\n issues: review.issues.clone(),\n summary: review.summary.clone(),\n reviewer: Some(reviewer_label.to_string()),\n };\n\n if sync_gitedit {\n sync_to_gitedit(\n repo_root,\n \"commit_queue_review\",\n &sync_sessions,\n None,\n Some(&review_data),\n );\n }\n if sync_myflow {\n sync_to_myflow(\n repo_root,\n \"commit_queue_review\",\n &sync_sessions,\n Some(&sync_window),\n Some(&review_data),\n None,\n );\n }\n}\n\nfn queue_flag_for_command(queue: CommitQueueMode) -> String {\n if queue.enabled {\n \" --queue\".to_string()\n } else if queue.override_flag == Some(false) {\n \" --no-queue\".to_string()\n } else {\n String::new()\n }\n}\n\nfn review_flag_for_command(queue: CommitQueueMode) -> String {\n if queue.open_review {\n \" --review\".to_string()\n } else {\n String::new()\n }\n}\n\nfn review_bookmark_prefix(repo_root: &Path) -> Option<String> {\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(jj_cfg) = cfg.jj {\n if let Some(prefix) = jj_cfg.review_prefix {\n let trimmed = prefix.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n } else {\n return None;\n }\n }\n }\n }\n }\n\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n if let Some(jj_cfg) = cfg.jj {\n if let Some(prefix) = jj_cfg.review_prefix {\n let trimmed = prefix.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n } else {\n return None;\n }\n }\n }\n }\n }\n\n Some(\"review\".to_string())\n}\n\nfn sanitize_review_branch(branch: &str) -> String {\n let mut out = String::new();\n for ch in branch.chars() {\n if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' {\n out.push(ch);\n } else if ch == '/' || ch == '.' {\n out.push('-');\n }\n }\n if out.is_empty() {\n \"branch\".to_string()\n } else {\n out\n }\n}\n\nfn create_review_bookmark(repo_root: &Path, commit_sha: &str, branch: &str) -> Result<String> {\n if env_flag(\"FLOW_COMMIT_QUEUE_JJ_DISABLE\") {\n bail!(\"FLOW_COMMIT_QUEUE_JJ_DISABLE=1\");\n }\n let Some(prefix) = review_bookmark_prefix(repo_root) else {\n bail!(\"review prefix disabled\");\n };\n let Some(jj_root) = vcs::jj_root_if_exists(repo_root) else {\n println!(\"ℹ️ jj workspace not found; skipping review bookmark creation.\");\n bail!(\"jj workspace not available\");\n };\n let branch_slug = sanitize_review_branch(branch);\n let base = format!(\"{}/{}-{}\", prefix, branch_slug, short_sha(commit_sha));\n let mut name = base.clone();\n let mut index = 1;\n while jj_bookmark_exists(&jj_root, &name) {\n name = format!(\"{}-{}\", base, index);\n index += 1;\n if index > 50 {\n bail!(\"too many review bookmarks with base {}\", base);\n }\n }\n\n if let Err(err) = jj_run_in(&jj_root, &[\"bookmark\", \"create\", &name, \"-r\", commit_sha]) {\n let msg = err.to_string().to_lowercase();\n if msg.contains(\"commit not found\")\n || msg.contains(\"current working-copy commit not found\")\n || msg.contains(\"failed to load short-prefixes index\")\n || msg.contains(\"unexpected error from store\")\n || msg.contains(\"failed to check out a commit\")\n {\n println!(\"⚠️ jj workspace appears corrupted; skipping review bookmark creation.\");\n println!(\n \" Fix: `jj git import` (or if still broken: `rm -rf .jj && jj git init --colocate`)\"\n );\n bail!(\"jj workspace corrupted\");\n }\n return Err(err);\n }\n println!(\"Queued review bookmark {}\", name);\n Ok(name)\n}\n\nfn delete_review_bookmark(repo_root: &Path, bookmark: &str) {\n if let Some(jj_root) = vcs::jj_root_if_exists(repo_root) {\n let _ = jj_run_in(&jj_root, &[\"bookmark\", \"delete\", bookmark]);\n }\n}\n\nfn jj_bookmark_exists(repo_root: &Path, name: &str) -> bool {\n let output = jj_capture_in(repo_root, &[\"bookmark\", \"list\"]).unwrap_or_default();\n for line in output.lines() {\n let trimmed = line.trim_start().trim_start_matches('*').trim();\n let Some((token, _rest)) = trimmed.split_once(' ') else {\n continue;\n };\n if token == name {\n return true;\n }\n }\n false\n}\n\nfn jj_run_in(repo_root: &Path, args: &[&str]) -> Result<()> {\n let output = Command::new(jj_bin())\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run jj {}\", args.join(\" \")))?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n let stdout = String::from_utf8_lossy(&output.stdout);\n let msg = if stderr.trim().is_empty() {\n stdout.trim()\n } else {\n stderr.trim()\n };\n bail!(\"jj {} failed: {}\", args.join(\" \"), msg);\n }\n Ok(())\n}\n\nfn jj_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(jj_bin())\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run jj {}\", args.join(\" \")))?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n let stdout = String::from_utf8_lossy(&output.stdout);\n let msg = if stderr.trim().is_empty() {\n stdout.trim()\n } else {\n stderr.trim()\n };\n bail!(\"jj {} failed: {}\", args.join(\" \"), msg);\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nfn jj_bin() -> String {\n env::var(\"FLOW_JJ_BIN\")\n .ok()\n .map(|v| v.trim().to_string())\n .filter(|v| !v.is_empty())\n .unwrap_or_else(|| \"jj\".to_string())\n}\n\nfn ensure_gh_available() -> Result<()> {\n let status = Command::new(\"gh\")\n .args([\"--version\"])\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .context(\"failed to run `gh` (GitHub CLI)\")?;\n if !status.success() {\n bail!(\"`gh` is installed but not working\");\n }\n Ok(())\n}\n\nfn gh_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"gh\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run gh {}\", args.join(\" \")))?;\n if !output.status.success() {\n bail!(\n \"gh {} failed: {}\",\n args.join(\" \"),\n String::from_utf8_lossy(&output.stderr).trim()\n );\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nfn github_repo_from_remote_url(url: &str) -> Option<String> {\n let trimmed = url.trim().trim_end_matches('/');\n if trimmed.is_empty() {\n return None;\n }\n\n // https://github.com/owner/repo(.git)\n if let Some(rest) = trimmed.strip_prefix(\"https://github.com/\") {\n return Some(rest.trim_end_matches(\".git\").to_string());\n }\n\n // git@github.com:owner/repo(.git)\n if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n return Some(rest.trim_end_matches(\".git\").to_string());\n }\n\n None\n}\n\nfn resolve_github_repo(repo_root: &Path) -> Result<String> {\n // First try origin URL.\n if let Ok(url) = git_capture_in(repo_root, &[\"remote\", \"get-url\", \"origin\"]) {\n if let Some(repo) = github_repo_from_remote_url(&url) {\n return Ok(repo);\n }\n }\n\n // Fallback: ask `gh` (works for GitHub Enterprise too if authenticated).\n let repo = gh_capture_in(\n repo_root,\n &[\n \"repo\",\n \"view\",\n \"--json\",\n \"nameWithOwner\",\n \"-q\",\n \".nameWithOwner\",\n ],\n )\n .context(\"failed to resolve GitHub repo for current directory\")?;\n let repo = repo.trim();\n if repo.is_empty() {\n bail!(\n \"unable to determine GitHub repo (origin URL not GitHub, and `gh repo view` returned empty)\"\n );\n }\n Ok(repo.to_string())\n}\n\nfn sanitize_ref_component(input: &str) -> String {\n let mut out = String::new();\n let mut last_sep = false;\n for ch in input.chars() {\n if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || ch == '.' {\n out.push(ch);\n last_sep = false;\n } else if !last_sep {\n out.push('-');\n last_sep = true;\n }\n }\n out.trim_matches('-').to_string()\n}\n\nfn default_pr_head(entry: &CommitQueueEntry) -> String {\n if let Some(head) = entry\n .pr_head\n .as_deref()\n .map(|s| s.trim())\n .filter(|s| !s.is_empty())\n {\n return head.to_string();\n }\n if let Some(bookmark) = entry\n .review_bookmark\n .as_deref()\n .map(|s| s.trim())\n .filter(|s| !s.is_empty())\n {\n return bookmark.to_string();\n }\n // Fallback if jj bookmark wasn't created for some reason.\n format!(\n \"pr/{}-{}\",\n sanitize_ref_component(&entry.branch),\n short_sha(&entry.commit_sha)\n )\n}\n\nfn ensure_pr_head_pushed(repo_root: &Path, head: &str, commit_sha: &str) -> Result<String> {\n // Prefer jj bookmarks when available.\n if which::which(\"jj\").is_ok() {\n // Ensure bookmark points at the commit, then push it.\n // If jj is unhealthy (store/index/template issues), fall back to git push.\n let jj_result = (|| -> Result<()> {\n let set_output = Command::new(\"jj\")\n .current_dir(repo_root)\n .args([\n \"bookmark\",\n \"set\",\n head,\n \"-r\",\n commit_sha,\n \"--allow-backwards\",\n ])\n .output()\n .context(\"failed to run jj bookmark set for PR head\")?;\n if !set_output.status.success() {\n let stderr = String::from_utf8_lossy(&set_output.stderr);\n let stdout = String::from_utf8_lossy(&set_output.stdout);\n bail!(\n \"jj bookmark set failed: {}\",\n format!(\"{}\\n{}\", stderr.trim(), stdout.trim()).trim()\n );\n }\n\n // We often push a brand new review/pr bookmark as the PR head.\n let push_output = Command::new(\"jj\")\n .current_dir(repo_root)\n .args([\"git\", \"push\", \"--bookmark\", head, \"--allow-new\"])\n .output()\n .context(\"failed to run jj git push for PR head\")?;\n if !push_output.status.success() {\n let stderr = String::from_utf8_lossy(&push_output.stderr);\n let stdout = String::from_utf8_lossy(&push_output.stdout);\n bail!(\n \"jj git push failed: {}\",\n format!(\"{}\\n{}\", stderr.trim(), stdout.trim()).trim()\n );\n }\n\n Ok(())\n })();\n if jj_result.is_ok() {\n // jj push uses the repo's configured/default git remote.\n // Keep plain branch head; gh can resolve this for same-repo pushes.\n return Ok(head.to_string());\n }\n let jj_error = jj_result.unwrap_err().to_string();\n let concise = jj_error\n .lines()\n .map(str::trim)\n .find(|line| !line.is_empty())\n .unwrap_or(\"jj failed\");\n eprintln!(\n \"⚠️ jj bookmark push failed ({}). Falling back to git branch push for PR head.\",\n concise\n );\n }\n\n // Fallback: push commit directly to a branch ref.\n // Try likely writable remotes first to support fork/upstream setups.\n let head_refspec = format!(\"{}:refs/heads/{}\", commit_sha, head);\n let remotes = pr_push_remote_candidates(repo_root);\n if remotes.is_empty() {\n bail!(\"No git remotes configured; cannot push PR head {}\", head);\n }\n\n let mut failures: Vec<String> = Vec::new();\n for remote in remotes {\n let push_output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"push\", \"-u\", &remote, &head_refspec])\n .output()\n .with_context(|| format!(\"failed to run git push for remote {remote}\"))?;\n if push_output.status.success() {\n return Ok(pr_head_selector_for_remote(repo_root, &remote, head));\n }\n\n let push_stderr = String::from_utf8_lossy(&push_output.stderr)\n .trim()\n .to_string();\n let push_stdout = String::from_utf8_lossy(&push_output.stdout)\n .trim()\n .to_string();\n\n // Branch exists/diverged: retry safely with force-with-lease on the same remote.\n let force_output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"push\", \"--force-with-lease\", &remote, &head_refspec])\n .output()\n .with_context(|| format!(\"failed to run git force push for remote {remote}\"))?;\n if force_output.status.success() {\n return Ok(pr_head_selector_for_remote(repo_root, &remote, head));\n }\n\n let force_stderr = String::from_utf8_lossy(&force_output.stderr)\n .trim()\n .to_string();\n failures.push(format!(\n \"{remote}: push='{}' force='{}'{}\",\n push_stderr,\n force_stderr,\n if push_stdout.is_empty() {\n String::new()\n } else {\n format!(\" stdout='{}'\", push_stdout)\n }\n ));\n }\n\n bail!(\n \"failed to push PR head {} to any remote:\\n{}\",\n head,\n failures.join(\"\\n\")\n );\n}\n\nfn pr_push_remote_candidates(repo_root: &Path) -> Vec<String> {\n let mut remotes: Vec<String> = git_capture_in(repo_root, &[\"remote\"])\n .unwrap_or_default()\n .lines()\n .map(str::trim)\n .filter(|s| !s.is_empty())\n .map(|s| s.to_string())\n .collect();\n\n remotes.sort_by_key(|r| match r.as_str() {\n \"fork\" => 0u8,\n \"origin\" => 1u8,\n \"upstream\" => 3u8,\n _ => 2u8,\n });\n remotes\n}\n\nfn pr_head_selector_for_remote(repo_root: &Path, remote: &str, head: &str) -> String {\n let Some(url) = git_capture_in(repo_root, &[\"remote\", \"get-url\", remote])\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n else {\n return head.to_string();\n };\n\n if let Some((owner, _repo)) = parse_github_remote(&url) {\n return format!(\"{owner}:{head}\");\n }\n\n head.to_string()\n}\n\nfn extract_pr_url(text: &str) -> Option<String> {\n let re = Regex::new(r\"https://github\\\\.com/[^/\\\\s]+/[^/\\\\s]+/pull/\\\\d+\").ok()?;\n re.find(text).map(|m| m.as_str().to_string())\n}\n\nfn pr_number_from_url(url: &str) -> Option<u64> {\n let parts: Vec<&str> = url.trim_end_matches('/').split('/').collect();\n parts.last()?.parse().ok()\n}\n\nfn split_head_selector(head: &str) -> (Option<&str>, &str) {\n let trimmed = head.trim();\n if let Some((owner, branch)) = trimmed.split_once(':') {\n let owner = owner.trim();\n let branch = branch.trim();\n if !owner.is_empty() && !branch.is_empty() {\n return (Some(owner), branch);\n }\n }\n (None, trimmed)\n}\n\nfn gh_find_open_pr_by_head(\n repo_root: &Path,\n repo: &str,\n head: &str,\n) -> Result<Option<(u64, String)>> {\n #[derive(Deserialize)]\n struct HeadOwner {\n login: String,\n }\n\n #[derive(Deserialize)]\n struct PrListItem {\n number: u64,\n url: String,\n #[serde(rename = \"headRefName\")]\n head_ref_name: String,\n #[serde(rename = \"headRepositoryOwner\")]\n head_repository_owner: Option<HeadOwner>,\n }\n\n let (owner_filter, branch) = split_head_selector(head);\n if branch.is_empty() {\n return Ok(None);\n }\n\n // gh --head matches by branch name; owner qualification must be filtered client-side.\n let out = gh_capture_in(\n repo_root,\n &[\n \"pr\",\n \"list\",\n \"--repo\",\n repo,\n \"--head\",\n branch,\n \"--state\",\n \"open\",\n \"--json\",\n \"number,url,headRefName,headRepositoryOwner\",\n ],\n )\n .unwrap_or_default();\n\n let prs: Vec<PrListItem> = serde_json::from_str(out.trim()).unwrap_or_default();\n for pr in prs {\n if pr.head_ref_name != branch {\n continue;\n }\n if let Some(owner) = owner_filter {\n let login = pr\n .head_repository_owner\n .as_ref()\n .map(|o| o.login.as_str())\n .unwrap_or_default();\n if !login.eq_ignore_ascii_case(owner) {\n continue;\n }\n }\n return Ok(Some((pr.number, pr.url)));\n }\n\n Ok(None)\n}\n\nfn gh_create_pr(\n repo_root: &Path,\n repo: &str,\n head: &str,\n base: &str,\n title: &str,\n body: &str,\n draft: bool,\n) -> Result<(u64, String)> {\n let normalized_body = normalize_markdown_linebreaks(body);\n let mut args: Vec<&str> = vec![\n \"pr\",\n \"create\",\n \"--repo\",\n repo,\n \"--head\",\n head,\n \"--base\",\n base,\n \"--title\",\n title,\n \"--body\",\n &normalized_body,\n ];\n if draft {\n args.push(\"--draft\");\n }\n\n let output = Command::new(\"gh\")\n .current_dir(repo_root)\n .args(&args)\n .output()\n .with_context(|| format!(\"failed to run gh {}\", args.join(\" \")))?;\n\n // gh can fail with \"already exists\" and still include the PR URL in stderr.\n let combined = format!(\n \"{}\\n{}\",\n String::from_utf8_lossy(&output.stdout),\n String::from_utf8_lossy(&output.stderr)\n );\n\n if !output.status.success() {\n if let Some(url) = extract_pr_url(&combined) {\n let number = pr_number_from_url(&url)\n .ok_or_else(|| anyhow::anyhow!(\"failed to parse PR number from URL {}\", url))?;\n return Ok((number, url));\n }\n bail!(\n \"gh {} failed: {}\",\n args.join(\" \"),\n String::from_utf8_lossy(&output.stderr).trim()\n );\n }\n\n // gh typically prints the PR URL, but some versions/configs can produce no stdout.\n if let Some(url) = extract_pr_url(&combined) {\n let number = pr_number_from_url(&url)\n .ok_or_else(|| anyhow::anyhow!(\"failed to parse PR number from URL {}\", url))?;\n return Ok((number, url));\n }\n\n if let Some(found) = gh_find_open_pr_by_head(repo_root, repo, head)? {\n return Ok(found);\n }\n\n bail!(\n \"failed to determine PR URL after creation (gh output had no URL and PR lookup by head returned empty)\"\n );\n}\n\nfn open_in_browser(url: &str) -> Result<()> {\n #[cfg(target_os = \"macos\")]\n {\n let status = Command::new(\"open\").arg(url).status()?;\n if !status.success() {\n bail!(\"failed to open browser\");\n }\n return Ok(());\n }\n\n #[cfg(not(target_os = \"macos\"))]\n {\n let status = Command::new(\"xdg-open\").arg(url).status()?;\n if !status.success() {\n bail!(\"failed to open browser\");\n }\n Ok(())\n }\n}\n\nfn commit_message_title_body(message: &str) -> (String, String) {\n let mut lines = message.lines();\n let title = lines.next().unwrap_or(\"no title\").trim().to_string();\n let rest = lines.collect::<Vec<_>>().join(\"\\n\").trim().to_string();\n (title, rest)\n}\n\nfn normalize_markdown_linebreaks(text: &str) -> String {\n let trimmed = text.trim();\n // Guardrail: if body has escaped line breaks but no real newlines, decode it.\n // This prevents malformed PR bodies like \"Summary\\\\n- item\" on GitHub.\n if !trimmed.contains('\\n') && trimmed.contains(\"\\\\n\") {\n return trimmed.replace(\"\\\\r\\\\n\", \"\\n\").replace(\"\\\\n\", \"\\n\");\n }\n trimmed.to_string()\n}\n\npub fn run_commit_queue(cmd: CommitQueueCommand) -> Result<()> {\n ensure_git_repo()?;\n let repo_root = git_root_or_cwd();\n ensure_commit_setup(&repo_root)?;\n\n let action = cmd.action.unwrap_or(CommitQueueAction::List);\n match action {\n CommitQueueAction::List => {\n let entries = load_commit_queue_entries(&repo_root)?;\n if entries.is_empty() {\n println!(\"No queued commits.\");\n return Ok(());\n }\n println!(\"Queued commits:\");\n for mut entry in entries {\n let _ = refresh_queue_entry_commit(&repo_root, &mut entry);\n let subject = entry.message.lines().next().unwrap_or(\"no message\").trim();\n let created_at = format_queue_created_at(&entry.created_at);\n let bookmark = entry\n .review_bookmark\n .as_ref()\n .map(|b| format!(\" {}\", b))\n .unwrap_or_default();\n println!(\n \" {} {} {} {}{}\",\n short_sha(&entry.commit_sha),\n entry.branch,\n created_at,\n subject,\n bookmark\n );\n }\n }\n CommitQueueAction::Show { hash } => {\n let mut entry = resolve_commit_queue_entry(&repo_root, &hash)?;\n let _ = refresh_queue_entry_commit(&repo_root, &mut entry);\n println!(\"Commit: {}\", entry.commit_sha);\n println!(\"Branch: {}\", entry.branch);\n println!(\"Queued: {}\", entry.created_at);\n if let Some(bookmark) = entry.review_bookmark.as_ref() {\n println!(\"Review bookmark: {}\", bookmark);\n }\n println!();\n println!(\"Message:\");\n println!(\"────────────────────────────────────────\");\n println!(\"{}\", entry.message.trim_end());\n println!(\"────────────────────────────────────────\");\n let issues_present = entry.review_issues_found\n || entry\n .review\n .as_deref()\n .map(|s| !s.trim().is_empty())\n .unwrap_or(false);\n if entry.review_timed_out {\n println!();\n println!(\"Review: timed out or failed\");\n }\n if issues_present {\n if let Some(body) = entry\n .review\n .as_deref()\n .map(|s| s.trim())\n .filter(|s| !s.is_empty())\n {\n println!();\n println!(\"Review issues:\");\n println!(\"{}\", body);\n }\n }\n if !entry.review_todo_ids.is_empty() {\n println!();\n println!(\"Todos: {}\", entry.review_todo_ids.join(\", \"));\n }\n if let Ok(stat) = git_capture_in(\n &repo_root,\n &[\"show\", \"--stat\", \"--format=\", &entry.commit_sha],\n ) {\n if !stat.trim().is_empty() {\n println!();\n println!(\"{}\", stat.trim_end());\n }\n }\n println!();\n println!(\"Open diff UI:\");\n println!(\" f commit-queue open {}\", short_sha(&entry.commit_sha));\n println!(\"Print diff:\");\n println!(\" f commit-queue diff {}\", short_sha(&entry.commit_sha));\n }\n CommitQueueAction::Open { hash } => {\n let mut entry = resolve_commit_queue_entry(&repo_root, &hash)?;\n let _ = refresh_queue_entry_commit(&repo_root, &mut entry);\n // Ensure the review session exists (Rise UI expects a review session file).\n let _ = write_rise_review_session(&repo_root, &entry);\n println!(\n \"Opening queued commit {} in Rise app...\",\n short_sha(&entry.commit_sha)\n );\n open_review_in_rise(&repo_root, &entry.commit_sha);\n }\n CommitQueueAction::Diff { hash } => {\n let mut entry = resolve_commit_queue_entry(&repo_root, &hash)?;\n let _ = refresh_queue_entry_commit(&repo_root, &mut entry);\n // Print a full patch (user can pipe to less -R).\n let patch = git_capture_in(\n &repo_root,\n &[\n \"show\",\n \"--color=always\",\n \"--patch\",\n \"--format=fuller\",\n &entry.commit_sha,\n ],\n )?;\n // Avoid panicking on SIGPIPE (e.g. `... | head`).\n if let Err(err) = io::stdout().write_all(patch.trim_end().as_bytes()) {\n if err.kind() != io::ErrorKind::BrokenPipe {\n return Err(err).context(\"failed to write diff to stdout\");\n }\n return Ok(());\n }\n if let Err(err) = io::stdout().write_all(b\"\\n\") {\n if err.kind() != io::ErrorKind::BrokenPipe {\n return Err(err).context(\"failed to write diff newline to stdout\");\n }\n }\n }\n CommitQueueAction::Review { hashes, all } => {\n let mut entries = load_commit_queue_entries(&repo_root)?;\n if entries.is_empty() {\n println!(\"No queued commits.\");\n return Ok(());\n }\n for entry in &mut entries {\n let _ = refresh_queue_entry_commit(&repo_root, entry);\n }\n\n let mut targets: Vec<CommitQueueEntry> = Vec::new();\n if !hashes.is_empty() {\n for hash in hashes {\n let matches: Vec<CommitQueueEntry> = entries\n .iter()\n .filter(|entry| commit_queue_entry_matches(entry, &hash))\n .cloned()\n .collect();\n match matches.len() {\n 0 => bail!(\"No queued commit matches {}\", hash),\n 1 => targets.push(matches[0].clone()),\n _ => bail!(\"Multiple queued commits match {}. Use a longer hash.\", hash),\n }\n }\n } else if all {\n targets = entries;\n } else {\n let current_branch =\n git_capture_in(&repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string());\n targets = entries\n .into_iter()\n .filter(|entry| entry.branch.trim() == current_branch.trim())\n .collect();\n }\n\n if targets.is_empty() {\n println!(\"No queued commits selected for review.\");\n return Ok(());\n }\n\n let review_instructions = get_review_instructions(&repo_root);\n let mut clean = 0usize;\n let mut with_issues = 0usize;\n let mut timed_out = 0usize;\n let mut failed = 0usize;\n\n for mut entry in targets {\n println!(\n \"==> Reviewing queued commit {} ({}) with Codex...\",\n short_sha(&entry.commit_sha),\n entry.branch\n );\n match review_queue_entry_with_codex(\n &repo_root,\n &mut entry,\n review_instructions.as_deref(),\n ) {\n Ok(()) => {\n if entry.review_timed_out {\n timed_out += 1;\n println!(\n \" ⚠ Review timed out again for {}\",\n short_sha(&entry.commit_sha)\n );\n } else if entry.review_issues_found {\n with_issues += 1;\n println!(\n \" ⚠ Review found issue(s) for {}\",\n short_sha(&entry.commit_sha)\n );\n } else {\n clean += 1;\n println!(\" ✓ Review clean for {}\", short_sha(&entry.commit_sha));\n }\n if !entry.review_todo_ids.is_empty() {\n match todo::count_open_todos(&repo_root, &entry.review_todo_ids) {\n Ok(open) => {\n if open > 0 {\n println!(\n \" ↳ {} open review todo(s): {}\",\n open,\n entry.review_todo_ids.join(\", \")\n );\n } else {\n println!(\" ↳ review todos accounted for\");\n }\n }\n Err(err) => println!(\" ↳ todo status check failed: {}\", err),\n }\n }\n }\n Err(err) => {\n failed += 1;\n println!(\n \" ✗ Failed to review {}: {}\",\n short_sha(&entry.commit_sha),\n err\n );\n }\n }\n }\n\n println!(\n \"Review refresh summary: clean={}, issues={}, timed_out={}, failed={}\",\n clean, with_issues, timed_out, failed\n );\n\n if failed > 0 {\n bail!(\"Some queued commit reviews failed. Resolve errors and re-run.\");\n }\n }\n CommitQueueAction::Approve {\n all,\n hash,\n queue_if_missing,\n mark_reviewed,\n force,\n allow_issues,\n allow_unreviewed,\n } => {\n if all {\n if hash.is_some() {\n bail!(\n \"--all cannot be combined with HASH. Use `f commit-queue approve --all`.\"\n );\n }\n if queue_if_missing {\n eprintln!(\"note: --queue-if-missing is ignored when using --all\");\n }\n if mark_reviewed {\n eprintln!(\"note: --mark-reviewed is ignored when using --all\");\n }\n return approve_all_queued_commits(\n &repo_root,\n force,\n allow_issues,\n allow_unreviewed,\n );\n }\n\n git_guard::ensure_clean_for_push(&repo_root)?;\n let auto_mode = hash.is_none();\n let target_hash = match hash {\n Some(value) => value,\n None => git_capture_in(&repo_root, &[\"rev-parse\", \"--verify\", \"HEAD\"])?\n .trim()\n .to_string(),\n };\n let effective_queue_if_missing = queue_if_missing || auto_mode;\n let effective_mark_reviewed = mark_reviewed || auto_mode;\n let effective_allow_unreviewed = allow_unreviewed || auto_mode;\n\n let mut entry = match resolve_commit_queue_entry(&repo_root, &target_hash) {\n Ok(entry) => entry,\n Err(err) => {\n let no_match = err\n .to_string()\n .starts_with(&format!(\"No queued commit matches {}\", target_hash));\n if effective_queue_if_missing && no_match {\n let entry = queue_existing_commit_for_approval(\n &repo_root,\n &target_hash,\n effective_mark_reviewed,\n )?;\n println!(\n \"Queued {} from git history for approval{}.\",\n short_sha(&entry.commit_sha),\n if effective_mark_reviewed {\n \" (marked manually reviewed)\"\n } else {\n \"\"\n }\n );\n entry\n } else {\n return Err(err);\n }\n }\n };\n let _ = refresh_queue_entry_commit(&repo_root, &mut entry);\n\n let issues_present = entry.review_issues_found\n || entry\n .review\n .as_deref()\n .map(|s| !s.trim().is_empty())\n .unwrap_or(false);\n let unreviewed = entry.version >= 2 && !entry.review_completed;\n\n if issues_present && !allow_issues && !force {\n bail!(\n \"Queued commit {} has review issues. Fix them, or re-run with --allow-issues.\",\n short_sha(&entry.commit_sha)\n );\n }\n if unreviewed && !effective_allow_unreviewed && !force {\n bail!(\n \"Queued commit {} does not have a clean review (missing). Re-run review, or re-run with --allow-unreviewed.\",\n short_sha(&entry.commit_sha)\n );\n }\n if entry.review_timed_out && !force {\n eprintln!(\n \"note: review timed out for {}; approving anyway (re-run `f commit-queue review {}` if you want a full review)\",\n short_sha(&entry.commit_sha),\n short_sha(&entry.commit_sha)\n );\n }\n\n let head_sha = git_capture_in(&repo_root, &[\"rev-parse\", \"HEAD\"])?;\n let head_sha = head_sha.trim();\n if head_sha != entry.commit_sha && !force {\n bail!(\n \"Queued commit {} is not at HEAD (current HEAD is {}). Checkout the commit or re-run with --force.\",\n short_sha(&entry.commit_sha),\n short_sha(head_sha)\n );\n }\n\n let current_branch = git_capture_in(&repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string());\n if current_branch.trim() != entry.branch && !force {\n bail!(\n \"Queued commit was created on branch {} but current branch is {}. Checkout the branch or re-run with --force.\",\n entry.branch,\n current_branch.trim()\n );\n }\n\n ensure_safe_upstream_for_commit_queue_push(&repo_root, head_sha, force)?;\n\n if git_try_in(&repo_root, &[\"fetch\", \"--quiet\"]).is_ok() {\n if let Ok(counts) = git_capture_in(\n &repo_root,\n &[\"rev-list\", \"--left-right\", \"--count\", \"@{u}...HEAD\"],\n ) {\n let parts: Vec<&str> = counts.split_whitespace().collect();\n if parts.len() == 2 {\n let behind = parts[0].parse::<u64>().unwrap_or(0);\n if behind > 0 && !force {\n bail!(\n \"Remote is ahead by {} commit(s). Run `f sync` or rebase, then re-approve.\",\n behind\n );\n }\n }\n }\n }\n\n let before_sha = git_capture_in(&repo_root, &[\"rev-parse\", \"@{u}\"]).ok();\n let push_remote = config::preferred_git_remote_for_repo(&repo_root);\n let push_branch = current_branch.trim().to_string();\n\n print!(\"Pushing... \");\n io::stdout().flush()?;\n let mut pushed = false;\n match git_push_try_in(&repo_root, &push_remote, &push_branch) {\n PushResult::Success => {\n println!(\"done\");\n pushed = true;\n }\n PushResult::NoRemoteRepo => {\n println!(\"skipped (no remote repo)\");\n }\n PushResult::RemoteAhead => {\n println!(\"failed (remote ahead)\");\n print!(\"Pulling with rebase... \");\n io::stdout().flush()?;\n match git_pull_rebase_try_in(&repo_root, &push_remote, &push_branch) {\n Ok(_) => {\n println!(\"done\");\n print!(\"Pushing... \");\n io::stdout().flush()?;\n git_push_run_in(&repo_root, &push_remote, &push_branch)?;\n println!(\"done\");\n pushed = true;\n }\n Err(_) => {\n println!(\"conflict!\");\n println!();\n println!(\"Rebase conflict detected. Resolve manually:\");\n println!(\" 1. Fix conflicts in the listed files\");\n println!(\" 2. git add <files>\");\n println!(\" 3. git rebase --continue\");\n println!(\" 4. git push\");\n println!();\n println!(\"Or abort with: git rebase --abort\");\n bail!(\"Rebase conflict - manual resolution required\");\n }\n }\n }\n }\n\n if pushed {\n if let (Some(before_sha), Ok(after_sha)) = (\n before_sha,\n git_capture_in(&repo_root, &[\"rev-parse\", \"HEAD\"]),\n ) {\n let branch = current_branch.trim();\n let before_sha = before_sha.trim();\n let after_sha = after_sha.trim();\n let _ = undo::record_action(\n &repo_root,\n undo::ActionType::Push,\n before_sha,\n after_sha,\n branch,\n true,\n Some(push_remote.as_str()),\n Some(&entry.message),\n );\n }\n if let Some(bookmark) = entry.review_bookmark.as_ref() {\n delete_review_bookmark(&repo_root, bookmark);\n }\n remove_commit_queue_entry_by_entry(&repo_root, &entry)?;\n if let Ok(done) =\n todo::complete_review_timeout_todos(&repo_root, &entry.review_todo_ids)\n {\n if done > 0 {\n println!(\"Auto-completed {} review follow-up todo(s).\", done);\n }\n }\n println!(\"✓ Approved and pushed {}\", short_sha(&entry.commit_sha));\n }\n }\n CommitQueueAction::ApproveAll {\n force,\n allow_issues,\n allow_unreviewed,\n } => approve_all_queued_commits(&repo_root, force, allow_issues, allow_unreviewed)?,\n CommitQueueAction::Drop { hash } => {\n let mut entry = resolve_commit_queue_entry(&repo_root, &hash)?;\n let _ = refresh_queue_entry_commit(&repo_root, &mut entry);\n if let Some(bookmark) = entry.review_bookmark.as_ref() {\n delete_review_bookmark(&repo_root, bookmark);\n }\n remove_commit_queue_entry_by_entry(&repo_root, &entry)?;\n println!(\"Dropped queued commit {}\", short_sha(&entry.commit_sha));\n }\n CommitQueueAction::PrCreate {\n hash,\n base,\n draft,\n open,\n } => {\n ensure_gh_available()?;\n let repo = resolve_github_repo(&repo_root)?;\n\n let mut entry = resolve_commit_queue_entry(&repo_root, &hash)?;\n let _ = refresh_queue_entry_commit(&repo_root, &mut entry);\n\n let head = default_pr_head(&entry);\n let gh_head = ensure_pr_head_pushed(&repo_root, &head, &entry.commit_sha)?;\n\n let (number, url) =\n if let Some(found) = gh_find_open_pr_by_head(&repo_root, &repo, &gh_head)? {\n found\n } else {\n let (title, body_rest) = commit_message_title_body(&entry.message);\n let mut body = String::new();\n if !body_rest.is_empty() {\n body.push_str(&body_rest);\n body.push_str(\"\\n\\n\");\n }\n if let Some(summary) = entry\n .summary\n .as_deref()\n .map(|s| s.trim())\n .filter(|s| !s.is_empty())\n {\n body.push_str(\"Review summary:\\n\");\n body.push_str(summary);\n body.push('\\n');\n }\n gh_create_pr(\n &repo_root,\n &repo,\n &gh_head,\n &base,\n &title,\n body.trim(),\n draft,\n )?\n };\n\n entry.pr_number = Some(number);\n entry.pr_url = Some(url.clone());\n entry.pr_head = Some(head.clone());\n entry.pr_base = Some(base.clone());\n let _ = write_commit_queue_entry(&repo_root, &entry);\n\n println!(\"PR: {}\", url);\n if open {\n let _ = open_in_browser(&url);\n }\n }\n CommitQueueAction::PrOpen { hash, base } => {\n ensure_gh_available()?;\n let repo = resolve_github_repo(&repo_root)?;\n\n let mut entry = resolve_commit_queue_entry(&repo_root, &hash)?;\n let _ = refresh_queue_entry_commit(&repo_root, &mut entry);\n\n let head = default_pr_head(&entry);\n let url = if let Some(url) = entry\n .pr_url\n .as_deref()\n .map(|s| s.trim())\n .filter(|s| !s.is_empty())\n {\n url.to_string()\n } else if let Some((_n, url)) = gh_find_open_pr_by_head(&repo_root, &repo, &head)? {\n url\n } else {\n // Create it if missing (as draft).\n let gh_head = ensure_pr_head_pushed(&repo_root, &head, &entry.commit_sha)?;\n let (title, body_rest) = commit_message_title_body(&entry.message);\n let (number, url) =\n if let Some(found) = gh_find_open_pr_by_head(&repo_root, &repo, &gh_head)? {\n found\n } else {\n gh_create_pr(\n &repo_root,\n &repo,\n &gh_head,\n &base,\n &title,\n body_rest.trim(),\n true,\n )?\n };\n entry.pr_number = Some(number);\n entry.pr_url = Some(url.clone());\n entry.pr_head = Some(head.clone());\n entry.pr_base = Some(base.clone());\n let _ = write_commit_queue_entry(&repo_root, &entry);\n url\n };\n\n println!(\"{}\", url);\n let _ = open_in_browser(&url);\n }\n }\n\n Ok(())\n}\n\npub fn run_pr(opts: PrOpts) -> Result<()> {\n let args = normalize_pr_args(&opts.args);\n if let Some(feedback) = parse_pr_feedback_args(&args)? {\n let repo_root = if feedback.selector.is_some() {\n std::env::current_dir().context(\"failed to resolve current directory\")?\n } else {\n ensure_git_repo()?;\n let repo_root = git_root_or_cwd();\n ensure_commit_setup(&repo_root)?;\n repo_root\n };\n return run_pr_feedback(&repo_root, feedback);\n }\n\n ensure_git_repo()?;\n let repo_root = git_root_or_cwd();\n ensure_commit_setup(&repo_root)?;\n\n match args.as_slice() {\n // Convenience: `f pr open` opens the PR for the current branch (or queued commit) without\n // creating a new commit.\n [a] if a == \"open\" => return run_pr_open(&repo_root, &opts),\n // Convenience: `f pr open edit` opens a local markdown file in Zed Preview and syncs PR\n // title/body on save.\n [a, b] if a == \"open\" && b == \"edit\" => return run_pr_open_edit(&repo_root, &opts),\n _ => {}\n }\n\n if !opts.paths.is_empty() && (opts.no_commit || opts.hash.is_some()) {\n bail!(\"--path cannot be used with --no-commit or --hash\");\n }\n\n let should_commit = !opts.no_commit && opts.hash.is_none();\n if should_commit {\n let queue = resolve_commit_queue_mode(true, false);\n let review_selection = resolve_review_selection_v2(false, None);\n let message = if args.is_empty() {\n None\n } else {\n Some(args.join(\" \"))\n };\n run_with_check_sync(\n true,\n false,\n review_selection,\n message.as_deref(),\n 1000,\n false,\n queue,\n false,\n &opts.paths,\n CommitGateOverrides::default(),\n )?;\n }\n\n let hash = if let Some(hash) = opts.hash {\n hash\n } else {\n let _ = refresh_commit_queue(&repo_root);\n let mut entries = load_commit_queue_entries(&repo_root)?;\n let Some(entry) = entries.pop() else {\n bail!(\n \"Commit queue is empty. Run `f pr \\\"message\\\"` or queue a commit first with `f commit --queue`.\"\n );\n };\n entry.commit_sha\n };\n\n run_commit_queue(CommitQueueCommand {\n action: Some(CommitQueueAction::PrCreate {\n hash,\n base: opts.base,\n draft: opts.draft,\n open: !opts.no_open,\n }),\n })\n}\n\nfn run_pr_open(repo_root: &Path, opts: &PrOpts) -> Result<()> {\n ensure_gh_available()?;\n let repo = resolve_github_repo(repo_root)?;\n\n // Prefer opening based on the current git branch name (most intuitive UX).\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string())\n .trim()\n .to_string();\n if !branch.is_empty() && branch != \"HEAD\" {\n if let Some((_n, url)) = gh_find_open_pr_by_head(repo_root, &repo, &branch)? {\n println!(\"PR: {}\", url);\n if !opts.no_open {\n let _ = open_in_browser(&url);\n }\n return Ok(());\n }\n }\n\n // Fallback: open based on queued commit (by explicit hash, by HEAD SHA, or latest entry).\n let hash = if let Some(hash) = opts.hash.clone() {\n hash\n } else {\n let head_sha = git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"])\n .unwrap_or_default()\n .trim()\n .to_string();\n let _ = refresh_commit_queue(repo_root);\n let mut entries = load_commit_queue_entries(repo_root)?;\n if entries.is_empty() {\n bail!(\"No PR found for current branch and commit queue is empty.\");\n }\n if !head_sha.is_empty() {\n if let Some(entry) = entries.iter().rev().find(|e| e.commit_sha == head_sha) {\n entry.commit_sha.clone()\n } else {\n entries.pop().unwrap().commit_sha\n }\n } else {\n entries.pop().unwrap().commit_sha\n }\n };\n\n // Reuse the commit queue PR-open behavior (creates draft if missing).\n run_commit_queue(CommitQueueCommand {\n action: Some(CommitQueueAction::PrOpen {\n hash,\n base: opts.base.clone(),\n }),\n })\n}\n\nfn normalize_pr_args(args: &[String]) -> Vec<String> {\n let mut normalized = Vec::new();\n for a in args {\n let t = a.trim();\n if !t.is_empty() {\n normalized.push(t.to_string());\n }\n }\n normalized\n}\n\n#[derive(Debug, Clone)]\nstruct PrFeedbackCommand {\n selector: Option<String>,\n record_todos: bool,\n show_full: bool,\n open_cursor: bool,\n}\n\n#[derive(Debug, Clone, Serialize)]\nstruct PrFeedbackItem {\n external_ref: String,\n source: &'static str,\n author: String,\n body: String,\n url: String,\n thread_id: Option<String>,\n path: Option<String>,\n line: Option<u64>,\n review_state: Option<String>,\n diff_hunk: Option<String>,\n}\n\n#[derive(Debug, Serialize)]\nstruct PrFeedbackSnapshot {\n repo: String,\n pr_number: u64,\n pr_url: String,\n pr_title: String,\n trace_id: String,\n generated_at: String,\n reviews_count: usize,\n review_comments_count: usize,\n issue_comments_count: usize,\n review_state_counts: HashMap<String, usize>,\n items: Vec<PrFeedbackItem>,\n}\n\nfn new_pr_feedback_trace_id() -> String {\n Uuid::new_v4().simple().to_string()\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhApiUser {\n login: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhPrFeedbackSummary {\n number: u64,\n url: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhPrTitleSummary {\n title: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhPrReviewComment {\n id: u64,\n #[serde(default)]\n body: String,\n #[serde(default)]\n html_url: String,\n #[serde(default)]\n path: Option<String>,\n #[serde(default)]\n line: Option<u64>,\n #[serde(default)]\n diff_hunk: Option<String>,\n #[serde(default)]\n in_reply_to_id: Option<u64>,\n user: GhApiUser,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhIssueComment {\n id: u64,\n #[serde(default)]\n body: String,\n #[serde(default)]\n html_url: String,\n user: GhApiUser,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhReview {\n id: u64,\n #[serde(default)]\n body: String,\n #[serde(default)]\n state: String,\n #[serde(default)]\n html_url: String,\n user: GhApiUser,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhGraphqlReviewThreadsResponse {\n data: GhGraphqlReviewThreadsData,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhGraphqlReviewThreadsData {\n repository: GhGraphqlReviewThreadsRepository,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhGraphqlReviewThreadsRepository {\n #[serde(rename = \"pullRequest\")]\n pull_request: GhGraphqlReviewThreadsPullRequest,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhGraphqlReviewThreadsPullRequest {\n #[serde(rename = \"reviewThreads\")]\n review_threads: GhGraphqlReviewThreadsConnection,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhGraphqlReviewThreadsConnection {\n nodes: Vec<GhGraphqlReviewThreadNode>,\n #[serde(rename = \"pageInfo\")]\n page_info: GhGraphqlPageInfo,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhGraphqlReviewThreadNode {\n id: String,\n comments: GhGraphqlReviewThreadComments,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhGraphqlReviewThreadComments {\n nodes: Vec<GhGraphqlReviewThreadCommentNode>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhGraphqlReviewThreadCommentNode {\n url: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GhGraphqlPageInfo {\n #[serde(rename = \"hasNextPage\")]\n has_next_page: bool,\n #[serde(rename = \"endCursor\")]\n end_cursor: Option<String>,\n}\n\n#[derive(Debug)]\nstruct LoadedPrFeedback {\n repo: String,\n pr_number: u64,\n pr_url: String,\n pr_title: String,\n reviews: Vec<GhReview>,\n review_comments: Vec<GhPrReviewComment>,\n issue_comments: Vec<GhIssueComment>,\n items: Vec<PrFeedbackItem>,\n}\n\n#[derive(Debug)]\nstruct PrFeedbackArtifacts {\n snapshot_path: PathBuf,\n snapshot_json_path: PathBuf,\n review_plan_path: PathBuf,\n review_rules_path: PathBuf,\n kit_system_path: PathBuf,\n}\n\nfn parse_pr_feedback_args(args: &[String]) -> Result<Option<PrFeedbackCommand>> {\n if args.first().map(|s| s.as_str()) != Some(\"feedback\") {\n return Ok(None);\n }\n\n let mut selector: Option<String> = None;\n let mut record_todos = false;\n let mut show_full = true;\n let mut open_cursor = false;\n for token in args.iter().skip(1) {\n match token.as_str() {\n \"--todo\" | \"todo\" => record_todos = true,\n \"--full\" | \"full\" => show_full = true,\n \"--compact\" | \"compact\" => show_full = false,\n \"--cursor\" | \"cursor\" => open_cursor = true,\n \"--help\" | \"-h\" => {\n return Ok(Some(PrFeedbackCommand {\n selector: Some(\"--help\".to_string()),\n record_todos: false,\n show_full: true,\n open_cursor: false,\n }));\n }\n _ if token.starts_with(\"--\") => {\n bail!(\"unknown `f pr feedback` option: {token}\");\n }\n _ => {\n if selector.is_some() {\n bail!(\"multiple PR selectors provided. Use exactly one selector.\");\n }\n selector = Some(token.clone());\n }\n }\n }\n\n Ok(Some(PrFeedbackCommand {\n selector,\n record_todos,\n show_full,\n open_cursor,\n }))\n}\n\nfn parse_github_pr_url(input: &str) -> Option<(String, u64)> {\n let trimmed = input.trim().trim_end_matches('/');\n let prefix = \"https://github.com/\";\n let rest = trimmed.strip_prefix(prefix)?;\n let mut parts = rest.split('/');\n let owner = parts.next()?.trim();\n let repo = parts.next()?.trim();\n let kind = parts.next()?.trim();\n let number = parts.next()?.trim();\n if owner.is_empty() || repo.is_empty() || kind != \"pull\" {\n return None;\n }\n let number = number.parse::<u64>().ok()?;\n Some((format!(\"{owner}/{repo}\"), number))\n}\n\nfn resolve_current_pr_for_feedback(repo_root: &Path, repo: &str) -> Result<(u64, String)> {\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string())\n .trim()\n .to_string();\n if !branch.is_empty() && branch != \"HEAD\" {\n if let Some((number, url)) = gh_find_open_pr_by_head(repo_root, repo, &branch)? {\n return Ok((number, url));\n }\n }\n\n let out = gh_capture_in(\n repo_root,\n &[\"pr\", \"view\", \"--repo\", repo, \"--json\", \"number,url\"],\n )?;\n let parsed: GhPrFeedbackSummary = serde_json::from_str(out.trim())\n .context(\"failed to parse gh pr view output while resolving current PR\")?;\n Ok((parsed.number, parsed.url))\n}\n\nfn gh_api_json_in<T: DeserializeOwned>(repo_root: &Path, endpoint: &str) -> Result<T> {\n let out = gh_capture_in(repo_root, &[\"api\", endpoint])?;\n serde_json::from_str(out.trim())\n .with_context(|| format!(\"failed to parse GitHub API response for `{endpoint}`\"))\n}\n\nfn gh_review_thread_ids_by_comment_url(\n repo_root: &Path,\n repo: &str,\n pr_number: u64,\n) -> Result<HashMap<String, String>> {\n let (owner, repo_name) = repo\n .split_once('/')\n .with_context(|| format!(\"invalid GitHub repo `{repo}`\"))?;\n let query = r#\"query FlowPrReviewThreads($owner: String!, $repo: String!, $prNumber: Int!, $cursor: String) {\n repository(owner: $owner, name: $repo) {\n pullRequest(number: $prNumber) {\n reviewThreads(first: 100, after: $cursor) {\n nodes {\n id\n comments(first: 100) {\n nodes {\n url\n }\n }\n }\n pageInfo {\n hasNextPage\n endCursor\n }\n }\n }\n }\n}\"#;\n\n let mut by_url = HashMap::new();\n let mut cursor: Option<String> = None;\n\n loop {\n let mut args = vec![\n \"api\".to_string(),\n \"graphql\".to_string(),\n \"-f\".to_string(),\n format!(\"query={query}\"),\n \"-F\".to_string(),\n format!(\"owner={owner}\"),\n \"-F\".to_string(),\n format!(\"repo={repo_name}\"),\n \"-F\".to_string(),\n format!(\"prNumber={pr_number}\"),\n ];\n if let Some(value) = cursor.as_ref() {\n args.push(\"-F\".to_string());\n args.push(format!(\"cursor={value}\"));\n }\n let arg_refs: Vec<&str> = args.iter().map(String::as_str).collect();\n let out = gh_capture_in(repo_root, &arg_refs)?;\n let parsed: GhGraphqlReviewThreadsResponse = serde_json::from_str(out.trim())\n .context(\"failed to parse GitHub GraphQL review thread response\")?;\n\n for thread in parsed\n .data\n .repository\n .pull_request\n .review_threads\n .nodes\n {\n for comment in thread.comments.nodes {\n let url = comment.url.trim();\n if !url.is_empty() {\n by_url.insert(url.to_string(), thread.id.clone());\n }\n }\n }\n\n let page_info = parsed.data.repository.pull_request.review_threads.page_info;\n if !page_info.has_next_page {\n break;\n }\n cursor = page_info.end_cursor;\n if cursor.is_none() {\n break;\n }\n }\n\n Ok(by_url)\n}\n\nfn pr_feedback_external_ref(repo: &str, pr_number: u64, source: &str, source_id: u64) -> String {\n let mut hasher = Sha1::new();\n hasher.update(repo.as_bytes());\n hasher.update(b\":\");\n hasher.update(pr_number.to_string().as_bytes());\n hasher.update(b\":\");\n hasher.update(source.as_bytes());\n hasher.update(b\":\");\n hasher.update(source_id.to_string().as_bytes());\n let hex = hex::encode(hasher.finalize());\n let short = hex.get(..12).unwrap_or(&hex);\n format!(\"flow-pr-feedback-{short}\")\n}\n\nfn compact_single_line(text: &str, max_chars: usize) -> String {\n let first = text\n .lines()\n .map(str::trim)\n .find(|line| !line.is_empty())\n .unwrap_or(\"\")\n .replace('\\t', \" \");\n if first.chars().count() <= max_chars {\n return first;\n }\n let mut out = String::new();\n for (idx, ch) in first.chars().enumerate() {\n if idx >= max_chars.saturating_sub(3) {\n out.push_str(\"...\");\n break;\n }\n out.push(ch);\n }\n out\n}\n\nfn pr_feedback_todo_title(pr_number: u64, item: &PrFeedbackItem) -> String {\n let snippet = compact_single_line(&item.body, 90);\n let mut title = format!(\"PR #{pr_number} {}: {}\", item.source, snippet);\n if title.trim().is_empty() {\n title = format!(\"PR #{pr_number} {} feedback\", item.source);\n }\n title\n}\n\nfn feedback_location_label(item: &PrFeedbackItem) -> Option<String> {\n match (item.path.as_deref(), item.line) {\n (Some(path), Some(line)) => Some(format!(\"{path}:{line}\")),\n (Some(path), None) => Some(path.to_string()),\n _ => None,\n }\n}\n\nfn feedback_review_state_label(item: &PrFeedbackItem) -> Option<String> {\n item.review_state\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n .map(|value| value.to_ascii_uppercase())\n}\n\nfn compact_diff_hunk(diff_hunk: &str, max_lines: usize, max_chars: usize) -> String {\n let mut out = Vec::new();\n let mut char_count = 0usize;\n for line in diff_hunk.lines().take(max_lines) {\n let trimmed = line.trim_end();\n if trimmed.is_empty() {\n continue;\n }\n let next_len = trimmed.chars().count();\n if char_count + next_len > max_chars {\n break;\n }\n out.push(trimmed.to_string());\n char_count += next_len;\n }\n let mut rendered = out.join(\"\\n\");\n if diff_hunk.lines().count() > max_lines || diff_hunk.chars().count() > max_chars {\n if !rendered.is_empty() {\n rendered.push('\\n');\n }\n rendered.push_str(\"...\");\n }\n rendered\n}\n\nfn compact_pr_feedback_context_block(value: &str, max_lines: usize, max_chars: usize) -> String {\n let mut rendered = String::new();\n let mut char_count = 0usize;\n for line in value.lines().take(max_lines) {\n let trimmed = line.trim_end();\n let next_len = trimmed.chars().count();\n if char_count + next_len > max_chars {\n break;\n }\n if !rendered.is_empty() {\n rendered.push('\\n');\n }\n rendered.push_str(trimmed);\n char_count += next_len;\n }\n if value.lines().count() > max_lines || value.chars().count() > max_chars {\n if !rendered.is_empty() {\n rendered.push('\\n');\n }\n rendered.push_str(\"...\");\n }\n rendered\n}\n\nfn command_on_path(command: &str) -> bool {\n let Some(path_os) = env::var_os(\"PATH\") else {\n return false;\n };\n env::split_paths(&path_os).any(|dir| dir.join(command).is_file())\n}\n\nfn cursor_review_open_command(selector: &str, compact: bool, open_cursor: bool) -> String {\n let mut parts = vec![\n \"f\".to_string(),\n \"pr\".to_string(),\n \"feedback\".to_string(),\n selector.to_string(),\n ];\n if compact {\n parts.push(\"--compact\".to_string());\n }\n if open_cursor {\n parts.push(\"--cursor\".to_string());\n }\n parts.join(\" \")\n}\n\nfn open_cursor_review_bundle(\n workspace_root: &Path,\n review_plan_path: &Path,\n review_rules_path: &Path,\n kit_system_path: &Path,\n background: bool,\n) -> Result<()> {\n let mut command = if cfg!(target_os = \"macos\") || !command_on_path(\"cursor\") {\n let mut command = Command::new(\"open\");\n if background {\n command.arg(\"-g\");\n }\n command.arg(\"-a\").arg(\"Cursor\");\n command\n } else {\n Command::new(\"cursor\")\n };\n command\n .arg(workspace_root)\n .arg(review_plan_path)\n .arg(review_rules_path)\n .arg(kit_system_path)\n .stdout(Stdio::null())\n .stderr(Stdio::null());\n let _status = command.status()?;\n Ok(())\n}\n\nfn pr_feedback_snapshot_json_path(repo_root: &Path, pr_number: u64) -> Result<PathBuf> {\n let dir = repo_root.join(\".ai\").join(\"reviews\");\n fs::create_dir_all(&dir)?;\n Ok(dir.join(format!(\"pr-feedback-{pr_number}.json\")))\n}\n\nfn pr_feedback_plan_root() -> PathBuf {\n if let Some(root) = env::var_os(\"FLOW_PR_FEEDBACK_PLAN_ROOT\").map(PathBuf::from) {\n return root;\n }\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"plan\")\n .join(\"review\")\n}\n\nfn pr_feedback_repo_slug(repo: &str) -> String {\n let mut out = String::new();\n let mut last_dash = false;\n for ch in repo.chars() {\n let mapped = if ch.is_ascii_alphanumeric() {\n last_dash = false;\n ch.to_ascii_lowercase()\n } else {\n if last_dash {\n continue;\n }\n last_dash = true;\n '-'\n };\n out.push(mapped);\n }\n out.trim_matches('-').to_string()\n}\n\nfn pr_feedback_review_plan_path_at(root: &Path, repo: &str, pr_number: u64) -> PathBuf {\n root.join(format!(\n \"{}-pr-{}-feedback.md\",\n pr_feedback_repo_slug(repo),\n pr_number\n ))\n}\n\nfn pr_feedback_kit_system_path_at(root: &Path, repo: &str, pr_number: u64) -> PathBuf {\n root.join(format!(\n \"{}-pr-{}-kit-system.md\",\n pr_feedback_repo_slug(repo),\n pr_number\n ))\n}\n\nfn pr_feedback_review_rules_path_at(root: &Path, repo: &str, pr_number: u64) -> PathBuf {\n root.join(format!(\n \"{}-pr-{}-review-rules.md\",\n pr_feedback_repo_slug(repo),\n pr_number\n ))\n}\n\nfn canonical_review_rules_doc_path() -> PathBuf {\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"docs\")\n .join(\"kit\")\n .join(\"review-rules.md\")\n}\n\nfn format_review_state_counts(reviews: &[GhReview]) -> String {\n let mut entries: Vec<(String, usize)> = review_state_counts_map(reviews).into_iter().collect();\n if entries.is_empty() {\n return \"none\".to_string();\n }\n entries.sort_by(|a, b| a.0.cmp(&b.0));\n entries\n .into_iter()\n .map(|(state, count)| format!(\"{state}:{count}\"))\n .collect::<Vec<_>>()\n .join(\", \")\n}\n\nfn review_state_counts_map(reviews: &[GhReview]) -> HashMap<String, usize> {\n let mut counts: HashMap<String, usize> = HashMap::new();\n for review in reviews {\n let key = if review.state.trim().is_empty() {\n \"UNKNOWN\".to_string()\n } else {\n review.state.trim().to_ascii_uppercase()\n };\n *counts.entry(key).or_insert(0) += 1;\n }\n counts\n}\n\nfn record_pr_feedback_todos(\n repo_root: &Path,\n repo: &str,\n pr_number: u64,\n items: &[PrFeedbackItem],\n) -> Result<Vec<String>> {\n let (path, mut todos) = todo::load_items_at_root(repo_root)?;\n let mut existing_refs = HashSet::new();\n for todo_item in &todos {\n if let Some(ext) = todo_item\n .external_ref\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n {\n existing_refs.insert(ext.to_string());\n }\n }\n\n let mut created = Vec::new();\n let now = chrono::Utc::now().to_rfc3339();\n for item in items {\n if existing_refs.contains(&item.external_ref) {\n continue;\n }\n let id = Uuid::new_v4().simple().to_string();\n let mut note = String::new();\n note.push_str(\"Source: GitHub PR feedback\\n\");\n note.push_str(\"Repo: \");\n note.push_str(repo);\n note.push('\\n');\n note.push_str(\"PR: \");\n note.push_str(&pr_number.to_string());\n note.push('\\n');\n note.push_str(\"Type: \");\n note.push_str(item.source);\n note.push('\\n');\n note.push_str(\"Author: \");\n note.push_str(&item.author);\n note.push('\\n');\n if let Some(location) = feedback_location_label(item) {\n note.push_str(\"Location: \");\n note.push_str(&location);\n note.push('\\n');\n }\n note.push_str(\"Link: \");\n note.push_str(&item.url);\n note.push('\\n');\n note.push('\\n');\n note.push_str(item.body.trim());\n\n todos.push(todo::TodoItem {\n id: id.clone(),\n title: pr_feedback_todo_title(pr_number, item),\n status: \"pending\".to_string(),\n created_at: now.clone(),\n updated_at: None,\n note: Some(note),\n session: None,\n external_ref: Some(item.external_ref.clone()),\n priority: Some(todo::parse_priority_from_issue(&item.body)),\n });\n existing_refs.insert(item.external_ref.clone());\n created.push(id);\n }\n\n if !created.is_empty() {\n todo::save_items(&path, &todos)?;\n }\n\n Ok(created)\n}\n\nfn write_pr_feedback_snapshot(\n repo_root: &Path,\n repo: &str,\n pr_number: u64,\n pr_url: &str,\n trace_id: &str,\n items: &[PrFeedbackItem],\n) -> Result<PathBuf> {\n let dir = repo_root.join(\".ai\").join(\"reviews\");\n fs::create_dir_all(&dir)?;\n let path = dir.join(format!(\"pr-feedback-{pr_number}.md\"));\n\n let mut out = String::new();\n out.push_str(\"# PR Feedback\\n\\n\");\n out.push_str(\"- Repo: `\");\n out.push_str(repo);\n out.push_str(\"`\\n\");\n out.push_str(\"- PR: #\");\n out.push_str(&pr_number.to_string());\n out.push('\\n');\n out.push_str(\"- URL: \");\n out.push_str(pr_url);\n out.push('\\n');\n out.push_str(\"- Trace ID: `\");\n out.push_str(trace_id);\n out.push_str(\"`\\n\");\n out.push_str(\"- Generated: \");\n out.push_str(&chrono::Utc::now().to_rfc3339());\n out.push('\\n');\n out.push('\\n');\n\n if items.is_empty() {\n out.push_str(\"No actionable text feedback found.\\n\");\n } else {\n out.push_str(\"## Actionable Items\\n\\n\");\n for (idx, item) in items.iter().enumerate() {\n out.push_str(&(idx + 1).to_string());\n out.push_str(\". [\");\n out.push_str(item.source);\n out.push_str(\"] \");\n out.push_str(&item.author);\n if let Some(location) = feedback_location_label(item) {\n out.push_str(\" (\");\n out.push_str(&location);\n out.push(')');\n }\n if let Some(state) = feedback_review_state_label(item) {\n out.push_str(\" [\");\n out.push_str(&state);\n out.push(']');\n }\n out.push('\\n');\n out.push_str(\" \");\n out.push_str(item.body.trim());\n out.push('\\n');\n out.push_str(\" \");\n out.push_str(&item.url);\n out.push('\\n');\n if let Some(diff_hunk) = item\n .diff_hunk\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n {\n out.push('\\n');\n out.push_str(\" ```diff\\n\");\n for line in compact_diff_hunk(diff_hunk, 20, 1000).lines() {\n out.push_str(\" \");\n out.push_str(line);\n out.push('\\n');\n }\n out.push_str(\" ```\\n\");\n }\n out.push('\\n');\n }\n }\n\n fs::write(&path, out)?;\n Ok(path)\n}\n\nfn write_pr_feedback_snapshot_json(snapshot: &PrFeedbackSnapshot, path: &Path) -> Result<()> {\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n let bytes = serde_json::to_vec_pretty(snapshot).context(\"failed to encode PR feedback JSON\")?;\n fs::write(path, bytes).with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(())\n}\n\nfn write_pr_feedback_review_plan(\n workspace_root: &Path,\n snapshot: &PrFeedbackSnapshot,\n markdown_snapshot_path: &Path,\n json_snapshot_path: &Path,\n) -> Result<PathBuf> {\n write_pr_feedback_review_plan_at(\n &pr_feedback_plan_root(),\n workspace_root,\n snapshot,\n markdown_snapshot_path,\n json_snapshot_path,\n )\n}\n\nfn write_pr_feedback_kit_system_prompt(\n snapshot: &PrFeedbackSnapshot,\n markdown_snapshot_path: &Path,\n json_snapshot_path: &Path,\n review_plan_path: &Path,\n) -> Result<PathBuf> {\n write_pr_feedback_kit_system_prompt_at(\n &pr_feedback_plan_root(),\n snapshot,\n markdown_snapshot_path,\n json_snapshot_path,\n review_plan_path,\n )\n}\n\nfn write_pr_feedback_review_rules(\n workspace_root: &Path,\n snapshot: &PrFeedbackSnapshot,\n markdown_snapshot_path: &Path,\n json_snapshot_path: &Path,\n review_plan_path: &Path,\n kit_system_path: &Path,\n) -> Result<PathBuf> {\n write_pr_feedback_review_rules_at(\n &pr_feedback_plan_root(),\n workspace_root,\n snapshot,\n markdown_snapshot_path,\n json_snapshot_path,\n review_plan_path,\n kit_system_path,\n )\n}\n\nfn write_pr_feedback_review_rules_at(\n plan_root: &Path,\n workspace_root: &Path,\n snapshot: &PrFeedbackSnapshot,\n markdown_snapshot_path: &Path,\n json_snapshot_path: &Path,\n review_plan_path: &Path,\n kit_system_path: &Path,\n) -> Result<PathBuf> {\n let path = pr_feedback_review_rules_path_at(plan_root, &snapshot.repo, snapshot.pr_number);\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n\n let canonical_rules_path = canonical_review_rules_doc_path();\n\n let mut out = String::new();\n out.push_str(\"# [\");\n out.push_str(&snapshot.pr_title);\n out.push_str(\"](\");\n out.push_str(&snapshot.pr_url);\n out.push_str(\") Review Rules\\n\\n\");\n out.push_str(\"Generated operator artifact for resolving PR feedback item by item in the current workspace.\\n\\n\");\n out.push_str(\"- Workspace: `\");\n out.push_str(&workspace_root.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"- Feedback plan: `\");\n out.push_str(&review_plan_path.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"- Feedback snapshot (markdown): `\");\n out.push_str(&markdown_snapshot_path.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"- Feedback snapshot (json): `\");\n out.push_str(&json_snapshot_path.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"- Kit system prompt: `\");\n out.push_str(&kit_system_path.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"- Canonical shared rules: `\");\n out.push_str(&canonical_rules_path.display().to_string());\n out.push_str(\"`\\n\\n\");\n out.push_str(\"## Run Here\\n\\n\");\n out.push_str(\"From the product workspace:\\n\\n```bash\\n\");\n out.push_str(\"cd \");\n out.push_str(&workspace_root.display().to_string());\n out.push_str(\"\\nL check \");\n out.push_str(&snapshot.pr_url);\n out.push_str(\n \"\\nkit review --dir . --base origin/main --feedback-auto --preset designer\\n```\\n\\n\",\n );\n out.push_str(\"Keep these visible together in Cursor:\\n\");\n out.push_str(\"- current file under review\\n\");\n out.push_str(\"- local diff for that file\\n\");\n out.push_str(\"- this review-rules artifact\\n\");\n out.push_str(\"- the feedback plan markdown\\n\");\n out.push_str(\"- the feedback JSON snapshot\\n\");\n out.push_str(\"- deterministic `kit review` output when relevant\\n\\n\");\n out.push_str(\"## One-Item Loop\\n\\n\");\n out.push_str(\"For every review item:\\n\\n\");\n out.push_str(\"1. read the reviewer comment\\n\");\n out.push_str(\"2. inspect the exact diff hunk\\n\");\n out.push_str(\"3. inspect adjacent code and dependent call sites\\n\");\n out.push_str(\"4. decide the concern status in the current code: still applies here, moved nearby, already resolved, or not a real issue\\n\");\n out.push_str(\"5. explain why the original diff ended up in that shape\\n\");\n out.push_str(\"6. choose the smallest acceptable fix or explicit no-fix decision\\n\");\n out.push_str(\"7. run the exact validation in the product repo\\n\");\n out.push_str(\"8. capture one durable Kit-side lesson only if it is reusable\\n\\n\");\n out.push_str(\"## Prompt Template\\n\\n```text\\n\");\n out.push_str(\"Use this PR review item block as the source of truth.\\n\\n\");\n out.push_str(\"Canonical review rules: \");\n out.push_str(&canonical_rules_path.display().to_string());\n out.push_str(\"\\nPR-local workflow artifact: \");\n out.push_str(&path.display().to_string());\n out.push_str(\"\\n\\nWorkflow:\\n\");\n out.push_str(\"- work in the product repo first\\n\");\n out.push_str(\"- inspect the exact local diff and adjacent call sites before deciding\\n\");\n out.push_str(\"- keep the product-repo fix separate from the future Kit improvement\\n\");\n out.push_str(\"- if the durable lesson is about the review workflow or prompt contract, update the canonical review rules doc instead of AGENTS.md\\n\\n\");\n out.push_str(\"Task:\\n\");\n out.push_str(\"1. Decide the Concern Status first: still applies here, moved nearby, already resolved, or not a real issue.\\n\");\n out.push_str(\"2. Decide whether the reviewer is right in the current code shape.\\n\");\n out.push_str(\"3. Explain why the current diff likely ended up in its flawed shape.\\n\");\n out.push_str(\"4. If the concern still applies here or moved nearby, propose the smallest acceptable fix in the current branch. Otherwise explain why no patch is required.\\n\");\n out.push_str(\"5. State the exact validation to run in the product repo.\\n\");\n out.push_str(\"6. If the same diff exposes an adjacent issue, label it fix-now, defer, or ignore.\\n\");\n out.push_str(\"7. If there is a durable lesson about the review operator workflow or prompt contract, propose the exact update for \");\n out.push_str(&canonical_rules_path.display().to_string());\n out.push_str(\".\\n\");\n out.push_str(\"8. If there is a durable lesson about Kit review behavior, propose the exact AGENTS.md update for ~/repos/mark3labs/kit/AGENTS.md.\\n\");\n out.push_str(\"9. If docs or AGENTS.md guidance are not enough, say what specific deterministic review rule or review-extension surface in ~/repos/mark3labs/kit should change.\\n\");\n out.push_str(\"10. Keep scope tight and avoid broad refactors.\\n\\n\");\n out.push_str(\"Rules:\\n\");\n out.push_str(\"- Decide Concern Status before proposing a patch.\\n\");\n out.push_str(\"- Inspect the exact local diff and adjacent call sites before deciding.\\n\");\n out.push_str(\"- Explain the coding habit, wrong assumption, or time pressure that likely produced the flawed diff shape.\\n\");\n out.push_str(\"- Prefer the smallest fix that answers the reviewer directly.\\n\");\n out.push_str(\"- If Concern Status is already resolved or not a real issue, do not invent a patch; explain the no-fix decision clearly.\\n\");\n out.push_str(\"- Validation must name the actual command, test, or manual behavior to check.\\n\");\n out.push_str(\"- Only propose a Kit upgrade if it is reusable across future PRs.\\n\");\n out.push_str(\"- If the issue is product-specific and not reusable, say so explicitly.\\n\");\n out.push_str(\"- Keep review-rules.md updates separate from AGENTS.md updates and separate from deterministic rule proposals.\\n\");\n out.push_str(\"- Use the existing Concern Status / Local Verdict / Why This Happened / Narrow Fix / Validation / Prevention Candidate / Kit Upgrade notes in the block as priors if they are already good. Improve them only when needed.\\n\");\n out.push_str(\"- Treat the item as complete only when Concern Status is explicit, validation has passed, the local review notes or ledger text is written, and the Prevention Candidate plus Kit Upgrade decision are explicitly recorded. A code patch is required only for Concern Status `still applies here` or `moved nearby`.\\n\\n\");\n out.push_str(\"Return sections:\\n\");\n out.push_str(\"- Concern Status\\n\");\n out.push_str(\"- Verdict\\n\");\n out.push_str(\"- Why This Happened\\n\");\n out.push_str(\"- Smallest Fix\\n\");\n out.push_str(\"- Validation\\n\");\n out.push_str(\"- Adjacent Coach Findings\\n\");\n out.push_str(\"- Prevention Candidate\\n\");\n out.push_str(\"- Kit Upgrade\\n\");\n out.push_str(\"- Ledger Update\\n\");\n out.push_str(\"- Completion Check\\n\");\n out.push_str(\"```\\n\\n\");\n out.push_str(\"## Required Output Sections\\n\\n\");\n out.push_str(\"- `Concern Status`\\n\");\n out.push_str(\"- `Verdict`\\n\");\n out.push_str(\"- `Why This Happened`\\n\");\n out.push_str(\"- `Smallest Fix`\\n\");\n out.push_str(\"- `Validation`\\n\");\n out.push_str(\"- `Adjacent Coach Findings`\\n\");\n out.push_str(\"- `Prevention Candidate`\\n\");\n out.push_str(\"- `Kit Upgrade`\\n\");\n out.push_str(\"- `Ledger Update`\\n\");\n out.push_str(\"- `Completion Check`\\n\\n\");\n out.push_str(\"## Kit Upgrade Decision Order\\n\\n\");\n out.push_str(\"1. `review-rules.md` update in `\");\n out.push_str(&canonical_rules_path.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"2. `AGENTS.md` update in `~/repos/mark3labs/kit/AGENTS.md`\\n\");\n out.push_str(\"3. deterministic Kit review rule\\n\");\n out.push_str(\"4. review extension / richer review packet\\n\");\n out.push_str(\"5. no Kit change\\n\\n\");\n out.push_str(\"## Suggested Failure Modes\\n\\n\");\n out.push_str(\"- `wrong-fix-root-cause`\\n\");\n out.push_str(\"- `unclear-extraction-intent`\\n\");\n out.push_str(\"- `over-generic-abstraction`\\n\");\n out.push_str(\"- `behavior-regression-risk`\\n\");\n out.push_str(\"- `code-shape-needs-refactor`\\n\");\n\n fs::write(&path, out).with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(path)\n}\n\nfn write_pr_feedback_kit_system_prompt_at(\n plan_root: &Path,\n snapshot: &PrFeedbackSnapshot,\n markdown_snapshot_path: &Path,\n json_snapshot_path: &Path,\n review_plan_path: &Path,\n) -> Result<PathBuf> {\n let path = pr_feedback_kit_system_path_at(plan_root, &snapshot.repo, snapshot.pr_number);\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n\n let mut out = String::new();\n out.push_str(\"# Kit PR Feedback Prevention System Prompt\\n\\n\");\n out.push_str(\"You are a strict repository review engineer. Study the attached PR feedback artifacts and design concrete guardrails so the same issues are caught before review next time.\\n\\n\");\n out.push_str(\"Priorities:\\n\");\n out.push_str(\"1. Prefer deterministic prevention first: lint rules, diff rules, static checks, tests, review presets, or build-time assertions.\\n\");\n out.push_str(\"2. Only propose agentic or extension-based review hooks when deterministic checks are insufficient.\\n\");\n out.push_str(\"3. Tie every recommendation to exact files, commands, hook points, or review entrypoints.\\n\");\n out.push_str(\"4. Do not restate reviewer comments. Explain root cause, prevention, and rollout cost.\\n\\n\");\n out.push_str(\"Attached artifacts:\\n\");\n out.push_str(\"- Feedback snapshot markdown: `\");\n out.push_str(&markdown_snapshot_path.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"- Feedback snapshot json: `\");\n out.push_str(&json_snapshot_path.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"- Human review plan: `\");\n out.push_str(&review_plan_path.display().to_string());\n out.push_str(\"`\\n\\n\");\n out.push_str(\"Expected output:\\n\");\n out.push_str(\"## Root Causes\\n\");\n out.push_str(\"- Group the feedback into a few structural failure modes.\\n\\n\");\n out.push_str(\"## Preventative Checks\\n\");\n out.push_str(\"- For each failure mode, propose the smallest deterministic check that would have caught it.\\n\");\n out.push_str(\"- Name the likely implementation target for each check.\\n\\n\");\n out.push_str(\"## Kit Review Bot Hooks\\n\");\n out.push_str(\"- Only include hooks that add real signal beyond deterministic checks.\\n\");\n out.push_str(\"- Describe the exact extension or review entrypoint to use.\\n\\n\");\n out.push_str(\"## Rollout\\n\");\n out.push_str(\"- Order work from highest-signal/lowest-cost to lower-priority improvements.\\n\");\n out.push_str(\"- Include validation steps for each added guardrail.\\n\");\n\n fs::write(&path, out).with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(path)\n}\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nenum PrFeedbackSeedKind {\n EnvContract,\n OverGeneric,\n OwnershipIntent,\n Default,\n}\n\nfn normalize_pr_feedback_seed_text(value: &str) -> String {\n value.split_whitespace().collect::<Vec<_>>().join(\" \")\n}\n\nfn truncate_pr_feedback_seed_text(value: &str, max_chars: usize) -> String {\n let normalized = normalize_pr_feedback_seed_text(value);\n let mut chars = normalized.chars();\n let truncated = chars.by_ref().take(max_chars).collect::<String>();\n if chars.next().is_some() {\n format!(\"{truncated}...\")\n } else {\n truncated\n }\n}\n\nfn pr_feedback_seed_kind(item: &PrFeedbackItem) -> PrFeedbackSeedKind {\n let body = item.body.to_ascii_lowercase();\n if body.contains(\".env\") || body.contains(\"env file\") || body.contains(\"environment\") {\n PrFeedbackSeedKind::EnvContract\n } else if body.contains(\"generic\") {\n PrFeedbackSeedKind::OverGeneric\n } else if body.contains(\"intent\")\n || body.contains(\"intnet\")\n || body.contains(\"moving\")\n || body.contains(\"move this\")\n {\n PrFeedbackSeedKind::OwnershipIntent\n } else {\n PrFeedbackSeedKind::Default\n }\n}\n\nfn pr_feedback_file_label(item: &PrFeedbackItem) -> String {\n let file = item\n .path\n .as_deref()\n .and_then(|value| Path::new(value).file_name())\n .and_then(|value| value.to_str())\n .unwrap_or(\"current file\");\n match item.line {\n Some(line) => format!(\"{file}:{line}\"),\n None => file.to_string(),\n }\n}\n\nfn pr_feedback_area_label(item: &PrFeedbackItem) -> &'static str {\n match item.path.as_deref() {\n Some(path) if path.starts_with(\"ide/designer\") => \"Designer\",\n _ => \"the product\",\n }\n}\n\nfn seeded_pr_feedback_plan_sections(\n item: &PrFeedbackItem,\n) -> (String, String, String, String, String, String, String) {\n let focus = truncate_pr_feedback_seed_text(&item.body, 160);\n let file_label = pr_feedback_file_label(item);\n let area = pr_feedback_area_label(item);\n let concern_status = \"decide whether it still applies here, moved nearby, is already resolved, or is not a real issue\".to_string();\n match pr_feedback_seed_kind(item) {\n PrFeedbackSeedKind::EnvContract => (\n concern_status,\n \"Reviewer is likely right that this should be fixed in configuration rather than hidden behind a runtime guard.\".to_string(),\n \"The diff likely added a defensive env check because local setup felt fragile, but that weakens a required runtime contract instead of enforcing it.\".to_string(),\n format!(\n \"Remove the runtime configuration band-aid in {file_label} and keep the required env contract explicit at the real usage boundary.\"\n ),\n format!(\n \"Run the smallest {area} check with the env configured correctly and confirm the feature still works without the extra guard.\"\n ),\n \"Review rule: do not add runtime env fallbacks when the feature contract requires setup-time configuration.\".to_string(),\n \"review-rules.md if this survives validation; otherwise none.\".to_string(),\n ),\n PrFeedbackSeedKind::OverGeneric => (\n concern_status,\n \"Reviewer is likely right to question whether this abstraction is more generic than the current product need.\".to_string(),\n \"The diff likely generalized early to feel reusable, but the reviewer only sees one concrete use case so the abstraction now overpromises intent.\".to_string(),\n format!(\n \"Narrow the abstraction in {file_label} to the concrete use case unless at least two real call sites justify keeping it generic.\"\n ),\n format!(\n \"Exercise the exact {area} flow that needs this code and confirm the narrower API still covers the behavior without breaking adjacent callers.\"\n ),\n \"Review rule: do not introduce generic helpers or executors unless the diff shows at least two real consumers or clearly justifies the shared contract.\".to_string(),\n \"deterministic Kit review rule if this pattern is detectable; otherwise review-rules.md.\".to_string(),\n ),\n PrFeedbackSeedKind::OwnershipIntent => (\n concern_status,\n \"The reviewer is asking for intent and ownership, not just whether the code compiles.\".to_string(),\n \"The diff likely moved or extracted code to clean up structure, but it did not make the new ownership boundary legible to a reviewer.\".to_string(),\n format!(\n \"Make the smallest placement or naming change in {file_label} that makes the owner and intent obvious at the touched call site.\"\n ),\n format!(\n \"Open the affected {area} flow and confirm the behavior is unchanged while the new ownership boundary is easier to explain.\"\n ),\n \"Review rule: when moving logic across component or module boundaries, make the new owner explicit in names or keep the logic colocated.\".to_string(),\n \"review-rules.md unless this turns into a deterministic ownership-boundary rule.\".to_string(),\n ),\n PrFeedbackSeedKind::Default => (\n concern_status,\n format!(\"Judge whether the reviewer is right about: {focus}\"),\n \"The diff likely optimized for implementation speed before making the intent legible to a reviewer.\".to_string(),\n format!(\n \"Make the smallest change in {file_label} and its immediate call site that answers the reviewer directly.\"\n ),\n format!(\n \"Run the smallest relevant {area} check for this flow and confirm adjacent behavior did not regress.\"\n ),\n \"Review heuristic: when a diff introduces a new helper, move, or behavior change, the surrounding call sites should make the intent obvious.\".to_string(),\n \"review-rules.md if the prevention survives validation; otherwise none.\".to_string(),\n ),\n }\n}\n\nfn write_pr_feedback_review_plan_at(\n plan_root: &Path,\n workspace_root: &Path,\n snapshot: &PrFeedbackSnapshot,\n markdown_snapshot_path: &Path,\n json_snapshot_path: &Path,\n) -> Result<PathBuf> {\n let path = pr_feedback_review_plan_path_at(plan_root, &snapshot.repo, snapshot.pr_number);\n let review_rules_path =\n pr_feedback_review_rules_path_at(plan_root, &snapshot.repo, snapshot.pr_number);\n let kit_system_path =\n pr_feedback_kit_system_path_at(plan_root, &snapshot.repo, snapshot.pr_number);\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n\n let mut out = String::new();\n out.push_str(\"# [\");\n out.push_str(&snapshot.pr_title);\n out.push_str(\"](\");\n out.push_str(&snapshot.pr_url);\n out.push_str(\")\\n\\n\");\n out.push_str(\"- Repo: `\");\n out.push_str(&snapshot.repo);\n out.push_str(\"`\\n\");\n out.push_str(\"- PR: #\");\n out.push_str(&snapshot.pr_number.to_string());\n out.push('\\n');\n out.push_str(\"- URL: \");\n out.push_str(&snapshot.pr_url);\n out.push('\\n');\n out.push_str(\"- Trace ID: `\");\n out.push_str(&snapshot.trace_id);\n out.push_str(\"`\\n\");\n out.push_str(\"- Workspace: `\");\n out.push_str(&workspace_root.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"- Generated: \");\n out.push_str(&snapshot.generated_at);\n out.push('\\n');\n out.push_str(\"- Snapshot (markdown): `\");\n out.push_str(&markdown_snapshot_path.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"- Snapshot (json): `\");\n out.push_str(&json_snapshot_path.display().to_string());\n out.push_str(\"`\\n\");\n out.push_str(\"- Review rules: `\");\n out.push_str(&review_rules_path.display().to_string());\n out.push_str(\"`\\n\\n\");\n out.push_str(\"## Cursor Review\\n\\n\");\n out.push_str(\"Reopen the workspace and review artifacts together:\\n\\n```bash\\n\");\n out.push_str(&cursor_review_open_command(&snapshot.pr_url, true, true));\n out.push_str(\"\\n```\\n\\n\");\n out.push_str(\"Keep these visible while resolving comments:\\n\");\n out.push_str(\"- the repo checkout / JJ workspace\\n\");\n out.push_str(\"- the generated review-rules artifact\\n\");\n out.push_str(\"- this feedback plan\\n\");\n out.push_str(\"- the current file diff\\n\");\n out.push_str(\"- the Kit system prompt for later prevention work\\n\\n\");\n out.push_str(\"## Kit Commands\\n\\n\");\n out.push_str(\"Deterministic review gate:\\n\\n```bash\\n\");\n out.push_str(\n \"kit review --dir . --base origin/main --feedback-auto --preset designer --json\\n\",\n );\n out.push_str(\"```\\n\\n\");\n out.push_str(\"Preventative rule synthesis from this feedback set:\\n\\n```bash\\n\");\n out.push_str(\"kit --system-prompt \");\n out.push_str(&kit_system_path.display().to_string());\n out.push_str(\" @\");\n out.push_str(&json_snapshot_path.display().to_string());\n out.push_str(\" @\");\n out.push_str(&path.display().to_string());\n out.push_str(\" \\\"Design preventative review and lint rules for this feedback set.\\\" --json\\n\");\n out.push_str(\"```\\n\\n\");\n\n let unique_files: Vec<String> = {\n let mut seen = HashSet::new();\n snapshot\n .items\n .iter()\n .filter_map(|item| item.path.as_ref())\n .filter(|path| seen.insert((*path).clone()))\n .take(8)\n .cloned()\n .collect()\n };\n\n out.push_str(\"## Summary\\n\\n\");\n out.push_str(\"- Actionable items: \");\n out.push_str(&snapshot.items.len().to_string());\n out.push('\\n');\n if !unique_files.is_empty() {\n out.push_str(\"- Main files: \");\n out.push_str(\n &unique_files\n .iter()\n .map(|path| format!(\"`{path}`\"))\n .collect::<Vec<_>>()\n .join(\", \"),\n );\n out.push('\\n');\n }\n out.push_str(\"- Review states: \");\n let mut review_states: Vec<(String, usize)> = snapshot\n .review_state_counts\n .iter()\n .map(|(state, count)| (state.clone(), *count))\n .collect();\n review_states.sort_by(|a, b| a.0.cmp(&b.0));\n if review_states.is_empty() {\n out.push_str(\"none\");\n } else {\n out.push_str(\n &review_states\n .into_iter()\n .map(|(state, count)| format!(\"{state}:{count}\"))\n .collect::<Vec<_>>()\n .join(\", \"),\n );\n }\n out.push_str(\"\\n\\n\");\n\n for (idx, item) in snapshot.items.iter().enumerate() {\n out.push_str(\"## Item \");\n out.push_str(&(idx + 1).to_string());\n out.push_str(\": \");\n out.push_str(\n &feedback_location_label(item)\n .or_else(|| item.path.clone())\n .unwrap_or_else(|| format!(\"{} feedback\", item.source)),\n );\n out.push_str(\"\\n\\n\");\n\n out.push_str(\"### Reviewer Feedback\\n\\n\");\n out.push_str(\"- Source: `\");\n out.push_str(item.source);\n out.push_str(\"`\\n\");\n out.push_str(\"- Author: `\");\n out.push_str(&item.author);\n out.push_str(\"`\\n\");\n if let Some(state) = feedback_review_state_label(item) {\n out.push_str(\"- Review state: `\");\n out.push_str(&state);\n out.push_str(\"`\\n\");\n }\n if let Some(location) = feedback_location_label(item) {\n out.push_str(\"- Location: `\");\n out.push_str(&location);\n out.push_str(\"`\\n\");\n }\n out.push_str(\"- URL: \");\n out.push_str(&item.url);\n out.push_str(\"\\n\\n\");\n out.push_str(item.body.trim());\n out.push_str(\"\\n\\n\");\n\n if let Some(diff_hunk) = item\n .diff_hunk\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n {\n out.push_str(\"### Diff Hunk\\n\\n```diff\\n\");\n out.push_str(&compact_diff_hunk(diff_hunk, 24, 1200));\n out.push_str(\"\\n```\\n\\n\");\n }\n\n let (concern_status, verdict, why, fix, validation, prevention, kit_upgrade) =\n seeded_pr_feedback_plan_sections(item);\n\n out.push_str(\"### Concern Status\\n\\n\");\n out.push_str(\"- \");\n out.push_str(&concern_status);\n out.push_str(\"\\n\\n\");\n out.push_str(\"### Local Verdict\\n\\n\");\n out.push_str(\"- \");\n out.push_str(&verdict);\n out.push_str(\"\\n\\n\");\n out.push_str(\"### Why This Happened\\n\\n\");\n out.push_str(\"- \");\n out.push_str(&why);\n out.push_str(\"\\n\\n\");\n out.push_str(\"### Narrow Fix\\n\\n\");\n out.push_str(\"- \");\n out.push_str(&fix);\n out.push_str(\"\\n\\n\");\n out.push_str(\"### Validation\\n\\n\");\n out.push_str(\"- \");\n out.push_str(&validation);\n out.push_str(\"\\n\\n\");\n out.push_str(\"### Prevention Candidate\\n\\n\");\n out.push_str(\"- \");\n out.push_str(&prevention);\n out.push_str(\"\\n\\n\");\n out.push_str(\"### Kit Upgrade\\n\\n\");\n out.push_str(\"- \");\n out.push_str(&kit_upgrade);\n out.push_str(\"\\n\\n\");\n out.push_str(\"### Status\\n\\n\");\n out.push_str(\"- [ ] open\\n\");\n out.push_str(\"- [ ] patched\\n\");\n out.push_str(\"- [ ] validated\\n\");\n out.push_str(\"- [ ] prevention-captured\\n\\n\");\n }\n\n out.push_str(\"## Kit Input\\n\\n```json\\n\");\n out.push_str(\n &serde_json::to_string_pretty(snapshot).context(\"failed to render kit input JSON\")?,\n );\n out.push_str(\"\\n```\\n\");\n\n fs::write(&path, out).with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(path)\n}\n\nfn load_pr_feedback_data(repo_root: &Path, selector: Option<&str>) -> Result<LoadedPrFeedback> {\n let (repo, pr_number, pr_url) = if let Some(selector) = selector {\n if let Some((repo, pr_number)) = parse_github_pr_url(selector) {\n let pr_url = format!(\"https://github.com/{repo}/pull/{pr_number}\");\n (repo, pr_number, pr_url)\n } else {\n let trimmed = selector.trim().trim_start_matches('#');\n let pr_number = trimmed.parse::<u64>().with_context(|| {\n format!(\"invalid PR selector `{selector}`; expected number or URL\")\n })?;\n let repo = resolve_github_repo(repo_root)?;\n let pr_url = format!(\"https://github.com/{repo}/pull/{pr_number}\");\n (repo, pr_number, pr_url)\n }\n } else {\n let repo = resolve_github_repo(repo_root)?;\n let (pr_number, pr_url) = resolve_current_pr_for_feedback(repo_root, &repo).with_context(\n || \"failed to resolve current PR. Pass an explicit selector: `f pr feedback <number>`\",\n )?;\n (repo, pr_number, pr_url)\n };\n\n let reviews_endpoint = format!(\"repos/{repo}/pulls/{pr_number}/reviews?per_page=100\");\n let review_comments_endpoint = format!(\"repos/{repo}/pulls/{pr_number}/comments?per_page=100\");\n let issue_comments_endpoint = format!(\"repos/{repo}/issues/{pr_number}/comments?per_page=100\");\n let pr_title = gh_capture_in(\n repo_root,\n &[\n \"pr\",\n \"view\",\n &pr_number.to_string(),\n \"--repo\",\n &repo,\n \"--json\",\n \"title\",\n ],\n )\n .and_then(|out| {\n serde_json::from_str::<GhPrTitleSummary>(out.trim())\n .map(|parsed| parsed.title)\n .context(\"failed to parse gh pr view title JSON\")\n })\n .unwrap_or_else(|_| format!(\"PR #{}\", pr_number));\n\n let reviews: Vec<GhReview> = gh_api_json_in(repo_root, &reviews_endpoint)?;\n let review_comments: Vec<GhPrReviewComment> =\n gh_api_json_in(repo_root, &review_comments_endpoint)?;\n let issue_comments: Vec<GhIssueComment> = gh_api_json_in(repo_root, &issue_comments_endpoint)?;\n let review_thread_ids =\n gh_review_thread_ids_by_comment_url(repo_root, &repo, pr_number).unwrap_or_default();\n\n let mut items: Vec<PrFeedbackItem> = Vec::new();\n for comment in &review_comments {\n if comment.in_reply_to_id.is_some() {\n continue;\n }\n let body = comment.body.trim();\n if body.is_empty() {\n continue;\n }\n items.push(PrFeedbackItem {\n external_ref: pr_feedback_external_ref(&repo, pr_number, \"review-comment\", comment.id),\n source: \"review-comment\",\n author: comment.user.login.clone(),\n body: body.to_string(),\n url: comment.html_url.trim().to_string(),\n thread_id: review_thread_ids.get(comment.html_url.trim()).cloned(),\n path: comment.path.clone(),\n line: comment.line,\n review_state: None,\n diff_hunk: comment.diff_hunk.clone(),\n });\n }\n for comment in &issue_comments {\n let body = comment.body.trim();\n if body.is_empty() {\n continue;\n }\n items.push(PrFeedbackItem {\n external_ref: pr_feedback_external_ref(&repo, pr_number, \"issue-comment\", comment.id),\n source: \"issue-comment\",\n author: comment.user.login.clone(),\n body: body.to_string(),\n url: comment.html_url.trim().to_string(),\n thread_id: None,\n path: None,\n line: None,\n review_state: None,\n diff_hunk: None,\n });\n }\n for review in &reviews {\n let body = review.body.trim();\n if body.is_empty() {\n continue;\n }\n items.push(PrFeedbackItem {\n external_ref: pr_feedback_external_ref(&repo, pr_number, \"review\", review.id),\n source: \"review\",\n author: review.user.login.clone(),\n body: body.to_string(),\n url: review.html_url.trim().to_string(),\n thread_id: None,\n path: None,\n line: None,\n review_state: Some(review.state.trim().to_string()),\n diff_hunk: None,\n });\n }\n\n Ok(LoadedPrFeedback {\n repo,\n pr_number,\n pr_url,\n pr_title,\n reviews,\n review_comments,\n issue_comments,\n items,\n })\n}\n\nfn build_pr_feedback_snapshot(data: &LoadedPrFeedback) -> PrFeedbackSnapshot {\n PrFeedbackSnapshot {\n repo: data.repo.clone(),\n pr_number: data.pr_number,\n pr_url: data.pr_url.clone(),\n pr_title: data.pr_title.clone(),\n trace_id: new_pr_feedback_trace_id(),\n generated_at: chrono::Utc::now().to_rfc3339(),\n reviews_count: data.reviews.len(),\n review_comments_count: data.review_comments.len(),\n issue_comments_count: data.issue_comments.len(),\n review_state_counts: review_state_counts_map(&data.reviews),\n items: data.items.clone(),\n }\n}\n\nfn write_pr_feedback_artifacts(\n repo_root: &Path,\n data: &LoadedPrFeedback,\n) -> Result<(PrFeedbackSnapshot, PrFeedbackArtifacts)> {\n let snapshot = build_pr_feedback_snapshot(data);\n let snapshot_path = write_pr_feedback_snapshot(\n repo_root,\n &data.repo,\n data.pr_number,\n &data.pr_url,\n &snapshot.trace_id,\n &data.items,\n )?;\n let snapshot_json_path = pr_feedback_snapshot_json_path(repo_root, data.pr_number)?;\n write_pr_feedback_snapshot_json(&snapshot, &snapshot_json_path)?;\n let review_plan_path =\n write_pr_feedback_review_plan(repo_root, &snapshot, &snapshot_path, &snapshot_json_path)?;\n let kit_system_path = write_pr_feedback_kit_system_prompt(\n &snapshot,\n &snapshot_path,\n &snapshot_json_path,\n &review_plan_path,\n )?;\n let review_rules_path = write_pr_feedback_review_rules(\n repo_root,\n &snapshot,\n &snapshot_path,\n &snapshot_json_path,\n &review_plan_path,\n &kit_system_path,\n )?;\n Ok((\n snapshot,\n PrFeedbackArtifacts {\n snapshot_path,\n snapshot_json_path,\n review_plan_path,\n review_rules_path,\n kit_system_path,\n },\n ))\n}\n\nfn render_pr_feedback_reference(\n workspace_root: &Path,\n snapshot: &PrFeedbackSnapshot,\n artifacts: &PrFeedbackArtifacts,\n) -> String {\n let mut out = String::new();\n out.push_str(\"[pr-feedback]\\n\");\n out.push_str(\"Workspace: \");\n out.push_str(&workspace_root.display().to_string());\n out.push('\\n');\n out.push_str(\"PR feedback: \");\n out.push_str(&snapshot.repo);\n out.push('#');\n out.push_str(&snapshot.pr_number.to_string());\n out.push('\\n');\n out.push_str(\"Trace ID: \");\n out.push_str(&snapshot.trace_id);\n out.push('\\n');\n out.push_str(\"URL: \");\n out.push_str(&snapshot.pr_url);\n out.push('\\n');\n out.push_str(\"Snapshot markdown: \");\n out.push_str(&artifacts.snapshot_path.display().to_string());\n out.push('\\n');\n out.push_str(\"Snapshot json: \");\n out.push_str(&artifacts.snapshot_json_path.display().to_string());\n out.push('\\n');\n out.push_str(\"Review plan: \");\n out.push_str(&artifacts.review_plan_path.display().to_string());\n out.push('\\n');\n out.push_str(\"Review rules: \");\n out.push_str(&artifacts.review_rules_path.display().to_string());\n out.push('\\n');\n out.push_str(\"Kit system prompt: \");\n out.push_str(&artifacts.kit_system_path.display().to_string());\n out.push('\\n');\n out.push_str(\"Cursor reopen: \");\n out.push_str(&cursor_review_open_command(&snapshot.pr_url, true, true));\n out.push_str(\"\\n\\n\");\n out.push_str(\"Summary:\\n\");\n out.push_str(\"- Actionable items: \");\n out.push_str(&snapshot.items.len().to_string());\n out.push('\\n');\n let mut review_states: Vec<(String, usize)> = snapshot\n .review_state_counts\n .iter()\n .map(|(state, count)| (state.clone(), *count))\n .collect();\n review_states.sort_by(|a, b| a.0.cmp(&b.0));\n out.push_str(\"- Review states: \");\n if review_states.is_empty() {\n out.push_str(\"none\");\n } else {\n out.push_str(\n &review_states\n .into_iter()\n .map(|(state, count)| format!(\"{state}:{count}\"))\n .collect::<Vec<_>>()\n .join(\", \"),\n );\n }\n out.push_str(\"\\n\\nTop feedback items:\\n\");\n for (idx, item) in snapshot.items.iter().take(6).enumerate() {\n out.push_str(&(idx + 1).to_string());\n out.push_str(\". \");\n if let Some(location) = feedback_location_label(item) {\n out.push_str(&location);\n out.push_str(\" - \");\n }\n out.push_str(&compact_single_line(&item.body, 140));\n out.push('\\n');\n if let Some(diff_hunk) = item\n .diff_hunk\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n {\n out.push_str(\" diff:\\n\");\n for line in compact_diff_hunk(diff_hunk, 8, 500).lines() {\n out.push_str(\" \");\n out.push_str(line);\n out.push('\\n');\n }\n }\n }\n out.push_str(\"\\nPlan excerpt:\\n\");\n if let Ok(body) = fs::read_to_string(&artifacts.review_plan_path) {\n out.push_str(&compact_pr_feedback_context_block(&body, 40, 2400));\n } else {\n out.push_str(\"- Unable to read generated review plan.\");\n }\n out\n}\n\npub fn resolve_pr_feedback_reference(repo_root: &Path, selector: &str) -> Result<String> {\n ensure_gh_available()?;\n let data = load_pr_feedback_data(repo_root, Some(selector))?;\n let (snapshot, artifacts) = write_pr_feedback_artifacts(repo_root, &data)?;\n Ok(render_pr_feedback_reference(\n repo_root, &snapshot, &artifacts,\n ))\n}\n\nfn run_pr_feedback(repo_root: &Path, cmd: PrFeedbackCommand) -> Result<()> {\n ensure_gh_available()?;\n\n if let Some(selector) = cmd.selector.as_deref() {\n if selector == \"--help\" || selector == \"-h\" {\n println!(\"Usage: f pr feedback [<pr-number|pr-url>] [--todo] [--compact] [--cursor]\");\n println!(\"Examples:\");\n println!(\" f pr feedback\");\n println!(\" f pr feedback 8\");\n println!(\" f pr feedback https://github.com/owner/repo/pull/8 --todo\");\n println!(\" f pr feedback 8\");\n println!(\" f pr feedback 8 --compact\");\n println!(\" f pr feedback 8 --compact --cursor\");\n return Ok(());\n }\n }\n\n let data = load_pr_feedback_data(repo_root, cmd.selector.as_deref())?;\n let repo = data.repo.clone();\n let pr_number = data.pr_number;\n let pr_url = data.pr_url.clone();\n let reviews = &data.reviews;\n let review_comments = &data.review_comments;\n let issue_comments = &data.issue_comments;\n let items = &data.items;\n\n let (snapshot, artifacts) = write_pr_feedback_artifacts(repo_root, &data)?;\n println!(\"PR feedback: {repo}#{pr_number}\");\n println!(\"Trace ID: {}\", snapshot.trace_id);\n println!(\"URL: {pr_url}\");\n println!(\n \"Reviews: {} ({})\",\n reviews.len(),\n format_review_state_counts(&reviews)\n );\n println!(\"Review comments: {}\", review_comments.len());\n println!(\"Issue comments: {}\", issue_comments.len());\n\n println!(\"Snapshot: {}\", artifacts.snapshot_path.display());\n println!(\"Snapshot JSON: {}\", artifacts.snapshot_json_path.display());\n println!(\"Review plan: {}\", artifacts.review_plan_path.display());\n println!(\"Review rules: {}\", artifacts.review_rules_path.display());\n println!(\"Kit system prompt: {}\", artifacts.kit_system_path.display());\n println!(\n \"Cursor reopen: {}\",\n cursor_review_open_command(&pr_url, true, true)\n );\n if cmd.open_cursor {\n open_cursor_review_bundle(\n repo_root,\n &artifacts.review_plan_path,\n &artifacts.review_rules_path,\n &artifacts.kit_system_path,\n true,\n )?;\n println!(\"Cursor: opened workspace + review artifacts\");\n }\n\n if items.is_empty() {\n println!(\"No actionable text feedback found.\");\n return Ok(());\n }\n\n println!();\n println!(\"Actionable items ({}):\", items.len());\n for (idx, item) in items.iter().enumerate() {\n let preview = compact_single_line(&item.body, 120);\n if let Some(location) = feedback_location_label(item) {\n println!(\"{}. [{}] {} {}\", idx + 1, item.source, location, preview);\n } else {\n println!(\"{}. [{}] {}\", idx + 1, item.source, preview);\n }\n println!(\" by {} {}\", item.author, item.url);\n if cmd.show_full {\n if let Some(state) = feedback_review_state_label(item) {\n println!(\" state: {}\", state);\n }\n if let Some(diff_hunk) = item\n .diff_hunk\n .as_deref()\n .map(str::trim)\n .filter(|value| !value.is_empty())\n {\n println!(\" diff:\");\n for line in compact_diff_hunk(diff_hunk, 16, 900).lines() {\n println!(\" {}\", line);\n }\n }\n }\n }\n\n if cmd.record_todos {\n let created = record_pr_feedback_todos(repo_root, &repo, pr_number, &items)?;\n if created.is_empty() {\n println!(\"Todos: no new todos created (all feedback already tracked).\");\n } else {\n println!(\"Todos: created {} item(s).\", created.len());\n println!(\"Use `f todo list` to review them.\");\n }\n } else {\n println!(\"Tip: rerun with `--todo` to record these items into `.ai/todos/todos.json`.\");\n }\n\n Ok(())\n}\n\n#[derive(Debug, Clone)]\nstruct GhPrView {\n title: String,\n body: String,\n}\n\nfn gh_pr_view(repo_root: &Path, repo: &str, number: u64) -> Result<GhPrView> {\n #[derive(serde::Deserialize)]\n struct GhPrJson {\n title: String,\n body: String,\n }\n\n let out = gh_capture_in(\n repo_root,\n &[\n \"pr\",\n \"view\",\n &number.to_string(),\n \"--repo\",\n repo,\n \"--json\",\n \"title,body\",\n ],\n )?;\n let parsed: GhPrJson = serde_json::from_str(out.trim())\n .with_context(|| format!(\"failed to parse gh pr view JSON for #{number}\"))?;\n Ok(GhPrView {\n title: parsed.title,\n body: parsed.body,\n })\n}\n\nfn flow_project_name(repo_root: &Path) -> String {\n let flow_toml = repo_root.join(\"flow.toml\");\n if flow_toml.exists() {\n if let Ok(cfg) = crate::config::load(&flow_toml) {\n if let Some(name) = cfg\n .project_name\n .as_deref()\n .map(|s| s.trim())\n .filter(|s| !s.is_empty())\n {\n return name.to_string();\n }\n }\n }\n\n repo_root\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(\"project\")\n .to_string()\n}\n\nfn open_in_zed_preview(path: &Path) -> Result<()> {\n // Prefer Zed Preview if installed, otherwise fall back to Zed.\n let try_open = |app: &str| -> Result<()> {\n Command::new(\"open\")\n .args([\"-a\", app])\n .arg(path)\n .status()\n .with_context(|| format!(\"failed to open {app}\"))?;\n Ok(())\n };\n\n try_open(\"/Applications/Zed Preview.app\").or_else(|_| try_open(\"/Applications/Zed.app\"))\n}\n\nfn parse_pr_edit_markdown(text: &str) -> Result<(String, String)> {\n // Expected shape:\n // # Title\n // <one line title>\n //\n // # Description\n // <markdown body...>\n let mut title: Option<String> = None;\n let mut desc_lines: Vec<String> = Vec::new();\n\n let mut lines = text.lines().peekable();\n while let Some(line) = lines.next() {\n let l = line.trim_end();\n if l.trim() == \"# Title\" {\n // Consume subsequent blank lines then read the first non-empty line as the title.\n while let Some(nl) = lines.peek() {\n if nl.trim().is_empty() {\n lines.next();\n } else {\n break;\n }\n }\n if let Some(nl) = lines.peek() {\n let t = nl.trim();\n if !t.is_empty() {\n title = Some(t.to_string());\n }\n }\n continue;\n }\n if l.trim() == \"# Description\" {\n // Skip leading blank lines in description.\n while let Some(nl) = lines.peek() {\n if nl.trim().is_empty() {\n lines.next();\n } else {\n break;\n }\n }\n // Collect remainder verbatim.\n for rest in lines {\n desc_lines.push(rest.to_string());\n }\n break;\n }\n }\n\n let title = title.unwrap_or_default().trim().to_string();\n if title.is_empty() {\n bail!(\"missing PR title in edit file (expected a non-empty line under `# Title`)\");\n }\n let body = desc_lines.join(\"\\n\").trim_end().to_string();\n Ok((title, body))\n}\n\nfn render_pr_edit_markdown(title: &str, body: &str) -> String {\n let mut out = String::new();\n out.push_str(\"# Title\\n\\n\");\n out.push_str(title.trim());\n out.push_str(\"\\n\\n# Description\\n\\n\");\n out.push_str(body.trim_end());\n out.push('\\n');\n out\n}\n\nfn render_pr_edit_markdown_with_frontmatter(\n repo: &str,\n number: u64,\n title: &str,\n body: &str,\n) -> String {\n let mut out = String::new();\n out.push_str(\"---\\n\");\n out.push_str(\"repo: \");\n out.push_str(repo.trim());\n out.push('\\n');\n out.push_str(\"pr: \");\n out.push_str(&number.to_string());\n out.push_str(\"\\n---\\n\\n\");\n out.push_str(&render_pr_edit_markdown(title, body));\n out\n}\n\nfn strip_existing_frontmatter(text: &str) -> &str {\n // If the file starts with a YAML frontmatter block, strip it so we can replace/insert ours.\n // Frontmatter:\n // ---\n // ...\n // ---\n let mut lines = text.lines();\n let Some(first) = lines.next() else {\n return text;\n };\n if first.trim() != \"---\" {\n return text;\n }\n let mut idx = first.len() + 1; // include newline\n for line in lines {\n idx += line.len() + 1;\n if line.trim() == \"---\" {\n break;\n }\n }\n // Skip trailing blank line(s) after frontmatter.\n let remainder = &text[idx..];\n remainder.trim_start_matches('\\n')\n}\n\nfn ensure_pr_edit_frontmatter(path: &Path, repo: &str, number: u64) -> Result<()> {\n use std::fs;\n let existing = fs::read_to_string(path).unwrap_or_default();\n let remainder = strip_existing_frontmatter(&existing);\n let rendered = format!(\n \"---\\nrepo: {}\\npr: {}\\n---\\n\\n{}\",\n repo.trim(),\n number,\n remainder.trim_start()\n );\n if rendered != existing {\n fs::write(path, rendered)?;\n }\n Ok(())\n}\n\nfn gh_pr_edit(repo_root: &Path, repo: &str, number: u64, title: &str, body: &str) -> Result<()> {\n use std::fs;\n\n let tmp_dir = std::env::temp_dir().join(\"flow-pr-edit\");\n let _ = fs::create_dir_all(&tmp_dir);\n let patch_path = tmp_dir.join(format!(\"pr-{number}.patch.json\"));\n let normalized_body = normalize_markdown_linebreaks(body);\n let payload = serde_json::json!({\n \"title\": title,\n \"body\": normalized_body,\n });\n fs::write(&patch_path, serde_json::to_string(&payload)?)?;\n\n // Use the REST API instead of `gh pr edit` to avoid GitHub GraphQL breaking changes.\n let endpoint = format!(\"repos/{repo}/pulls/{number}\");\n let output = Command::new(\"gh\")\n .current_dir(repo_root)\n .arg(\"api\")\n .arg(\"-X\")\n .arg(\"PATCH\")\n .arg(endpoint)\n .arg(\"--input\")\n .arg(&patch_path)\n .arg(\"--silent\")\n .output()\n .context(\"failed to run gh api (PATCH pull request)\")?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n let stdout = String::from_utf8_lossy(&output.stdout);\n bail!(\"failed to update PR via GitHub API:\\n{stdout}\\n{stderr}\");\n }\n Ok(())\n}\n\nfn resolve_pr_for_open(repo_root: &Path, opts: &PrOpts) -> Result<(String, u64, String)> {\n ensure_gh_available()?;\n let repo = resolve_github_repo(repo_root)?;\n\n // Prefer opening based on the current git branch name (most intuitive UX).\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string())\n .trim()\n .to_string();\n if !branch.is_empty() && branch != \"HEAD\" {\n if let Some((n, url)) = gh_find_open_pr_by_head(repo_root, &repo, &branch)? {\n return Ok((repo, n, url));\n }\n }\n\n // Fallback: open based on queued commit (by explicit hash, by HEAD SHA, or latest entry).\n let hash = if let Some(hash) = opts.hash.clone() {\n hash\n } else {\n let head_sha = git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"])\n .unwrap_or_default()\n .trim()\n .to_string();\n let _ = refresh_commit_queue(repo_root);\n let mut entries = load_commit_queue_entries(repo_root)?;\n if entries.is_empty() {\n bail!(\"No PR found for current branch and commit queue is empty.\");\n }\n if !head_sha.is_empty() {\n if let Some(entry) = entries.iter().rev().find(|e| e.commit_sha == head_sha) {\n entry.commit_sha.clone()\n } else {\n entries.pop().unwrap().commit_sha\n }\n } else {\n entries.pop().unwrap().commit_sha\n }\n };\n\n let mut entry = resolve_commit_queue_entry(repo_root, &hash)?;\n let _ = refresh_queue_entry_commit(repo_root, &mut entry);\n\n let head = default_pr_head(&entry);\n let (number, url) = if let Some(url) = entry\n .pr_url\n .as_deref()\n .map(|s| s.trim())\n .filter(|s| !s.is_empty())\n .map(|s| s.to_string())\n {\n let n = entry\n .pr_number\n .or_else(|| pr_number_from_url(&url))\n .unwrap_or(0);\n if n > 0 {\n (n, url)\n } else if let Some((n, u)) = gh_find_open_pr_by_head(repo_root, &repo, &head)? {\n (n, u)\n } else {\n // If URL exists but we can't parse number or find by head, re-create is risky; just fail.\n bail!(\"found PR url in queue entry but could not resolve PR number\");\n }\n } else if let Some((n, u)) = gh_find_open_pr_by_head(repo_root, &repo, &head)? {\n (n, u)\n } else {\n // Create it if missing (as draft).\n let gh_head = ensure_pr_head_pushed(repo_root, &head, &entry.commit_sha)?;\n let (title, body_rest) = commit_message_title_body(&entry.message);\n let (n, u) = if let Some(found) = gh_find_open_pr_by_head(repo_root, &repo, &gh_head)? {\n found\n } else {\n gh_create_pr(\n repo_root,\n &repo,\n &gh_head,\n &opts.base,\n &title,\n body_rest.trim(),\n true,\n )?\n };\n entry.pr_number = Some(n);\n entry.pr_url = Some(u.clone());\n entry.pr_head = Some(head.clone());\n entry.pr_base = Some(opts.base.clone());\n let _ = write_commit_queue_entry(repo_root, &entry);\n (n, u)\n };\n\n Ok((repo, number, url))\n}\n\nfn run_pr_open_edit(repo_root: &Path, opts: &PrOpts) -> Result<()> {\n use ::notify::RecursiveMode;\n use notify_debouncer_mini::new_debouncer;\n use std::fs;\n use std::sync::mpsc;\n use std::time::Duration;\n\n let (repo, number, url) = resolve_pr_for_open(repo_root, opts)?;\n let current = gh_pr_view(repo_root, &repo, number)?;\n\n let project = flow_project_name(repo_root);\n let home = dirs::home_dir().context(\"could not resolve home directory\")?;\n let edit_dir = home.join(\".flow\").join(\"pr-edit\");\n fs::create_dir_all(&edit_dir)?;\n let edit_path = edit_dir.join(format!(\"{project}-{number}.md\"));\n\n if !edit_path.exists() {\n let rendered =\n render_pr_edit_markdown_with_frontmatter(&repo, number, ¤t.title, ¤t.body);\n fs::write(&edit_path, rendered)?;\n } else {\n // Backfill frontmatter for older files so the always-on daemon can sync them.\n let _ = ensure_pr_edit_frontmatter(&edit_path, &repo, number);\n }\n\n // Register a sidecar mapping too (useful if users delete the frontmatter).\n let _ = crate::pr_edit::index_upsert_file(&edit_path, &repo, number);\n\n println!(\"PR: {url}\");\n if !opts.no_open {\n let _ = open_in_browser(&url);\n }\n\n open_in_zed_preview(&edit_path)?;\n println!(\n \"Editing {} (save to sync to GitHub, Ctrl-C to stop)\",\n edit_path.display()\n );\n\n // Seed hash so the initial file creation/open doesn't immediately trigger an API update.\n let mut last_hash: Option<String> = fs::read_to_string(&edit_path).ok().map(|text| {\n let mut hasher = std::collections::hash_map::DefaultHasher::new();\n use std::hash::Hash;\n use std::hash::Hasher;\n text.hash(&mut hasher);\n format!(\"{:x}\", hasher.finish())\n });\n let (event_tx, event_rx) = mpsc::channel();\n let mut debouncer = new_debouncer(Duration::from_millis(250), event_tx)\n .context(\"failed to initialize file watcher\")?;\n debouncer\n .watcher()\n .watch(\n edit_path.parent().unwrap_or(repo_root).as_ref(),\n RecursiveMode::NonRecursive,\n )\n .with_context(|| format!(\"failed to watch {}\", edit_path.display()))?;\n\n loop {\n match event_rx.recv() {\n Ok(Ok(events)) => {\n let touched = events.iter().any(|e| e.path == edit_path);\n if !touched {\n continue;\n }\n let Ok(text) = fs::read_to_string(&edit_path) else {\n continue;\n };\n // Lightweight dedupe to avoid re-sending on editor temp writes.\n let mut hasher = std::collections::hash_map::DefaultHasher::new();\n use std::hash::Hash;\n use std::hash::Hasher;\n text.hash(&mut hasher);\n let h = format!(\"{:x}\", hasher.finish());\n if last_hash.as_deref() == Some(&h) {\n continue;\n }\n last_hash = Some(h);\n\n match parse_pr_edit_markdown(&text) {\n Ok((title, body)) => {\n if let Err(err) = gh_pr_edit(repo_root, &repo, number, &title, &body) {\n eprintln!(\"Failed to update PR #{number}: {err:#}\");\n } else {\n println!(\"✓ Updated PR #{number}\");\n }\n }\n Err(err) => {\n eprintln!(\"Skipped update: {err:#}\");\n }\n }\n }\n Ok(Err(err)) => {\n eprintln!(\"watcher error: {err:?}\");\n }\n Err(_) => break,\n }\n }\n\n Ok(())\n}\n\nfn format_queue_created_at(ts: &str) -> String {\n if ts.trim().is_empty() {\n return \"unknown\".to_string();\n }\n\n let parsed = chrono::DateTime::parse_from_rfc3339(ts).or_else(|_| {\n chrono::NaiveDateTime::parse_from_str(ts, \"%Y-%m-%dT%H:%M:%S%.fZ\")\n .map(|dt| dt.and_utc().fixed_offset())\n });\n\n let Ok(dt) = parsed else {\n return ts.to_string();\n };\n\n let now = chrono::Utc::now();\n let duration = now.signed_duration_since(dt);\n let seconds = duration.num_seconds();\n if seconds < 0 {\n return \"just now\".to_string();\n }\n\n let minutes = duration.num_minutes();\n let hours = duration.num_hours();\n let days = duration.num_days();\n let weeks = days / 7;\n\n if seconds < 60 {\n \"just now\".to_string()\n } else if minutes < 60 {\n format!(\"{}m ago\", minutes)\n } else if hours < 24 {\n format!(\"{}h ago\", hours)\n } else if days == 1 {\n \"yesterday\".to_string()\n } else if days < 7 {\n format!(\"{}d ago\", days)\n } else if weeks < 4 {\n format!(\"{}w ago\", weeks)\n } else {\n dt.format(\"%b %d\").to_string()\n }\n}\n\nfn get_openai_key() -> Result<String> {\n std::env::var(\"OPENAI_API_KEY\").context(\"OPENAI_API_KEY environment variable not set\")\n}\n\n#[derive(Debug, Clone)]\nenum CommitMessageProvider {\n OpenAi { api_key: String },\n Remote { api_url: String, token: String },\n}\n\n#[derive(Debug, Clone)]\nenum CommitMessageOverride {\n Selection(CommitMessageSelection),\n}\n\nfn parse_commit_message_override(\n tool: &str,\n model: Option<String>,\n) -> Option<CommitMessageOverride> {\n parse_commit_message_selection_with_model(tool, model).map(CommitMessageOverride::Selection)\n}\n\nfn resolve_commit_message_override(repo_root: &Path) -> Option<CommitMessageOverride> {\n // TypeScript config has highest priority.\n if let Some(ts_config) = config::load_ts_config() {\n if let Some(flow) = ts_config.flow {\n if let Some(commit) = flow.commit {\n if let Some(tool) = commit.message_tool {\n return parse_commit_message_override(&tool, commit.message_model);\n }\n }\n }\n }\n\n // Local flow.toml\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(commit_cfg) = cfg.commit.as_ref() {\n if let Some(tool) = commit_cfg.message_tool.as_deref() {\n return parse_commit_message_override(tool, commit_cfg.message_model.clone());\n }\n }\n }\n }\n\n // Global flow config\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n if let Some(commit_cfg) = cfg.commit.as_ref() {\n if let Some(tool) = commit_cfg.message_tool.as_deref() {\n return parse_commit_message_override(tool, commit_cfg.message_model.clone());\n }\n }\n }\n }\n\n None\n}\n\nfn resolve_commit_message_providers() -> Vec<CommitMessageProvider> {\n let mut providers = Vec::new();\n\n if let Ok(Some(token)) = crate::env::load_ai_auth_token() {\n if let Ok(api_url) = crate::env::load_ai_api_url() {\n let trimmed_url = api_url.trim().trim_end_matches('/').to_string();\n if !trimmed_url.is_empty() {\n providers.push(CommitMessageProvider::Remote {\n api_url: trimmed_url,\n token,\n });\n }\n }\n }\n\n if let Ok(api_key) = get_openai_key() {\n let trimmed = api_key.trim().to_string();\n if !trimmed.is_empty() {\n providers.push(CommitMessageProvider::OpenAi { api_key: trimmed });\n }\n }\n\n providers\n}\n\nfn commit_message_from_provider(\n provider: &CommitMessageProvider,\n diff: &str,\n status: &str,\n truncated: bool,\n) -> Result<String> {\n let message = match provider {\n CommitMessageProvider::OpenAi { api_key } => {\n generate_commit_message(api_key, diff, status, truncated)\n }\n CommitMessageProvider::Remote { api_url, token } => {\n generate_commit_message_remote(api_url, token, diff, status, truncated)\n }\n }?;\n Ok(sanitize_commit_message(&message))\n}\n\nfn commit_message_from_selection(\n selection: &CommitMessageSelection,\n providers: &[CommitMessageProvider],\n diff: &str,\n status: &str,\n truncated: bool,\n) -> Result<String> {\n match selection {\n CommitMessageSelection::Kimi { model } => {\n generate_commit_message_kimi(diff, status, truncated, model.as_deref())\n }\n CommitMessageSelection::Claude => generate_commit_message_claude(diff, status, truncated),\n CommitMessageSelection::Opencode { model } => {\n generate_commit_message_opencode(diff, status, truncated, model)\n }\n CommitMessageSelection::OpenRouter { model } => {\n generate_commit_message_openrouter(diff, status, truncated, model)\n }\n CommitMessageSelection::Rise { model } => {\n generate_commit_message_rise(diff, status, truncated, model)\n }\n CommitMessageSelection::Remote => {\n let provider = providers\n .iter()\n .find(|provider| matches!(provider, CommitMessageProvider::Remote { .. }))\n .ok_or_else(|| anyhow!(\"myflow provider unavailable; run `f auth`\"))?;\n commit_message_from_provider(provider, diff, status, truncated)\n }\n CommitMessageSelection::OpenAi => {\n let provider = providers\n .iter()\n .find(|provider| matches!(provider, CommitMessageProvider::OpenAi { .. }))\n .ok_or_else(|| anyhow!(\"OPENAI_API_KEY is not configured\"))?;\n commit_message_from_provider(provider, diff, status, truncated)\n }\n CommitMessageSelection::Heuristic => Ok(build_deterministic_commit_message(diff)),\n }\n}\n\nfn truncate_commit_subject(subject: &str) -> String {\n if subject.chars().count() <= 72 {\n return subject.to_string();\n }\n let mut truncated: String = subject.chars().take(69).collect();\n while truncated.ends_with(' ') {\n truncated.pop();\n }\n format!(\"{}...\", truncated)\n}\n\nfn build_deterministic_commit_message(diff: &str) -> String {\n let mut files = changed_files_from_diff(diff);\n files.sort();\n files.dedup();\n\n let subject = if files.is_empty() {\n \"Update project files\".to_string()\n } else if files.len() == 1 {\n format!(\"Update {}\", files[0])\n } else {\n format!(\"Update {} files\", files.len())\n };\n let subject = truncate_commit_subject(&subject);\n\n if files.is_empty() {\n return subject;\n }\n\n let mut lines = Vec::new();\n for file in files.iter().take(3) {\n lines.push(format!(\"- {}\", file));\n }\n if files.len() > 3 {\n lines.push(format!(\"- and {} more files\", files.len() - 3));\n }\n\n if lines.is_empty() {\n subject\n } else {\n format!(\"{}\\n\\n{}\", subject, lines.join(\"\\n\"))\n }\n}\n\nfn generate_commit_message_with_fallbacks(\n repo_root: &Path,\n review_selection: Option<&ReviewSelection>,\n commit_message_override: Option<&CommitMessageOverride>,\n diff: &str,\n status: &str,\n truncated: bool,\n) -> Result<String> {\n let providers = resolve_commit_message_providers();\n let override_selection = commit_message_override.map(|override_tool| match override_tool {\n CommitMessageOverride::Selection(selection) => selection,\n });\n let attempts = commit_message_attempts(repo_root, review_selection, override_selection);\n\n let mut errors: Vec<String> = Vec::new();\n for (idx, selection) in attempts.iter().enumerate() {\n match commit_message_from_selection(selection, &providers, diff, status, truncated) {\n Ok(message) => {\n let sanitized = sanitize_commit_message(&message);\n if sanitized.trim().is_empty() {\n errors.push(format!(\n \"{} returned an empty commit message\",\n selection.key()\n ));\n continue;\n }\n if idx > 0 {\n println!(\n \"✓ Commit message fallback succeeded via {}\",\n selection.label()\n );\n }\n return Ok(sanitized);\n }\n Err(err) => {\n if idx + 1 < attempts.len() {\n println!(\n \"⚠ {} commit message failed: {}. Trying next fallback...\",\n selection.label(),\n err\n );\n }\n errors.push(format!(\"{}: {}\", selection.key(), err));\n }\n }\n }\n\n if commit_message_fail_open_enabled(repo_root) {\n println!(\"⚠ Commit message generation failed; using deterministic fallback message.\");\n return Ok(build_deterministic_commit_message(diff));\n }\n\n if errors.is_empty() {\n bail!(\n \"commit message generation failed: no valid tools/providers configured for this repo\"\n );\n }\n\n bail!(\n \"commit message generation failed:\\n {}\",\n errors.join(\"\\n \")\n )\n}\n\nfn sanitize_commit_message(message: &str) -> String {\n let filtered: Vec<&str> = message\n .lines()\n .filter(|line| !line.trim().contains(\"[Image #\"))\n .collect();\n\n let cleaned = filtered.join(\"\\n\").trim().to_string();\n if cleaned.is_empty() {\n return message.trim().to_string();\n }\n cleaned\n}\n\nfn generate_commit_message_kimi(\n diff: &str,\n status: &str,\n truncated: bool,\n model: Option<&str>,\n) -> Result<String> {\n let mut prompt = String::from(\n \"Write a git commit message for these changes. Output ONLY the commit message, nothing else.\\n\\n\\\n Guidelines:\\n\\\n - Use imperative mood (\\\"Add feature\\\" not \\\"Added feature\\\")\\n\\\n - First line: concise summary under 72 chars\\n\\\n - Focus on WHAT and WHY, not just listing files\\n\\\n - Never include secrets or credentials\\n\\n\\\n Git diff:\\n\",\n );\n prompt.push_str(diff);\n\n if truncated {\n prompt.push_str(\"\\n\\n[Diff truncated]\");\n }\n\n let status = status.trim();\n if !status.is_empty() {\n prompt.push_str(\"\\n\\nGit status:\\n\");\n prompt.push_str(status);\n }\n\n info!(\n model = model.unwrap_or(\"default\"),\n prompt_len = prompt.len(),\n \"calling kimi for commit message\"\n );\n\n let mut cmd = Command::new(\"kimi\");\n cmd.args([\"--quiet\"]);\n if let Some(model) = model {\n if !model.trim().is_empty() {\n cmd.args([\"--model\", model]);\n }\n }\n cmd.stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .stderr(Stdio::piped());\n\n let mut child = cmd\n .spawn()\n .context(\"failed to run kimi for commit message\")?;\n\n if let Some(mut stdin) = child.stdin.take() {\n stdin\n .write_all(prompt.as_bytes())\n .context(\"failed to write prompt to kimi\")?;\n }\n\n let output = child\n .wait_with_output()\n .context(\"failed to wait for kimi output\")?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n let stdout = String::from_utf8_lossy(&output.stdout);\n let error_msg = if stderr.trim().is_empty() {\n stdout.trim()\n } else {\n stderr.trim()\n };\n bail!(\"kimi failed: {}\", error_msg);\n }\n\n let message = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if message.is_empty() {\n bail!(\"kimi returned empty commit message\");\n }\n\n Ok(message)\n}\n\nfn git_run(args: &[&str]) -> Result<()> {\n let mut cmd = Command::new(\"git\");\n if args.first() == Some(&\"commit\") {\n cmd.env(\"FLOW_COMMIT\", \"1\");\n if entire_enabled() {\n cmd.env(\"ENTIRE_TEST_TTY\", \"1\");\n }\n }\n let status = cmd\n .args(args)\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n\n if !status.success() {\n bail!(\"git {} failed with status {}\", args.join(\" \"), status);\n }\n Ok(())\n}\n\nfn git_run_in(workdir: &std::path::Path, args: &[&str]) -> Result<()> {\n let mut cmd = Command::new(\"git\");\n if args.first() == Some(&\"commit\") {\n cmd.env(\"FLOW_COMMIT\", \"1\");\n if entire_enabled() {\n cmd.env(\"ENTIRE_TEST_TTY\", \"1\");\n }\n }\n let status = cmd\n .current_dir(workdir)\n .args(args)\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n\n if !status.success() {\n bail!(\"git {} failed with status {}\", args.join(\" \"), status);\n }\n Ok(())\n}\n\n/// Try to run a git command, returning Ok/Err without bailing.\nfn git_try(args: &[&str]) -> Result<()> {\n let status = Command::new(\"git\")\n .args(args)\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n\n if !status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n Ok(())\n}\n\n/// Push result indicating success, remote ahead, or no remote repo.\nenum PushResult {\n Success,\n RemoteAhead,\n NoRemoteRepo,\n}\n\nfn branch_is_detached(branch: &str) -> bool {\n let trimmed = branch.trim();\n trimmed.is_empty() || trimmed == \"HEAD\"\n}\n\nfn git_push_args<'a>(remote: &'a str, branch: &'a str) -> Vec<&'a str> {\n if branch_is_detached(branch) {\n vec![\"push\", remote, \"HEAD\"]\n } else {\n vec![\"push\", \"-u\", remote, branch.trim()]\n }\n}\n\nfn git_pull_rebase_args<'a>(remote: &'a str, branch: &'a str) -> Vec<&'a str> {\n if branch_is_detached(branch) {\n vec![\"pull\", \"--rebase\"]\n } else {\n vec![\"pull\", \"--rebase\", remote, branch.trim()]\n }\n}\n\nfn git_push_run(remote: &str, branch: &str) -> Result<()> {\n let args = git_push_args(remote, branch);\n git_run(&args)\n}\n\nfn git_push_run_in(workdir: &std::path::Path, remote: &str, branch: &str) -> Result<()> {\n let args = git_push_args(remote, branch);\n git_run_in(workdir, &args)\n}\n\nfn git_pull_rebase_try(remote: &str, branch: &str) -> Result<()> {\n let args = git_pull_rebase_args(remote, branch);\n git_try(&args)\n}\n\nfn git_pull_rebase_try_in(workdir: &std::path::Path, remote: &str, branch: &str) -> Result<()> {\n let args = git_pull_rebase_args(remote, branch);\n git_try_in(workdir, &args)\n}\n\n/// Try to push and detect if failure is due to missing remote repo.\nfn git_push_try(remote: &str, branch: &str) -> PushResult {\n let args = git_push_args(remote, branch);\n let output = Command::new(\"git\").args(args).output().ok();\n\n let Some(output) = output else {\n return PushResult::RemoteAhead;\n };\n\n if output.status.success() {\n return PushResult::Success;\n }\n\n let stderr = String::from_utf8_lossy(&output.stderr).to_lowercase();\n if stderr.contains(\"repository not found\")\n || stderr.contains(\"does not exist\")\n || stderr.contains(\"could not read from remote\")\n {\n PushResult::NoRemoteRepo\n } else {\n PushResult::RemoteAhead\n }\n}\n\nfn git_push_try_in(workdir: &std::path::Path, remote: &str, branch: &str) -> PushResult {\n let args = git_push_args(remote, branch);\n let output = Command::new(\"git\")\n .current_dir(workdir)\n .args(args)\n .output()\n .ok();\n\n let Some(output) = output else {\n return PushResult::RemoteAhead;\n };\n\n if output.status.success() {\n return PushResult::Success;\n }\n\n let stderr = String::from_utf8_lossy(&output.stderr).to_lowercase();\n if stderr.contains(\"repository not found\")\n || stderr.contains(\"does not exist\")\n || stderr.contains(\"could not read from remote\")\n {\n PushResult::NoRemoteRepo\n } else {\n PushResult::RemoteAhead\n }\n}\n\nfn git_try_in(workdir: &std::path::Path, args: &[&str]) -> Result<()> {\n let status = Command::new(\"git\")\n .current_dir(workdir)\n .args(args)\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n\n if !status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n Ok(())\n}\n\n#[derive(Default)]\nstruct GitCaptureCacheState {\n depth: usize,\n entries: HashMap<String, String>,\n}\n\nthread_local! {\n static GIT_CAPTURE_CACHE: RefCell<GitCaptureCacheState> = RefCell::new(GitCaptureCacheState::default());\n}\n\nstruct GitCaptureCacheScope;\n\nimpl GitCaptureCacheScope {\n fn begin() -> Self {\n GIT_CAPTURE_CACHE.with(|state| {\n let mut state = state.borrow_mut();\n if state.depth == 0 {\n state.entries.clear();\n }\n state.depth += 1;\n });\n Self\n }\n}\n\nimpl Drop for GitCaptureCacheScope {\n fn drop(&mut self) {\n GIT_CAPTURE_CACHE.with(|state| {\n let mut state = state.borrow_mut();\n state.depth = state.depth.saturating_sub(1);\n if state.depth == 0 {\n state.entries.clear();\n }\n });\n }\n}\n\nfn git_capture_cacheable(args: &[&str]) -> bool {\n args == [\"rev-parse\", \"--show-toplevel\"]\n || args == [\"rev-parse\", \"--git-dir\"]\n || (args.len() == 3 && args[0] == \"remote\" && args[1] == \"get-url\")\n}\n\nfn git_capture_cache_key(workdir: Option<&std::path::Path>, args: &[&str]) -> Option<String> {\n if !git_capture_cacheable(args) {\n return None;\n }\n\n let cwd = workdir\n .map(|p| p.to_string_lossy().into_owned())\n .unwrap_or_default();\n Some(format!(\"{cwd}|{}\", args.join(\"\\x1f\")))\n}\n\nfn git_capture_cached_lookup(key: &str) -> Option<String> {\n GIT_CAPTURE_CACHE.with(|state| {\n let state = state.borrow();\n if state.depth == 0 {\n return None;\n }\n state.entries.get(key).cloned()\n })\n}\n\nfn git_capture_cached_store(key: String, value: String) {\n GIT_CAPTURE_CACHE.with(|state| {\n let mut state = state.borrow_mut();\n if state.depth > 0 {\n state.entries.insert(key, value);\n }\n });\n}\n\nfn git_capture(args: &[&str]) -> Result<String> {\n if let Some(key) = git_capture_cache_key(None, args) {\n if let Some(cached) = git_capture_cached_lookup(&key) {\n return Ok(cached);\n }\n }\n\n let output = Command::new(\"git\")\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n\n if !output.status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n\n let out = String::from_utf8_lossy(&output.stdout).to_string();\n if let Some(key) = git_capture_cache_key(None, args) {\n git_capture_cached_store(key, out.clone());\n }\n Ok(out)\n}\n\nfn git_capture_in(workdir: &std::path::Path, args: &[&str]) -> Result<String> {\n if let Some(key) = git_capture_cache_key(Some(workdir), args) {\n if let Some(cached) = git_capture_cached_lookup(&key) {\n return Ok(cached);\n }\n }\n\n let output = Command::new(\"git\")\n .current_dir(workdir)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n\n if !output.status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n\n let out = String::from_utf8_lossy(&output.stdout).to_string();\n if let Some(key) = git_capture_cache_key(Some(workdir), args) {\n git_capture_cached_store(key, out.clone());\n }\n Ok(out)\n}\n\n/// Find the largest valid UTF-8 char boundary at or before `pos`.\nfn floor_char_boundary(s: &str, pos: usize) -> usize {\n let mut end = pos.min(s.len());\n while end > 0 && !s.is_char_boundary(end) {\n end -= 1;\n }\n end\n}\n\nfn truncate_diff(diff: &str) -> (String, bool) {\n if diff.len() <= MAX_DIFF_CHARS {\n (diff.to_string(), false)\n } else {\n let end = floor_char_boundary(diff, MAX_DIFF_CHARS);\n let truncated = format!(\n \"{}\\n\\n[Diff truncated to first {} characters]\",\n &diff[..end],\n end\n );\n (truncated, true)\n }\n}\n\nfn truncate_context(context: &str, max_chars: usize) -> String {\n if context.len() <= max_chars {\n context.to_string()\n } else {\n let end = floor_char_boundary(context, max_chars);\n format!(\n \"{}\\n\\n[Context truncated to first {} characters]\",\n &context[..end],\n end\n )\n }\n}\n\n/// Generate commit message using opencode or OpenRouter directly.\n#[allow(dead_code)]\nfn generate_commit_message_opencode(\n diff: &str,\n status: &str,\n truncated: bool,\n model: &str,\n) -> Result<String> {\n // For OpenRouter models, call API directly to avoid tool use issues\n if model.starts_with(\"openrouter/\") {\n return generate_commit_message_openrouter(diff, status, truncated, model);\n }\n\n // For zen models (and others), use opencode run with --print flag\n generate_commit_message_opencode_run(diff, status, truncated, model)\n}\n\n/// Generate commit message using opencode run command.\nfn generate_commit_message_opencode_run(\n diff: &str,\n status: &str,\n truncated: bool,\n model: &str,\n) -> Result<String> {\n let mut prompt = String::from(\n \"Write a git commit message for these changes. Output ONLY the commit message, nothing else.\\n\\n\\\n Guidelines:\\n\\\n - Use imperative mood (\\\"Add feature\\\" not \\\"Added feature\\\")\\n\\\n - First line: concise summary under 72 chars\\n\\\n - Focus on WHAT and WHY, not just listing files\\n\\n\\\n Git diff:\\n\",\n );\n prompt.push_str(diff);\n\n if truncated {\n prompt.push_str(\"\\n\\n[Diff truncated]\");\n }\n\n let status = status.trim();\n if !status.is_empty() {\n prompt.push_str(\"\\n\\nGit status:\\n\");\n prompt.push_str(status);\n }\n\n info!(\n model = model,\n prompt_len = prompt.len(),\n \"calling opencode run for commit message\"\n );\n let start = std::time::Instant::now();\n\n // Use --format json to get output in non-interactive mode\n let output = Command::new(\"opencode\")\n .args([\"run\", \"--model\", model, \"--format\", \"json\", &prompt])\n .output()\n .context(\"failed to run opencode for commit message\")?;\n\n info!(\n elapsed_ms = start.elapsed().as_millis() as u64,\n success = output.status.success(),\n stdout_len = output.stdout.len(),\n stderr_len = output.stderr.len(),\n \"opencode run completed\"\n );\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n let stdout = String::from_utf8_lossy(&output.stdout);\n let error_msg = if stderr.trim().is_empty() {\n stdout.trim()\n } else {\n stderr.trim()\n };\n bail!(\"opencode failed: {}\", error_msg);\n }\n\n // Parse JSON lines to extract text content\n let stdout = String::from_utf8_lossy(&output.stdout);\n let mut message = String::new();\n for line in stdout.lines() {\n if let Ok(json) = serde_json::from_str::<serde_json::Value>(line) {\n if json.get(\"type\").and_then(|t| t.as_str()) == Some(\"text\") {\n if let Some(text) = json\n .get(\"part\")\n .and_then(|p| p.get(\"text\"))\n .and_then(|t| t.as_str())\n {\n message.push_str(text);\n }\n }\n }\n }\n\n let message = message.trim().to_string();\n if message.is_empty() {\n bail!(\"opencode returned empty commit message\");\n }\n\n Ok(trim_quotes(&message))\n}\n\n/// Generate commit message using Claude Code CLI.\nfn generate_commit_message_claude(diff: &str, status: &str, truncated: bool) -> Result<String> {\n let mut prompt = String::from(\n \"Write a git commit message for these changes. Output ONLY the commit message, nothing else.\\n\\n\\\n Guidelines:\\n\\\n - Use imperative mood (\\\"Add feature\\\" not \\\"Added feature\\\")\\n\\\n - First line: concise summary under 72 chars\\n\\\n - Focus on WHAT and WHY, not just listing files\\n\\n\\\n Git diff:\\n\",\n );\n prompt.push_str(diff);\n\n if truncated {\n prompt.push_str(\"\\n\\n[Diff truncated]\");\n }\n\n let status = status.trim();\n if !status.is_empty() {\n prompt.push_str(\"\\n\\nGit status:\\n\");\n prompt.push_str(status);\n }\n\n let output = Command::new(\"claude\")\n .args([\"-p\", &prompt])\n .output()\n .context(\"failed to run claude for commit message\")?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"claude failed: {}\", stderr.trim());\n }\n\n let message = String::from_utf8_lossy(&output.stdout).trim().to_string();\n\n if message.is_empty() {\n bail!(\"claude returned empty commit message\");\n }\n\n Ok(trim_quotes(&message))\n}\n\n/// Generate commit message using Rise daemon (local AI proxy).\nfn generate_commit_message_rise(\n diff: &str,\n status: &str,\n truncated: bool,\n model: &str,\n) -> Result<String> {\n let mut user_prompt =\n String::from(\"Write a git commit message for the staged changes.\\n\\nGit diff:\\n\");\n user_prompt.push_str(diff);\n\n if truncated {\n user_prompt.push_str(\"\\n\\n[Diff truncated]\");\n }\n\n let status = status.trim();\n if !status.is_empty() {\n user_prompt.push_str(\"\\n\\nGit status:\\n\");\n user_prompt.push_str(status);\n }\n\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(120))\n .context(\"failed to create HTTP client\")?;\n\n let body = ChatRequest {\n model: model.to_string(),\n messages: vec![\n Message {\n role: \"system\".to_string(),\n content: SYSTEM_PROMPT.to_string(),\n },\n Message {\n role: \"user\".to_string(),\n content: user_prompt,\n },\n ],\n temperature: 0.3,\n };\n\n info!(model = model, \"calling Rise daemon for commit message\");\n let start = std::time::Instant::now();\n\n let rise_url = rise_url();\n let text = send_rise_request_text(&client, &rise_url, &body, model)?;\n\n info!(\n elapsed_ms = start.elapsed().as_millis() as u64,\n \"Rise daemon responded\"\n );\n let message = parse_rise_output(&text).context(\"failed to parse Rise response\")?;\n\n let message = message.trim().to_string();\n if message.is_empty() {\n bail!(\"Rise daemon returned empty commit message\");\n }\n\n Ok(trim_quotes(&message))\n}\n\n/// Generate commit message using OpenRouter API directly.\nfn generate_commit_message_openrouter(\n diff: &str,\n status: &str,\n truncated: bool,\n model: &str,\n) -> Result<String> {\n let api_key = openrouter_api_key()?;\n let model_id = openrouter_model_id(model);\n\n let mut user_prompt =\n String::from(\"Write a git commit message for the staged changes.\\n\\nGit diff:\\n\");\n user_prompt.push_str(diff);\n\n if truncated {\n user_prompt.push_str(\"\\n\\n[Diff truncated]\");\n }\n\n let status = status.trim();\n if !status.is_empty() {\n user_prompt.push_str(\"\\n\\nGit status:\\n\");\n user_prompt.push_str(status);\n }\n\n let client = openrouter_http_client(Duration::from_secs(60))?;\n\n let body = ChatRequest {\n model: model_id.to_string(),\n messages: vec![\n Message {\n role: \"system\".to_string(),\n content: SYSTEM_PROMPT.to_string(),\n },\n Message {\n role: \"user\".to_string(),\n content: user_prompt,\n },\n ],\n temperature: 0.3,\n };\n\n let parsed: ChatResponse = openrouter_chat_completion_with_retry(&client, &api_key, &body)\n .context(\"OpenRouter request failed\")?;\n\n let message = parsed\n .choices\n .first()\n .and_then(|c| c.message.as_ref())\n .map(|m| m.content.trim().to_string())\n .unwrap_or_default();\n\n if message.is_empty() {\n bail!(\"OpenRouter returned empty commit message\");\n }\n\n Ok(trim_quotes(&message))\n}\n\nfn generate_commit_message(\n api_key: &str,\n diff: &str,\n status: &str,\n truncated: bool,\n) -> Result<String> {\n let mut user_prompt =\n String::from(\"Write a git commit message for the staged changes.\\n\\nGit diff:\\n\");\n user_prompt.push_str(diff);\n\n if truncated {\n user_prompt.push_str(\"\\n\\n[Diff truncated to fit within prompt]\");\n }\n\n let status = status.trim();\n if !status.is_empty() {\n user_prompt.push_str(\"\\n\\nGit status --short:\\n\");\n user_prompt.push_str(status);\n }\n\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(60))\n .context(\"failed to create HTTP client\")?;\n\n let body = ChatRequest {\n model: MODEL.to_string(),\n messages: vec![\n Message {\n role: \"system\".to_string(),\n content: SYSTEM_PROMPT.to_string(),\n },\n Message {\n role: \"user\".to_string(),\n content: user_prompt,\n },\n ],\n temperature: 0.3,\n };\n\n // Retry logic for transient failures\n const MAX_RETRIES: u32 = 3;\n let mut last_error = None;\n\n for attempt in 0..MAX_RETRIES {\n if attempt > 0 {\n let delay = Duration::from_secs(2u64.pow(attempt));\n print!(\"Retrying in {}s... \", delay.as_secs());\n io::stdout().flush().ok();\n std::thread::sleep(delay);\n }\n\n match client\n .post(\"https://api.openai.com/v1/chat/completions\")\n .header(\"Authorization\", format!(\"Bearer {}\", api_key))\n .json(&body)\n .send()\n {\n Ok(resp) => {\n if !resp.status().is_success() {\n let status = resp.status();\n let text = resp.text().unwrap_or_default();\n // Don't retry client errors (4xx)\n if status.is_client_error() {\n bail!(\"OpenAI API error {}: {}\", status, text);\n }\n last_error = Some(format!(\"OpenAI API error {}: {}\", status, text));\n continue;\n }\n\n let parsed: ChatResponse =\n resp.json().context(\"failed to parse OpenAI response\")?;\n\n let message = parsed\n .choices\n .first()\n .and_then(|c| c.message.as_ref())\n .map(|m| m.content.trim().to_string())\n .unwrap_or_default();\n\n if message.is_empty() {\n bail!(\"OpenAI returned empty commit message\");\n }\n\n return Ok(trim_quotes(&message));\n }\n Err(e) => {\n last_error = Some(format!(\"failed to call OpenAI API: {}\", e));\n if attempt < MAX_RETRIES - 1 {\n println!(\"API call failed, will retry...\");\n }\n }\n }\n }\n\n bail!(\n \"{}\",\n last_error.unwrap_or_else(|| \"OpenAI API failed after retries\".to_string())\n )\n}\n\nfn generate_commit_message_remote(\n api_url: &str,\n token: &str,\n diff: &str,\n status: &str,\n truncated: bool,\n) -> Result<String> {\n let trimmed = api_url.trim().trim_end_matches('/');\n let url = format!(\"{}/api/ai/commit-message\", trimmed);\n\n let client = crate::http_client::blocking_with_timeout(Duration::from_secs(\n commit_with_check_timeout_secs(),\n ))\n .context(\"failed to create HTTP client for remote commit message\")?;\n\n let payload = json!({\n \"diff\": diff,\n \"status\": status,\n \"truncated\": truncated,\n });\n\n let response = client\n .post(&url)\n .bearer_auth(token)\n .json(&payload)\n .send()\n .context(\"failed to request remote commit message\")?;\n\n if !response.status().is_success() {\n if response.status() == StatusCode::UNAUTHORIZED {\n bail!(\"remote commit message unauthorized. Run `f auth` to login.\");\n }\n if response.status() == StatusCode::PAYMENT_REQUIRED {\n bail!(\n \"remote commit message requires an active subscription. Visit myflow to subscribe.\"\n );\n }\n let status = response.status();\n let body = response.text().unwrap_or_default();\n bail!(\"remote commit message failed: HTTP {} {}\", status, body);\n }\n\n let payload: RemoteCommitMessageResponse = response\n .json()\n .context(\"failed to parse remote commit message response\")?;\n\n let message = payload.message.trim().to_string();\n if message.is_empty() {\n bail!(\"remote commit message was empty\");\n }\n\n Ok(trim_quotes(&message))\n}\n\nfn trim_quotes(s: &str) -> String {\n let s = s.trim();\n if s.len() >= 2 {\n let first = s.chars().next().unwrap();\n let last = s.chars().last().unwrap();\n if (first == '\"' && last == '\"') || (first == '\\'' && last == '\\'') {\n return s[1..s.len() - 1].to_string();\n }\n }\n s.to_string()\n}\n\nfn capture_staged_snapshot_in(workdir: &std::path::Path) -> Result<StagedSnapshot> {\n let staged_diff = git_capture_in(workdir, &[\"diff\", \"--cached\"])?;\n if staged_diff.trim().is_empty() {\n return Ok(StagedSnapshot { patch_path: None });\n }\n\n let mut file = NamedTempFile::new().context(\"failed to create temp file for staged diff\")?;\n file.write_all(staged_diff.as_bytes())\n .context(\"failed to write staged diff snapshot\")?;\n let path = file\n .into_temp_path()\n .keep()\n .context(\"failed to persist staged diff snapshot\")?;\n\n Ok(StagedSnapshot {\n patch_path: Some(path),\n })\n}\n\nfn restore_staged_snapshot_in(workdir: &std::path::Path, snapshot: &StagedSnapshot) -> Result<()> {\n let _ = git_try_in(workdir, &[\"reset\", \"HEAD\"]);\n if let Some(path) = &snapshot.patch_path {\n let path_str = path\n .to_str()\n .context(\"failed to convert staged snapshot path to string\")?;\n let _ = git_try_in(workdir, &[\"apply\", \"--cached\", path_str]);\n let _ = std::fs::remove_file(path);\n }\n Ok(())\n}\n\nfn cleanup_staged_snapshot(snapshot: &StagedSnapshot) {\n if let Some(path) = &snapshot.patch_path {\n let _ = std::fs::remove_file(path);\n }\n}\n\n/// Extract text content from kimi's stream-json output.\n/// Format: {\"role\":\"assistant\",\"content\":[{\"type\":\"think\",\"think\":\"...\"},{\"type\":\"text\",\"text\":\"...\"}]}\nfn extract_kimi_text_content(output: &str) -> Option<String> {\n let trimmed = output.trim();\n if trimmed.is_empty() {\n return None;\n }\n\n // Try to parse as JSON\n let json: serde_json::Value = serde_json::from_str(trimmed).ok()?;\n\n // Extract content array\n let content = json.get(\"content\")?.as_array()?;\n\n // Find the \"text\" type content and concatenate all text\n let mut text_parts = Vec::new();\n for item in content {\n if item.get(\"type\").and_then(|t| t.as_str()) == Some(\"text\") {\n if let Some(text) = item.get(\"text\").and_then(|t| t.as_str()) {\n text_parts.push(text.to_string());\n }\n }\n }\n\n if text_parts.is_empty() {\n None\n } else {\n Some(text_parts.join(\"\\n\"))\n }\n}\n\nfn normalize_future_tasks(tasks: &[String]) -> Vec<String> {\n let mut seen = HashSet::new();\n let mut normalized = Vec::new();\n for task in tasks {\n let trimmed = task.trim().trim_start_matches('-').trim();\n if trimmed.is_empty() {\n continue;\n }\n let key = trimmed.to_lowercase();\n if seen.insert(key) {\n normalized.push(trimmed.to_string());\n }\n }\n normalized\n}\n\nfn openrouter_model_id(model: &str) -> &str {\n // Only strip \"openrouter/\" prefix when there's a nested provider path\n // e.g. \"openrouter/meta-llama/llama-3.3-70b\" → \"meta-llama/llama-3.3-70b\"\n // but keep \"openrouter/pony-alpha\" as-is (first-party OpenRouter model).\n if let Some(rest) = model\n .strip_prefix(\"openrouter/\")\n .or_else(|| model.strip_prefix(\"openrouter:\"))\n {\n if rest.contains('/') {\n return rest;\n }\n }\n model\n}\n\nfn openrouter_model_label(model: &str) -> String {\n format!(\"openrouter/{}\", openrouter_model_id(model))\n}\n\nfn openrouter_api_key() -> Result<String> {\n if let Ok(value) = std::env::var(\"OPENROUTER_API_KEY\") {\n if !value.trim().is_empty() {\n return Ok(value);\n }\n }\n\n if is_local_env_backend() {\n if let Ok(vars) = crate::env::fetch_personal_env_vars(&[\"OPENROUTER_API_KEY\".to_string()]) {\n if let Some(value) = vars.get(\"OPENROUTER_API_KEY\") {\n if !value.trim().is_empty() {\n return Ok(value.clone());\n }\n }\n }\n }\n\n bail!(\"OPENROUTER_API_KEY not set. Get one at https://openrouter.ai/keys\");\n}\n\nfn parse_review_json(output: &str) -> Option<ReviewJson> {\n let trimmed = output.trim();\n if trimmed.is_empty() {\n return None;\n }\n\n if let Ok(parsed) = serde_json::from_str::<ReviewJson>(trimmed) {\n return Some(parsed);\n }\n\n let start = trimmed.find('{')?;\n let end = trimmed.rfind('}')?;\n if end <= start {\n return None;\n }\n let candidate = &trimmed[start..=end];\n serde_json::from_str::<ReviewJson>(candidate).ok()\n}\n\nfn record_review_outputs_to_beads_rust(\n repo_root: &Path,\n review: &ReviewResult,\n reviewer: &str,\n model_label: &str,\n committed_sha: Option<&str>,\n review_run_id: &str,\n) {\n if env_flag(\"FLOW_BEADS_RUST_DISABLE\") {\n return;\n }\n let beads_dir = beads_rust_beads_dir(repo_root);\n if let Err(err) = fs::create_dir_all(&beads_dir) {\n println!(\n \"⚠️ Failed to prepare repo-local beads dir {}: {}\",\n beads_dir.display(),\n err\n );\n return;\n }\n\n let project_path = repo_root.display().to_string();\n let project_name = repo_root\n .file_name()\n .map(|name| name.to_string_lossy().to_string())\n .unwrap_or_else(|| \"project\".to_string());\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string())\n .trim()\n .to_string();\n\n let sha_short = committed_sha.map(short_sha).unwrap_or(\"unknown\");\n let project_label = safe_label_value(&project_name);\n let branch_label = safe_label_value(&branch);\n let reviewer_label = safe_label_value(reviewer);\n\n let mut created = 0usize;\n\n // Snapshot bead: one per review run, always.\n match create_review_run_bead(\n &beads_dir,\n review,\n &project_path,\n &project_name,\n &branch,\n sha_short,\n reviewer,\n model_label,\n review_run_id,\n ) {\n Ok(true) => created += 1,\n Ok(false) => {}\n Err(err) => println!(\"⚠️ Failed to create review snapshot bead: {}\", err),\n }\n\n // Issue beads: one per issue in this review run.\n for issue in &review.issues {\n match create_review_issue_bead(\n &beads_dir,\n issue,\n &project_path,\n &project_name,\n &branch,\n sha_short,\n reviewer,\n model_label,\n review.summary.as_deref(),\n review_run_id,\n ) {\n Ok(true) => created += 1,\n Ok(false) => {}\n Err(err) => println!(\"⚠️ Failed to create review issue bead: {}\", err),\n }\n }\n\n // Future-task beads: one per suggestion in this review run.\n for task in &review.future_tasks {\n match create_review_future_task_bead(\n &beads_dir,\n task,\n &project_path,\n &project_label,\n &branch,\n &branch_label,\n sha_short,\n &reviewer_label,\n model_label,\n review.summary.as_deref(),\n review_run_id,\n ) {\n Ok(true) => created += 1,\n Ok(false) => {}\n Err(err) => println!(\"⚠️ Failed to create review task bead: {}\", err),\n }\n }\n\n if created > 0 {\n println!(\n \"Recorded {} review bead(s) to {}\",\n created,\n beads_dir.display()\n );\n }\n}\n\nfn create_review_run_bead(\n beads_dir: &Path,\n review: &ReviewResult,\n project_path: &str,\n project_name: &str,\n branch: &str,\n sha_short: &str,\n reviewer: &str,\n model_label: &str,\n review_run_id: &str,\n) -> Result<bool> {\n let title = format!(\"Review: {} {}\", project_name, sha_short);\n let external_ref = format!(\n \"flow-review-run:{}\",\n flow_review_item_id(review_run_id, \"run\", \"snapshot\")\n );\n let labels = format!(\n \"flow-review,review:run,task,project:{},commit:{},branch:{},reviewer:{}\",\n safe_label_value(project_name),\n sha_short,\n safe_label_value(branch),\n safe_label_value(reviewer)\n );\n\n let mut desc = String::new();\n desc.push_str(\"Review snapshot\\n\\n\");\n desc.push_str(\"Project: \");\n desc.push_str(project_path);\n desc.push_str(\"\\nBranch: \");\n desc.push_str(branch);\n desc.push_str(\"\\nCommit: \");\n desc.push_str(sha_short);\n desc.push_str(\"\\nReviewer: \");\n desc.push_str(reviewer);\n desc.push_str(\"\\nModel: \");\n desc.push_str(model_label);\n desc.push_str(\"\\nRun ID: \");\n desc.push_str(review_run_id);\n if let Some(summary) = review\n .summary\n .as_deref()\n .map(|s| s.trim())\n .filter(|s| !s.is_empty())\n {\n desc.push_str(\"\\n\\nSummary:\\n\");\n desc.push_str(summary);\n }\n if !review.issues.is_empty() {\n desc.push_str(\"\\n\\nIssues:\\n\");\n for issue in &review.issues {\n desc.push_str(\"- \");\n desc.push_str(issue.trim());\n desc.push('\\n');\n }\n }\n if !review.future_tasks.is_empty() {\n desc.push_str(\"\\nFuture tasks:\\n\");\n for task in &review.future_tasks {\n desc.push_str(\"- \");\n desc.push_str(task.trim());\n desc.push('\\n');\n }\n }\n if review.timed_out {\n desc.push_str(\"\\nNote: Review timed out.\\n\");\n }\n\n br_create_ephemeral(\n beads_dir,\n &title,\n &desc,\n \"task\",\n \"4\",\n \"open\",\n &external_ref,\n &labels,\n )\n .context(\"run br create for review snapshot\")\n}\n\nfn create_review_issue_bead(\n beads_dir: &Path,\n issue: &str,\n project_path: &str,\n project_name: &str,\n branch: &str,\n sha_short: &str,\n reviewer: &str,\n model_label: &str,\n summary: Option<&str>,\n review_run_id: &str,\n) -> Result<bool> {\n let title = review_task_title(issue);\n let external_ref = format!(\n \"flow-review-issue:{}\",\n flow_review_item_id(review_run_id, \"issue\", issue)\n );\n let labels = format!(\n \"flow-review,review:issue,bug,project:{},commit:{},branch:{},reviewer:{}\",\n safe_label_value(project_name),\n sha_short,\n safe_label_value(branch),\n safe_label_value(reviewer)\n );\n let priority = infer_review_bead_priority(issue).to_string();\n\n let mut desc = String::new();\n desc.push_str(issue.trim());\n desc.push_str(\"\\n\\nProject: \");\n desc.push_str(project_path);\n desc.push_str(\"\\nBranch: \");\n desc.push_str(branch);\n desc.push_str(\"\\nCommit: \");\n desc.push_str(sha_short);\n desc.push_str(\"\\nReviewer: \");\n desc.push_str(reviewer);\n desc.push_str(\"\\nModel: \");\n desc.push_str(model_label);\n desc.push_str(\"\\nRun ID: \");\n desc.push_str(review_run_id);\n if let Some(summary) = summary.map(|s| s.trim()).filter(|s| !s.is_empty()) {\n desc.push_str(\"\\nReview summary: \");\n desc.push_str(summary);\n }\n\n br_create_ephemeral(\n beads_dir,\n &title,\n &desc,\n \"bug\",\n &priority,\n \"open\",\n &external_ref,\n &labels,\n )\n .context(\"run br create for review issue\")\n}\n\nfn create_review_future_task_bead(\n beads_dir: &Path,\n task: &str,\n project_path: &str,\n project_label: &str,\n branch: &str,\n branch_label: &str,\n sha_short: &str,\n reviewer_label: &str,\n model_label: &str,\n summary: Option<&str>,\n review_run_id: &str,\n) -> Result<bool> {\n let title = review_task_title(task);\n let description = review_task_description_with_commit(\n task,\n project_path,\n branch,\n sha_short,\n reviewer_label,\n summary,\n model_label,\n review_run_id,\n );\n let external_ref = format!(\n \"flow-review-task:{}\",\n flow_review_item_id(review_run_id, \"task\", task)\n );\n let labels = format!(\n \"flow-review,review:task,task,project:{},commit:{},branch:{},reviewer:{}\",\n project_label, sha_short, branch_label, reviewer_label\n );\n\n br_create_ephemeral(\n beads_dir,\n &title,\n &description,\n \"task\",\n \"4\",\n \"open\",\n &external_ref,\n &labels,\n )\n .context(\"run br create for review task\")\n}\n\nfn br_create_ephemeral(\n beads_dir: &Path,\n title: &str,\n description: &str,\n issue_type: &str,\n priority: &str,\n status: &str,\n external_ref: &str,\n labels: &str,\n) -> Result<bool> {\n let output = Command::new(\"br\")\n .arg(\"create\")\n .arg(\"--title\")\n .arg(title)\n .arg(\"--description\")\n .arg(description)\n .arg(\"--type\")\n .arg(issue_type)\n .arg(\"--priority\")\n .arg(priority)\n .arg(\"--status\")\n .arg(status)\n .arg(\"--external-ref\")\n .arg(external_ref)\n .arg(\"--labels\")\n .arg(labels)\n .arg(\"--ephemeral\")\n .arg(\"--silent\")\n .arg(\"--no-auto-flush\")\n .arg(\"--no-auto-import\")\n .env(\"BEADS_DIR\", beads_dir)\n .output()\n .context(\"run br create\")?;\n\n if output.status.success() {\n return Ok(true);\n }\n if br_create_failed_due_to_duplicate_external_ref(&output) {\n return Ok(false);\n }\n let stderr = String::from_utf8_lossy(&output.stderr);\n let stdout = String::from_utf8_lossy(&output.stdout);\n let msg = if stderr.trim().is_empty() {\n stdout.trim()\n } else {\n stderr.trim()\n };\n bail!(\"beads create failed: {}\", msg);\n}\n\nfn infer_review_bead_priority(issue: &str) -> u8 {\n let lower = issue.to_lowercase();\n if lower.contains(\"secret\")\n || lower.contains(\"credential\")\n || lower.contains(\"api key\")\n || lower.contains(\"injection\")\n || lower.contains(\"vulnerability\")\n {\n return 0; // critical\n }\n if lower.contains(\"crash\")\n || lower.contains(\"data loss\")\n || lower.contains(\"race condition\")\n || lower.contains(\"buffer overflow\")\n {\n return 1; // high\n }\n if lower.contains(\"bug\")\n || lower.contains(\"error handling\")\n || lower.contains(\"panic\")\n || lower.contains(\"unwrap\")\n || lower.contains(\"missing validation\")\n {\n return 2; // medium\n }\n if lower.contains(\"style\")\n || lower.contains(\"refactor\")\n || lower.contains(\"unused\")\n || lower.contains(\"naming\")\n || lower.contains(\"dead code\")\n {\n return 3; // low\n }\n 3 // default for issues\n}\n\nfn br_create_failed_due_to_duplicate_external_ref(output: &std::process::Output) -> bool {\n let mut combined = String::new();\n combined.push_str(&String::from_utf8_lossy(&output.stdout));\n combined.push('\\n');\n combined.push_str(&String::from_utf8_lossy(&output.stderr));\n let lower = combined.to_lowercase();\n lower.contains(\"unique constraint failed\")\n && (lower.contains(\"issues.external_ref\") || lower.contains(\"external_ref\"))\n}\n\nfn safe_label_value(value: &str) -> String {\n let mut out = String::new();\n for ch in value.trim().chars() {\n if ch.is_ascii_alphanumeric() || matches!(ch, '.' | '_' | '-') {\n out.push(ch);\n } else {\n out.push('_');\n }\n }\n if out.is_empty() {\n \"unknown\".to_string()\n } else {\n out\n }\n}\n\nfn flow_review_project_key(repo_root: &Path) -> String {\n if let Ok(url) = git_capture_in(repo_root, &[\"config\", \"--get\", \"remote.origin.url\"]) {\n let url = url.trim();\n if !url.is_empty() {\n if let Some(key) = normalize_git_remote_to_owner_repo(url) {\n return key;\n }\n return url.to_string();\n }\n }\n repo_root.display().to_string()\n}\n\nfn normalize_git_remote_to_owner_repo(url: &str) -> Option<String> {\n let trimmed = url.trim().trim_end_matches('/');\n // git@github.com:owner/repo.git\n if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n let rest = rest.trim_end_matches(\".git\");\n if rest.split('/').count() == 2 {\n return Some(rest.to_string());\n }\n }\n // https://github.com/owner/repo(.git)\n if let Some(rest) = trimmed.strip_prefix(\"https://github.com/\") {\n let rest = rest.trim_end_matches(\".git\");\n let parts: Vec<&str> = rest.split('/').collect();\n if parts.len() >= 2 {\n return Some(format!(\"{}/{}\", parts[0], parts[1]));\n }\n }\n None\n}\n\nfn flow_review_run_id(repo_root: &Path, diff: &str, model_label: &str, reviewer: &str) -> String {\n let project_key = flow_review_project_key(repo_root);\n let mut hasher = Sha1::new();\n hasher.update(project_key.as_bytes());\n hasher.update(b\":\");\n hasher.update(reviewer.trim().as_bytes());\n hasher.update(b\":\");\n hasher.update(model_label.trim().as_bytes());\n hasher.update(b\":\");\n hasher.update(diff.as_bytes());\n let hex = hex::encode(hasher.finalize());\n hex.get(..12).unwrap_or(&hex).to_string()\n}\n\nfn flow_review_item_id(review_run_id: &str, kind: &str, text: &str) -> String {\n let mut hasher = Sha1::new();\n hasher.update(kind.as_bytes());\n hasher.update(b\":\");\n hasher.update(review_run_id.as_bytes());\n hasher.update(b\":\");\n hasher.update(text.trim().as_bytes());\n let hex = hex::encode(hasher.finalize());\n hex.get(..12).unwrap_or(&hex).to_string()\n}\n\nfn review_task_title(task: &str) -> String {\n let trimmed = task.trim().trim_start_matches('-').trim();\n let max_len = 120;\n let mut title = String::new();\n let mut count = 0;\n for ch in trimmed.chars() {\n if count >= max_len {\n title.push_str(\"...\");\n break;\n }\n title.push(ch);\n count += 1;\n }\n title\n}\n\nfn review_task_description_with_commit(\n task: &str,\n project_path: &str,\n branch: &str,\n sha_short: &str,\n reviewer_label: &str,\n summary: Option<&str>,\n model_label: &str,\n review_run_id: &str,\n) -> String {\n let mut desc = String::new();\n desc.push_str(task.trim());\n desc.push_str(\"\\n\\nProject: \");\n desc.push_str(project_path);\n desc.push_str(\"\\nBranch: \");\n desc.push_str(branch);\n desc.push_str(\"\\nCommit: \");\n desc.push_str(sha_short);\n desc.push_str(\"\\nReviewer: \");\n desc.push_str(reviewer_label);\n desc.push_str(\"\\nModel: \");\n desc.push_str(model_label);\n desc.push_str(\"\\nRun ID: \");\n desc.push_str(review_run_id);\n if let Some(summary) = summary {\n desc.push_str(\"\\nReview summary: \");\n desc.push_str(summary);\n }\n desc\n}\n\nfn env_flag(name: &str) -> bool {\n env::var(name)\n .ok()\n .map(|value| {\n matches!(\n value.trim().to_ascii_lowercase().as_str(),\n \"1\" | \"true\" | \"yes\" | \"on\"\n )\n })\n .unwrap_or(false)\n}\n\n/// Send critical review issues to cloud for reactive display.\nfn send_to_cloud(project_path: &std::path::Path, issues: &[String], summary: Option<&str>) {\n // Try production worker first, then local\n let endpoints = [\n \"https://myflow.sh/api/v1/events\", // Production worker\n \"http://localhost:8787/api/v1/events\", // Local dev\n ];\n\n let project_name = project_path\n .file_name()\n .map(|s| s.to_string_lossy().to_string())\n .unwrap_or_else(|| \"unknown\".to_string());\n\n let payload = json!({\n \"type\": \"review_issue\",\n \"project\": project_name,\n \"issues\": issues,\n \"summary\": summary,\n \"timestamp\": chrono::Utc::now().to_rfc3339(),\n });\n\n let client = match crate::http_client::blocking_with_timeout(Duration::from_secs(2)) {\n Ok(c) => c,\n Err(_) => return,\n };\n\n for endpoint in &endpoints {\n if client.post(*endpoint).json(&payload).send().is_ok() {\n debug!(\"Sent review issues to {}\", endpoint);\n return;\n }\n }\n}\n\nenum ReviewEvent {\n Line(String),\n StderrLine(String),\n StdoutDone,\n StderrDone,\n}\n\nfn should_show_review_context() -> bool {\n std::env::var(\"FLOW_SHOW_REVIEW_CONTEXT\")\n .map(|v| matches!(v.as_str(), \"1\" | \"true\" | \"yes\" | \"on\"))\n .unwrap_or(false)\n}\n\n/// Check if gitedit is globally enabled in ~/.config/flow/config.ts.\n/// Returns true by default if not specified (opt-out).\nfn gitedit_globally_enabled() -> bool {\n if let Some(ts_config) = config::load_ts_config() {\n if let Some(flow) = ts_config.flow {\n if let Some(enabled) = flow.gitedit {\n return enabled;\n }\n }\n }\n // Default to false (opt-in) - gitedit not working well currently\n false\n}\n\n/// Check if gitedit mirroring is enabled in flow.toml.\nfn gitedit_mirror_enabled() -> bool {\n let repo_root = git_root_or_cwd();\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n return cfg.options.gitedit_mirror.unwrap_or(false);\n }\n }\n\n false\n}\n\n/// Check if gitedit mirroring is enabled for commit in the repo root.\nfn gitedit_mirror_enabled_for_commit(repo_root: &std::path::Path) -> bool {\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n return cfg.options.gitedit_mirror.unwrap_or(false);\n }\n }\n\n false\n}\n\n/// Check if gitedit mirroring is enabled for commitWithCheck in flow.toml.\nfn gitedit_mirror_enabled_for_commit_with_check(repo_root: &std::path::Path) -> bool {\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(value) = cfg.options.commit_with_check_gitedit_mirror {\n return value;\n }\n return cfg.options.gitedit_mirror.unwrap_or(false);\n }\n }\n\n false\n}\n\n/// Get the gitedit API URL from config or use default.\nfn gitedit_api_url(repo_root: &std::path::Path) -> String {\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(url) = cfg.options.gitedit_url {\n return url;\n }\n }\n }\n\n \"https://gitedit.dev\".to_string()\n}\n\nfn gitedit_token(repo_root: &std::path::Path) -> Option<String> {\n for key in [\n \"GITEDIT_PUBLISH_TOKEN\",\n \"GITEDIT_TOKEN\",\n \"FLOW_GITEDIT_TOKEN\",\n ] {\n if let Ok(value) = std::env::var(key) {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n }\n }\n }\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(token) = cfg.options.gitedit_token {\n let trimmed = token.trim().to_string();\n if !trimmed.is_empty() {\n return Some(trimmed);\n }\n }\n }\n }\n None\n}\n\nfn gitedit_repo_override(repo_root: &std::path::Path) -> Option<(String, String)> {\n let local_config = repo_root.join(\"flow.toml\");\n if !local_config.exists() {\n return None;\n }\n\n let cfg = config::load(&local_config).ok()?;\n let raw = cfg.options.gitedit_repo_full_name?;\n let mut value = raw.trim();\n\n if let Some(rest) = value.strip_prefix(\"gh/\") {\n value = rest;\n }\n if let Some(idx) = value.find(\"github.com/\") {\n value = &value[idx + \"github.com/\".len()..];\n }\n if let Some(rest) = value.strip_suffix(\".git\") {\n value = rest;\n }\n\n let mut parts = value.split('/').filter(|s| !s.is_empty());\n let owner = parts.next()?.to_string();\n let repo = parts.next()?.to_string();\n Some((owner, repo))\n}\n\n/// Data from AI code review to sync to gitedit.\n#[derive(Debug, Clone, Default)]\npub struct GitEditReviewData {\n pub diff: Option<String>,\n pub issues_found: bool,\n pub issues: Vec<String>,\n pub summary: Option<String>,\n pub reviewer: Option<String>, // \"claude\" or \"codex\"\n}\n\n/// Sync commit to gitedit.dev for mirroring.\nfn sync_to_gitedit(\n repo_root: &std::path::Path,\n event: &str,\n ai_sessions: &[ai::GitEditSessionData],\n session_hash: Option<&str>,\n review_data: Option<&GitEditReviewData>,\n) {\n let (owner, repo) = if let Some((owner, repo)) = gitedit_repo_override(repo_root) {\n (owner, repo)\n } else {\n // Get remote origin URL to extract owner/repo\n let remote_url = match git_capture_in(repo_root, &[\"remote\", \"get-url\", \"origin\"]) {\n Ok(url) => url.trim().to_string(),\n Err(_) => {\n debug!(\"No git remote found, skipping gitedit sync\");\n return;\n }\n };\n\n // Parse owner/repo from remote URL\n // Supports: git@github.com:owner/repo.git, https://github.com/owner/repo.git\n match parse_github_remote(&remote_url) {\n Some((o, r)) => (o, r),\n None => {\n debug!(\"Could not parse GitHub remote URL: {}\", remote_url);\n return;\n }\n }\n };\n\n // Get current commit SHA\n let commit_sha = match git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"]) {\n Ok(sha) => sha.trim().to_string(),\n Err(_) => {\n debug!(\"Could not get commit SHA\");\n return;\n }\n };\n\n // Get current branch\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .ok()\n .map(|b| b.trim().to_string());\n let ref_name = branch.as_ref().map(|name| format!(\"refs/heads/{}\", name));\n\n // Get commit message\n let commit_message = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%B\"])\n .ok()\n .map(|m| m.trim().to_string());\n\n // Get author info\n let author_name = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%an\"])\n .ok()\n .map(|n| n.trim().to_string());\n let author_email = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%ae\"])\n .ok()\n .map(|e| e.trim().to_string());\n\n let session_count = ai_sessions.len();\n let ai_sessions_json: Vec<serde_json::Value> = ai_sessions\n .iter()\n .map(|s| {\n json!({\n \"session_id\": s.session_id,\n \"provider\": s.provider,\n \"started_at\": s.started_at,\n \"last_activity_at\": s.last_activity_at,\n \"exchange_count\": s.exchanges.len(),\n \"context_summary\": s.context_summary,\n \"exchanges\": s.exchanges.iter().map(|e| json!({\n \"user_message\": e.user_message,\n \"assistant_message\": e.assistant_message,\n \"timestamp\": e.timestamp,\n })).collect::<Vec<_>>(),\n })\n })\n .collect();\n\n let base_url = gitedit_api_url(repo_root);\n let base_url = base_url.trim_end_matches('/').to_string();\n let api_url = format!(\"{}/api/mirrors/sync\", base_url);\n let view_url = format!(\"{}/{}/{}\", base_url, owner, repo);\n\n // Build review data if present\n let review_json = review_data.map(|r| {\n json!({\n \"diff\": r.diff,\n \"issues_found\": r.issues_found,\n \"issues\": r.issues,\n \"summary\": r.summary,\n \"reviewer\": r.reviewer,\n })\n });\n\n let payload = json!({\n \"owner\": owner,\n \"repo\": repo,\n \"commit_sha\": commit_sha,\n \"branch\": branch,\n \"ref\": ref_name,\n \"event\": event,\n \"source\": \"flow-cli\",\n \"commit_message\": commit_message,\n \"author_name\": author_name,\n \"author_email\": author_email,\n \"session_hash\": session_hash,\n \"ai_sessions\": ai_sessions_json,\n \"review\": review_json,\n });\n\n let client = match crate::http_client::blocking_with_timeout(Duration::from_secs(10)) {\n Ok(c) => c,\n Err(_) => return,\n };\n\n let mut request = client.post(&api_url).json(&payload);\n if let Some(token) = gitedit_token(repo_root) {\n request = request.bearer_auth(token);\n }\n match request.send() {\n Ok(resp) if resp.status().is_success() => {\n if session_count > 0 {\n println!(\n \"✓ Synced to {} ({} AI session{})\",\n view_url,\n session_count,\n if session_count == 1 { \"\" } else { \"s\" }\n );\n } else {\n println!(\"✓ Synced to {}\", view_url);\n }\n debug!(\"Gitedit sync successful\");\n }\n Ok(resp) => {\n debug!(\"Gitedit sync failed: HTTP {}\", resp.status());\n }\n Err(e) => {\n debug!(\"Gitedit sync error: {}\", e);\n }\n }\n}\n\nfn gitedit_sessions_hash(\n owner: &str,\n repo: &str,\n sessions: &[ai::GitEditSessionData],\n) -> Option<String> {\n if sessions.is_empty() {\n return None;\n }\n\n // Hash includes owner/repo so the URL uniquely identifies the project\n let serialized = serde_json::to_string(sessions).ok()?;\n let mut hasher = DefaultHasher::new();\n owner.hash(&mut hasher);\n repo.hash(&mut hasher);\n serialized.hash(&mut hasher);\n Some(format!(\"{:016x}\", hasher.finish()))\n}\n\n/// Get owner/repo from git remote or gitedit override.\nfn get_gitedit_project(repo_root: &std::path::Path) -> Option<(String, String)> {\n // Check for override first\n if let Some((owner, repo)) = gitedit_repo_override(repo_root) {\n return Some((owner, repo));\n }\n\n // Get from git remote\n let remote_url = git_capture_in(repo_root, &[\"remote\", \"get-url\", \"origin\"]).ok()?;\n parse_github_remote(remote_url.trim())\n}\n\n/// Parse owner and repo from a GitHub remote URL.\nfn parse_github_remote(url: &str) -> Option<(String, String)> {\n let url = url.trim();\n\n // SSH format: git@github.com:owner/repo.git\n if url.starts_with(\"git@github.com:\") {\n let path = url.strip_prefix(\"git@github.com:\")?;\n let path = path.strip_suffix(\".git\").unwrap_or(path);\n let parts: Vec<&str> = path.split('/').collect();\n if parts.len() >= 2 {\n return Some((parts[0].to_string(), parts[1].to_string()));\n }\n }\n\n // HTTPS format: https://github.com/owner/repo.git\n if url.contains(\"github.com/\") {\n let idx = url.find(\"github.com/\")?;\n let path = &url[idx + 11..];\n let path = path.strip_suffix(\".git\").unwrap_or(path);\n let parts: Vec<&str> = path.split('/').collect();\n if parts.len() >= 2 {\n return Some((parts[0].to_string(), parts[1].to_string()));\n }\n }\n\n None\n}\n\n// ── myflow.sh sync ──────────────────────────────────────────────────\n\n/// Check if myflow mirroring is enabled in flow.toml.\nfn myflow_mirror_enabled(repo_root: &std::path::Path) -> bool {\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n return cfg.options.myflow_mirror.unwrap_or(false);\n }\n }\n false\n}\n\n/// Get the myflow API URL from config or use default.\nfn myflow_api_url(repo_root: &std::path::Path) -> String {\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(url) = cfg.options.myflow_url {\n return url;\n }\n }\n }\n \"https://myflow.sh\".to_string()\n}\n\n/// Get the myflow token from env, flow.toml, or ~/.config/flow/auth.toml.\nfn myflow_token(repo_root: &std::path::Path) -> Option<String> {\n // 1. Check env var\n if let Ok(value) = std::env::var(\"MYFLOW_TOKEN\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n }\n }\n\n // 2. Check flow.toml\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(token) = cfg.options.myflow_token {\n let trimmed = token.trim().to_string();\n if !trimmed.is_empty() {\n return Some(trimmed);\n }\n }\n }\n }\n\n // 3. Fall back to ~/.config/flow/auth.toml token\n let config_dir = dirs::config_dir()?.join(\"flow\");\n let auth_path = config_dir.join(\"auth.toml\");\n if auth_path.exists() {\n if let Ok(content) = std::fs::read_to_string(&auth_path) {\n if let Ok(auth) = toml::from_str::<toml::Value>(&content) {\n if let Some(token) = auth.get(\"token\").and_then(|v| v.as_str()) {\n let trimmed = token.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n }\n }\n }\n }\n }\n\n None\n}\n\nfn post_myflow_sync_events(\n client: &Client,\n events_api_url: &str,\n token: Option<&str>,\n owner: &str,\n repo: &str,\n commit_sha: &str,\n events: Vec<serde_json::Value>,\n) {\n if events.is_empty() {\n return;\n }\n\n let payload = json!({\n \"owner\": owner,\n \"repo\": repo,\n \"commit_sha\": commit_sha,\n \"correlation_id\": commit_sha,\n \"events\": events,\n });\n\n let mut request = client.post(events_api_url).json(&payload);\n if let Some(value) = token {\n request = request.bearer_auth(value);\n }\n\n match request.send() {\n Ok(resp) if resp.status().is_success() => {}\n Ok(resp) => {\n debug!(\"myflow sync-events failed: HTTP {}\", resp.status());\n }\n Err(err) => {\n debug!(\"myflow sync-events error: {}\", err);\n }\n }\n}\n\n/// Sync commit data to myflow.sh, mirroring the gitedit sync pattern.\n/// Fire-and-forget: never fails the commit on sync error.\nfn sync_to_myflow(\n repo_root: &std::path::Path,\n event: &str,\n ai_sessions: &[ai::GitEditSessionData],\n session_window: Option<&MyflowSessionWindow>,\n review_data: Option<&GitEditReviewData>,\n skill_gate: Option<&SkillGateReport>,\n) {\n // Get remote origin URL to extract owner/repo\n let remote_url = match git_capture_in(repo_root, &[\"remote\", \"get-url\", \"origin\"]) {\n Ok(url) => url.trim().to_string(),\n Err(_) => {\n debug!(\"No git remote found, skipping myflow sync\");\n return;\n }\n };\n\n let (owner, repo) = match parse_github_remote(&remote_url) {\n Some((o, r)) => (o, r),\n None => {\n debug!(\n \"Could not parse GitHub remote URL for myflow: {}\",\n remote_url\n );\n return;\n }\n };\n\n // Get current commit SHA\n let commit_sha = match git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"]) {\n Ok(sha) => sha.trim().to_string(),\n Err(_) => {\n debug!(\"Could not get commit SHA for myflow\");\n return;\n }\n };\n\n // Get current branch\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .ok()\n .map(|b| b.trim().to_string());\n\n // Get commit message\n let commit_message = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%B\"])\n .ok()\n .map(|m| m.trim().to_string());\n\n // Get author info\n let author_name = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%an\"])\n .ok()\n .map(|n| n.trim().to_string());\n let author_email = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%ae\"])\n .ok()\n .map(|e| e.trim().to_string());\n\n let session_count = ai_sessions.len();\n let ai_sessions_json: Vec<serde_json::Value> = ai_sessions\n .iter()\n .map(|s| {\n json!({\n \"session_id\": s.session_id,\n \"provider\": s.provider,\n \"started_at\": s.started_at,\n \"last_activity_at\": s.last_activity_at,\n \"exchange_count\": s.exchanges.len(),\n \"context_summary\": s.context_summary,\n \"exchanges\": s.exchanges.iter().map(|e| json!({\n \"user_message\": e.user_message,\n \"assistant_message\": e.assistant_message,\n \"timestamp\": e.timestamp,\n })).collect::<Vec<_>>(),\n })\n })\n .collect();\n\n let base_url = myflow_api_url(repo_root);\n let base_url = base_url.trim_end_matches('/').to_string();\n let api_url = format!(\"{}/api/sync\", base_url);\n let events_api_url = format!(\"{}/api/sync/events\", base_url);\n let started_at_ms = chrono::Utc::now().timestamp_millis();\n\n // Build review data if present\n let review_json = review_data.map(|r| {\n json!({\n \"issues_found\": r.issues_found,\n \"issues\": r.issues,\n \"summary\": r.summary,\n \"reviewer\": r.reviewer,\n })\n });\n\n // Build features data from .ai/features/ if present\n let features_json: Vec<serde_json::Value> = features::load_all_features(repo_root)\n .unwrap_or_default()\n .iter()\n .map(|f| {\n json!({\n \"name\": f.name,\n \"title\": f.content.lines().next().unwrap_or(&f.name).trim_start_matches('#').trim(),\n \"status\": f.status,\n \"description\": f.description,\n \"files\": f.files,\n \"tests\": f.tests,\n \"coverage\": f.coverage,\n \"last_verified_sha\": f.last_verified,\n })\n })\n .collect();\n\n let skill_gate_json = skill_gate.map(|gate| {\n json!({\n \"pass\": gate.pass,\n \"mode\": gate.mode,\n \"override\": gate.override_flag,\n \"required_skills\": gate.required_skills,\n \"missing_skills\": gate.missing_skills,\n \"version_failures\": gate.version_failures,\n \"loaded_versions\": gate.loaded_versions,\n })\n });\n\n let payload = json!({\n \"owner\": owner,\n \"repo\": repo,\n \"commit_sha\": commit_sha,\n \"branch\": branch,\n \"event\": event,\n \"source\": \"flow-cli\",\n \"commit_message\": commit_message,\n \"author_name\": author_name,\n \"author_email\": author_email,\n \"ai_sessions\": ai_sessions_json,\n \"session_window\": session_window.map(|window| json!({\n \"mode\": window.mode,\n \"since_ts\": window.since_ts,\n \"until_ts\": window.until_ts,\n \"collected_at\": window.collected_at,\n })),\n \"review\": review_json,\n \"features\": if features_json.is_empty() { None } else { Some(features_json) },\n \"skill_gate\": skill_gate_json,\n \"sync_events\": [\n {\n \"correlation_id\": commit_sha,\n \"commit_sha\": commit_sha,\n \"event_type\": \"transport\",\n \"tier\": \"client\",\n \"direction\": \"outbound\",\n \"status\": \"pending\",\n \"at_ms\": started_at_ms,\n \"details\": {\n \"phase\": \"request_start\",\n \"target\": \"api/sync\",\n \"source\": \"flow-cli\",\n },\n }\n ],\n });\n\n let client = match crate::http_client::blocking_with_timeout(Duration::from_secs(10)) {\n Ok(c) => c,\n Err(_) => return,\n };\n\n let token = myflow_token(repo_root);\n let mut request = client.post(&api_url).json(&payload);\n if let Some(value) = token.as_deref() {\n request = request.bearer_auth(value);\n }\n match request.send() {\n Ok(resp) if resp.status().is_success() => {\n let finished_at_ms = chrono::Utc::now().timestamp_millis();\n let latency_ms = std::cmp::max(0, finished_at_ms - started_at_ms);\n post_myflow_sync_events(\n &client,\n &events_api_url,\n token.as_deref(),\n &owner,\n &repo,\n &commit_sha,\n vec![\n json!({\n \"correlation_id\": commit_sha,\n \"commit_sha\": commit_sha,\n \"event_type\": \"transport\",\n \"tier\": \"client\",\n \"direction\": \"outbound\",\n \"status\": \"ok\",\n \"latency_ms\": latency_ms,\n \"at_ms\": finished_at_ms,\n \"details\": {\n \"phase\": \"request_complete\",\n \"target\": \"api/sync\",\n },\n }),\n json!({\n \"correlation_id\": commit_sha,\n \"commit_sha\": commit_sha,\n \"event_type\": \"persistence_ack\",\n \"tier\": \"server\",\n \"direction\": \"inbound\",\n \"status\": \"ok\",\n \"latency_ms\": latency_ms,\n \"at_ms\": finished_at_ms,\n \"details\": {\n \"phase\": \"sync_ack\",\n \"target\": \"api/sync\",\n },\n }),\n json!({\n \"correlation_id\": commit_sha,\n \"commit_sha\": commit_sha,\n \"event_type\": \"query_settled\",\n \"tier\": \"client\",\n \"direction\": \"inbound\",\n \"status\": \"ok\",\n \"latency_ms\": latency_ms,\n \"at_ms\": finished_at_ms,\n \"details\": {\n \"phase\": \"ui_visible\",\n \"source\": \"flow-cli\",\n },\n }),\n ],\n );\n\n if session_count > 0 {\n println!(\n \"✓ Synced to myflow.sh ({} AI session{})\",\n session_count,\n if session_count == 1 { \"\" } else { \"s\" }\n );\n } else {\n println!(\"✓ Synced to myflow.sh\");\n }\n }\n Ok(resp) => {\n let finished_at_ms = chrono::Utc::now().timestamp_millis();\n let latency_ms = std::cmp::max(0, finished_at_ms - started_at_ms);\n let status_code = resp.status().as_u16();\n post_myflow_sync_events(\n &client,\n &events_api_url,\n token.as_deref(),\n &owner,\n &repo,\n &commit_sha,\n vec![\n json!({\n \"correlation_id\": commit_sha,\n \"commit_sha\": commit_sha,\n \"event_type\": \"transport\",\n \"tier\": \"client\",\n \"direction\": \"outbound\",\n \"status\": \"error\",\n \"latency_ms\": latency_ms,\n \"error_code\": format!(\"HTTP_{}\", status_code),\n \"at_ms\": finished_at_ms,\n \"details\": {\n \"phase\": \"request_failed\",\n \"target\": \"api/sync\",\n \"status_code\": status_code,\n },\n }),\n json!({\n \"correlation_id\": commit_sha,\n \"commit_sha\": commit_sha,\n \"event_type\": \"error\",\n \"tier\": \"client\",\n \"status\": \"error\",\n \"error_code\": format!(\"HTTP_{}\", status_code),\n \"at_ms\": finished_at_ms,\n \"details\": {\n \"phase\": \"sync_error\",\n \"target\": \"api/sync\",\n \"status_code\": status_code,\n },\n }),\n ],\n );\n debug!(\"myflow sync failed: HTTP {}\", resp.status());\n }\n Err(e) => {\n let finished_at_ms = chrono::Utc::now().timestamp_millis();\n let latency_ms = std::cmp::max(0, finished_at_ms - started_at_ms);\n post_myflow_sync_events(\n &client,\n &events_api_url,\n token.as_deref(),\n &owner,\n &repo,\n &commit_sha,\n vec![\n json!({\n \"correlation_id\": commit_sha,\n \"commit_sha\": commit_sha,\n \"event_type\": \"transport\",\n \"tier\": \"client\",\n \"direction\": \"outbound\",\n \"status\": \"error\",\n \"latency_ms\": latency_ms,\n \"error_code\": \"NETWORK_ERROR\",\n \"at_ms\": finished_at_ms,\n \"details\": {\n \"phase\": \"request_exception\",\n \"target\": \"api/sync\",\n \"error\": e.to_string(),\n },\n }),\n json!({\n \"correlation_id\": commit_sha,\n \"commit_sha\": commit_sha,\n \"event_type\": \"error\",\n \"tier\": \"client\",\n \"status\": \"error\",\n \"error_code\": \"NETWORK_ERROR\",\n \"at_ms\": finished_at_ms,\n \"details\": {\n \"phase\": \"sync_error\",\n \"target\": \"api/sync\",\n },\n }),\n ],\n );\n debug!(\"myflow sync error: {}\", e);\n }\n }\n}\n\nfn entire_enabled() -> bool {\n if let Ok(value) = env::var(\"FLOW_ENTIRE_DISABLE\") {\n let v = value.to_ascii_lowercase();\n if v == \"1\" || v == \"true\" || v == \"yes\" {\n return false;\n }\n }\n let repo_root = git_root_or_cwd();\n if !repo_root.join(\".entire/settings.json\").exists() {\n return false;\n }\n which::which(\"entire\").is_ok()\n}\n\nfn unhash_capture_enabled() -> bool {\n if let Ok(value) = env::var(\"UNHASH_DISABLE\") {\n let v = value.to_ascii_lowercase();\n if v == \"1\" || v == \"true\" || v == \"yes\" {\n return false;\n }\n }\n if let Ok(value) = env::var(\"FLOW_UNHASH\") {\n let v = value.to_ascii_lowercase();\n if v == \"0\" || v == \"false\" || v == \"no\" {\n return false;\n }\n }\n true\n}\n\nfn capture_unhash_bundle(\n repo_root: &Path,\n diff: &str,\n status: Option<&str>,\n review: Option<&ReviewResult>,\n review_model: Option<&str>,\n review_reviewer: Option<&str>,\n review_instructions: Option<&str>,\n session_context: Option<&str>,\n sessions: Option<&[ai::GitEditSessionData]>,\n gitedit_session_hash: Option<&str>,\n commit_message: &str,\n author_message: Option<&str>,\n include_context: bool,\n) -> Option<String> {\n if !unhash_capture_enabled() {\n return None;\n }\n\n match try_capture_unhash_bundle(\n repo_root,\n diff,\n status,\n review,\n review_model,\n review_reviewer,\n review_instructions,\n session_context,\n sessions,\n gitedit_session_hash,\n commit_message,\n author_message,\n include_context,\n ) {\n Ok(hash) => hash,\n Err(err) => {\n debug!(\"unhash capture failed: {}\", err);\n None\n }\n }\n}\n\nconst UNHASH_TRACE_DEFAULT_BYTES: u64 = 64 * 1024;\n\nfn default_assistant_trace_roots() -> Vec<PathBuf> {\n let mut roots = Vec::new();\n if let Some(home) = dirs::home_dir() {\n roots.push(\n home.join(\"repos\")\n .join(\"garden-co\")\n .join(\"jazz2\")\n .join(\"assistant-traces\"),\n );\n roots.push(\n home.join(\"code\")\n .join(\"org\")\n .join(\"1f\")\n .join(\"jazz2\")\n .join(\"assistant-traces\"),\n );\n }\n roots\n}\n\nfn assistant_traces_root() -> Option<std::path::PathBuf> {\n if let Ok(value) = env::var(\"UNHASH_TRACE_DIR\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Some(std::path::PathBuf::from(trimmed));\n }\n }\n default_assistant_trace_roots()\n .into_iter()\n .find(|candidate| candidate.exists())\n .or_else(|| default_assistant_trace_roots().into_iter().next())\n}\n\nfn unhash_trace_max_bytes() -> u64 {\n if let Ok(value) = env::var(\"UNHASH_TRACE_MAX_BYTES\") {\n if let Ok(parsed) = value.trim().parse::<u64>() {\n if parsed > 0 {\n return parsed;\n }\n }\n }\n UNHASH_TRACE_DEFAULT_BYTES\n}\n\nfn read_tail_bytes(path: &Path, max_bytes: u64) -> Result<Vec<u8>> {\n let mut file = fs::File::open(path).with_context(|| format!(\"open {}\", path.display()))?;\n let len = file.metadata()?.len();\n if len > max_bytes {\n let offset = max_bytes.min(len) as i64;\n file.seek(SeekFrom::End(-offset))?;\n }\n let mut buf = Vec::new();\n file.read_to_end(&mut buf)?;\n Ok(buf)\n}\n\nfn write_agent_trace_file(bundle_path: &Path, rel_path: &str, data: &[u8]) -> Result<()> {\n let target = bundle_path.join(rel_path);\n if let Some(parent) = target.parent() {\n fs::create_dir_all(parent)?;\n }\n fs::write(&target, data)?;\n Ok(())\n}\n\nfn write_agent_traces(bundle_path: &Path, repo_root: &Path) {\n let mut sources = Vec::new();\n let max_bytes = unhash_trace_max_bytes();\n if max_bytes == 0 {\n return;\n }\n\n let trace_root = assistant_traces_root();\n if let Some(root) = trace_root {\n let trace_files = [\n \"ai.jsonl\",\n \"linsa.jsonl\",\n \"gen.new.jsonl\",\n \"last-failure.json\",\n ];\n for name in trace_files {\n let path = root.join(name);\n if !path.exists() {\n continue;\n }\n match read_tail_bytes(&path, max_bytes) {\n Ok(data) => {\n let rel = format!(\"agent/traces/{}\", name);\n if let Err(err) = write_agent_trace_file(bundle_path, &rel, &data) {\n debug!(\"failed to write agent trace {}: {}\", rel, err);\n continue;\n }\n sources.push(json!({\n \"label\": name,\n \"path\": path.display().to_string(),\n \"bytes\": data.len(),\n }));\n }\n Err(err) => debug!(\"failed to read trace {}: {}\", path.display(), err),\n }\n }\n }\n\n if let Some(home) = dirs::home_dir() {\n let cmdlog = home.join(\".cmd\").join(\"f\").join(\"index.jsonl\");\n if cmdlog.exists() {\n match read_tail_bytes(&cmdlog, max_bytes) {\n Ok(data) => {\n let rel = \"agent/cmdlog/f.index.jsonl\";\n if let Err(err) = write_agent_trace_file(bundle_path, rel, &data) {\n debug!(\"failed to write {}: {}\", rel, err);\n } else {\n sources.push(json!({\n \"label\": \"cmdlog.f.index\",\n \"path\": cmdlog.display().to_string(),\n \"bytes\": data.len(),\n }));\n }\n }\n Err(err) => debug!(\"failed to read cmdlog: {}\", err),\n }\n }\n\n let xdg = env::var(\"XDG_DATA_HOME\")\n .ok()\n .filter(|s| !s.trim().is_empty())\n .map(std::path::PathBuf::from)\n .unwrap_or_else(|| home.join(\".local\").join(\"share\"));\n let fish_dir = xdg.join(\"fish\").join(\"io-trace\");\n let fish_files = [\n (\"agent/fish/last.stdout\", fish_dir.join(\"last.stdout\")),\n (\"agent/fish/last.stderr\", fish_dir.join(\"last.stderr\")),\n (\"agent/fish/rise.meta\", fish_dir.join(\"rise.meta\")),\n (\n \"agent/fish/rise.history.jsonl\",\n fish_dir.join(\"rise.history.jsonl\"),\n ),\n ];\n for (rel, path) in fish_files {\n if !path.exists() {\n continue;\n }\n match read_tail_bytes(&path, max_bytes) {\n Ok(data) => {\n if let Err(err) = write_agent_trace_file(bundle_path, rel, &data) {\n debug!(\"failed to write {}: {}\", rel, err);\n } else {\n sources.push(json!({\n \"label\": rel,\n \"path\": path.display().to_string(),\n \"bytes\": data.len(),\n }));\n }\n }\n Err(err) => debug!(\"failed to read {}: {}\", path.display(), err),\n }\n }\n }\n\n if !sources.is_empty() {\n let index = json!({\n \"captured_at\": chrono::Utc::now().to_rfc3339(),\n \"repo_root\": repo_root.to_string_lossy().to_string(),\n \"sources\": sources,\n });\n if let Ok(encoded) = serde_json::to_vec_pretty(&index) {\n let _ = write_agent_trace_file(bundle_path, \"agent/trace_index.json\", &encoded);\n }\n }\n}\n\nfn write_agent_learning(\n bundle_path: &Path,\n repo_root: &Path,\n diff: &str,\n _status: &str,\n review: Option<&ReviewResult>,\n commit_message: &str,\n sessions_count: usize,\n) {\n let changed_files = changed_files_from_diff(diff);\n let summary = review\n .and_then(|r| r.summary.clone())\n .filter(|s| !s.trim().is_empty())\n .unwrap_or_else(|| commit_message.to_string());\n let issues = review.map(|r| r.issues.clone()).unwrap_or_default();\n let future_tasks = review.map(|r| r.future_tasks.clone()).unwrap_or_default();\n\n let root_cause = if !summary.trim().is_empty() {\n summary.clone()\n } else if !issues.is_empty() {\n issues.join(\"; \")\n } else {\n \"unknown (see diff)\".to_string()\n };\n let prevention = if !future_tasks.is_empty() {\n future_tasks.join(\"; \")\n } else {\n \"Add a regression test or guard for the affected behavior.\".to_string()\n };\n\n let mut tag_texts = Vec::new();\n if !summary.is_empty() {\n tag_texts.push(summary.clone());\n }\n tag_texts.extend(issues.iter().cloned());\n let tags = classify_learning_tags(&tag_texts);\n\n let learn_json = json!({\n \"commit\": commit_message,\n \"repo\": repo_root.file_name().and_then(|n| n.to_str()).unwrap_or(\"repo\"),\n \"repo_root\": repo_root.to_string_lossy().to_string(),\n \"issue\": issues.first().cloned().unwrap_or_else(|| \"none\".to_string()),\n \"root_cause\": root_cause,\n \"fix\": commit_message,\n \"prevention\": prevention,\n \"affected_files\": changed_files,\n \"tests\": [],\n \"tags\": tags,\n \"ai_sessions\": sessions_count,\n \"review_issues\": issues,\n \"review_future_tasks\": future_tasks,\n \"created_at\": chrono::Utc::now().to_rfc3339(),\n });\n\n let decision_md = render_learning_decision_md(&learn_json);\n let regression_md = render_learning_regression_md(&learn_json);\n let patch_summary_md = render_learning_patch_summary_md(&learn_json);\n\n if let Ok(encoded) = serde_json::to_vec_pretty(&learn_json) {\n let _ = write_agent_trace_file(bundle_path, \"agent/learn.json\", &encoded);\n }\n let _ = write_agent_trace_file(bundle_path, \"agent/decision.md\", decision_md.as_bytes());\n let _ = write_agent_trace_file(bundle_path, \"agent/regression.md\", regression_md.as_bytes());\n let _ = write_agent_trace_file(\n bundle_path,\n \"agent/patch_summary.md\",\n patch_summary_md.as_bytes(),\n );\n\n let _ = append_learning_store(\n repo_root,\n &learn_json,\n &decision_md,\n ®ression_md,\n &patch_summary_md,\n );\n}\n\nfn classify_learning_tags(texts: &[String]) -> Vec<String> {\n let mut tags = HashSet::new();\n for text in texts {\n let lowered = text.to_lowercase();\n if lowered.contains(\"perf\")\n || lowered.contains(\"performance\")\n || lowered.contains(\"latency\")\n {\n tags.insert(\"perf\".to_string());\n }\n if lowered.contains(\"security\") || lowered.contains(\"vulnerability\") {\n tags.insert(\"security\".to_string());\n }\n if lowered.contains(\"panic\")\n || lowered.contains(\"crash\")\n || lowered.contains(\"error\")\n || lowered.contains(\"bug\")\n {\n tags.insert(\"bug\".to_string());\n }\n if lowered.contains(\"prompt\") || lowered.contains(\"instruction\") {\n tags.insert(\"prompt\".to_string());\n }\n if lowered.contains(\"test\") || lowered.contains(\"regression\") {\n tags.insert(\"test\".to_string());\n }\n }\n let mut out: Vec<String> = tags.into_iter().collect();\n out.sort();\n out\n}\n\nfn render_learning_decision_md(learn: &serde_json::Value) -> String {\n let summary = learn\n .get(\"root_cause\")\n .and_then(|v| v.as_str())\n .unwrap_or(\"n/a\");\n let fix = learn.get(\"fix\").and_then(|v| v.as_str()).unwrap_or(\"n/a\");\n let prevention = learn\n .get(\"prevention\")\n .and_then(|v| v.as_str())\n .unwrap_or(\"n/a\");\n format!(\n \"# Decision\\n\\n## Summary\\n{}\\n\\n## Fix\\n{}\\n\\n## Prevention\\n{}\\n\",\n summary, fix, prevention\n )\n}\n\nfn render_learning_regression_md(learn: &serde_json::Value) -> String {\n let issue = learn\n .get(\"issue\")\n .and_then(|v| v.as_str())\n .unwrap_or(\"none\");\n let prevention = learn\n .get(\"prevention\")\n .and_then(|v| v.as_str())\n .unwrap_or(\"n/a\");\n format!(\n \"# Regression Guard\\n\\n- If you see: {}\\n- Do: {}\\n\",\n issue, prevention\n )\n}\n\nfn render_learning_patch_summary_md(learn: &serde_json::Value) -> String {\n let commit = learn.get(\"fix\").and_then(|v| v.as_str()).unwrap_or(\"n/a\");\n let files = learn\n .get(\"affected_files\")\n .and_then(|v| v.as_array())\n .cloned()\n .unwrap_or_default();\n let mut out = String::from(\"# Patch Summary\\n\\n\");\n out.push_str(&format!(\"- Commit: {}\\n\", commit));\n out.push_str(\"- Files:\\n\");\n if files.is_empty() {\n out.push_str(\" - (none)\\n\");\n } else {\n for file in files {\n if let Some(name) = file.as_str() {\n out.push_str(&format!(\" - {}\\n\", name));\n }\n }\n }\n out\n}\n\nfn append_learning_store(\n repo_root: &Path,\n learn_json: &serde_json::Value,\n decision_md: &str,\n regression_md: &str,\n patch_summary_md: &str,\n) -> Result<()> {\n let learn_dir = learning_store_root(repo_root)?;\n fs::create_dir_all(&learn_dir)?;\n\n let learn_jsonl = learn_dir.join(\"learn.jsonl\");\n let line = serde_json::to_string(learn_json)? + \"\\n\";\n fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(&learn_jsonl)?\n .write_all(line.as_bytes())?;\n\n let learn_md = learn_dir.join(\"learn.md\");\n let mut md = String::new();\n md.push_str(\"\\n---\\n\\n\");\n md.push_str(decision_md);\n md.push('\\n');\n md.push_str(regression_md);\n md.push('\\n');\n md.push_str(patch_summary_md);\n md.push('\\n');\n\n fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(&learn_md)?\n .write_all(md.as_bytes())?;\n\n let _ = append_jazz_learning(&line);\n\n Ok(())\n}\n\nfn learning_store_root(repo_root: &Path) -> Result<PathBuf> {\n if let Ok(value) = env::var(\"FLOW_LEARN_DIR\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(PathBuf::from(trimmed));\n }\n }\n if let Ok(value) = env::var(\"FLOW_BASE_DIR\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(PathBuf::from(trimmed)\n .join(\".ai\")\n .join(\"internal\")\n .join(\"learn\"));\n }\n }\n\n if let Some(home) = dirs::home_dir() {\n return Ok(home\n .join(\"code\")\n .join(\"org\")\n .join(\"linsa\")\n .join(\"base\")\n .join(\".ai\")\n .join(\"internal\")\n .join(\"learn\"));\n }\n\n Ok(repo_root.join(\".ai\").join(\"internal\").join(\"learn\"))\n}\n\nfn append_jazz_learning(line: &str) -> Result<()> {\n let Some(root) = jazz_assistant_traces_root() else {\n return Ok(());\n };\n fs::create_dir_all(&root)?;\n let path = root.join(\"base.learn.jsonl\");\n fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(&path)?\n .write_all(line.as_bytes())?;\n Ok(())\n}\n\nfn jazz_assistant_traces_root() -> Option<PathBuf> {\n if let Ok(value) = env::var(\"FLOW_JAZZ_TRACE_DIR\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Some(PathBuf::from(trimmed));\n }\n }\n default_assistant_trace_roots()\n .into_iter()\n .find(|candidate| candidate.exists())\n .or_else(|| default_assistant_trace_roots().into_iter().next())\n}\n\nfn try_capture_unhash_bundle(\n repo_root: &Path,\n diff: &str,\n status: Option<&str>,\n review: Option<&ReviewResult>,\n review_model: Option<&str>,\n review_reviewer: Option<&str>,\n review_instructions: Option<&str>,\n session_context: Option<&str>,\n sessions: Option<&[ai::GitEditSessionData]>,\n gitedit_session_hash: Option<&str>,\n commit_message: &str,\n author_message: Option<&str>,\n include_context: bool,\n) -> Result<Option<String>> {\n let unhash_bin = match which::which(\"unhash\") {\n Ok(path) => path,\n Err(_) => {\n debug!(\"unhash not found on PATH; skipping commit bundle\");\n return Ok(None);\n }\n };\n\n let mut injected_key: Option<String> = None;\n if env::var(\"UNHASH_KEY\").is_err() {\n if let Ok(Some(value)) = flow_env::get_personal_env_var(\"UNHASH_KEY\") {\n injected_key = Some(value);\n } else {\n debug!(\"UNHASH_KEY not set; skipping commit bundle\");\n return Ok(None);\n }\n }\n\n let unhash_dir = repo_root.join(\".ai/internal/unhash\");\n fs::create_dir_all(&unhash_dir)\n .with_context(|| format!(\"create unhash dir {}\", unhash_dir.display()))?;\n\n let bundle_dir: TempDir = TempBuilder::new()\n .prefix(\"commit-\")\n .tempdir_in(&unhash_dir)\n .context(\"create unhash temp dir\")?;\n\n let bundle_path = bundle_dir.path();\n fs::write(bundle_path.join(\"diff.patch\"), diff).context(\"write diff.patch\")?;\n\n let status_value = status\n .map(|s| s.to_string())\n .unwrap_or_else(|| git_capture_in(repo_root, &[\"status\", \"--short\"]).unwrap_or_default());\n fs::write(bundle_path.join(\"status.txt\"), &status_value).context(\"write status.txt\")?;\n\n if let Some(context) = session_context {\n fs::write(bundle_path.join(\"context.txt\"), context).context(\"write context.txt\")?;\n }\n\n let sessions_data: Vec<ai::GitEditSessionData> = match sessions {\n Some(items) => items.to_vec(),\n None => ai::get_sessions_for_gitedit(&repo_root.to_path_buf()).unwrap_or_default(),\n };\n if !sessions_data.is_empty() {\n let json =\n serde_json::to_string_pretty(&sessions_data).context(\"serialize sessions.json\")?;\n fs::write(bundle_path.join(\"sessions.json\"), json).context(\"write sessions.json\")?;\n }\n\n write_agent_traces(bundle_path, repo_root);\n write_agent_learning(\n bundle_path,\n repo_root,\n diff,\n &status_value,\n review,\n commit_message,\n sessions_data.len(),\n );\n\n if let Some(review) = review {\n let review_payload = UnhashReviewPayload {\n issues_found: review.issues_found,\n issues: review.issues.clone(),\n summary: review.summary.clone(),\n future_tasks: review.future_tasks.clone(),\n timed_out: review.timed_out,\n model: review_model.map(|s| s.to_string()),\n reviewer: review_reviewer.map(|s| s.to_string()),\n };\n let json =\n serde_json::to_string_pretty(&review_payload).context(\"serialize review.json\")?;\n fs::write(bundle_path.join(\"review.json\"), json).context(\"write review.json\")?;\n }\n\n let branch = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"unknown\".to_string());\n let repo_label = match get_gitedit_project(repo_root) {\n Some((owner, repo)) => format!(\"{}/{}\", owner, repo),\n None => repo_root\n .file_name()\n .map(|name| name.to_string_lossy().to_string())\n .unwrap_or_else(|| \"local-repo\".to_string()),\n };\n\n let metadata = UnhashCommitMetadata {\n repo: repo_label,\n repo_root: repo_root.to_string_lossy().to_string(),\n branch: branch.trim().to_string(),\n created_at: chrono::Utc::now().to_rfc3339(),\n commit_message: commit_message.to_string(),\n author_message: author_message.map(|s| s.to_string()),\n include_context,\n context_chars: session_context.map(|c| c.len()),\n review_model: review_model.map(|s| s.to_string()),\n review_instructions: review_instructions.map(|s| s.to_string()),\n review_issues: review.map(|r| r.issues.clone()).unwrap_or_default(),\n review_summary: review.and_then(|r| r.summary.clone()),\n review_future_tasks: review.map(|r| r.future_tasks.clone()).unwrap_or_default(),\n review_timed_out: review.map(|r| r.timed_out).unwrap_or(false),\n gitedit_session_hash: gitedit_session_hash.map(|s| s.to_string()),\n session_count: sessions_data.len(),\n };\n let meta_json = serde_json::to_string_pretty(&metadata).context(\"serialize commit.json\")?;\n fs::write(bundle_path.join(\"commit.json\"), meta_json).context(\"write commit.json\")?;\n\n let out_file = TempBuilder::new()\n .prefix(\"bundle-\")\n .suffix(\".uhx\")\n .tempfile_in(&unhash_dir)\n .context(\"create temp bundle file\")?;\n let out_path = out_file.path().to_path_buf();\n drop(out_file);\n\n let mut cmd = Command::new(unhash_bin);\n cmd.arg(bundle_path).arg(\"--out\").arg(&out_path);\n cmd.current_dir(repo_root);\n if let Some(value) = injected_key {\n cmd.env(\"UNHASH_KEY\", value);\n }\n\n let output = cmd.output().context(\"run unhash\")?;\n if !output.status.success() {\n let stdout = String::from_utf8_lossy(&output.stdout);\n let stderr = String::from_utf8_lossy(&output.stderr);\n debug!(\"unhash failed: {} {}{}\", output.status, stdout, stderr);\n return Ok(None);\n }\n\n let stdout = String::from_utf8_lossy(&output.stdout);\n let mut hash = String::new();\n for line in stdout.lines() {\n let trimmed = line.trim();\n if !trimmed.is_empty() {\n hash = trimmed.to_string();\n break;\n }\n }\n if hash.is_empty() {\n debug!(\"unhash output missing hash\");\n return Ok(None);\n }\n\n let final_path = unhash_dir.join(format!(\"{}.uhx\", hash));\n if final_path != out_path {\n if let Err(err) = fs::rename(&out_path, &final_path) {\n debug!(\"failed to move unhash bundle: {}\", err);\n }\n }\n\n Ok(Some(hash))\n}\n\nfn stage_changes_for_commit(workdir: &Path, stage_paths: &[String]) -> Result<()> {\n print!(\"Staging changes... \");\n io::stdout().flush()?;\n\n if stage_paths.is_empty() {\n git_run_in(workdir, &[\"add\", \".\"])?;\n println!(\"done\");\n return Ok(());\n }\n\n git_run_in(workdir, &[\"reset\", \"--quiet\"])?;\n\n let mut cmd = Command::new(\"git\");\n let status = cmd\n .current_dir(workdir)\n .arg(\"add\")\n .arg(\"--\")\n .args(stage_paths)\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run git add for selected paths\")?;\n\n if !status.success() {\n bail!(\"git add -- <paths> failed with status {}\", status);\n }\n\n println!(\n \"done ({} path{})\",\n stage_paths.len(),\n if stage_paths.len() == 1 { \"\" } else { \"s\" }\n );\n\n Ok(())\n}\n\nfn split_paragraphs(message: &str) -> Vec<String> {\n let mut paragraphs = Vec::new();\n let mut current = Vec::new();\n\n for line in message.lines() {\n if line.trim().is_empty() {\n if !current.is_empty() {\n paragraphs.push(current.join(\"\\n\"));\n current.clear();\n }\n } else {\n current.push(line.trim_end());\n }\n }\n\n if !current.is_empty() {\n paragraphs.push(current.join(\"\\n\"));\n }\n\n paragraphs\n}\n\nfn stage_paths_cli_flags(stage_paths: &[String]) -> String {\n let mut flags = String::new();\n for path in stage_paths {\n flags.push_str(&format!(\" --path {:?}\", path));\n }\n flags\n}\n\nfn delegate_to_hub(\n push: bool,\n queue: CommitQueueMode,\n include_unhash: bool,\n stage_paths: &[String],\n) -> Result<()> {\n let repo_root = git_root_or_cwd();\n warn_if_commit_invoked_from_subdir(&repo_root);\n\n // Build the command to run using the current executable path\n let push_flag = if push { \"\" } else { \" --no-push\" };\n let queue_flag = queue_flag_for_command(queue);\n let review_flag = review_flag_for_command(queue);\n let hashed_flag = if include_unhash { \" --hashed\" } else { \"\" };\n let path_flags = stage_paths_cli_flags(stage_paths);\n let flow_bin = std::env::current_exe()\n .ok()\n .map(|p| p.display().to_string())\n .unwrap_or_else(|| \"flow\".to_string());\n let command = format!(\n \"{} commit --sync{}{}{}{}{}\",\n flow_bin, push_flag, queue_flag, review_flag, hashed_flag, path_flags\n );\n\n let url = format!(\"http://{}:{}/tasks/run\", HUB_HOST, HUB_PORT);\n let client = crate::http_client::blocking_with_timeout(Duration::from_secs(5))\n .context(\"failed to create HTTP client\")?;\n\n let payload = json!({\n \"task\": {\n \"name\": \"commit\",\n \"command\": command,\n \"dependencies\": {\n \"commands\": [],\n \"flox\": [],\n },\n },\n \"cwd\": repo_root.to_string_lossy(),\n \"flow_version\": env!(\"CARGO_PKG_VERSION\"),\n });\n\n let resp = client\n .post(&url)\n .json(&payload)\n .send()\n .context(\"failed to submit commit to hub\")?;\n\n if resp.status().is_success() {\n // Parse response to get task_id\n let body: serde_json::Value = resp.json().unwrap_or_default();\n if let Some(task_id) = body.get(\"task_id\").and_then(|v| v.as_str()) {\n println!(\"Delegated commit to hub\");\n println!(\" View logs: f logs --task-id {}\", task_id);\n println!(\" Stream logs: f logs --task-id {} --follow\", task_id);\n } else {\n println!(\"Delegated commit to hub\");\n }\n Ok(())\n } else {\n let body = resp.text().unwrap_or_default();\n bail!(\"hub returned error: {}\", body);\n }\n}\n\nfn delegate_to_hub_with_check(\n command_name: &str,\n push: bool,\n include_context: bool,\n review_selection: ReviewSelection,\n author_message: Option<&str>,\n max_tokens: usize,\n queue: CommitQueueMode,\n include_unhash: bool,\n stage_paths: &[String],\n gate_overrides: CommitGateOverrides,\n) -> Result<()> {\n let repo_root = resolve_commit_with_check_root()?;\n warn_if_commit_invoked_from_subdir(&repo_root);\n\n // Generate early gitedit hash from session IDs + owner/repo\n let early_gitedit_url = generate_early_gitedit_url(&repo_root);\n\n // Build the command to run using the current executable path\n let push_flag = if push { \"\" } else { \" --no-push\" };\n let queue_flag = queue_flag_for_command(queue);\n let review_flag = review_flag_for_command(queue);\n let context_flag = if include_context { \" --context\" } else { \"\" };\n let codex_flag = if review_selection.is_codex() {\n \" --codex\"\n } else {\n \"\"\n };\n let message_flag = author_message\n .map(|m| format!(\" --message {:?}\", m))\n .unwrap_or_default();\n let review_model_flag = review_selection\n .review_model_arg()\n .map(|arg| format!(\" --review-model {}\", arg.as_arg()))\n .unwrap_or_default();\n let hashed_flag = if include_unhash { \" --hashed\" } else { \"\" };\n let skip_quality_flag = if gate_overrides.skip_quality {\n \" --skip-quality\"\n } else {\n \"\"\n };\n let skip_docs_flag = if gate_overrides.skip_docs {\n \" --skip-docs\"\n } else {\n \"\"\n };\n let skip_tests_flag = if gate_overrides.skip_tests {\n \" --skip-tests\"\n } else {\n \"\"\n };\n let path_flags = stage_paths_cli_flags(stage_paths);\n let flow_bin = std::env::current_exe()\n .ok()\n .map(|p| p.display().to_string())\n .unwrap_or_else(|| \"flow\".to_string());\n let command = format!(\n \"{} {} --sync{}{}{}{}{}{}{}{}{}{}{}{} --tokens {}\",\n flow_bin,\n command_name,\n push_flag,\n context_flag,\n codex_flag,\n review_model_flag,\n message_flag,\n queue_flag,\n review_flag,\n hashed_flag,\n skip_quality_flag,\n skip_docs_flag,\n skip_tests_flag,\n path_flags,\n max_tokens\n );\n\n let url = format!(\"http://{}:{}/tasks/run\", HUB_HOST, HUB_PORT);\n let client = crate::http_client::blocking_with_timeout(Duration::from_secs(5))\n .context(\"failed to create HTTP client\")?;\n\n let payload = json!({\n \"task\": {\n \"name\": command_name,\n \"command\": command,\n \"dependencies\": {\n \"commands\": [],\n \"flox\": [],\n },\n },\n \"cwd\": repo_root.to_string_lossy(),\n \"flow_version\": env!(\"CARGO_PKG_VERSION\"),\n });\n\n let resp = client\n .post(&url)\n .json(&payload)\n .send()\n .context(\"failed to submit commitWithCheck to hub\")?;\n\n if resp.status().is_success() {\n // Parse response to get task_id\n let body: serde_json::Value = resp.json().unwrap_or_default();\n if let Some(task_id) = body.get(\"task_id\").and_then(|v| v.as_str()) {\n println!(\"Delegated {} to hub\", command_name);\n println!(\" View logs: f logs --task-id {}\", task_id);\n println!(\" Stream logs: f logs --task-id {} --follow\", task_id);\n if let Some(gitedit_url) = early_gitedit_url {\n println!(\" GitEdit: {}\", gitedit_url);\n }\n } else {\n println!(\"Delegated {} to hub\", command_name);\n }\n Ok(())\n } else {\n let body = resp.text().unwrap_or_default();\n bail!(\"hub returned error: {}\", body);\n }\n}\n\n/// Generate gitedit URL early from session IDs (before full data load).\nfn generate_early_gitedit_url(repo_root: &std::path::Path) -> Option<String> {\n // Check if gitedit is globally enabled\n if !gitedit_globally_enabled() {\n return None;\n }\n\n // Get owner/repo\n let (owner, repo) = get_gitedit_project(repo_root)?;\n\n // Get session IDs and checkpoint for hashing\n let (session_ids, checkpoint_ts) =\n ai::get_session_ids_for_hash(&repo_root.to_path_buf()).ok()?;\n\n if session_ids.is_empty() {\n return None;\n }\n\n // Generate hash from owner/repo + session IDs + checkpoint\n let mut hasher = DefaultHasher::new();\n owner.hash(&mut hasher);\n repo.hash(&mut hasher);\n for sid in &session_ids {\n sid.hash(&mut hasher);\n }\n if let Some(ts) = &checkpoint_ts {\n ts.hash(&mut hasher);\n }\n let hash = format!(\"{:016x}\", hasher.finish());\n\n let base_url = gitedit_api_url(repo_root);\n let base_url = base_url.trim_end_matches('/');\n Some(format!(\"{}/{}\", base_url, hash))\n}\n\n// ─────────────────────────────────────────────────────────────\n// Pre-commit fixers\n// ─────────────────────────────────────────────────────────────\n\n/// Run pre-commit fixers from [commit] config.\npub fn run_fixers(repo_root: &Path) -> Result<bool> {\n let config_path = repo_root.join(\"flow.toml\");\n let config = if config_path.exists() {\n config::load(&config_path)?\n } else {\n return Ok(false);\n };\n\n let commit_cfg = match &config.commit {\n Some(c) if !c.fixers.is_empty() => c,\n _ => return Ok(false),\n };\n\n let mut any_fixed = false;\n\n for fixer in &commit_cfg.fixers {\n match run_fixer(repo_root, fixer) {\n Ok(fixed) => {\n if fixed {\n any_fixed = true;\n }\n }\n Err(e) => {\n eprintln!(\"Fixer '{}' failed: {}\", fixer, e);\n }\n }\n }\n\n Ok(any_fixed)\n}\n\n/// Run a single fixer. Returns true if any files were modified.\nfn run_fixer(repo_root: &Path, fixer: &str) -> Result<bool> {\n // Custom command: \"cmd:prettier --write\"\n if let Some(cmd) = fixer.strip_prefix(\"cmd:\") {\n return run_action_script(repo_root, cmd);\n }\n\n // Check for script in .ai/actions/\n let action_path = repo_root.join(\".ai/actions\").join(fixer);\n if action_path.exists() {\n return run_action_script(repo_root, action_path.to_str().unwrap_or(fixer));\n }\n\n // Fallback to built-in fixers\n match fixer {\n \"mdx-comments\" => fix_mdx_comments(repo_root),\n \"trailing-whitespace\" => fix_trailing_whitespace(repo_root),\n \"end-of-file\" => fix_end_of_file(repo_root),\n \"lowercase-filenames\" => fix_lowercase_filenames(repo_root),\n _ => {\n debug!(\"Unknown fixer and no .ai/actions/{} script found\", fixer);\n Ok(false)\n }\n }\n}\n\n/// Run an action script from .ai/actions/ or a custom command.\nfn run_action_script(repo_root: &Path, cmd: &str) -> Result<bool> {\n let display_name = cmd.strip_prefix(\".ai/actions/\").unwrap_or(cmd);\n println!(\"Running: {}\", display_name);\n\n let status = Command::new(\"sh\")\n .arg(\"-c\")\n .arg(cmd)\n .current_dir(repo_root)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()?;\n\n Ok(status.success())\n}\n\n/// Fix MDX comments: convert <!-- --> to {/* */}\nfn fix_mdx_comments(repo_root: &Path) -> Result<bool> {\n // Quick check: any HTML comments in MDX files?\n let check = Command::new(\"git\")\n .args([\"grep\", \"-l\", \"<!--\", \"--\", \"*.mdx\", \"**/*.mdx\"])\n .current_dir(repo_root)\n .output()?;\n\n let files_with_issues: Vec<_> = String::from_utf8_lossy(&check.stdout)\n .lines()\n .filter(|l| !l.is_empty())\n .map(|l| repo_root.join(l))\n .collect();\n\n if files_with_issues.is_empty() {\n return Ok(false);\n }\n\n let mut fixed_any = false;\n for file in files_with_issues {\n if let Ok(content) = fs::read_to_string(&file) {\n let fixed = fix_html_comments_to_jsx(&content);\n if fixed != content {\n fs::write(&file, &fixed)?;\n println!(\" Fixed MDX comments: {}\", file.display());\n fixed_any = true;\n }\n }\n }\n\n if fixed_any {\n println!(\"✓ Fixed MDX comments\");\n }\n\n Ok(fixed_any)\n}\n\n/// Convert HTML comments to JSX comments in MDX content.\nfn fix_html_comments_to_jsx(content: &str) -> String {\n let mut result = String::with_capacity(content.len());\n let mut chars = content.chars().peekable();\n\n while let Some(c) = chars.next() {\n if c == '<' && chars.peek() == Some(&'!') {\n // Potential HTML comment\n let mut buf = String::from(\"<\");\n buf.push(chars.next().unwrap()); // !\n\n // Check for --\n if chars.peek() == Some(&'-') {\n buf.push(chars.next().unwrap()); // first -\n if chars.peek() == Some(&'-') {\n buf.push(chars.next().unwrap()); // second -\n\n // Found <!--, now collect until -->\n let mut comment_content = String::new();\n loop {\n match chars.next() {\n Some('-') => {\n if chars.peek() == Some(&'-') {\n chars.next(); // consume second -\n if chars.peek() == Some(&'>') {\n chars.next(); // consume >\n // Found -->, convert to JSX comment\n result.push_str(\"{/* \");\n result.push_str(comment_content.trim());\n result.push_str(\" */}\");\n break;\n } else {\n comment_content.push_str(\"--\");\n }\n } else {\n comment_content.push('-');\n }\n }\n Some(ch) => comment_content.push(ch),\n None => {\n // Unclosed comment, keep original\n result.push_str(&buf);\n result.push_str(&comment_content);\n break;\n }\n }\n }\n continue;\n }\n }\n result.push_str(&buf);\n } else {\n result.push(c);\n }\n }\n\n result\n}\n\n/// Fix trailing whitespace in text files.\nfn fix_trailing_whitespace(repo_root: &Path) -> Result<bool> {\n // Quick check: any trailing whitespace in working directory changes?\n let check = Command::new(\"git\")\n .args([\"diff\", \"--check\"])\n .current_dir(repo_root)\n .output()?;\n\n // --check exits non-zero and outputs lines if there's trailing whitespace\n if check.stdout.is_empty() {\n return Ok(false);\n }\n\n let mut fixed_any = false;\n\n // Get modified/new text files (unstaged)\n let output = Command::new(\"git\")\n .args([\"diff\", \"--name-only\", \"--diff-filter=ACMR\"])\n .current_dir(repo_root)\n .output()?;\n\n let files: Vec<_> = String::from_utf8_lossy(&output.stdout)\n .lines()\n .filter(|l| !l.is_empty())\n .map(|l| repo_root.join(l))\n .collect();\n\n for file in files {\n if !file.exists() || is_binary(&file) {\n continue;\n }\n if let Ok(content) = fs::read_to_string(&file) {\n let fixed: String = content\n .lines()\n .map(|line| line.trim_end())\n .collect::<Vec<_>>()\n .join(\"\\n\");\n\n // Preserve original line ending\n let fixed = if content.ends_with('\\n') && !fixed.ends_with('\\n') {\n format!(\"{}\\n\", fixed)\n } else {\n fixed\n };\n\n if fixed != content {\n fs::write(&file, &fixed)?;\n println!(\" Trimmed whitespace: {}\", file.display());\n fixed_any = true;\n }\n }\n }\n\n if fixed_any {\n println!(\"✓ Fixed trailing whitespace\");\n }\n\n Ok(fixed_any)\n}\n\n/// Ensure files end with a newline.\nfn fix_end_of_file(repo_root: &Path) -> Result<bool> {\n // Quick check: any files missing final newline in working directory?\n let check = Command::new(\"git\")\n .args([\"diff\"])\n .current_dir(repo_root)\n .output()?;\n\n let diff_output = String::from_utf8_lossy(&check.stdout);\n if !diff_output.contains(\"\\\\ No newline at end of file\") {\n return Ok(false);\n }\n\n let mut fixed_any = false;\n\n let output = Command::new(\"git\")\n .args([\"diff\", \"--name-only\", \"--diff-filter=ACMR\"])\n .current_dir(repo_root)\n .output()?;\n\n let files: Vec<_> = String::from_utf8_lossy(&output.stdout)\n .lines()\n .filter(|l| !l.is_empty())\n .map(|l| repo_root.join(l))\n .collect();\n\n for file in files {\n if !file.exists() || is_binary(&file) {\n continue;\n }\n if let Ok(content) = fs::read_to_string(&file) {\n if !content.is_empty() && !content.ends_with('\\n') {\n fs::write(&file, format!(\"{}\\n\", content))?;\n println!(\" Added newline: {}\", file.display());\n fixed_any = true;\n }\n }\n }\n\n if fixed_any {\n println!(\"✓ Fixed end of file newlines\");\n }\n\n Ok(fixed_any)\n}\n\n/// Rename staged files with uppercase basenames to lowercase.\nfn fix_lowercase_filenames(repo_root: &Path) -> Result<bool> {\n // Get staged new/renamed files\n let output = Command::new(\"git\")\n .args([\"diff\", \"--cached\", \"--name-only\", \"--diff-filter=ACR\"])\n .current_dir(repo_root)\n .output()?;\n\n let files: Vec<String> = String::from_utf8_lossy(&output.stdout)\n .lines()\n .filter(|l| !l.is_empty())\n .map(|l| l.to_string())\n .collect();\n\n let mut fixed_any = false;\n\n for file in &files {\n let path = Path::new(file);\n let basename = match path.file_name().and_then(|n| n.to_str()) {\n Some(n) => n,\n None => continue,\n };\n\n if !basename.chars().any(|c| c.is_ascii_uppercase()) {\n continue;\n }\n\n let lower = basename.to_ascii_lowercase();\n let new_path = match path.parent() {\n Some(p) if p != Path::new(\"\") => p.join(&lower),\n _ => PathBuf::from(&lower),\n };\n\n let status = Command::new(\"git\")\n .args([\"mv\", file, new_path.to_str().unwrap_or(&lower)])\n .current_dir(repo_root)\n .output()?;\n\n if status.status.success() {\n println!(\" Renamed: {} → {}\", file, new_path.display());\n fixed_any = true;\n }\n }\n\n if fixed_any {\n println!(\"✓ Fixed uppercase filenames\");\n }\n\n Ok(fixed_any)\n}\n\n/// Simple binary file detection.\nfn is_binary(path: &Path) -> bool {\n let ext = path.extension().and_then(|e| e.to_str()).unwrap_or(\"\");\n matches!(\n ext,\n \"png\"\n | \"jpg\"\n | \"jpeg\"\n | \"gif\"\n | \"ico\"\n | \"webp\"\n | \"svg\"\n | \"woff\"\n | \"woff2\"\n | \"ttf\"\n | \"otf\"\n | \"eot\"\n | \"zip\"\n | \"tar\"\n | \"gz\"\n | \"rar\"\n | \"7z\"\n | \"pdf\"\n | \"doc\"\n | \"docx\"\n | \"xls\"\n | \"xlsx\"\n | \"exe\"\n | \"dll\"\n | \"so\"\n | \"dylib\"\n | \"mp3\"\n | \"mp4\"\n | \"wav\"\n | \"avi\"\n | \"mov\"\n )\n}\n\n/// Get review instructions from [commit] config or .ai/ folder.\npub fn get_review_instructions(repo_root: &Path) -> Option<String> {\n // Check config first\n let config_path = repo_root.join(\"flow.toml\");\n if let Ok(config) = config::load(&config_path) {\n if let Some(commit_cfg) = config.commit.as_ref() {\n // Try inline instructions\n if let Some(instructions) = &commit_cfg.review_instructions {\n return Some(instructions.clone());\n }\n\n // Try loading from configured file\n if let Some(file_path) = &commit_cfg.review_instructions_file {\n let full_path = repo_root.join(file_path);\n if let Ok(content) = fs::read_to_string(full_path) {\n return Some(content);\n }\n }\n }\n }\n\n // Auto-discover from .ai/ folder (no config needed)\n let candidates = [\n \".ai/review.md\",\n \".ai/commit-review.md\",\n \".ai/instructions.md\",\n ];\n\n for candidate in candidates {\n let path = repo_root.join(candidate);\n if let Ok(content) = fs::read_to_string(&path) {\n return Some(content);\n }\n }\n\n None\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use tempfile::tempdir;\n\n #[test]\n fn ai_scratch_tests_are_excluded_from_related_tests() {\n let repo_root = Path::new(\".\");\n let changed = vec![\n \".ai/test/generated/auth-flow.test.ts\".to_string(),\n \"mobile/src/pages/chats/home/ui/ChatsList.test.tsx\".to_string(),\n ];\n\n let related = find_related_tests(repo_root, &changed, \".ai/test\");\n assert_eq!(\n related,\n vec![\"mobile/src/pages/chats/home/ui/ChatsList.test.tsx\".to_string()]\n );\n }\n\n #[test]\n fn path_within_dir_handles_relative_prefixes() {\n assert!(path_is_within_dir(\"./.ai/test/foo.test.ts\", \".ai/test\"));\n assert!(path_is_within_dir(\".ai/test\", \".ai/test\"));\n assert!(!path_is_within_dir(\"mobile/src/foo.test.ts\", \".ai/test\"));\n }\n\n #[test]\n fn commit_message_selection_parsing_supports_fallback_specs() {\n assert!(matches!(\n parse_commit_message_selection_spec(\"remote\"),\n Some(CommitMessageSelection::Remote)\n ));\n assert!(matches!(\n parse_commit_message_selection_spec(\"openai\"),\n Some(CommitMessageSelection::OpenAi)\n ));\n assert!(matches!(\n parse_commit_message_selection_spec(\"heuristic\"),\n Some(CommitMessageSelection::Heuristic)\n ));\n\n match parse_commit_message_selection_spec(\"openrouter:moonshotai/kimi-k2\") {\n Some(CommitMessageSelection::OpenRouter { model }) => {\n assert_eq!(model, \"moonshotai/kimi-k2\")\n }\n _ => panic!(\"expected openrouter message selection\"),\n }\n\n match parse_commit_message_selection_with_model(\n \"rise\",\n Some(\"zai:glm-4.7-thinking\".to_string()),\n ) {\n Some(CommitMessageSelection::Rise { model }) => {\n assert_eq!(model, \"zai:glm-4.7-thinking\")\n }\n _ => panic!(\"expected rise message selection\"),\n }\n }\n\n #[test]\n fn deterministic_commit_message_includes_changed_files() {\n let diff = format!(\n \"{} b/src/lib.rs\\n+added\\n{} b/src/main.rs\\n+added\",\n \"+++\", \"+++\"\n );\n let message = build_deterministic_commit_message(&diff);\n assert!(message.starts_with(\"Update 2 files\"));\n assert!(message.contains(\"- src/lib.rs\"));\n assert!(message.contains(\"- src/main.rs\"));\n }\n\n #[test]\n fn glm5_alias_maps_to_rise_selection() {\n match parse_review_selection_spec(\"glm5\") {\n Some(ReviewSelection::Rise { model }) => assert_eq!(model, DEFAULT_GLM5_RISE_MODEL),\n _ => panic!(\"expected glm5 to map to rise review selection\"),\n }\n\n match parse_commit_message_selection_spec(\"glm5\") {\n Some(CommitMessageSelection::Rise { model }) => {\n assert_eq!(model, DEFAULT_GLM5_RISE_MODEL)\n }\n _ => panic!(\"expected glm5 to map to rise commit message selection\"),\n }\n }\n\n #[test]\n fn normalize_markdown_linebreaks_decodes_literal_newlines() {\n let input = \"## Summary\\\\n- one\\\\n- two\\\\n\\\\n## Why\\\\n- because\";\n let out = normalize_markdown_linebreaks(input);\n assert!(out.contains(\"## Summary\\n- one\\n- two\"));\n assert!(out.contains(\"\\n\\n## Why\\n- because\"));\n }\n\n #[test]\n fn normalize_markdown_linebreaks_preserves_existing_multiline_text() {\n let input = \"## Summary\\n- already\\n- multiline\";\n let out = normalize_markdown_linebreaks(input);\n assert_eq!(out, input);\n }\n\n #[test]\n fn normalize_codex_bin_value_expands_tilde_paths() {\n let expected = config::expand_path(\"~/code/flow/scripts/codex-flow-wrapper\")\n .to_string_lossy()\n .into_owned();\n assert_eq!(\n normalize_codex_bin_value(\"~/code/flow/scripts/codex-flow-wrapper\"),\n expected\n );\n }\n\n #[test]\n fn configured_codex_bin_for_workdir_uses_expanded_global_path() {\n let global_cfg = config::default_config_path();\n let backup = fs::read_to_string(&global_cfg).ok();\n let root = global_cfg\n .parent()\n .expect(\"global config dir\")\n .to_path_buf();\n fs::create_dir_all(&root).expect(\"create global config dir\");\n fs::write(\n &global_cfg,\n \"[options]\\ncodex_bin = \\\"~/code/flow/scripts/codex-flow-wrapper\\\"\\n\",\n )\n .expect(\"write global codex config\");\n\n let temp = tempdir().expect(\"tempdir\");\n let resolved = configured_codex_bin_for_workdir(temp.path());\n let expected = config::expand_path(\"~/code/flow/scripts/codex-flow-wrapper\")\n .to_string_lossy()\n .into_owned();\n assert_eq!(resolved, expected);\n\n match backup {\n Some(content) => fs::write(&global_cfg, content).expect(\"restore global config\"),\n None => {\n let _ = fs::remove_file(&global_cfg);\n }\n }\n }\n\n #[test]\n fn invariants_dep_check_flags_unapproved_dependencies() {\n let package_json = r#\"{\n \"dependencies\": { \"react\": \"^18.0.0\", \"@reatom/core\": \"^3.0.0\" },\n \"devDependencies\": { \"vitest\": \"^1.0.0\" }\n }\"#;\n let approved = vec![\"@reatom/core\".to_string(), \"vitest\".to_string()];\n let mut findings = Vec::new();\n\n check_unapproved_deps(package_json, &approved, \"package.json\", &mut findings);\n\n assert_eq!(findings.len(), 1);\n assert_eq!(findings[0].category, \"deps\");\n assert!(findings[0].message.contains(\"react\"));\n assert_eq!(findings[0].file.as_deref(), Some(\"package.json\"));\n }\n\n #[test]\n fn invariant_prompt_context_includes_rules_and_findings() {\n let mut terminology = HashMap::new();\n terminology.insert(\"Flow\".to_string(), \"CLI tool\".to_string());\n let inv = config::InvariantsConfig {\n architecture_style: Some(\"event-driven\".to_string()),\n non_negotiable: vec![\"no inline imports\".to_string()],\n terminology,\n ..Default::default()\n };\n let report = InvariantGateReport {\n findings: vec![InvariantFinding {\n severity: \"warning\".to_string(),\n category: \"forbidden\".to_string(),\n message: \"Forbidden pattern 'useState(' in added line\".to_string(),\n file: Some(\"web/app.tsx\".to_string()),\n }],\n };\n\n let ctx = report.to_prompt_context(&inv);\n assert!(ctx.contains(\"Project Invariants\"));\n assert!(ctx.contains(\"Architecture: event-driven\"));\n assert!(ctx.contains(\"no inline imports\"));\n assert!(ctx.contains(\"Flow: CLI tool\"));\n assert!(ctx.contains(\"web/app.tsx\"));\n assert!(ctx.contains(\"Forbidden pattern\"));\n }\n\n #[test]\n fn parse_pr_feedback_args_accepts_full_flag() {\n let parsed = parse_pr_feedback_args(&[\n \"feedback\".to_string(),\n \"2922\".to_string(),\n \"--full\".to_string(),\n ])\n .expect(\"parse\")\n .expect(\"command\");\n\n assert_eq!(parsed.selector.as_deref(), Some(\"2922\"));\n assert!(parsed.show_full);\n assert!(!parsed.record_todos);\n assert!(!parsed.open_cursor);\n }\n\n #[test]\n fn parse_pr_feedback_args_defaults_to_full_output() {\n let parsed = parse_pr_feedback_args(&[\"feedback\".to_string(), \"2922\".to_string()])\n .expect(\"parse\")\n .expect(\"command\");\n\n assert_eq!(parsed.selector.as_deref(), Some(\"2922\"));\n assert!(parsed.show_full);\n assert!(!parsed.open_cursor);\n }\n\n #[test]\n fn parse_pr_feedback_args_accepts_compact_flag() {\n let parsed = parse_pr_feedback_args(&[\n \"feedback\".to_string(),\n \"2922\".to_string(),\n \"--compact\".to_string(),\n ])\n .expect(\"parse\")\n .expect(\"command\");\n\n assert_eq!(parsed.selector.as_deref(), Some(\"2922\"));\n assert!(!parsed.show_full);\n assert!(!parsed.open_cursor);\n }\n\n #[test]\n fn parse_pr_feedback_args_accepts_cursor_flag() {\n let parsed = parse_pr_feedback_args(&[\n \"feedback\".to_string(),\n \"2922\".to_string(),\n \"--cursor\".to_string(),\n ])\n .expect(\"parse\")\n .expect(\"command\");\n\n assert_eq!(parsed.selector.as_deref(), Some(\"2922\"));\n assert!(parsed.open_cursor);\n }\n\n #[test]\n fn write_pr_feedback_review_plan_includes_snapshot_and_kit_input() {\n let temp = tempdir().expect(\"tempdir\");\n let snapshot_path = temp.path().join(\".ai/reviews/pr-feedback-2922.md\");\n let json_path = temp.path().join(\".ai/reviews/pr-feedback-2922.json\");\n fs::create_dir_all(snapshot_path.parent().expect(\"snapshot parent\")).expect(\"mkdirs\");\n fs::write(&snapshot_path, \"# snapshot\\n\").expect(\"write snapshot\");\n fs::write(&json_path, \"{}\\n\").expect(\"write json snapshot\");\n\n let snapshot = PrFeedbackSnapshot {\n repo: \"fl2024008/prometheus\".to_string(),\n pr_number: 2922,\n pr_url: \"https://github.com/fl2024008/prometheus/pull/2922\".to_string(),\n pr_title: \"feat(designer): add build123d Python live viewer\".to_string(),\n trace_id: \"trace-2922\".to_string(),\n generated_at: \"2026-03-17T15:00:00Z\".to_string(),\n reviews_count: 1,\n review_comments_count: 1,\n issue_comments_count: 0,\n review_state_counts: HashMap::from([(\"CHANGES_REQUESTED\".to_string(), 1usize)]),\n items: vec![PrFeedbackItem {\n external_ref: \"ref\".to_string(),\n source: \"review-comment\",\n author: \"reviewer\".to_string(),\n body: \"Please move this logic.\".to_string(),\n url: \"https://github.com/example\".to_string(),\n thread_id: None,\n path: Some(\"src/file.ts\".to_string()),\n line: Some(42),\n review_state: None,\n diff_hunk: Some(\"@@ -1,2 +1,2 @@\\n-old\\n+new\".to_string()),\n }],\n };\n\n let plan_root = temp.path().join(\"review-plans\");\n fs::create_dir_all(&plan_root).expect(\"plan root\");\n let plan_path = write_pr_feedback_review_plan_at(\n &plan_root,\n temp.path(),\n &snapshot,\n &snapshot_path,\n &json_path,\n )\n .expect(\"write plan\");\n let body = fs::read_to_string(&plan_path).expect(\"read plan\");\n assert!(body.contains(\"# [feat(designer): add build123d Python live viewer](https://github.com/fl2024008/prometheus/pull/2922)\"));\n assert!(body.contains(\"## Cursor Review\"));\n assert!(body.contains(\"Snapshot (markdown):\"));\n assert!(body.contains(\"Trace ID: `trace-2922`\"));\n assert!(body.contains(\"## Kit Commands\"));\n assert!(body.contains(\"--feedback-auto --preset designer\"));\n assert!(body.contains(\n \"f pr feedback https://github.com/fl2024008/prometheus/pull/2922 --compact --cursor\"\n ));\n assert!(body.contains(\"### Diff Hunk\"));\n assert!(body.contains(\"### Concern Status\"));\n assert!(body.contains(\"The reviewer is asking for intent and ownership\"));\n assert!(body.contains(\"The diff likely moved or extracted code to clean up structure\"));\n assert!(body.contains(\"Make the smallest placement or naming change in file.ts:42\"));\n assert!(body.contains(\"Open the affected the product flow\"));\n assert!(body.contains(\"when moving logic across component or module boundaries\"));\n assert!(body.contains(\"### Kit Upgrade\"));\n assert!(body.contains(\"### Status\"));\n assert!(body.contains(\"## Kit Input\"));\n assert!(plan_path.ends_with(\"fl2024008-prometheus-pr-2922-feedback.md\"));\n }\n\n #[test]\n fn write_pr_feedback_review_rules_mentions_artifacts() {\n let temp = tempdir().expect(\"tempdir\");\n let snapshot_path = temp.path().join(\".ai/reviews/pr-feedback-2922.md\");\n let json_path = temp.path().join(\".ai/reviews/pr-feedback-2922.json\");\n let review_plan_path = temp\n .path()\n .join(\"review/fl2024008-prometheus-pr-2922-feedback.md\");\n let kit_system_path = temp\n .path()\n .join(\"review/fl2024008-prometheus-pr-2922-kit-system.md\");\n fs::create_dir_all(snapshot_path.parent().expect(\"snapshot parent\")).expect(\"mkdirs\");\n fs::create_dir_all(review_plan_path.parent().expect(\"review plan parent\")).expect(\"mkdirs\");\n fs::write(&snapshot_path, \"# snapshot\\n\").expect(\"write snapshot\");\n fs::write(&json_path, \"{}\\n\").expect(\"write json snapshot\");\n fs::write(&review_plan_path, \"# plan\\n\").expect(\"write review plan\");\n fs::write(&kit_system_path, \"# kit\\n\").expect(\"write kit prompt\");\n\n let snapshot = PrFeedbackSnapshot {\n repo: \"fl2024008/prometheus\".to_string(),\n pr_number: 2922,\n pr_url: \"https://github.com/fl2024008/prometheus/pull/2922\".to_string(),\n pr_title: \"feat(designer): add build123d Python live viewer\".to_string(),\n trace_id: \"trace-2922\".to_string(),\n generated_at: \"2026-03-17T15:00:00Z\".to_string(),\n reviews_count: 1,\n review_comments_count: 1,\n issue_comments_count: 0,\n review_state_counts: HashMap::from([(\"CHANGES_REQUESTED\".to_string(), 1usize)]),\n items: vec![],\n };\n\n let plan_root = temp.path().join(\"review-plans\");\n fs::create_dir_all(&plan_root).expect(\"plan root\");\n let review_rules_path = write_pr_feedback_review_rules_at(\n &plan_root,\n temp.path(),\n &snapshot,\n &snapshot_path,\n &json_path,\n &review_plan_path,\n &kit_system_path,\n )\n .expect(\"write review rules\");\n let body = fs::read_to_string(&review_rules_path).expect(\"read review rules\");\n assert!(\n body.contains(\"Generated operator artifact for resolving PR feedback item by item\")\n );\n assert!(body.contains(&snapshot_path.display().to_string()));\n assert!(body.contains(&json_path.display().to_string()));\n assert!(body.contains(&review_plan_path.display().to_string()));\n assert!(body.contains(&kit_system_path.display().to_string()));\n assert!(body.contains(\"## One-Item Loop\"));\n assert!(body.contains(\"## Prompt Template\"));\n assert!(body.contains(\"Decide the Concern Status first\"));\n assert!(body.contains(\"- Concern Status\"));\n assert!(body.contains(\"- `Concern Status`\"));\n assert!(review_rules_path.ends_with(\"fl2024008-prometheus-pr-2922-review-rules.md\"));\n }\n\n #[test]\n fn write_pr_feedback_kit_system_prompt_mentions_artifacts() {\n let temp = tempdir().expect(\"tempdir\");\n let snapshot_path = temp.path().join(\".ai/reviews/pr-feedback-2922.md\");\n let json_path = temp.path().join(\".ai/reviews/pr-feedback-2922.json\");\n let review_plan_path = temp\n .path()\n .join(\"review/fl2024008-prometheus-pr-2922-feedback.md\");\n fs::create_dir_all(snapshot_path.parent().expect(\"snapshot parent\")).expect(\"mkdirs\");\n fs::create_dir_all(review_plan_path.parent().expect(\"review plan parent\")).expect(\"mkdirs\");\n fs::write(&snapshot_path, \"# snapshot\\n\").expect(\"write snapshot\");\n fs::write(&json_path, \"{}\\n\").expect(\"write json snapshot\");\n fs::write(&review_plan_path, \"# plan\\n\").expect(\"write review plan\");\n\n let snapshot = PrFeedbackSnapshot {\n repo: \"fl2024008/prometheus\".to_string(),\n pr_number: 2922,\n pr_url: \"https://github.com/fl2024008/prometheus/pull/2922\".to_string(),\n pr_title: \"feat(designer): add build123d Python live viewer\".to_string(),\n trace_id: \"trace-2922\".to_string(),\n generated_at: \"2026-03-17T15:00:00Z\".to_string(),\n reviews_count: 1,\n review_comments_count: 1,\n issue_comments_count: 0,\n review_state_counts: HashMap::from([(\"CHANGES_REQUESTED\".to_string(), 1usize)]),\n items: vec![],\n };\n\n let plan_root = temp.path().join(\"review-plans\");\n fs::create_dir_all(&plan_root).expect(\"plan root\");\n let kit_system_path = write_pr_feedback_kit_system_prompt_at(\n &plan_root,\n &snapshot,\n &snapshot_path,\n &json_path,\n &review_plan_path,\n )\n .expect(\"write kit prompt\");\n let body = fs::read_to_string(&kit_system_path).expect(\"read kit prompt\");\n assert!(body.contains(\"Kit PR Feedback Prevention System Prompt\"));\n assert!(body.contains(&snapshot_path.display().to_string()));\n assert!(body.contains(&json_path.display().to_string()));\n assert!(body.contains(&review_plan_path.display().to_string()));\n assert!(kit_system_path.ends_with(\"fl2024008-prometheus-pr-2922-kit-system.md\"));\n }\n}\n" }, { "path": "src/commits.rs", "content": "//! Browse and analyze git commits with AI session metadata.\n//!\n//! Shows commits with attached AI sessions, reviews, and other metadata.\n\nuse std::collections::HashSet;\nuse std::fs;\nuse std::io::Write;\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::{CommitsAction, CommitsCommand, CommitsOpts};\nuse crate::vcs;\n\nconst TOP_COMMITS_PATH: &str = \".ai/internal/commits/top.txt\";\n\n/// Commit with associated metadata\n#[derive(Debug, Clone)]\nstruct CommitEntry {\n /// Git commit hash (short)\n hash: String,\n /// Full commit hash\n full_hash: String,\n /// Commit subject line (used in display)\n #[allow(dead_code)]\n subject: String,\n /// Relative time (e.g., \"2 hours ago\")\n relative_time: String,\n /// Author name\n author: String,\n /// Whether this commit has AI session metadata\n has_ai_metadata: bool,\n /// Whether this commit is marked notable\n is_top: bool,\n /// Display string for fzf\n display: String,\n}\n\n/// Run the commits subcommand.\npub fn run(cmd: CommitsCommand) -> Result<()> {\n match cmd.action {\n Some(CommitsAction::Top) => run_top(),\n Some(CommitsAction::Mark { hash }) => mark_top_commit(&hash),\n Some(CommitsAction::Unmark { hash }) => unmark_top_commit(&hash),\n None => run_list(&cmd.opts),\n }\n}\n\nfn run_list(opts: &CommitsOpts) -> Result<()> {\n let _ = vcs::ensure_jj_repo()?;\n let top_entries = load_top_entries()?;\n let top_set = top_hashes(&top_entries);\n let commits = list_commits(opts.limit, opts.all, &top_set)?;\n\n if commits.is_empty() {\n println!(\"No commits found.\");\n return Ok(());\n }\n\n // Check for fzf\n if which::which(\"fzf\").is_err() {\n println!(\"fzf not found – install it for fuzzy selection.\");\n println!(\"\\nCommits:\");\n for commit in &commits {\n println!(\"{}\", commit.display);\n }\n return Ok(());\n }\n\n // Run fzf with preview\n println!(\"Tip: press ctrl-t to toggle notable for the selected commit.\");\n if let Some(selection) = run_commits_fzf(&commits)? {\n match selection.action {\n CommitAction::Show => show_commit_details(selection.entry)?,\n CommitAction::ToggleTop => toggle_top_commit(selection.entry)?,\n }\n }\n\n Ok(())\n}\n\nfn run_top() -> Result<()> {\n let top_entries = load_top_entries()?;\n if top_entries.is_empty() {\n println!(\"No notable commits yet.\");\n return Ok(());\n }\n\n let commits = list_commits_by_hashes(&top_entries)?;\n if commits.is_empty() {\n println!(\"No notable commits found.\");\n return Ok(());\n }\n\n if which::which(\"fzf\").is_err() {\n println!(\"fzf not found – install it for fuzzy selection.\");\n println!(\"\\nNotable commits:\");\n for commit in &commits {\n println!(\"{}\", commit.display);\n }\n return Ok(());\n }\n\n println!(\"Tip: press ctrl-t to toggle notable for the selected commit.\");\n if let Some(selection) = run_commits_fzf(&commits)? {\n match selection.action {\n CommitAction::Show => show_commit_details(selection.entry)?,\n CommitAction::ToggleTop => toggle_top_commit(selection.entry)?,\n }\n }\n\n Ok(())\n}\n\nfn mark_top_commit(hash: &str) -> Result<()> {\n let commit = load_commit_by_ref(hash)?.context(\"Commit not found\")?;\n let mut entries = load_top_entries()?;\n if entries.iter().any(|entry| entry.hash == commit.full_hash) {\n println!(\"Commit already marked notable: {}\", commit.hash);\n return Ok(());\n }\n let label = commit.subject.replace('\\t', \" \");\n entries.push(TopEntry {\n hash: commit.full_hash.clone(),\n label: Some(label),\n });\n write_top_entries(&entries)?;\n println!(\"Marked notable: {} {}\", commit.hash, commit.subject);\n Ok(())\n}\n\nfn unmark_top_commit(hash: &str) -> Result<()> {\n let full_hash = resolve_full_hash(hash)?;\n let mut entries = load_top_entries()?;\n let before = entries.len();\n entries.retain(|entry| entry.hash != full_hash);\n if entries.len() == before {\n println!(\"Commit not in notable list: {}\", hash);\n return Ok(());\n }\n write_top_entries(&entries)?;\n println!(\"Removed notable commit: {}\", hash);\n Ok(())\n}\n\n/// List recent commits with metadata.\nfn list_commits(\n limit: usize,\n all_branches: bool,\n top_hashes: &HashSet<String>,\n) -> Result<Vec<CommitEntry>> {\n let mut args = vec![\"log\", \"--pretty=format:%h|%H|%s|%ar|%an\", \"-n\"];\n let limit_str = limit.to_string();\n args.push(&limit_str);\n\n if all_branches {\n args.push(\"--all\");\n }\n\n let output = Command::new(\"git\")\n .args(&args)\n .output()\n .context(\"failed to run git log\")?;\n\n if !output.status.success() {\n bail!(\"git log failed\");\n }\n\n let stdout = String::from_utf8_lossy(&output.stdout);\n let mut commits = Vec::new();\n\n for line in stdout.lines() {\n let parts: Vec<&str> = line.splitn(5, '|').collect();\n if parts.len() < 5 {\n continue;\n }\n\n let hash = parts[0].to_string();\n let full_hash = parts[1].to_string();\n let subject = parts[2].to_string();\n let relative_time = parts[3].to_string();\n let author = parts[4].to_string();\n\n // Check if commit has AI metadata (check git notes or commit trailers)\n let has_ai_metadata = check_ai_metadata(&full_hash);\n let is_top = top_hashes.contains(&full_hash);\n\n // Build display string\n let ai_indicator = if has_ai_metadata { \"◆ \" } else { \" \" };\n let top_indicator = if is_top { \"TOP \" } else { \" \" };\n let pretty = format!(\n \"{}{}{} | {} | {} | {}\",\n top_indicator,\n ai_indicator,\n hash,\n truncate_str(&subject, 50),\n relative_time,\n author\n );\n let display = format!(\"{}\\t{}\", hash, pretty);\n\n commits.push(CommitEntry {\n hash,\n full_hash,\n subject,\n relative_time,\n author,\n has_ai_metadata,\n is_top,\n display,\n });\n }\n\n Ok(commits)\n}\n\nfn list_commits_by_hashes(entries: &[TopEntry]) -> Result<Vec<CommitEntry>> {\n let mut commits = Vec::new();\n for entry in entries {\n if let Some(commit) = load_commit_by_ref(&entry.hash)? {\n commits.push(commit);\n }\n }\n Ok(commits)\n}\n\n/// Check if a commit has AI session metadata attached.\nfn check_ai_metadata(commit_hash: &str) -> bool {\n // Check git notes for AI metadata\n let output = Command::new(\"git\")\n .args([\"notes\", \"show\", commit_hash])\n .output();\n\n if let Ok(output) = output {\n if output.status.success() {\n let notes = String::from_utf8_lossy(&output.stdout);\n if notes.contains(\"ai-session\") || notes.contains(\"claude\") || notes.contains(\"codex\") {\n return true;\n }\n }\n }\n\n // Check commit message for AI-related trailers\n let output = Command::new(\"git\")\n .args([\"log\", \"-1\", \"--format=%B\", commit_hash])\n .output();\n\n if let Ok(output) = output {\n if output.status.success() {\n let body = String::from_utf8_lossy(&output.stdout).to_lowercase();\n if body.contains(\"reviewed-by: codex\")\n || body.contains(\"reviewed-by: claude\")\n || body.contains(\"ai-session:\")\n {\n return true;\n }\n }\n }\n\n false\n}\n\nenum CommitAction {\n Show,\n ToggleTop,\n}\n\nstruct CommitSelection<'a> {\n entry: &'a CommitEntry,\n action: CommitAction,\n}\n\n/// Run fzf with preview for commits.\nfn run_commits_fzf(commits: &[CommitEntry]) -> Result<Option<CommitSelection<'_>>> {\n let mut child = Command::new(\"fzf\")\n .arg(\"--prompt\")\n .arg(\"commits> \")\n .arg(\"--ansi\")\n .arg(\"--header\")\n .arg(\"ctrl-t: toggle notable\")\n .arg(\"--expect\")\n .arg(\"ctrl-t\")\n .arg(\"--delimiter\")\n .arg(\"\\t\")\n .arg(\"--with-nth\")\n .arg(\"2..\")\n .arg(\"--preview\")\n .arg(\"git -c log.showSignature=false show --stat --color=always {1}\")\n .arg(\"--preview-window\")\n .arg(\"down:50%:wrap\")\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n {\n let stdin = child.stdin.as_mut().context(\"failed to open fzf stdin\")?;\n for commit in commits {\n // Write with hash first for preview extraction\n writeln!(stdin, \"{}\", commit.display)?;\n }\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n\n let selection = String::from_utf8(output.stdout).context(\"fzf output was not valid UTF-8\")?;\n let mut lines = selection.lines();\n let key = lines.next().unwrap_or(\"\");\n let selection = lines.next().unwrap_or(\"\").trim();\n\n if selection.is_empty() {\n return Ok(None);\n }\n\n let action = if key == \"ctrl-t\" {\n CommitAction::ToggleTop\n } else {\n CommitAction::Show\n };\n let Some(entry) = commits.iter().find(|c| c.display == selection) else {\n return Ok(None);\n };\n Ok(Some(CommitSelection { entry, action }))\n}\n\n/// Show detailed commit information including AI metadata.\nfn show_commit_details(commit: &CommitEntry) -> Result<()> {\n println!(\"\\n────────────────────────────────────────\");\n println!(\"Commit: {} ({})\", commit.hash, commit.relative_time);\n println!(\"Author: {}\", commit.author);\n if commit.is_top {\n println!(\"Notable: yes\");\n }\n println!(\"────────────────────────────────────────\\n\");\n\n // Show commit message\n let output = Command::new(\"git\")\n .args([\"log\", \"-1\", \"--format=%B\", &commit.full_hash])\n .output()\n .context(\"failed to get commit message\")?;\n\n if output.status.success() {\n let message = String::from_utf8_lossy(&output.stdout);\n println!(\"Message:\\n{}\", message);\n }\n\n // Show AI metadata if present\n if commit.has_ai_metadata {\n println!(\"────────────────────────────────────────\");\n println!(\"AI Session Metadata:\");\n println!(\"────────────────────────────────────────\\n\");\n\n // Try to get notes\n let notes_output = Command::new(\"git\")\n .args([\"notes\", \"show\", &commit.full_hash])\n .output();\n\n if let Ok(notes) = notes_output {\n if notes.status.success() {\n let notes_content = String::from_utf8_lossy(¬es.stdout);\n println!(\"{}\", notes_content);\n }\n }\n }\n\n // Show files changed\n println!(\"────────────────────────────────────────\");\n println!(\"Files Changed:\");\n println!(\"────────────────────────────────────────\\n\");\n\n let files_output = Command::new(\"git\")\n .args([\"show\", \"--stat\", \"--format=\", &commit.full_hash])\n .output()\n .context(\"failed to get files changed\")?;\n\n if files_output.status.success() {\n let files = String::from_utf8_lossy(&files_output.stdout);\n println!(\"{}\", files);\n }\n\n Ok(())\n}\n\n/// Truncate a string to a maximum length, adding \"...\" if truncated.\nfn truncate_str(s: &str, max_len: usize) -> String {\n if s.len() <= max_len {\n s.to_string()\n } else {\n // Find valid UTF-8 char boundary\n let target = max_len.saturating_sub(3);\n let mut end = target.min(s.len());\n while end > 0 && !s.is_char_boundary(end) {\n end -= 1;\n }\n format!(\"{}...\", &s[..end])\n }\n}\n\n#[derive(Debug, Clone)]\nstruct TopEntry {\n hash: String,\n label: Option<String>,\n}\n\nfn toggle_top_commit(commit: &CommitEntry) -> Result<()> {\n let mut entries = load_top_entries()?;\n if entries.iter().any(|entry| entry.hash == commit.full_hash) {\n entries.retain(|entry| entry.hash != commit.full_hash);\n write_top_entries(&entries)?;\n println!(\"Removed notable commit: {} {}\", commit.hash, commit.subject);\n } else {\n let label = commit.subject.replace('\\t', \" \");\n entries.push(TopEntry {\n hash: commit.full_hash.clone(),\n label: Some(label),\n });\n write_top_entries(&entries)?;\n println!(\"Marked notable: {} {}\", commit.hash, commit.subject);\n }\n Ok(())\n}\n\nfn load_commit_by_ref(commit_ref: &str) -> Result<Option<CommitEntry>> {\n let output = Command::new(\"git\")\n .args([\"log\", \"-1\", \"--pretty=format:%h|%H|%s|%ar|%an\", commit_ref])\n .output()\n .context(\"failed to run git log\")?;\n\n if !output.status.success() {\n return Ok(None);\n }\n\n let stdout = String::from_utf8_lossy(&output.stdout);\n let line = stdout.lines().next().unwrap_or(\"\");\n let parts: Vec<&str> = line.splitn(5, '|').collect();\n if parts.len() < 5 {\n return Ok(None);\n }\n\n let hash = parts[0].to_string();\n let full_hash = parts[1].to_string();\n let subject = parts[2].to_string();\n let relative_time = parts[3].to_string();\n let author = parts[4].to_string();\n let has_ai_metadata = check_ai_metadata(&full_hash);\n\n let ai_indicator = if has_ai_metadata { \"◆ \" } else { \" \" };\n let pretty = format!(\n \"TOP {}{} | {} | {} | {}\",\n ai_indicator,\n hash,\n truncate_str(&subject, 50),\n relative_time,\n author\n );\n let display = format!(\"{}\\t{}\", hash, pretty);\n\n Ok(Some(CommitEntry {\n hash,\n full_hash,\n subject,\n relative_time,\n author,\n has_ai_metadata,\n is_top: true,\n display,\n }))\n}\n\nfn resolve_full_hash(commit_ref: &str) -> Result<String> {\n let output = Command::new(\"git\")\n .args([\"rev-parse\", commit_ref])\n .output()\n .context(\"failed to run git rev-parse\")?;\n if !output.status.success() {\n bail!(\"commit not found: {}\", commit_ref);\n }\n Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())\n}\n\nfn load_top_entries() -> Result<Vec<TopEntry>> {\n let path = top_file_path()?;\n if !path.exists() {\n return Ok(Vec::new());\n }\n let content = fs::read_to_string(&path).context(\"failed to read top commits\")?;\n let mut entries = Vec::new();\n for line in content.lines() {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n continue;\n }\n let (hash, label) = match trimmed.split_once('\\t') {\n Some((hash, label)) => (hash.to_string(), Some(label.to_string())),\n None => (trimmed.to_string(), None),\n };\n entries.push(TopEntry { hash, label });\n }\n Ok(entries)\n}\n\nfn write_top_entries(entries: &[TopEntry]) -> Result<()> {\n let path = top_file_path()?;\n if entries.is_empty() {\n if path.exists() {\n fs::remove_file(&path).context(\"failed to remove top commits file\")?;\n }\n return Ok(());\n }\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent).context(\"failed to create top commits dir\")?;\n }\n let mut out = String::new();\n for entry in entries {\n if let Some(label) = &entry.label {\n out.push_str(&format!(\"{}\\t{}\\n\", entry.hash, label));\n } else {\n out.push_str(&format!(\"{}\\n\", entry.hash));\n }\n }\n fs::write(&path, out).context(\"failed to write top commits\")?;\n Ok(())\n}\n\nfn top_hashes(entries: &[TopEntry]) -> HashSet<String> {\n entries.iter().map(|entry| entry.hash.clone()).collect()\n}\n\nfn top_file_path() -> Result<PathBuf> {\n let root = repo_root()?;\n Ok(root.join(TOP_COMMITS_PATH))\n}\n\nfn repo_root() -> Result<PathBuf> {\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"--show-toplevel\"])\n .output()\n .context(\"failed to run git rev-parse\")?;\n if !output.status.success() {\n bail!(\"not inside a git repository\");\n }\n Ok(Path::new(String::from_utf8_lossy(&output.stdout).trim()).to_path_buf())\n}\n" }, { "path": "src/config.rs", "content": "use std::{\n collections::HashMap,\n fs,\n path::{Path, PathBuf},\n sync::OnceLock,\n time::{SystemTime, UNIX_EPOCH},\n};\n\nuse anyhow::{Context, Result};\nuse serde::{Deserialize, Deserializer, Serialize};\nuse shellexpand::tilde;\n\nuse crate::fixup;\n\nconst CONFIG_CACHE_VERSION: u32 = 1;\nconst CONFIG_CACHE_ENV_DISABLE: &str = \"FLOW_DISABLE_CONFIG_CACHE\";\n\n/// Top-level configuration for flowd, currently focused on managed servers.\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct Config {\n #[serde(default)]\n pub version: Option<u32>,\n /// Optional human-friendly project name (applies to local project configs).\n #[serde(\n default,\n rename = \"name\",\n alias = \"project_name\",\n alias = \"project-name\"\n )]\n pub project_name: Option<String>,\n /// Optional env store space override for cloud.\n #[serde(default, rename = \"env_space\", alias = \"env-space\")]\n pub env_space: Option<String>,\n /// Env store scope: \"project\" (default) or \"personal\".\n #[serde(\n default,\n rename = \"env_space_kind\",\n alias = \"env-space-kind\",\n alias = \"env-space-scope\"\n )]\n pub env_space_kind: Option<String>,\n /// Flow-specific settings (primary_task, etc.)\n #[serde(default)]\n pub flow: FlowSettings,\n /// Project lifecycle orchestration for `f up` / `f down`.\n #[serde(default)]\n pub lifecycle: Option<LifecycleConfig>,\n /// Codex-first control plane settings.\n #[serde(default)]\n pub codex: Option<CodexConfig>,\n #[serde(default)]\n pub options: OptionsConfig,\n #[serde(default, alias = \"server\", alias = \"server-local\")]\n pub servers: Vec<ServerConfig>,\n #[serde(default, rename = \"server-remote\")]\n pub remote_servers: Vec<RemoteServerConfig>,\n #[serde(default)]\n pub tasks: Vec<TaskConfig>,\n /// Skills enforcement configuration (auto-sync/install).\n #[serde(default)]\n pub skills: Option<SkillsConfig>,\n /// Anonymous usage analytics settings.\n #[serde(default)]\n pub analytics: Option<AnalyticsConfig>,\n /// Hive agents defined for this project (array format: [[agent]]).\n #[serde(default, rename = \"agent\")]\n pub agents: Vec<crate::hive::AgentConfig>,\n /// Agent registry references (map format: [agents]).\n #[serde(default)]\n pub agents_registry: HashMap<String, String>,\n /// Everruns runtime defaults for `f ai everruns`.\n #[serde(default)]\n pub everruns: Option<EverrunsConfig>,\n #[serde(default, alias = \"deps\")]\n pub dependencies: HashMap<String, DependencySpec>,\n #[serde(default, alias = \"alias\", deserialize_with = \"deserialize_aliases\")]\n pub aliases: HashMap<String, String>,\n #[serde(default, rename = \"commands\")]\n pub command_files: Vec<CommandFileConfig>,\n #[serde(default)]\n pub storage: Option<StorageConfig>,\n #[serde(default)]\n pub flox: Option<FloxConfig>,\n #[serde(default, alias = \"watcher\", alias = \"always-run\")]\n pub watchers: Vec<WatcherConfig>,\n #[serde(default)]\n pub stream: Option<StreamConfig>,\n #[serde(default, rename = \"server-hub\")]\n pub server_hub: Option<ServerHubConfig>,\n /// Background daemons that flow can manage (start/stop/status).\n #[serde(default, alias = \"daemon\")]\n pub daemons: Vec<DaemonConfig>,\n /// Host deployment config for Linux servers.\n #[serde(default)]\n pub host: Option<crate::deploy::HostConfig>,\n /// Cloudflare Workers deployment config.\n #[serde(default)]\n pub cloudflare: Option<crate::deploy::CloudflareConfig>,\n /// Railway deployment config.\n #[serde(default)]\n pub railway: Option<crate::deploy::RailwayConfig>,\n /// Web deployment config.\n #[serde(default)]\n pub web: Option<crate::deploy::WebConfig>,\n /// Production deploy overrides (used by `f prod`).\n #[serde(default, alias = \"production\")]\n pub prod: Option<crate::deploy::ProdConfig>,\n /// Release configuration (hosts, npm, etc.).\n #[serde(default)]\n pub release: Option<ReleaseConfig>,\n /// Project invariants for AI-driven enforcement.\n #[serde(default)]\n pub invariants: Option<InvariantsConfig>,\n /// Commit workflow config (fixers, review instructions).\n #[serde(default)]\n pub commit: Option<CommitConfig>,\n /// Git workflow config (default remotes for push/sync).\n #[serde(default)]\n pub git: Option<GitConfig>,\n /// Jujutsu (jj) workflow config.\n #[serde(default)]\n pub jj: Option<JjConfig>,\n /// Setup defaults (global or project-level).\n #[serde(default)]\n pub setup: Option<SetupConfig>,\n /// Task lookup resolution policy for nested flow.toml discovery.\n #[serde(\n default,\n rename = \"task_resolution\",\n alias = \"task-resolution\",\n alias = \"taskResolution\"\n )]\n pub task_resolution: Option<TaskResolutionConfig>,\n /// SSH defaults (global or project-level).\n #[serde(default)]\n pub ssh: Option<SshConfig>,\n /// macOS launchd service management config.\n #[serde(default)]\n pub macos: Option<MacosConfig>,\n /// Proxy server configuration.\n #[serde(default)]\n pub proxy: Option<crate::proxy::ProxyConfig>,\n /// Proxy targets (array format: [[proxies]]).\n #[serde(default, alias = \"proxy-target\")]\n pub proxies: Vec<crate::proxy::ProxyTargetConfig>,\n /// Commit explanation config (AI-generated markdown summaries).\n #[serde(default, rename = \"explain-commits\", alias = \"explain_commits\")]\n pub explain_commits: Option<ExplainCommitsConfig>,\n}\n\n/// Commit explanation config — AI-generated markdown summaries per commit.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct ExplainCommitsConfig {\n /// Whether auto-explain is enabled on sync (default: false).\n #[serde(default)]\n pub enabled: Option<bool>,\n /// Output directory relative to repo root (default: \"docs/commits\").\n #[serde(default)]\n pub output_dir: Option<String>,\n /// AI model to use (default: \"moonshotai/kimi-k2.5\").\n #[serde(default)]\n pub model: Option<String>,\n /// AI provider (default: \"nvidia\").\n #[serde(default)]\n pub provider: Option<String>,\n /// Max commits to explain per sync (default: 10).\n #[serde(default)]\n pub batch_size: Option<usize>,\n}\n\n/// Everruns AI runtime defaults.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct EverrunsConfig {\n /// Everruns API base URL (for example: http://127.0.0.1:9300/api).\n #[serde(default, alias = \"base-url\", alias = \"baseUrl\")]\n pub base_url: Option<String>,\n /// Env var name that contains the API key (default: EVERRUNS_API_KEY).\n #[serde(\n default,\n rename = \"api_key_env\",\n alias = \"api-key-env\",\n alias = \"apiKeyEnv\"\n )]\n pub api_key_env: Option<String>,\n /// Default session id to reuse.\n #[serde(\n default,\n rename = \"session_id\",\n alias = \"session-id\",\n alias = \"sessionId\"\n )]\n pub session_id: Option<String>,\n /// Default agent id for new sessions.\n #[serde(default, rename = \"agent_id\", alias = \"agent-id\", alias = \"agentId\")]\n pub agent_id: Option<String>,\n /// Default harness id for new sessions.\n #[serde(\n default,\n rename = \"harness_id\",\n alias = \"harness-id\",\n alias = \"harnessId\"\n )]\n pub harness_id: Option<String>,\n /// Default model id override for new sessions.\n #[serde(default, rename = \"model_id\", alias = \"model-id\", alias = \"modelId\")]\n pub model_id: Option<String>,\n}\n\n/// macOS launchd service management config.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct MacosConfig {\n /// Service patterns that are allowed (won't be flagged).\n /// Supports wildcards like \"com.nikiv.*\".\n #[serde(default)]\n pub allowed: Vec<String>,\n /// Service patterns that should be blocked/disabled.\n /// Supports wildcards like \"com.google.*\".\n #[serde(default)]\n pub blocked: Vec<String>,\n}\n\n/// SSH config (mode, key name, etc.).\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct SshConfig {\n /// ssh mode: \"auto\", \"force\", or \"https\"\n #[serde(default)]\n pub mode: Option<String>,\n /// default key name to unlock (defaults to \"default\").\n #[serde(default)]\n pub key_name: Option<String>,\n /// auto-unlock ssh keys when needed (default: true).\n #[serde(default)]\n pub auto_unlock: Option<bool>,\n}\n\n/// Configuration for commit workflow.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct CommitConfig {\n /// Pre-commit fixers to run before staging.\n /// Built-in: \"mdx-comments\", \"trailing-whitespace\", \"end-of-file\"\n /// Custom: \"cmd:prettier --write\"\n #[serde(default)]\n pub fixers: Vec<String>,\n /// Custom instructions passed to AI code review.\n #[serde(default)]\n pub review_instructions: Option<String>,\n /// File path to load review instructions from.\n #[serde(default)]\n pub review_instructions_file: Option<String>,\n /// Tool to use for commit review: \"claude\", \"codex\", \"opencode\", \"kimi\"\n #[serde(default)]\n pub tool: Option<String>,\n /// Model to use for commit review (tool-specific)\n #[serde(default)]\n pub model: Option<String>,\n /// Tool to use for commit message generation: \"kimi\"\n #[serde(\n default,\n rename = \"message-tool\",\n alias = \"message_tool\",\n alias = \"messageTool\"\n )]\n pub message_tool: Option<String>,\n /// Model to use for commit message generation (tool-specific)\n #[serde(\n default,\n rename = \"message-model\",\n alias = \"message_model\",\n alias = \"messageModel\"\n )]\n pub message_model: Option<String>,\n /// Continue commit if review fails after fallbacks (default: true)\n #[serde(\n default,\n rename = \"review-fail-open\",\n alias = \"review_fail_open\",\n alias = \"reviewFailOpen\"\n )]\n pub review_fail_open: Option<bool>,\n /// Continue commit if commit-message generation fails after fallbacks (default: true)\n #[serde(\n default,\n rename = \"message-fail-open\",\n alias = \"message_fail_open\",\n alias = \"messageFailOpen\"\n )]\n pub message_fail_open: Option<bool>,\n /// Optional ordered fallback chain for review tool/model.\n /// Examples: [\"openrouter:openrouter/free\", \"claude\", \"codex-high\"]\n #[serde(\n default,\n rename = \"review-fallbacks\",\n alias = \"review_fallbacks\",\n alias = \"reviewFallbacks\"\n )]\n pub review_fallbacks: Option<Vec<String>>,\n /// Optional ordered fallback chain for commit message generation.\n /// Examples: [\"remote\", \"openai\", \"openrouter:openrouter/free\", \"heuristic\"]\n #[serde(\n default,\n rename = \"message-fallbacks\",\n alias = \"message_fallbacks\",\n alias = \"messageFallbacks\"\n )]\n pub message_fallbacks: Option<Vec<String>>,\n /// Queue commits for review before push.\n #[serde(default)]\n pub queue: Option<bool>,\n /// Queue only when review finds issues (overrides queue if review passes).\n #[serde(\n default,\n rename = \"queue_on_issues\",\n alias = \"queue-on-issues\",\n alias = \"queueOnIssues\"\n )]\n pub queue_on_issues: Option<bool>,\n /// Use `f commit --quick` behavior by default (fast commit + async Codex deep review).\n #[serde(\n default,\n rename = \"quick-default\",\n alias = \"quick_default\",\n alias = \"quickDefault\"\n )]\n pub quick_default: Option<bool>,\n /// Quality gate configuration for commit-time feature doc/test enforcement.\n #[serde(default)]\n pub quality: Option<QualityConfig>,\n /// Test-runner enforcement and pre-commit test gate settings.\n #[serde(default)]\n pub testing: Option<TestingConfig>,\n /// Required workflow skills gate for commit-time enforcement.\n #[serde(\n default,\n rename = \"skill_gate\",\n alias = \"skill-gate\",\n alias = \"skillGate\"\n )]\n pub skill_gate: Option<SkillGateConfig>,\n /// Push gate for review todos: \"warn\" (default) | \"block\" | \"off\"\n #[serde(\n default,\n rename = \"review-push-gate\",\n alias = \"review_push_gate\",\n alias = \"reviewPushGate\"\n )]\n pub review_push_gate: Option<String>,\n}\n\n/// Quality gate configuration: enforce documentation and test requirements at commit time.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct QualityConfig {\n /// Gate mode: \"warn\" (default) | \"block\" | \"off\"\n #[serde(default)]\n pub mode: Option<String>,\n /// Require feature docs for touched features (default: true)\n #[serde(default)]\n pub require_docs: Option<bool>,\n /// Require test files for changed source code (default: true)\n #[serde(default)]\n pub require_tests: Option<bool>,\n /// Auto-generate/update feature docs at commit time (default: true)\n #[serde(default)]\n pub auto_generate_docs: Option<bool>,\n /// Doc detail level: \"basic\" | \"detailed\" (default: \"basic\")\n #[serde(default)]\n pub doc_level: Option<String>,\n /// Glob patterns exempt from quality checks\n #[serde(default)]\n pub exempt_paths: Option<Vec<String>>,\n /// Days before a feature doc is flagged stale (default: 30)\n #[serde(default)]\n pub stale_days: Option<u32>,\n}\n\n/// Testing gate configuration: enforce Bun test runner usage and quick local checks.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct TestingConfig {\n /// Gate mode: \"warn\" (default) | \"block\" | \"off\"\n #[serde(default)]\n pub mode: Option<String>,\n /// Required runner (currently \"bun\" only). Default: \"bun\".\n #[serde(default)]\n pub runner: Option<String>,\n /// In Bun repo layout, require `bun bd test` instead of `bun test`. Default: true.\n #[serde(default)]\n pub bun_repo_strict: Option<bool>,\n /// Require at least one related test for staged source changes. Default: true.\n #[serde(default)]\n pub require_related_tests: Option<bool>,\n /// Directory for AI scratch tests (typically gitignored). Default: \".ai/test\".\n #[serde(default)]\n pub ai_scratch_test_dir: Option<String>,\n /// Run AI scratch tests when no related tracked tests are detected. Default: true.\n #[serde(default)]\n pub run_ai_scratch_tests: Option<bool>,\n /// Allow AI scratch tests to satisfy related-test gate requirements. Default: false.\n #[serde(default)]\n pub allow_ai_scratch_to_satisfy_gate: Option<bool>,\n /// Soft budget in seconds for the local test gate; emits warning if exceeded. Default: 15.\n #[serde(default)]\n pub max_local_gate_seconds: Option<u64>,\n}\n\n/// Skill gate configuration: require specific workflow skills before commit.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct SkillGateConfig {\n /// Gate mode: \"warn\" | \"block\" | \"off\"\n #[serde(default)]\n pub mode: Option<String>,\n /// Required skill names (must exist in .ai/skills).\n #[serde(default)]\n pub required: Vec<String>,\n /// Optional per-skill minimum version (from skill frontmatter \"version\").\n #[serde(default, rename = \"min_version\", alias = \"min-version\")]\n pub min_version: Option<HashMap<String, u32>>,\n}\n\n/// Project invariants for AI-driven enforcement at commit time.\n///\n/// Defines machine-parseable rules that flow checks against staged changes.\n/// Findings are injected into AI review prompts and can block or warn on commit.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct InvariantsConfig {\n /// Gate mode: \"warn\" (default) | \"block\" | \"off\"\n #[serde(default)]\n pub mode: Option<String>,\n /// Architecture style description (informational, injected into AI prompts).\n #[serde(default, rename = \"architecture_style\", alias = \"architecture-style\")]\n pub architecture_style: Option<String>,\n /// Non-negotiable patterns the project must follow (prose rules for AI context).\n #[serde(default, rename = \"non_negotiable\", alias = \"non-negotiable\")]\n pub non_negotiable: Vec<String>,\n /// Forbidden string patterns checked against staged diff content.\n /// If any pattern appears in the diff, a finding is emitted.\n #[serde(default)]\n pub forbidden: Vec<String>,\n /// Canonical terminology map: term -> definition.\n /// Injected into AI review prompts to prevent drift.\n #[serde(default)]\n pub terminology: HashMap<String, String>,\n /// Dependency policy sub-section.\n #[serde(default)]\n pub deps: Option<InvariantsDepsConfig>,\n /// File-level rules (max lines, etc.).\n #[serde(default)]\n pub files: Option<InvariantsFilesConfig>,\n}\n\n/// Dependency policy within invariants.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct InvariantsDepsConfig {\n /// Policy: \"approval_required\" (default) | \"open\"\n #[serde(default)]\n pub policy: Option<String>,\n /// Approved dependency names. New deps not on this list trigger a finding.\n #[serde(default)]\n pub approved: Vec<String>,\n}\n\n/// File-level invariant rules.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct InvariantsFilesConfig {\n /// Maximum lines per source file. Files exceeding this in the diff trigger a warning.\n #[serde(default, rename = \"max_lines\", alias = \"max-lines\")]\n pub max_lines: Option<u32>,\n}\n\n/// Jujutsu (jj) workflow config.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct JjConfig {\n /// Default branch to rebase onto (e.g., \"main\").\n #[serde(\n default,\n rename = \"default_branch\",\n alias = \"default-branch\",\n alias = \"defaultBranch\"\n )]\n pub default_branch: Option<String>,\n /// Default git remote (e.g., \"origin\").\n #[serde(default)]\n pub remote: Option<String>,\n /// Auto-track bookmarks on create.\n #[serde(\n default,\n rename = \"auto_track\",\n alias = \"auto-track\",\n alias = \"autoTrack\"\n )]\n pub auto_track: Option<bool>,\n /// Home branch that review/codex branches stack on top of (for example: \"nikiv\").\n #[serde(\n default,\n rename = \"home_branch\",\n alias = \"home-branch\",\n alias = \"homeBranch\"\n )]\n pub home_branch: Option<String>,\n /// Prefix for review bookmarks created by flow (e.g., \"review\").\n #[serde(\n default,\n rename = \"review_prefix\",\n alias = \"review-prefix\",\n alias = \"reviewPrefix\"\n )]\n pub review_prefix: Option<String>,\n}\n\n/// Git workflow config.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct GitConfig {\n /// Default writable remote used by flow commit/sync (e.g., \"origin\", \"fork\", \"myflow-i\").\n #[serde(default)]\n pub remote: Option<String>,\n /// Enable private fork push (pushes to `{owner}/{repo}{suffix}` instead of origin).\n #[serde(default, rename = \"fork-push\", alias = \"fork_push\")]\n pub fork_push: Option<bool>,\n /// Suffix appended to repo name for fork push (default: \"-i\").\n #[serde(default, rename = \"fork-push-suffix\", alias = \"fork_push_suffix\")]\n pub fork_push_suffix: Option<String>,\n /// GitHub owner for fork push (auto-detected from `gh api user` / `git config github.user`).\n #[serde(default, rename = \"fork-push-owner\", alias = \"fork_push_owner\")]\n pub fork_push_owner: Option<String>,\n}\n\n/// TypeScript config loaded from ~/.config/flow/config.ts\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct TsConfig {\n #[serde(default)]\n pub flow: Option<TsFlowConfig>,\n}\n\n/// Flow section from TypeScript config.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct TsFlowConfig {\n #[serde(default)]\n pub commit: Option<TsCommitConfig>,\n #[serde(default)]\n pub review: Option<TsReviewConfig>,\n #[serde(default)]\n pub agents: Option<TsAgentsConfig>,\n #[serde(default)]\n pub env: Option<TsEnvConfig>,\n #[serde(default, rename = \"taskFailureAgents\")]\n pub task_failure_agents: Option<TsTaskFailureAgentsConfig>,\n /// Optional command to run on task failure.\n #[serde(\n default,\n rename = \"taskFailureHook\",\n alias = \"task_failure_hook\",\n alias = \"task-failure-hook\"\n )]\n pub task_failure_hook: Option<String>,\n /// Enable gitedit.dev hash in commit messages. Default false.\n #[serde(default)]\n pub gitedit: Option<bool>,\n /// Log level: \"off\", \"error\", \"warn\", \"info\", \"debug\", \"trace\". Default \"warn\".\n #[serde(default)]\n pub log_level: Option<String>,\n}\n\n/// Env settings from TypeScript config.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct TsEnvConfig {\n /// Preferred env backend: \"cloud\" or \"local\".\n #[serde(default)]\n pub backend: Option<String>,\n /// Env vars to inject into every task from the personal env store.\n #[serde(\n default,\n rename = \"global_keys\",\n alias = \"globalKeys\",\n alias = \"global-keys\"\n )]\n pub global_keys: Vec<String>,\n}\n\n/// Agents settings from TypeScript config.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct TsAgentsConfig {\n /// Tool to use: \"claude\", \"gen\", \"opencode\"\n #[serde(default)]\n pub tool: Option<String>,\n /// Default model for agents (e.g., \"openrouter/moonshotai/kimi-k2:free\")\n #[serde(default)]\n pub model: Option<String>,\n}\n\n/// Task-failure agent routing settings from TypeScript config.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct TsTaskFailureAgentsConfig {\n /// Enable auto-routing on task failure.\n #[serde(default)]\n pub enabled: Option<bool>,\n /// Tool to use (currently \"hive\").\n #[serde(default)]\n pub tool: Option<String>,\n /// Max lines of task output to include in prompt.\n #[serde(default, rename = \"maxLines\")]\n pub max_lines: Option<usize>,\n /// Max chars of task output to include in prompt.\n #[serde(default, rename = \"maxChars\")]\n pub max_chars: Option<usize>,\n /// Max agents to run per failure.\n #[serde(default, rename = \"maxAgents\")]\n pub max_agents: Option<usize>,\n}\n\n/// Commit settings from TypeScript config.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct TsCommitConfig {\n /// Tool to use: \"claude\", \"codex\", \"opencode\"\n #[serde(default)]\n pub tool: Option<String>,\n /// Model identifier (e.g., \"opencode/minimax-m2.1-free\")\n #[serde(default)]\n pub model: Option<String>,\n /// Tool to use for commit message generation: \"kimi\"\n #[serde(\n default,\n rename = \"messageTool\",\n alias = \"message_tool\",\n alias = \"message-tool\"\n )]\n pub message_tool: Option<String>,\n /// Model identifier for commit message generation\n #[serde(\n default,\n rename = \"messageModel\",\n alias = \"message_model\",\n alias = \"message-model\"\n )]\n pub message_model: Option<String>,\n /// Continue commit if review fails after fallbacks (default: true)\n #[serde(\n default,\n rename = \"reviewFailOpen\",\n alias = \"review_fail_open\",\n alias = \"review-fail-open\"\n )]\n pub review_fail_open: Option<bool>,\n /// Continue commit if commit-message generation fails after fallbacks (default: true)\n #[serde(\n default,\n rename = \"messageFailOpen\",\n alias = \"message_fail_open\",\n alias = \"message-fail-open\"\n )]\n pub message_fail_open: Option<bool>,\n /// Optional ordered fallback chain for review.\n #[serde(\n default,\n rename = \"reviewFallbacks\",\n alias = \"review_fallbacks\",\n alias = \"review-fallbacks\"\n )]\n pub review_fallbacks: Option<Vec<String>>,\n /// Optional ordered fallback chain for message generation.\n #[serde(\n default,\n rename = \"messageFallbacks\",\n alias = \"message_fallbacks\",\n alias = \"message-fallbacks\"\n )]\n pub message_fallbacks: Option<Vec<String>>,\n /// Custom review instructions\n #[serde(default)]\n pub review_instructions: Option<String>,\n /// Queue commits for review before push.\n #[serde(default)]\n pub queue: Option<bool>,\n /// Queue only when review finds issues (overrides queue if review passes).\n #[serde(\n default,\n rename = \"queueOnIssues\",\n alias = \"queue_on_issues\",\n alias = \"queue-on-issues\"\n )]\n pub queue_on_issues: Option<bool>,\n /// Use `f commit --quick` behavior by default.\n #[serde(\n default,\n rename = \"quickDefault\",\n alias = \"quick_default\",\n alias = \"quick-default\"\n )]\n pub quick_default: Option<bool>,\n /// Whether to run async (delegate to hub). Default true.\n #[serde(default, rename = \"async\")]\n pub async_enabled: Option<bool>,\n}\n\n/// Review settings from TypeScript config (overrides commit settings for review).\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct TsReviewConfig {\n /// Tool to use for review: \"claude\", \"codex\", \"opencode\", \"kimi\"\n #[serde(default)]\n pub tool: Option<String>,\n /// Model identifier for review (e.g., \"opencode/glm-4.7-free\")\n #[serde(default)]\n pub model: Option<String>,\n}\n\nimpl Default for Config {\n fn default() -> Self {\n Self {\n version: None,\n project_name: None,\n env_space: None,\n env_space_kind: None,\n flow: FlowSettings::default(),\n lifecycle: None,\n codex: None,\n options: OptionsConfig::default(),\n servers: Vec::new(),\n remote_servers: Vec::new(),\n tasks: Vec::new(),\n skills: None,\n analytics: None,\n agents: Vec::new(),\n agents_registry: HashMap::new(),\n everruns: None,\n dependencies: HashMap::new(),\n aliases: HashMap::new(),\n command_files: Vec::new(),\n storage: None,\n flox: None,\n watchers: Vec::new(),\n stream: None,\n server_hub: None,\n daemons: Vec::new(),\n host: None,\n cloudflare: None,\n railway: None,\n web: None,\n prod: None,\n release: None,\n invariants: None,\n commit: None,\n git: None,\n jj: None,\n setup: None,\n task_resolution: None,\n ssh: None,\n macos: None,\n proxy: None,\n proxies: Vec::new(),\n explain_commits: None,\n }\n }\n}\n\n/// Flow-specific settings for autonomous agent workflows.\n#[derive(Debug, Clone, Default, Deserialize, Serialize)]\npub struct FlowSettings {\n /// The primary task to run after code changes (e.g., \"release\", \"deploy\").\n #[serde(default, alias = \"primary-task\")]\n pub primary_task: Option<String>,\n /// Task to run when invoking `f deploy release`.\n #[serde(default, rename = \"release_task\", alias = \"release-task\")]\n pub release_task: Option<String>,\n /// Task to run when invoking `f deploy` with no subcommand.\n #[serde(default, rename = \"deploy_task\", alias = \"deploy-task\")]\n pub deploy_task: Option<String>,\n}\n\n/// Project lifecycle configuration for `f up` and `f down`.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct LifecycleConfig {\n /// Task to run for `f up` (default fallback order: \"up\", then \"dev\").\n #[serde(default, rename = \"up_task\", alias = \"up-task\", alias = \"upTask\")]\n pub up_task: Option<String>,\n /// Task to run for `f down` (default: \"down\").\n #[serde(default, rename = \"down_task\", alias = \"down-task\", alias = \"downTask\")]\n pub down_task: Option<String>,\n /// Optional local-domain lifecycle behavior.\n #[serde(default)]\n pub domains: Option<LifecycleDomainsConfig>,\n}\n\n/// Optional local-domain automation used by lifecycle commands.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct LifecycleDomainsConfig {\n /// Hostname to map, for example: \"myflow.localhost\".\n #[serde(default, alias = \"domain\")]\n pub host: Option<String>,\n /// Upstream target in host:port format, for example: \"127.0.0.1:3000\".\n #[serde(default)]\n pub target: Option<String>,\n /// Extra host mappings to provision alongside the primary lifecycle domain.\n #[serde(default)]\n pub aliases: Vec<LifecycleDomainAliasConfig>,\n /// Domains engine: \"docker\" or \"native\" (default uses Flow global default).\n #[serde(default)]\n pub engine: Option<String>,\n /// Remove configured host mapping on `f down` (default: false).\n #[serde(\n default,\n rename = \"remove_on_down\",\n alias = \"remove-on-down\",\n alias = \"removeOnDown\"\n )]\n pub remove_on_down: Option<bool>,\n /// Stop shared domains proxy on `f down` (default: false).\n #[serde(\n default,\n rename = \"stop_proxy_on_down\",\n alias = \"stop-proxy-on-down\",\n alias = \"stopProxyOnDown\"\n )]\n pub stop_proxy_on_down: Option<bool>,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct LifecycleDomainAliasConfig {\n /// Hostname to map, for example: \"api.myflow.localhost\".\n #[serde(default, alias = \"domain\")]\n pub host: Option<String>,\n /// Upstream target in host:port format, for example: \"127.0.0.1:8780\".\n #[serde(default)]\n pub target: Option<String>,\n}\n\n/// Skills enforcement configuration.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct SkillsConfig {\n /// Auto-sync flow.toml tasks into .ai/skills.\n #[serde(\n default,\n rename = \"sync_tasks\",\n alias = \"sync-tasks\",\n alias = \"syncTasks\"\n )]\n pub sync_tasks: bool,\n /// Skills to install from the registry when missing.\n #[serde(default)]\n pub install: Vec<String>,\n /// Codex-specific skills behavior.\n #[serde(default)]\n pub codex: Option<SkillsCodexConfig>,\n /// Optional seq scraper integration for dependency skill generation.\n #[serde(default)]\n pub seq: Option<SkillsSeqConfig>,\n}\n\n/// Anonymous usage analytics settings.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct AnalyticsConfig {\n /// Force analytics enabled/disabled regardless of local prompt state.\n #[serde(default)]\n pub enabled: Option<bool>,\n /// Ingest endpoint for analytics events.\n #[serde(default)]\n pub endpoint: Option<String>,\n /// Client-side sampling rate (0.0..1.0, default 1.0).\n #[serde(default)]\n pub sample_rate: Option<f32>,\n}\n\n/// Codex-focused skills settings.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct SkillsCodexConfig {\n /// Generate `agents/openai.yaml` metadata for task-synced skills.\n #[serde(\n default,\n rename = \"generate_openai_yaml\",\n alias = \"generate-openai-yaml\",\n alias = \"generateOpenaiYaml\"\n )]\n pub generate_openai_yaml: Option<bool>,\n /// After sync/install, force Codex app-server to reload skills for this cwd.\n #[serde(\n default,\n rename = \"force_reload_after_sync\",\n alias = \"force-reload-after-sync\",\n alias = \"forceReloadAfterSync\"\n )]\n pub force_reload_after_sync: Option<bool>,\n /// Default implicit invocation policy for task-synced skills metadata.\n #[serde(\n default,\n rename = \"task_skill_allow_implicit_invocation\",\n alias = \"task-skill-allow-implicit-invocation\",\n alias = \"taskSkillAllowImplicitInvocation\"\n )]\n pub task_skill_allow_implicit_invocation: Option<bool>,\n}\n\n/// Codex-first control plane settings.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct CodexConfig {\n /// Whether `f codex open` should auto-run reference resolvers when patterns match.\n #[serde(\n default,\n rename = \"auto_resolve_references\",\n alias = \"auto-resolve-references\",\n alias = \"autoResolveReferences\"\n )]\n pub auto_resolve_references: Option<bool>,\n /// Whether Flow may materialize per-launch runtime skills for Codex wrapper transports.\n #[serde(\n default,\n rename = \"runtime_skills\",\n alias = \"runtime-skills\",\n alias = \"runtimeSkills\"\n )]\n pub runtime_skills: Option<bool>,\n /// Default repo path used for home-session style Codex lookups.\n #[serde(\n default,\n rename = \"home_session_path\",\n alias = \"home-session-path\",\n alias = \"homeSessionPath\"\n )]\n pub home_session_path: Option<String>,\n /// Hard cap for injected prompt context before Codex sees the query.\n #[serde(\n default,\n rename = \"prompt_context_budget_chars\",\n alias = \"prompt-context-budget-chars\",\n alias = \"promptContextBudgetChars\"\n )]\n pub prompt_context_budget_chars: Option<usize>,\n /// Limit how many resolved references Flow may inject for one prompt.\n #[serde(\n default,\n rename = \"max_resolved_references\",\n alias = \"max-resolved-references\",\n alias = \"maxResolvedReferences\"\n )]\n pub max_resolved_references: Option<usize>,\n /// External reference resolvers that can unroll URLs or other tokens into compact context.\n #[serde(\n default,\n rename = \"reference_resolver\",\n alias = \"reference-resolver\",\n alias = \"referenceResolver\"\n )]\n pub reference_resolvers: Vec<CodexReferenceResolverConfig>,\n /// External skill repositories that Flow may scan/sync for Codex runtime injection.\n #[serde(\n default,\n rename = \"skill_source\",\n alias = \"skill-source\",\n alias = \"skillSource\"\n )]\n pub skill_sources: Vec<CodexSkillSourceConfig>,\n}\n\nimpl CodexConfig {\n pub(crate) fn merge(&mut self, other: CodexConfig) {\n if other.auto_resolve_references.is_some() {\n self.auto_resolve_references = other.auto_resolve_references;\n }\n if other.runtime_skills.is_some() {\n self.runtime_skills = other.runtime_skills;\n }\n if other.home_session_path.is_some() {\n self.home_session_path = other.home_session_path;\n }\n if other.prompt_context_budget_chars.is_some() {\n self.prompt_context_budget_chars = other.prompt_context_budget_chars;\n }\n if other.max_resolved_references.is_some() {\n self.max_resolved_references = other.max_resolved_references;\n }\n for resolver in other.reference_resolvers {\n if let Some(existing) = self\n .reference_resolvers\n .iter_mut()\n .find(|value| value.name == resolver.name)\n {\n *existing = resolver;\n } else {\n self.reference_resolvers.push(resolver);\n }\n }\n for source in other.skill_sources {\n if let Some(existing) = self\n .skill_sources\n .iter_mut()\n .find(|value| value.name == source.name)\n {\n *existing = source;\n } else {\n self.skill_sources.push(source);\n }\n }\n }\n}\n\n/// External skill repository registration for Codex runtime helpers.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct CodexSkillSourceConfig {\n /// Human-friendly source name.\n pub name: String,\n /// Local path to the source repo or skill root.\n pub path: String,\n /// Whether this source is enabled for discovery/sync.\n #[serde(default)]\n pub enabled: Option<bool>,\n}\n\n/// External resolver registration for `f codex resolve` and `f codex open`.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct CodexReferenceResolverConfig {\n /// Human-friendly resolver name.\n pub name: String,\n /// Wildcard patterns that match candidate reference tokens.\n #[serde(default, rename = \"match\", alias = \"matches\")]\n pub matches: Vec<String>,\n /// Shell command template to run when a pattern matches.\n pub command: String,\n /// Optional label used when injecting the resolver output into the prompt.\n #[serde(default, rename = \"inject_as\", alias = \"inject-as\", alias = \"injectAs\")]\n pub inject_as: Option<String>,\n}\n\n/// Seq-backed skills fetch configuration.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct SkillsSeqConfig {\n /// Fetch mode (\"local-cli\" today; \"remote-api\" reserved).\n #[serde(default)]\n pub mode: Option<String>,\n /// Path to seq repo (used to resolve tools/teach_deps.py).\n #[serde(default, rename = \"seq_repo\", alias = \"seq-repo\")]\n pub seq_repo: Option<String>,\n /// Full path to teach_deps.py (overrides seq_repo).\n #[serde(default, rename = \"script_path\", alias = \"script-path\")]\n pub script_path: Option<String>,\n /// Scraper daemon/API base URL.\n #[serde(\n default,\n rename = \"scraper_base_url\",\n alias = \"scraper-base-url\",\n alias = \"scraperBaseUrl\"\n )]\n pub scraper_base_url: Option<String>,\n /// Scraper bearer token.\n #[serde(\n default,\n rename = \"scraper_api_key\",\n alias = \"scraper-api-key\",\n alias = \"scraperApiKey\"\n )]\n pub scraper_api_key: Option<String>,\n /// Output directory for generated skills.\n #[serde(default, rename = \"out_dir\", alias = \"out-dir\")]\n pub out_dir: Option<String>,\n /// Cache TTL in hours.\n #[serde(\n default,\n rename = \"cache_ttl_hours\",\n alias = \"cache-ttl-hours\",\n alias = \"cacheTtlHours\"\n )]\n pub cache_ttl_hours: Option<f64>,\n /// Direct fetch fallback when scraper queue is unavailable.\n #[serde(\n default,\n rename = \"allow_direct_fallback\",\n alias = \"allow-direct-fallback\",\n alias = \"allowDirectFallback\"\n )]\n pub allow_direct_fallback: Option<bool>,\n /// Optional seq.mem JSONEachRow destination path.\n #[serde(\n default,\n rename = \"mem_events_path\",\n alias = \"mem-events-path\",\n alias = \"memEventsPath\"\n )]\n pub mem_events_path: Option<String>,\n /// Default per-ecosystem dependency count for auto mode.\n #[serde(default)]\n pub top: Option<usize>,\n /// Default ecosystems for auto mode.\n #[serde(default)]\n pub ecosystems: Option<String>,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct ReleaseConfig {\n /// Default release provider (e.g., \"registry\", \"task\").\n #[serde(default)]\n pub default: Option<String>,\n /// Versioning scheme (e.g., \"calver\").\n #[serde(default)]\n pub versioning: Option<String>,\n /// Optional suffix for calver (appended as pre-release, e.g., \"1\" -> 2026.1.12-1).\n #[serde(default)]\n pub calver_suffix: Option<String>,\n /// Release host domain.\n #[serde(default)]\n pub domain: Option<String>,\n /// Base URL for release artifacts.\n #[serde(default)]\n pub base_url: Option<String>,\n /// Release host root path.\n #[serde(default)]\n pub root: Option<String>,\n /// Caddyfile path.\n #[serde(default)]\n pub caddyfile: Option<String>,\n /// Readme file path to update.\n #[serde(default)]\n pub readme: Option<String>,\n /// Flow registry release config.\n #[serde(default)]\n pub registry: Option<RegistryReleaseConfig>,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct RegistryReleaseConfig {\n /// Base URL for the registry (e.g., \"https://myflow.sh\").\n #[serde(default)]\n pub url: Option<String>,\n /// Registry package name (defaults to project name).\n #[serde(default)]\n pub package: Option<String>,\n /// Optional binary names to upload.\n #[serde(default)]\n pub bins: Option<Vec<String>>,\n /// Default binary name to install.\n #[serde(default)]\n pub default_bin: Option<String>,\n /// Env var that holds the registry token.\n #[serde(default)]\n pub token_env: Option<String>,\n /// Whether to update the latest pointer by default.\n #[serde(default)]\n pub latest: Option<bool>,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct SetupConfig {\n /// Server setup defaults (used by f setup release).\n #[serde(default)]\n pub server: Option<SetupServerConfig>,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct SetupServerConfig {\n /// Optional template flow.toml path to pull [host] defaults from.\n pub template: Option<String>,\n /// Optional inline [host] defaults.\n #[serde(default)]\n pub host: Option<crate::deploy::HostConfig>,\n}\n\n/// Task lookup policy for nested flow.toml discovery.\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct TaskResolutionConfig {\n /// Preferred scope order for ambiguous task names (e.g. [\"mobile\", \"root\"]).\n #[serde(\n default,\n rename = \"preferred_scopes\",\n alias = \"preferred-scopes\",\n alias = \"preferredScopes\"\n )]\n pub preferred_scopes: Vec<String>,\n /// Exact task-name routes (task -> scope), used before preferred scope order.\n #[serde(default)]\n pub routes: HashMap<String, String>,\n /// Print a note when implicit scope routing chooses a target.\n #[serde(\n default,\n rename = \"warn_on_implicit_scope\",\n alias = \"warn-on-implicit-scope\",\n alias = \"warnOnImplicitScope\"\n )]\n pub warn_on_implicit_scope: Option<bool>,\n}\n\n/// Global feature toggles.\n#[derive(Debug, Clone, Default, Deserialize, Serialize)]\npub struct OptionsConfig {\n #[serde(default, rename = \"trace_terminal_io\")]\n pub trace_terminal_io: bool,\n #[serde(\n default,\n rename = \"commit_with_check_async\",\n alias = \"commit-with-check-async\"\n )]\n pub commit_with_check_async: Option<bool>,\n #[serde(\n default,\n rename = \"commit_with_check_use_repo_root\",\n alias = \"commit-with-check-use-repo-root\"\n )]\n pub commit_with_check_use_repo_root: Option<bool>,\n #[serde(\n default,\n rename = \"commit_with_check_timeout_secs\",\n alias = \"commit-with-check-timeout-secs\"\n )]\n pub commit_with_check_timeout_secs: Option<u64>,\n /// Number of retries when review times out (default 1).\n #[serde(\n default,\n rename = \"commit_with_check_review_retries\",\n alias = \"commit-with-check-review-retries\"\n )]\n pub commit_with_check_review_retries: Option<u32>,\n /// Remote Claude review URL for commitWithCheck.\n #[serde(\n default,\n rename = \"commit_with_check_review_url\",\n alias = \"commit-with-check-review-url\"\n )]\n pub commit_with_check_review_url: Option<String>,\n /// Optional auth token for remote review.\n #[serde(\n default,\n rename = \"commit_with_check_review_token\",\n alias = \"commit-with-check-review-token\"\n )]\n pub commit_with_check_review_token: Option<String>,\n /// Enable mirroring commits to gitedit.dev for commitWithCheck.\n #[serde(\n default,\n rename = \"commit_with_check_gitedit_mirror\",\n alias = \"commit-with-check-gitedit-mirror\"\n )]\n pub commit_with_check_gitedit_mirror: Option<bool>,\n /// Enable mirroring commits to gitedit.dev (opt-in per project).\n #[serde(default, rename = \"gitedit_mirror\", alias = \"gitedit-mirror\")]\n pub gitedit_mirror: Option<bool>,\n /// Custom gitedit API URL (defaults to https://gitedit.dev).\n #[serde(default, rename = \"gitedit_url\", alias = \"gitedit-url\")]\n pub gitedit_url: Option<String>,\n /// Override repo full name for gitedit sync (e.g., \"giteditdev/gitedit\").\n #[serde(\n default,\n rename = \"gitedit_repo_full_name\",\n alias = \"gitedit-repo-full-name\"\n )]\n pub gitedit_repo_full_name: Option<String>,\n /// Optional token for gitedit sync/publish.\n #[serde(default, rename = \"gitedit_token\", alias = \"gitedit-token\")]\n pub gitedit_token: Option<String>,\n /// Enable mirroring commits to myflow.sh (opt-in per project).\n #[serde(default, rename = \"myflow_mirror\", alias = \"myflow-mirror\")]\n pub myflow_mirror: Option<bool>,\n /// Custom myflow API URL (defaults to https://myflow.sh).\n #[serde(default, rename = \"myflow_url\", alias = \"myflow-url\")]\n pub myflow_url: Option<String>,\n /// Optional token for myflow sync.\n #[serde(default, rename = \"myflow_token\", alias = \"myflow-token\")]\n pub myflow_token: Option<String>,\n /// Override Codex binary path/name (defaults to \"codex\").\n /// Useful for wrapper transports that still support `app-server` JSON-RPC.\n #[serde(default, rename = \"codex_bin\", alias = \"codex-bin\")]\n pub codex_bin: Option<String>,\n}\n\nimpl OptionsConfig {\n fn merge(&mut self, other: OptionsConfig) {\n if other.trace_terminal_io {\n self.trace_terminal_io = true;\n }\n if other.commit_with_check_async.is_some() {\n self.commit_with_check_async = other.commit_with_check_async;\n }\n if other.commit_with_check_use_repo_root.is_some() {\n self.commit_with_check_use_repo_root = other.commit_with_check_use_repo_root;\n }\n if other.commit_with_check_timeout_secs.is_some() {\n self.commit_with_check_timeout_secs = other.commit_with_check_timeout_secs;\n }\n if other.commit_with_check_review_retries.is_some() {\n self.commit_with_check_review_retries = other.commit_with_check_review_retries;\n }\n if other.commit_with_check_review_url.is_some() {\n self.commit_with_check_review_url = other.commit_with_check_review_url;\n }\n if other.commit_with_check_review_token.is_some() {\n self.commit_with_check_review_token = other.commit_with_check_review_token;\n }\n if other.commit_with_check_gitedit_mirror.is_some() {\n self.commit_with_check_gitedit_mirror = other.commit_with_check_gitedit_mirror;\n }\n if other.gitedit_mirror.is_some() {\n self.gitedit_mirror = other.gitedit_mirror;\n }\n if other.gitedit_url.is_some() {\n self.gitedit_url = other.gitedit_url;\n }\n if other.gitedit_repo_full_name.is_some() {\n self.gitedit_repo_full_name = other.gitedit_repo_full_name;\n }\n if other.gitedit_token.is_some() {\n self.gitedit_token = other.gitedit_token;\n }\n if other.myflow_mirror.is_some() {\n self.myflow_mirror = other.myflow_mirror;\n }\n if other.myflow_url.is_some() {\n self.myflow_url = other.myflow_url;\n }\n if other.myflow_token.is_some() {\n self.myflow_token = other.myflow_token;\n }\n if other.codex_bin.is_some() {\n self.codex_bin = other.codex_bin;\n }\n }\n}\n\nimpl TaskResolutionConfig {\n fn merge(&mut self, other: TaskResolutionConfig) {\n if self.preferred_scopes.is_empty() {\n self.preferred_scopes = other.preferred_scopes;\n } else {\n for scope in other.preferred_scopes {\n if !self.preferred_scopes.iter().any(|s| s == &scope) {\n self.preferred_scopes.push(scope);\n }\n }\n }\n if self.warn_on_implicit_scope.is_none() {\n self.warn_on_implicit_scope = other.warn_on_implicit_scope;\n }\n for (task, scope) in other.routes {\n self.routes.entry(task).or_insert(scope);\n }\n }\n}\n\n/// Configuration for a single managed HTTP server process.\n#[derive(Debug, Clone, Serialize, PartialEq, Eq)]\npub struct ServerConfig {\n /// Human-friendly name used in the TUI and HTTP API.\n pub name: String,\n /// Program to execute, e.g. \"node\", \"cargo\".\n pub command: String,\n /// Arguments passed to the command.\n pub args: Vec<String>,\n /// Optional port the server listens on (for display only).\n pub port: Option<u16>,\n /// Optional working directory for the process.\n pub working_dir: Option<PathBuf>,\n /// Additional environment variables.\n pub env: HashMap<String, String>,\n /// Whether this server should be started automatically with the daemon.\n pub autostart: bool,\n}\n\nimpl ServerConfig {\n pub fn to_daemon_config(&self) -> DaemonConfig {\n DaemonConfig {\n name: self.name.clone(),\n binary: self.command.clone(),\n command: None,\n args: self.args.clone(),\n working_dir: self\n .working_dir\n .as_ref()\n .map(|p| p.to_string_lossy().to_string()),\n port: self.port,\n env: self.env.clone(),\n autostart: self.autostart,\n restart: Some(DaemonRestartPolicy::OnFailure),\n description: Some(format!(\"Dev server: {}\", self.name)),\n health_url: None,\n health_socket: None,\n host: None,\n boot: false,\n autostop: false,\n retry: Some(3),\n ready_delay: None,\n ready_output: None,\n }\n }\n}\n\nimpl<'de> Deserialize<'de> for ServerConfig {\n fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>\n where\n D: Deserializer<'de>,\n {\n #[derive(Deserialize)]\n struct RawServerConfig {\n #[serde(default)]\n name: Option<String>,\n command: String,\n #[serde(default)]\n args: Vec<String>,\n #[serde(default)]\n port: Option<u16>,\n #[serde(default, alias = \"path\")]\n working_dir: Option<String>,\n #[serde(default)]\n env: HashMap<String, String>,\n #[serde(default = \"default_autostart\")]\n autostart: bool,\n }\n\n let raw = RawServerConfig::deserialize(deserializer)?;\n let mut command = raw.command;\n let mut args = raw.args;\n\n if args.is_empty() {\n if let Ok(parts) = shell_words::split(&command) {\n if let Some((head, tail)) = parts.split_first() {\n command = head.clone();\n args = tail.to_vec();\n }\n }\n }\n\n let name = raw\n .name\n .or_else(|| {\n raw.working_dir.as_ref().and_then(|dir| {\n Path::new(dir)\n .file_name()\n .map(|n| n.to_string_lossy().to_string())\n .filter(|s| !s.is_empty())\n })\n })\n .unwrap_or_else(|| {\n if command.is_empty() {\n \"server\".to_string()\n } else {\n command.clone()\n }\n });\n\n let command = expand_path(&command).to_string_lossy().into_owned();\n\n Ok(ServerConfig {\n name,\n command,\n args,\n port: raw.port,\n working_dir: raw.working_dir.map(|dir| expand_path(&dir)),\n env: raw.env,\n autostart: raw.autostart,\n })\n }\n}\n\nfn default_autostart() -> bool {\n true\n}\n\n/// Local project automation task description.\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct TaskConfig {\n /// Unique identifier for the task (used when selecting it interactively).\n pub name: String,\n /// Shell command that should be executed for this task.\n pub command: String,\n /// Whether this task should be handed off to the hub daemon instead of running locally.\n #[serde(default, rename = \"delegate-to-hub\", alias = \"delegate_to_hub\")]\n pub delegate_to_hub: bool,\n /// Whether this task should run automatically when entering the project root.\n #[serde(default)]\n pub activate_on_cd_to_root: bool,\n /// Optional task-specific dependencies that must be made available before the command runs.\n #[serde(default)]\n pub dependencies: Vec<String>,\n /// Optional human-friendly description.\n #[serde(default, alias = \"desc\")]\n pub description: Option<String>,\n /// Optional short aliases that `f run` should recognize (e.g. \"dcr\" for \"deploy-cli-release\").\n #[serde(\n default,\n alias = \"shortcut\",\n alias = \"short\",\n deserialize_with = \"deserialize_shortcuts\"\n )]\n pub shortcuts: Vec<String>,\n /// Whether this task requires interactive input (stdin passthrough, TTY).\n #[serde(default)]\n pub interactive: bool,\n /// Require confirmation when matched via LM Studio (for destructive tasks).\n #[serde(default, alias = \"confirm-on-match\")]\n pub confirm_on_match: bool,\n /// Command to run when the task is cancelled (Ctrl+C).\n #[serde(default, alias = \"on-cancel\")]\n pub on_cancel: Option<String>,\n /// Optional file path to save combined task output (relative to project root unless absolute).\n #[serde(default, alias = \"output-file\")]\n pub output_file: Option<String>,\n}\n\n/// Definition of a dependency that can be referenced by automation tasks.\n#[derive(Debug, Clone, Deserialize, Serialize)]\n#[serde(untagged)]\npub enum DependencySpec {\n /// Single command/binary that should be available on PATH.\n Single(String),\n /// Multiple commands that should be checked together.\n Multiple(Vec<String>),\n /// Flox package descriptor that should be added to the local env manifest.\n Flox(FloxInstallSpec),\n}\n\nfn deserialize_shortcuts<'de, D>(deserializer: D) -> std::result::Result<Vec<String>, D::Error>\nwhere\n D: Deserializer<'de>,\n{\n #[derive(Deserialize)]\n #[serde(untagged)]\n enum ShortcutField {\n Single(String),\n Multiple(Vec<String>),\n }\n\n let value = Option::<ShortcutField>::deserialize(deserializer)?;\n let shortcuts = match value {\n Some(ShortcutField::Single(alias)) => vec![alias],\n Some(ShortcutField::Multiple(aliases)) => aliases,\n None => Vec::new(),\n };\n Ok(shortcuts)\n}\n\n/// Storage configuration describing remote environments providers.\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct StorageConfig {\n /// Provider identifier understood by the hosted hub.\n pub provider: String,\n /// Environment variable that stores the API key/token.\n #[serde(default = \"default_storage_env_var\")]\n pub env_var: String,\n /// Base URL for the storage hub (defaults to hosted flow hub).\n #[serde(default = \"default_hub_url\")]\n pub hub_url: String,\n /// Environments that can be synced locally.\n #[serde(default)]\n pub envs: Vec<StorageEnvConfig>,\n}\n\nfn default_hub_url() -> String {\n \"https://myflow.sh\".to_string()\n}\n\nfn default_storage_env_var() -> String {\n \"FLOW_SECRETS_TOKEN\".to_string()\n}\n\n/// Definition of an environment with named variables.\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct StorageEnvConfig {\n pub name: String,\n #[serde(default)]\n pub description: Option<String>,\n #[serde(default)]\n pub variables: Vec<StorageVariable>,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct StorageVariable {\n pub key: String,\n #[serde(default)]\n pub default: Option<String>,\n}\n\n/// Flox manifest-style configuration (install set, etc.).\n#[derive(Debug, Clone, Default, Deserialize, Serialize)]\npub struct FloxConfig {\n #[serde(default, rename = \"install\", alias = \"deps\")]\n pub install: HashMap<String, FloxInstallSpec>,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct FloxInstallSpec {\n #[serde(rename = \"pkg-path\")]\n pub pkg_path: String,\n #[serde(default, rename = \"pkg-group\")]\n pub pkg_group: Option<String>,\n #[serde(default)]\n pub version: Option<String>,\n #[serde(default)]\n pub systems: Option<Vec<String>>,\n #[serde(default)]\n pub priority: Option<i64>,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct CommandFileConfig {\n pub path: String,\n #[serde(default)]\n pub description: Option<String>,\n}\n\n#[allow(dead_code)]\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct RemoteServerConfig {\n #[serde(flatten)]\n pub server: ServerConfig,\n /// Optional hub name that coordinates this remote process.\n #[serde(default)]\n pub hub: Option<String>,\n /// Paths to sync to the remote hub before launching.\n #[serde(default)]\n pub sync_paths: Vec<PathBuf>,\n}\n\n#[allow(dead_code)]\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct ServerHubConfig {\n pub name: String,\n pub host: String,\n #[serde(default = \"default_server_hub_port\")]\n pub port: u16,\n #[serde(default)]\n pub tailscale: Option<String>,\n #[serde(default)]\n pub description: Option<String>,\n}\n\nfn default_server_hub_port() -> u16 {\n 9050\n}\n\n/// File watcher configuration for local automation.\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct WatcherConfig {\n #[serde(default)]\n pub driver: WatcherDriver,\n pub name: String,\n pub path: String,\n #[serde(default, rename = \"match\")]\n pub filter: Option<String>,\n #[serde(default)]\n pub command: Option<String>,\n #[serde(default = \"default_debounce_ms\")]\n pub debounce_ms: u64,\n #[serde(default)]\n pub run_on_start: bool,\n #[serde(default)]\n pub env: HashMap<String, String>,\n #[serde(default)]\n pub poltergeist: Option<PoltergeistConfig>,\n}\n\n#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"snake_case\")]\npub enum WatcherDriver {\n Shell,\n Poltergeist,\n}\n\nimpl Default for WatcherDriver {\n fn default() -> Self {\n WatcherDriver::Shell\n }\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct PoltergeistConfig {\n #[serde(default = \"default_poltergeist_binary\")]\n pub binary: String,\n #[serde(default)]\n pub mode: PoltergeistMode,\n #[serde(default)]\n pub args: Vec<String>,\n}\n\nimpl Default for PoltergeistConfig {\n fn default() -> Self {\n Self {\n binary: default_poltergeist_binary(),\n mode: PoltergeistMode::Haunt,\n args: Vec::new(),\n }\n }\n}\n\n#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"snake_case\")]\npub enum PoltergeistMode {\n Haunt,\n Panel,\n Status,\n}\n\nimpl Default for PoltergeistMode {\n fn default() -> Self {\n PoltergeistMode::Haunt\n }\n}\n\nfn default_debounce_ms() -> u64 {\n 200\n}\n\nfn default_poltergeist_binary() -> String {\n \"poltergeist\".to_string()\n}\n\nimpl PoltergeistMode {\n pub fn as_subcommand(&self) -> &'static str {\n match self {\n PoltergeistMode::Haunt => \"haunt\",\n PoltergeistMode::Panel => \"panel\",\n PoltergeistMode::Status => \"status\",\n }\n }\n}\n\n/// Streaming configuration handled by the hub (stub for future OBS integration).\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct StreamConfig {\n pub provider: String,\n #[serde(default)]\n pub hotkey: Option<String>,\n #[serde(default)]\n pub toggle_url: Option<String>,\n}\n\n/// Restart behavior for managed daemons.\n#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]\n#[serde(rename_all = \"kebab-case\")]\npub enum DaemonRestartPolicy {\n Never,\n OnFailure,\n Always,\n}\n\n/// Configuration for a background daemon that flow can manage.\n///\n/// Example in flow.toml:\n/// ```toml\n/// [[daemon]]\n/// name = \"lin\"\n/// binary = \"lin\"\n/// command = \"daemon\"\n/// args = [\"--host\", \"127.0.0.1\", \"--port\", \"9050\"]\n/// health_url = \"http://127.0.0.1:9050/health\"\n///\n/// [[daemon]]\n/// name = \"base\"\n/// binary = \"base\"\n/// command = \"jazz\"\n/// args = [\"--port\", \"7201\"]\n/// health_url = \"http://127.0.0.1:7201/health\"\n/// working_dir = \"~/code/myflow\"\n/// ```\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct DaemonConfig {\n /// Unique name for this daemon (used in `f daemon start <name>`).\n pub name: String,\n /// Binary to execute (can be a name on PATH or absolute path).\n pub binary: String,\n /// Subcommand to run the daemon (e.g., \"daemon\", \"jazz\", \"serve\").\n #[serde(default)]\n pub command: Option<String>,\n /// Additional arguments passed after the command.\n #[serde(default)]\n pub args: Vec<String>,\n /// Health check URL to determine if daemon is running.\n #[serde(default, alias = \"health\")]\n pub health_url: Option<String>,\n /// Unix socket path to probe to determine if a daemon is running.\n #[serde(default, alias = \"health-socket\", alias = \"health_socket\")]\n pub health_socket: Option<String>,\n /// Port the daemon listens on (extracted from health_url if not specified).\n #[serde(default)]\n pub port: Option<u16>,\n /// Host the daemon binds to.\n #[serde(default)]\n pub host: Option<String>,\n /// Working directory for the daemon process.\n #[serde(default, alias = \"path\")]\n pub working_dir: Option<String>,\n /// Environment variables to set for the daemon.\n #[serde(default)]\n pub env: HashMap<String, String>,\n /// Whether to start this daemon automatically when flow starts.\n #[serde(default)]\n pub autostart: bool,\n /// Whether to stop this daemon when leaving the project.\n #[serde(default)]\n pub autostop: bool,\n /// Whether to start this daemon during boot/startup sessions.\n #[serde(default)]\n pub boot: bool,\n /// Restart policy (never, on-failure, always).\n #[serde(default)]\n pub restart: Option<DaemonRestartPolicy>,\n /// Maximum restart attempts (optional).\n #[serde(default)]\n pub retry: Option<u32>,\n /// Milliseconds to wait before considering the daemon ready.\n #[serde(default)]\n pub ready_delay: Option<u64>,\n /// Output pattern (string or regex) to match for readiness.\n #[serde(default)]\n pub ready_output: Option<String>,\n /// Description of what this daemon does.\n #[serde(default)]\n pub description: Option<String>,\n}\n\nimpl DaemonConfig {\n /// Get the effective health URL, building from host/port if not specified.\n pub fn effective_health_url(&self) -> Option<String> {\n if let Some(url) = &self.health_url {\n return Some(url.clone());\n }\n let host = self.host.as_deref().unwrap_or(\"127.0.0.1\");\n self.port.map(|p| format!(\"http://{}:{}/health\", host, p))\n }\n\n /// Get the effective unix socket health target, if configured.\n pub fn effective_health_socket(&self) -> Option<PathBuf> {\n self.health_socket.as_ref().map(|path| expand_path(path))\n }\n\n /// Get the effective host.\n pub fn effective_host(&self) -> &str {\n self.host.as_deref().unwrap_or(\"127.0.0.1\")\n }\n\n /// Human-readable health target for status output.\n pub fn health_target_label(&self) -> Option<String> {\n if let Some(url) = self.effective_health_url() {\n return Some(url.replace(\"/health\", \"\"));\n }\n self.effective_health_socket()\n .map(|path| format!(\"unix:{}\", path.display()))\n }\n}\n\nimpl DependencySpec {\n /// Add one or more command names to the provided buffer.\n pub fn extend_commands(&self, buffer: &mut Vec<String>) {\n match self {\n DependencySpec::Single(cmd) => buffer.push(cmd.clone()),\n DependencySpec::Multiple(cmds) => buffer.extend(cmds.iter().cloned()),\n DependencySpec::Flox(_) => {}\n }\n }\n}\n\nfn deserialize_aliases<'de, D>(deserializer: D) -> Result<HashMap<String, String>, D::Error>\nwhere\n D: Deserializer<'de>,\n{\n #[derive(Deserialize)]\n #[serde(untagged)]\n enum AliasInput {\n Map(HashMap<String, String>),\n List(Vec<HashMap<String, String>>),\n }\n\n let maybe = Option::<AliasInput>::deserialize(deserializer)?;\n let mut aliases = HashMap::new();\n if let Some(input) = maybe {\n match input {\n AliasInput::Map(map) => aliases = map,\n AliasInput::List(list) => {\n for table in list {\n for (name, command) in table {\n aliases.insert(name, command);\n }\n }\n }\n }\n }\n\n Ok(aliases)\n}\n\n/// Default config path: ~/.config/flow/flow.toml (falls back to legacy config.toml)\npub fn default_config_path() -> PathBuf {\n let base = global_config_dir();\n\n let primary = base.join(\"flow.toml\");\n if primary.exists() {\n return primary;\n }\n\n let legacy = base.join(\"config.toml\");\n if legacy.exists() {\n tracing::warn!(\"using legacy config path ~/.config/flow/config.toml; rename to flow.toml\");\n return legacy;\n }\n\n primary\n}\n\n/// Global config directory: ~/.config/flow\npub fn global_config_dir() -> PathBuf {\n std::env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".config/flow\")\n}\n\nfn legacy_global_state_dir_for(config_dir: &Path) -> PathBuf {\n config_dir.with_file_name(\"flow-state\")\n}\n\nfn select_global_state_dir(config_dir: &Path) -> PathBuf {\n let legacy_dir = legacy_global_state_dir_for(config_dir);\n if is_dir_path(&legacy_dir) {\n return legacy_dir;\n }\n if is_dir_path(config_dir) || !config_dir.exists() {\n return config_dir.to_path_buf();\n }\n legacy_dir\n}\n\n/// Ensure the global config directory exists (moves aside files that block it).\npub fn ensure_global_config_dir() -> Result<PathBuf> {\n let dir = global_config_dir();\n if let Some(parent) = dir.parent() {\n ensure_dir(parent)?;\n }\n ensure_dir(&dir)?;\n Ok(dir)\n}\n\n/// Global state directory for runtime data.\npub fn global_state_dir() -> PathBuf {\n let config_dir = global_config_dir();\n select_global_state_dir(&config_dir)\n}\n\n/// Global state directory candidates (primary first) for migration-safe readers.\npub fn global_state_dir_candidates() -> Vec<PathBuf> {\n let config_dir = global_config_dir();\n let legacy_dir = legacy_global_state_dir_for(&config_dir);\n let primary = select_global_state_dir(&config_dir);\n let mut candidates = vec![primary.clone()];\n for candidate in [config_dir, legacy_dir] {\n if candidate != primary && is_dir_path(&candidate) {\n candidates.push(candidate);\n }\n }\n candidates\n}\n\n/// Ensure the global state directory exists.\npub fn ensure_global_state_dir() -> Result<PathBuf> {\n let dir = global_state_dir();\n if let Some(parent) = dir.parent() {\n ensure_dir(parent)?;\n }\n ensure_dir(&dir)?;\n Ok(dir)\n}\n\nfn ensure_dir(path: &Path) -> Result<()> {\n if let Ok(meta) = fs::symlink_metadata(path) {\n let is_dir = meta.is_dir();\n let is_symlink = meta.file_type().is_symlink();\n if is_dir {\n return Ok(());\n }\n if is_symlink {\n if let Ok(target_meta) = fs::metadata(path) {\n if target_meta.is_dir() {\n return Ok(());\n }\n }\n }\n\n let backup = backup_path(path);\n fs::rename(path, &backup).with_context(|| {\n format!(\n \"failed to move existing {} to {}\",\n path.display(),\n backup.display()\n )\n })?;\n tracing::warn!(\n \"moved blocking path {} to {}\",\n path.display(),\n backup.display()\n );\n }\n\n fs::create_dir_all(path).with_context(|| format!(\"failed to create {}\", path.display()))?;\n Ok(())\n}\n\nfn is_dir_path(path: &Path) -> bool {\n if let Ok(meta) = fs::symlink_metadata(path) {\n if meta.is_dir() {\n return true;\n }\n if meta.file_type().is_symlink() {\n if let Ok(target_meta) = fs::metadata(path) {\n return target_meta.is_dir();\n }\n }\n }\n false\n}\n\nfn backup_path(path: &Path) -> PathBuf {\n let name = path.file_name().and_then(|n| n.to_str()).unwrap_or(\"flow\");\n let ts = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|d| d.as_secs())\n .unwrap_or(0);\n path.with_file_name(format!(\"{}-archive-{}\", name, ts))\n}\n\n/// Load global secrets from ~/.config/flow/secrets.toml\npub fn load_global_secrets() {\n let secrets_path = global_config_dir().join(\"secrets.toml\");\n if secrets_path.exists() {\n if let Ok(secrets) = load_secrets(&secrets_path) {\n let mut dummy = Config::default();\n merge_secrets(&mut dummy, secrets);\n tracing::debug!(path = %secrets_path.display(), \"loaded global secrets\");\n }\n }\n}\n\n/// Path to TypeScript config: ~/.config/flow/config.ts\npub fn ts_config_path() -> PathBuf {\n global_config_dir().join(\"config.ts\")\n}\n\n/// Load TypeScript config from ~/.config/flow/config.ts using bun.\n/// Returns None if config.ts doesn't exist or fails to load.\npub fn load_ts_config() -> Option<TsConfig> {\n let config_path = ts_config_path();\n if !config_path.exists() {\n return None;\n }\n\n // Use bun to evaluate the TypeScript and output JSON\n let loader_script = format!(\n r#\"const config = await import(\"{}\"); console.log(JSON.stringify(config.default || config));\"#,\n config_path.display()\n );\n\n let mut child = std::process::Command::new(\"bun\")\n .args([\"run\", \"-\"])\n .stdin(std::process::Stdio::piped())\n .stdout(std::process::Stdio::piped())\n .stderr(std::process::Stdio::piped())\n .spawn()\n .ok()?;\n\n if let Some(mut stdin) = child.stdin.take() {\n use std::io::Write;\n let _ = stdin.write_all(loader_script.as_bytes());\n }\n\n let output = child.wait_with_output().ok()?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n tracing::warn!(\"failed to load config.ts: {}\", stderr.trim());\n return None;\n }\n\n let json = String::from_utf8_lossy(&output.stdout);\n match serde_json::from_str::<TsConfig>(json.trim()) {\n Ok(config) => {\n tracing::debug!(path = %config_path.display(), \"loaded TypeScript config\");\n Some(config)\n }\n Err(err) => {\n tracing::warn!(\"failed to parse config.ts output: {}\", err);\n None\n }\n }\n}\n\n/// Preferred env backend from ~/.config/flow/config.ts (\"cloud\" or \"local\").\npub fn preferred_env_backend() -> Option<String> {\n let config = load_ts_config()?;\n let backend = config.flow?.env?.backend?;\n let trimmed = backend.trim();\n if trimmed.is_empty() {\n return None;\n }\n Some(trimmed.to_ascii_lowercase())\n}\n\n/// Env vars to inject into every task from the personal env store.\n/// Defaults to AI server connection vars unless overridden in config.ts.\npub fn global_env_keys() -> Vec<String> {\n static GLOBAL_KEYS: OnceLock<Vec<String>> = OnceLock::new();\n GLOBAL_KEYS\n .get_or_init(|| {\n let mut keys = vec![\n \"AI_SERVER_URL\".to_string(),\n \"AI_SERVER_TOKEN\".to_string(),\n \"AI_SERVER_MODEL\".to_string(),\n \"ZAI_API_KEY\".to_string(),\n ];\n\n if let Some(config) = load_ts_config() {\n if let Some(env) = config.flow.and_then(|flow| flow.env) {\n if !env.global_keys.is_empty() {\n keys = env.global_keys;\n }\n }\n }\n\n keys\n })\n .clone()\n}\n\npub fn expand_path(raw: &str) -> PathBuf {\n let tilde_expanded = tilde(raw).into_owned();\n let env_expanded = match shellexpand::env(&tilde_expanded) {\n Ok(val) => val.into_owned(),\n Err(_) => tilde_expanded,\n };\n PathBuf::from(env_expanded)\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct ConfigCacheEntry {\n version: u32,\n config: Config,\n watched: Vec<ConfigPathStamp>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct ConfigPathStamp {\n path: PathBuf,\n is_dir: bool,\n len: u64,\n modified_sec: u64,\n modified_nsec: u32,\n}\n\n#[derive(Debug)]\nstruct ConfigLoadArtifacts {\n config: Config,\n watched_paths: Vec<PathBuf>,\n}\n\npub fn load<P: AsRef<Path>>(path: P) -> Result<Config> {\n let path = path.as_ref();\n if config_cache_disabled() {\n let mut cfg = load_uncached(path)?.config;\n load_sibling_secrets(&mut cfg, path);\n return Ok(cfg);\n }\n\n let canonical = path\n .canonicalize()\n .with_context(|| format!(\"failed to resolve path {}\", path.display()))?;\n let cache_path = config_cache_path(&canonical);\n if let Some(entry) = read_config_cache(&cache_path)\n && config_stamps_match(&entry.watched)\n {\n let mut cfg = entry.config;\n load_sibling_secrets(&mut cfg, &canonical);\n return Ok(cfg);\n }\n\n let artifacts = load_uncached(&canonical)?;\n let mut cfg = artifacts.config.clone();\n load_sibling_secrets(&mut cfg, &canonical);\n let cache = ConfigCacheEntry {\n version: CONFIG_CACHE_VERSION,\n config: artifacts.config,\n watched: config_stamps_for_paths(&artifacts.watched_paths),\n };\n if let Err(err) = write_config_cache(&cache_path, &cache) {\n tracing::debug!(path = %cache_path.display(), error = %err, \"failed to write config cache\");\n }\n\n Ok(cfg)\n}\n\n/// Secrets that can be loaded from a separate file to avoid exposing on stream.\n#[derive(Debug, Clone, Default, Deserialize)]\nstruct Secrets {\n #[serde(default)]\n env: HashMap<String, String>,\n #[serde(default)]\n cloudflare: Option<CloudflareSecrets>,\n #[serde(default)]\n openai: Option<ApiKeySecret>,\n #[serde(default)]\n anthropic: Option<ApiKeySecret>,\n #[serde(default)]\n cerebras: Option<ApiKeySecret>,\n}\n\n#[derive(Debug, Clone, Default, Deserialize)]\nstruct CloudflareSecrets {\n account_id: Option<String>,\n stream_token: Option<String>,\n stream_key: Option<String>,\n}\n\n#[derive(Debug, Clone, Default, Deserialize)]\nstruct ApiKeySecret {\n #[serde(alias = \"api_key\", alias = \"key\")]\n api_key: Option<String>,\n}\n\nfn load_secrets(path: &Path) -> Result<Secrets> {\n let contents = fs::read_to_string(path)\n .with_context(|| format!(\"failed to read secrets at {}\", path.display()))?;\n let secrets: Secrets = toml::from_str(&contents)\n .with_context(|| format!(\"failed to parse secrets at {}\", path.display()))?;\n Ok(secrets)\n}\n\nfn merge_secrets(cfg: &mut Config, secrets: Secrets) {\n // Inject secrets as environment variables for child processes\n // SAFETY: We're setting env vars at startup before any threads are spawned\n unsafe {\n for (key, value) in secrets.env {\n std::env::set_var(&key, &value);\n }\n if let Some(cf) = secrets.cloudflare {\n if let Some(v) = cf.account_id {\n std::env::set_var(\"CLOUDFLARE_ACCOUNT_ID\", &v);\n }\n if let Some(v) = cf.stream_token {\n std::env::set_var(\"CLOUDFLARE_STREAM_TOKEN\", &v);\n }\n if let Some(v) = cf.stream_key {\n std::env::set_var(\"CLOUDFLARE_STREAM_KEY\", &v);\n }\n }\n if let Some(openai) = secrets.openai {\n if let Some(v) = openai.api_key {\n std::env::set_var(\"OPENAI_API_KEY\", &v);\n }\n }\n if let Some(anthropic) = secrets.anthropic {\n if let Some(v) = anthropic.api_key {\n std::env::set_var(\"ANTHROPIC_API_KEY\", &v);\n }\n }\n if let Some(cerebras) = secrets.cerebras {\n if let Some(v) = cerebras.api_key {\n std::env::set_var(\"CEREBRAS_API_KEY\", &v);\n }\n }\n }\n // Storage config can also reference these env vars\n let _ = cfg; // cfg itself doesn't need modification, env vars are set\n}\n\nfn load_uncached(path: &Path) -> Result<ConfigLoadArtifacts> {\n let mut visited = Vec::new();\n let mut watched_paths = Vec::new();\n let config = load_with_includes(path, &mut visited, &mut watched_paths)?;\n Ok(ConfigLoadArtifacts {\n config,\n watched_paths,\n })\n}\n\nfn load_sibling_secrets(cfg: &mut Config, path: &Path) {\n if let Some(parent) = path.parent() {\n let secrets_path = parent.join(\"secrets.toml\");\n if secrets_path.exists() {\n if let Ok(secrets) = load_secrets(&secrets_path) {\n merge_secrets(cfg, secrets);\n tracing::debug!(path = %secrets_path.display(), \"loaded secrets file\");\n }\n }\n }\n}\n\nfn load_with_includes(\n path: &Path,\n visited: &mut Vec<PathBuf>,\n watched_paths: &mut Vec<PathBuf>,\n) -> Result<Config> {\n let canonical = path\n .canonicalize()\n .with_context(|| format!(\"failed to resolve path {}\", path.display()))?;\n if visited.contains(&canonical) {\n anyhow::bail!(\n \"cycle detected while loading config includes: {}\",\n path.display()\n );\n }\n visited.push(canonical.clone());\n watched_paths.push(canonical.clone());\n\n let contents = fs::read_to_string(&canonical)\n .with_context(|| format!(\"failed to read flow config at {}\", path.display()))?;\n let mut cfg: Config = match toml::from_str(&contents) {\n Ok(cfg) => cfg,\n Err(err) => {\n let fix = fixup::fix_toml_content(&contents);\n if fix.fixes_applied.is_empty() {\n return Err(err)\n .with_context(|| format!(\"failed to parse flow config at {}\", path.display()));\n }\n let fixed = fixup::apply_fixes_to_content(&contents, &fix.fixes_applied);\n if let Err(write_err) = fs::write(&canonical, &fixed) {\n return Err(err)\n .with_context(|| format!(\"failed to parse flow config at {}\", path.display()))\n .with_context(|| format!(\"auto-fix write failed: {}\", write_err));\n }\n toml::from_str(&fixed).with_context(|| {\n format!(\n \"failed to parse flow config at {} (after auto-fix)\",\n path.display()\n )\n })?\n }\n };\n\n for include in cfg.command_files.clone() {\n let include_path = resolve_include_path(&canonical, &include.path);\n if let Some(description) = include.description.as_deref() {\n tracing::debug!(\n path = %include_path.display(),\n description,\n \"loading additional command file\"\n );\n }\n let included = load_with_includes(&include_path, visited, watched_paths)\n .with_context(|| format!(\"failed to load commands file {}\", include_path.display()))?;\n merge_config(&mut cfg, included);\n }\n\n visited.pop();\n Ok(cfg)\n}\n\nfn config_cache_disabled() -> bool {\n matches!(\n std::env::var(CONFIG_CACHE_ENV_DISABLE)\n .ok()\n .as_deref()\n .map(str::trim)\n .map(str::to_ascii_lowercase)\n .as_deref(),\n Some(\"1\" | \"true\" | \"yes\" | \"on\")\n )\n}\n\nfn config_cache_path(path: &Path) -> PathBuf {\n let hash = blake3::hash(path.to_string_lossy().as_bytes()).to_hex();\n global_state_dir()\n .join(\"config-cache\")\n .join(format!(\"{hash}.msgpack\"))\n}\n\nfn read_config_cache(path: &Path) -> Option<ConfigCacheEntry> {\n let bytes = fs::read(path).ok()?;\n let cache = rmp_serde::from_slice::<ConfigCacheEntry>(&bytes).ok()?;\n if cache.version != CONFIG_CACHE_VERSION {\n return None;\n }\n Some(cache)\n}\n\nfn write_config_cache(path: &Path, cache: &ConfigCacheEntry) -> Result<()> {\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create config cache dir {}\", parent.display()))?;\n }\n\n let bytes = rmp_serde::to_vec(cache).context(\"failed to encode config cache\")?;\n let tmp_path = path.with_extension(format!(\"msgpack.tmp.{}\", std::process::id()));\n fs::write(&tmp_path, bytes)\n .with_context(|| format!(\"failed to write config cache {}\", tmp_path.display()))?;\n if let Err(err) = fs::rename(&tmp_path, path) {\n if path.exists() {\n let _ = fs::remove_file(path);\n fs::rename(&tmp_path, path)\n .with_context(|| format!(\"failed to finalize config cache {}\", path.display()))?;\n } else {\n return Err(err)\n .with_context(|| format!(\"failed to finalize config cache {}\", path.display()));\n }\n }\n Ok(())\n}\n\nfn config_stamps_for_paths(paths: &[PathBuf]) -> Vec<ConfigPathStamp> {\n let mut stamps: Vec<ConfigPathStamp> = paths\n .iter()\n .filter_map(|path| ConfigPathStamp::capture(path))\n .collect();\n stamps.sort_by(|a, b| a.path.cmp(&b.path));\n stamps.dedup_by(|a, b| a.path == b.path);\n stamps\n}\n\nfn config_stamps_match(stamps: &[ConfigPathStamp]) -> bool {\n stamps.iter().all(ConfigPathStamp::matches_current)\n}\n\nimpl ConfigPathStamp {\n fn capture(path: &Path) -> Option<Self> {\n let metadata = fs::metadata(path).ok()?;\n let modified = metadata.modified().ok()?.duration_since(UNIX_EPOCH).ok()?;\n Some(Self {\n path: path.to_path_buf(),\n is_dir: metadata.is_dir(),\n len: metadata.len(),\n modified_sec: modified.as_secs(),\n modified_nsec: modified.subsec_nanos(),\n })\n }\n\n fn matches_current(&self) -> bool {\n let Some(current) = Self::capture(&self.path) else {\n return false;\n };\n self.is_dir == current.is_dir\n && self.len == current.len\n && self.modified_sec == current.modified_sec\n && self.modified_nsec == current.modified_nsec\n }\n}\n\npub(crate) fn resolve_include_path(base: &Path, include: &str) -> PathBuf {\n let include_path = PathBuf::from(include);\n if include_path.is_absolute() {\n include_path\n } else if let Some(parent) = base.parent() {\n parent.join(include_path)\n } else {\n include_path\n }\n}\n\nfn merge_config(base: &mut Config, other: Config) {\n if base.project_name.is_none() {\n base.project_name = other.project_name;\n }\n if base.flow.primary_task.is_none() {\n base.flow.primary_task = other.flow.primary_task;\n }\n if base.flow.release_task.is_none() {\n base.flow.release_task = other.flow.release_task;\n }\n if base.flow.deploy_task.is_none() {\n base.flow.deploy_task = other.flow.deploy_task;\n }\n if base.codex.is_none() {\n base.codex = other.codex;\n } else if let (Some(base_codex), Some(other_codex)) = (base.codex.as_mut(), other.codex) {\n base_codex.merge(other_codex);\n }\n merge_release_config(base, other.release);\n if base.setup.is_none() {\n base.setup = other.setup;\n } else if let (Some(base_setup), Some(other_setup)) = (base.setup.as_mut(), other.setup) {\n if base_setup.server.is_none() {\n base_setup.server = other_setup.server;\n } else if let (Some(base_server), Some(other_server)) =\n (base_setup.server.as_mut(), other_setup.server)\n {\n if base_server.template.is_none() {\n base_server.template = other_server.template;\n }\n if base_server.host.is_none() {\n base_server.host = other_server.host;\n }\n }\n }\n if base.task_resolution.is_none() {\n base.task_resolution = other.task_resolution;\n } else if let (Some(base_resolution), Some(other_resolution)) =\n (base.task_resolution.as_mut(), other.task_resolution)\n {\n base_resolution.merge(other_resolution);\n }\n if base.analytics.is_none() {\n base.analytics = other.analytics;\n }\n if base.git.is_none() {\n base.git = other.git;\n }\n if base.jj.is_none() {\n base.jj = other.jj;\n }\n if base.everruns.is_none() {\n base.everruns = other.everruns;\n }\n base.options.merge(other.options);\n base.servers.extend(other.servers);\n base.remote_servers.extend(other.remote_servers);\n base.tasks.extend(other.tasks);\n base.watchers.extend(other.watchers);\n base.daemons.extend(other.daemons);\n base.stream = base.stream.take().or(other.stream);\n base.invariants = base.invariants.take().or(other.invariants);\n base.storage = base.storage.take().or(other.storage);\n base.server_hub = base.server_hub.take().or(other.server_hub);\n for (key, value) in other.aliases {\n base.aliases.entry(key).or_insert(value);\n }\n for (key, value) in other.dependencies {\n base.dependencies.entry(key).or_insert(value);\n }\n match (&mut base.flox, other.flox) {\n (Some(base_flox), Some(other_flox)) => {\n for (key, value) in other_flox.install {\n base_flox.install.entry(key).or_insert(value);\n }\n }\n (None, Some(other_flox)) => base.flox = Some(other_flox),\n _ => {}\n }\n}\n\nfn merge_release_config(base: &mut Config, other: Option<ReleaseConfig>) {\n let Some(other) = other else {\n return;\n };\n let base_release = base.release.get_or_insert_with(ReleaseConfig::default);\n\n if base_release.default.is_none() {\n base_release.default = other.default;\n }\n if base_release.domain.is_none() {\n base_release.domain = other.domain;\n }\n if base_release.base_url.is_none() {\n base_release.base_url = other.base_url;\n }\n if base_release.root.is_none() {\n base_release.root = other.root;\n }\n if base_release.caddyfile.is_none() {\n base_release.caddyfile = other.caddyfile;\n }\n if base_release.readme.is_none() {\n base_release.readme = other.readme;\n }\n\n if let Some(other_registry) = other.registry {\n let registry = base_release\n .registry\n .get_or_insert_with(RegistryReleaseConfig::default);\n if registry.url.is_none() {\n registry.url = other_registry.url;\n }\n if registry.package.is_none() {\n registry.package = other_registry.package;\n }\n if registry.bins.is_none() {\n registry.bins = other_registry.bins;\n }\n if registry.default_bin.is_none() {\n registry.default_bin = other_registry.default_bin;\n }\n if registry.token_env.is_none() {\n registry.token_env = other_registry.token_env;\n }\n if registry.latest.is_none() {\n registry.latest = other_registry.latest;\n }\n }\n}\n\nfn first_non_empty_remote(value: Option<&str>) -> Option<String> {\n let trimmed = value.map(str::trim).unwrap_or_default();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n }\n}\n\nfn preferred_git_remote_from_cfg(cfg: &Config) -> Option<String> {\n if let Some(remote) = cfg\n .git\n .as_ref()\n .and_then(|git_cfg| first_non_empty_remote(git_cfg.remote.as_deref()))\n {\n return Some(remote);\n }\n\n // Backward compatibility: honor jj.remote when git.remote is not set.\n cfg.jj\n .as_ref()\n .and_then(|jj_cfg| first_non_empty_remote(jj_cfg.remote.as_deref()))\n}\n\n/// Resolve the preferred writable git remote for a repository.\n///\n/// Precedence:\n/// 1. `<repo>/flow.toml` `[git].remote`\n/// 2. `<repo>/flow.toml` `[jj].remote` (legacy fallback)\n/// 3. `~/.config/flow/flow.toml` `[git].remote`\n/// 4. `~/.config/flow/flow.toml` `[jj].remote` (legacy fallback)\n/// 5. `\"origin\"`\npub fn preferred_git_remote_for_repo(repo_root: &Path) -> String {\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = load(&local_config) {\n if let Some(remote) = preferred_git_remote_from_cfg(&cfg) {\n return remote;\n }\n }\n }\n\n let global_config = default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = load(&global_config) {\n if let Some(remote) = preferred_git_remote_from_cfg(&cfg) {\n return remote;\n }\n }\n }\n\n \"origin\".to_string()\n}\n\n/// Load config from the given path, logging a warning and returning an empty\n/// config if anything goes wrong. This keeps the daemon usable even if the\n/// config file is missing or invalid.\npub fn load_or_default<P: AsRef<Path>>(path: P) -> Config {\n match load(path) {\n Ok(cfg) => cfg,\n Err(err) => {\n tracing::warn!(\n ?err,\n \"failed to load flow config; starting with no managed servers\"\n );\n Config::default()\n }\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use std::path::PathBuf;\n use tempfile::tempdir;\n\n fn fixture_path(relative: &str) -> PathBuf {\n PathBuf::from(env!(\"CARGO_MANIFEST_DIR\")).join(relative)\n }\n\n #[test]\n fn load_parses_global_fixture() {\n let cfg = load(fixture_path(\"test-data/global-config/flow.toml\"))\n .expect(\"global config fixture should parse\");\n\n assert_eq!(cfg.version, Some(1));\n assert!(cfg.options.trace_terminal_io, \"options table should parse\");\n assert_eq!(cfg.servers.len(), 1);\n assert_eq!(cfg.remote_servers.len(), 1);\n assert_eq!(cfg.watchers.len(), 1);\n assert_eq!(\n cfg.tasks.len(),\n 1,\n \"global config should inherit tasks from included command files\"\n );\n\n let watcher = &cfg.watchers[0];\n assert_eq!(watcher.driver, WatcherDriver::Shell);\n assert_eq!(watcher.name, \"karabiner\");\n assert_eq!(watcher.path, \"~/config/i/karabiner\");\n assert_eq!(watcher.filter.as_deref(), Some(\"karabiner.edn\"));\n assert_eq!(watcher.command.as_deref(), Some(\"~/bin/goku\"));\n assert_eq!(watcher.debounce_ms, 150);\n assert!(watcher.run_on_start);\n assert!(watcher.poltergeist.is_none());\n\n let server = &cfg.servers[0];\n assert_eq!(server.name, \"cloud\");\n assert_eq!(server.command, \"blade\");\n assert_eq!(server.args, [\"--port\", \"4000\"]);\n let working_dir = server\n .working_dir\n .as_ref()\n .expect(\"server working dir should parse\");\n assert!(\n working_dir.ends_with(\"code/myflow\"),\n \"unexpected working dir: {}\",\n working_dir.display()\n );\n assert!(server.env.is_empty());\n assert!(\n server.autostart,\n \"autostart should default to true when omitted\"\n );\n\n let sync_task = &cfg.tasks[0];\n assert_eq!(sync_task.name, \"sync-config\");\n assert_eq!(\n sync_task.command,\n \"rsync -av ~/.config/flow remote:~/flow-config\"\n );\n assert!(\n cfg.aliases.contains_key(\"fsh\"),\n \"included aliases should merge into base config\"\n );\n\n let remote = &cfg.remote_servers[0];\n assert_eq!(remote.server.name, \"homelab-blade\");\n assert_eq!(remote.hub.as_deref(), Some(\"homelab\"));\n assert_eq!(remote.sync_paths, [PathBuf::from(\"~/config/i/karabiner\")]);\n\n let hub = cfg.server_hub.as_ref().expect(\"server hub config\");\n assert_eq!(hub.name, \"homelab\");\n assert_eq!(hub.host, \"tailscale\");\n assert_eq!(hub.port, 9050);\n assert_eq!(hub.tailscale.as_deref(), Some(\"linux-hub\"));\n }\n\n #[test]\n fn server_port_is_preserved_when_present() {\n let toml = r#\"\n [[server]]\n name = \"api\"\n command = \"npm start\"\n port = 8080\n \"#;\n\n let cfg: Config = toml::from_str(toml).expect(\"server config should parse\");\n let server = cfg.servers.first().expect(\"server should parse\");\n assert_eq!(server.port, Some(8080));\n\n // Missing port should deserialize as None for backward compatibility.\n let no_port_toml = r#\"\n [[server]]\n name = \"web\"\n command = \"npm run dev\"\n \"#;\n let cfg: Config =\n toml::from_str(no_port_toml).expect(\"server config without port should parse\");\n assert_eq!(cfg.servers[0].port, None);\n }\n\n #[test]\n fn expand_path_supports_tilde_and_env() {\n let home = std::env::var(\"HOME\").expect(\"HOME must be set for tests\");\n let expected = PathBuf::from(&home).join(\"projects/demo\");\n\n assert_eq!(expand_path(\"~/projects/demo\"), expected);\n assert_eq!(expand_path(\"$HOME/projects/demo\"), expected);\n }\n\n #[test]\n fn lifecycle_domains_aliases_parse() {\n let toml = r#\"\n [lifecycle]\n up_task = \"dev\"\n\n [lifecycle.domains]\n host = \"myflow.localhost\"\n target = \"127.0.0.1:3000\"\n engine = \"native\"\n\n [[lifecycle.domains.aliases]]\n host = \"api.myflow.localhost\"\n target = \"127.0.0.1:8780\"\n \"#;\n\n let cfg: Config =\n toml::from_str(toml).expect(\"lifecycle domains alias config should parse\");\n let lifecycle = cfg.lifecycle.expect(\"lifecycle should parse\");\n let domains = lifecycle.domains.expect(\"domains should parse\");\n assert_eq!(domains.host.as_deref(), Some(\"myflow.localhost\"));\n assert_eq!(domains.target.as_deref(), Some(\"127.0.0.1:3000\"));\n assert_eq!(domains.aliases.len(), 1);\n assert_eq!(\n domains.aliases[0].host.as_deref(),\n Some(\"api.myflow.localhost\")\n );\n assert_eq!(domains.aliases[0].target.as_deref(), Some(\"127.0.0.1:8780\"));\n }\n\n #[test]\n fn global_state_dir_prefers_config_dir_for_fresh_homes() {\n let dir = tempdir().expect(\"tempdir\");\n let config_dir = dir.path().join(\".config/flow\");\n assert_eq!(select_global_state_dir(&config_dir), config_dir);\n }\n\n #[test]\n fn global_state_dir_preserves_legacy_state_root_when_present() {\n let dir = tempdir().expect(\"tempdir\");\n let config_dir = dir.path().join(\".config/flow\");\n let legacy_dir = dir.path().join(\".config/flow-state\");\n fs::create_dir_all(&legacy_dir).expect(\"legacy dir\");\n assert_eq!(select_global_state_dir(&config_dir), legacy_dir);\n }\n\n #[test]\n fn global_state_dir_falls_back_when_config_path_is_blocked() {\n let dir = tempdir().expect(\"tempdir\");\n let config_dir = dir.path().join(\".config/flow\");\n fs::create_dir_all(config_dir.parent().expect(\"config parent\")).expect(\"parent dir\");\n fs::write(&config_dir, \"blocked\").expect(\"blocking file\");\n assert_eq!(\n select_global_state_dir(&config_dir),\n dir.path().join(\".config/flow-state\")\n );\n }\n\n #[test]\n fn parses_poltergeist_watcher() {\n let toml = r#\"\n [[watchers]]\n driver = \"poltergeist\"\n name = \"peekaboo\"\n path = \"~/code/myflow/peekaboo\"\n\n [watchers.poltergeist]\n binary = \"/opt/bin/poltergeist\"\n mode = \"panel\"\n args = [\"status\", \"--verbose\"]\n \"#;\n\n let cfg: Config = toml::from_str(toml).expect(\"poltergeist watcher should parse\");\n assert_eq!(cfg.watchers.len(), 1);\n let watcher = &cfg.watchers[0];\n assert_eq!(watcher.driver, WatcherDriver::Poltergeist);\n assert_eq!(watcher.command, None);\n assert_eq!(watcher.path, \"~/code/myflow/peekaboo\");\n\n let poltergeist = watcher\n .poltergeist\n .as_ref()\n .expect(\"poltergeist config should exist\");\n assert_eq!(poltergeist.binary, \"/opt/bin/poltergeist\");\n assert_eq!(poltergeist.mode, PoltergeistMode::Panel);\n assert_eq!(poltergeist.args, vec![\"status\", \"--verbose\"]);\n }\n\n #[test]\n fn load_or_default_returns_empty_when_missing() {\n let missing_path = fixture_path(\"test-data/global-config/does-not-exist.toml\");\n let cfg = load_or_default(missing_path);\n assert!(\n cfg.servers.is_empty(),\n \"missing config should fall back to empty server list\"\n );\n }\n\n #[test]\n fn load_parses_project_tasks() {\n let cfg = load(fixture_path(\"test-data/simple-project/flow.toml\"))\n .expect(\"simple project config should parse\");\n\n assert!(cfg.servers.is_empty(), \"project fixture focuses on tasks\");\n assert_eq!(cfg.tasks.len(), 2);\n\n let lint = &cfg.tasks[0];\n assert_eq!(lint.name, \"lint\");\n assert_eq!(lint.command, \"golangci-lint run\");\n assert_eq!(\n lint.description.as_deref(),\n Some(\"Run static analysis for Go sources\")\n );\n\n let test_task = &cfg.tasks[1];\n assert_eq!(test_task.name, \"test\");\n assert_eq!(test_task.command, \"gotestsum -f pkgname ./...\");\n assert_eq!(\n test_task.description.as_deref(),\n Some(\"Execute the Go test suite with gotestsum output\"),\n \"desc alias should populate description\"\n );\n }\n\n #[test]\n fn load_parses_dependency_table() {\n let contents = r#\"\n[dependencies]\nfast = \"fast\"\ntoolkit = [\"rg\", \"fd\"]\n\n[[tasks]]\nname = \"ci\"\ncommand = \"ci\"\ndependencies = [\"fast\", \"toolkit\"]\n\"#;\n let cfg: Config =\n toml::from_str(contents).expect(\"inline config with dependencies should parse\");\n\n let task = cfg.tasks.first().expect(\"task should parse\");\n assert_eq!(\n task.dependencies,\n [\"fast\", \"toolkit\"],\n \"task dependency references should parse\"\n );\n\n let fast = cfg\n .dependencies\n .get(\"fast\")\n .expect(\"fast dependency should be present\");\n match fast {\n DependencySpec::Single(expr) => {\n assert_eq!(expr, \"fast\");\n }\n other => panic!(\"fast dependency variant mismatch: {other:?}\"),\n }\n\n let toolkit = cfg\n .dependencies\n .get(\"toolkit\")\n .expect(\"toolkit dependency should be present\");\n match toolkit {\n DependencySpec::Multiple(exprs) => {\n assert_eq!(exprs, &[\"rg\", \"fd\"]);\n }\n other => panic!(\"toolkit dependency variant mismatch: {other:?}\"),\n }\n }\n\n #[test]\n fn parses_flox_dependencies_and_config() {\n let contents = r#\"\n[dependencies]\nrg.pkg-path = \"ripgrep\"\n\n[flox.deps]\nfd.pkg-path = \"fd\"\n\"#;\n\n let cfg: Config = toml::from_str(contents).expect(\"config with flox deps should parse\");\n\n match cfg.dependencies.get(\"rg\") {\n Some(DependencySpec::Flox(spec)) => {\n assert_eq!(spec.pkg_path, \"ripgrep\");\n }\n other => panic!(\"unexpected dependency variant: {other:?}\"),\n }\n\n let flox = cfg.flox.expect(\"flox config should exist\");\n let fd = flox\n .install\n .get(\"fd\")\n .expect(\"fd install should be present\");\n assert_eq!(fd.pkg_path, \"fd\");\n }\n\n #[test]\n fn task_activation_flag_defaults_and_parses() {\n let toml = r#\"\n[[tasks]]\nname = \"lint\"\ncommand = \"golangci-lint run\"\n\n[[tasks]]\nname = \"setup\"\ncommand = \"cargo check\"\nactivate_on_cd_to_root = true\n\"#;\n\n let cfg: Config = toml::from_str(toml).expect(\"activation config should parse\");\n assert_eq!(cfg.tasks.len(), 2);\n assert!(!cfg.tasks[0].activate_on_cd_to_root);\n assert!(cfg.tasks[1].activate_on_cd_to_root);\n }\n\n #[test]\n fn load_parses_aliases() {\n let contents = r#\"\n[aliases]\nfr = \"f run\"\nls = \"f tasks\"\n\"#;\n let cfg: Config = toml::from_str(contents).expect(\"inline alias config should parse\");\n assert_eq!(cfg.aliases.get(\"fr\").map(String::as_str), Some(\"f run\"));\n assert_eq!(cfg.aliases.get(\"ls\").map(String::as_str), Some(\"f tasks\"));\n }\n\n #[test]\n fn load_parses_alias_array_table() {\n let contents = r#\"\n[[alias]]\nfr = \"f run\"\nfc = \"f commit\"\n\n[[alias]]\ndev = \"f run dev\"\n\"#;\n let cfg: Config = toml::from_str(contents).expect(\"alias array config should parse\");\n assert_eq!(cfg.aliases.get(\"fr\").map(String::as_str), Some(\"f run\"));\n assert_eq!(cfg.aliases.get(\"fc\").map(String::as_str), Some(\"f commit\"));\n assert_eq!(\n cfg.aliases.get(\"dev\").map(String::as_str),\n Some(\"f run dev\")\n );\n }\n\n #[test]\n fn options_defaults_are_false() {\n let cfg: Config =\n toml::from_str(\"\").expect(\"empty config should parse with default options\");\n assert!(!cfg.options.trace_terminal_io);\n assert!(cfg.options.commit_with_check_async.is_none());\n assert!(cfg.options.commit_with_check_use_repo_root.is_none());\n assert!(cfg.options.commit_with_check_timeout_secs.is_none());\n assert!(cfg.options.commit_with_check_gitedit_mirror.is_none());\n }\n\n #[test]\n fn options_trace_flag_parses() {\n let toml = r#\"\n[options]\ntrace_terminal_io = true\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"options table should parse\");\n assert!(cfg.options.trace_terminal_io);\n }\n\n #[test]\n fn options_commit_with_check_timeout_parses() {\n let toml = r#\"\n[options]\ncommit_with_check_timeout_secs = 120\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"options table should parse\");\n assert_eq!(cfg.options.commit_with_check_timeout_secs, Some(120));\n }\n\n #[test]\n fn options_commit_with_check_review_retries_parses() {\n let toml = r#\"\n[options]\ncommit_with_check_review_retries = 3\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"options table should parse\");\n assert_eq!(cfg.options.commit_with_check_review_retries, Some(3));\n }\n\n #[test]\n fn options_commit_with_check_async_parses() {\n let toml = r#\"\n[options]\ncommit_with_check_async = false\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"options table should parse\");\n assert_eq!(cfg.options.commit_with_check_async, Some(false));\n }\n\n #[test]\n fn options_commit_with_check_use_repo_root_parses() {\n let toml = r#\"\n[options]\ncommit_with_check_use_repo_root = false\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"options table should parse\");\n assert_eq!(cfg.options.commit_with_check_use_repo_root, Some(false));\n }\n\n #[test]\n fn options_commit_with_check_gitedit_mirror_parses() {\n let toml = r#\"\n[options]\ncommit_with_check_gitedit_mirror = true\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"options table should parse\");\n assert_eq!(cfg.options.commit_with_check_gitedit_mirror, Some(true));\n }\n\n #[test]\n fn options_codex_bin_parses() {\n let toml = r#\"\n[options]\ncodex_bin = \"/tmp/codex-jazz\"\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"options table should parse\");\n assert_eq!(cfg.options.codex_bin.as_deref(), Some(\"/tmp/codex-jazz\"));\n }\n\n #[test]\n fn task_resolution_config_parses() {\n let toml = r#\"\n[task_resolution]\npreferred_scopes = [\"mobile\", \"root\"]\nwarn_on_implicit_scope = true\n\n[task_resolution.routes]\ndev = \"mobile\"\ntest = \"root\"\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"task_resolution should parse\");\n let resolution = cfg\n .task_resolution\n .expect(\"task_resolution config expected\");\n assert_eq!(\n resolution.preferred_scopes,\n vec![\"mobile\".to_string(), \"root\".to_string()]\n );\n assert_eq!(resolution.warn_on_implicit_scope, Some(true));\n assert_eq!(\n resolution.routes.get(\"dev\").map(String::as_str),\n Some(\"mobile\")\n );\n assert_eq!(\n resolution.routes.get(\"test\").map(String::as_str),\n Some(\"root\")\n );\n }\n\n #[test]\n fn commit_testing_config_parses() {\n let toml = r#\"\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"commit.testing should parse\");\n let commit = cfg.commit.expect(\"commit config expected\");\n let testing = commit.testing.expect(\"testing config expected\");\n assert_eq!(testing.mode.as_deref(), Some(\"block\"));\n assert_eq!(testing.runner.as_deref(), Some(\"bun\"));\n assert_eq!(testing.bun_repo_strict, Some(true));\n assert_eq!(testing.require_related_tests, Some(true));\n assert_eq!(testing.ai_scratch_test_dir.as_deref(), Some(\".ai/test\"));\n assert_eq!(testing.run_ai_scratch_tests, Some(true));\n assert_eq!(testing.allow_ai_scratch_to_satisfy_gate, Some(false));\n assert_eq!(testing.max_local_gate_seconds, Some(20));\n }\n\n #[test]\n fn commit_quick_default_parses() {\n let toml = r#\"\n[commit]\nquick-default = true\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"commit config should parse\");\n let commit = cfg.commit.expect(\"commit config expected\");\n assert_eq!(commit.quick_default, Some(true));\n }\n\n #[test]\n fn commit_skill_gate_config_parses() {\n let toml = r#\"\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"commit.skill_gate should parse\");\n let commit = cfg.commit.expect(\"commit config expected\");\n let skill_gate = commit.skill_gate.expect(\"skill gate config expected\");\n assert_eq!(skill_gate.mode.as_deref(), Some(\"block\"));\n assert_eq!(\n skill_gate.required,\n vec![\"quality-bun-feature-delivery\".to_string()]\n );\n let min_version = skill_gate.min_version.expect(\"min_version map expected\");\n assert_eq!(min_version.get(\"quality-bun-feature-delivery\"), Some(&2));\n }\n\n #[test]\n fn skills_codex_config_parses() {\n let toml = r#\"\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"skills.codex should parse\");\n let skills = cfg.skills.expect(\"skills config expected\");\n assert!(skills.sync_tasks);\n assert_eq!(\n skills.install,\n vec![\"quality-bun-feature-delivery\".to_string()]\n );\n let codex = skills.codex.expect(\"skills.codex expected\");\n assert_eq!(codex.generate_openai_yaml, Some(true));\n assert_eq!(codex.force_reload_after_sync, Some(true));\n assert_eq!(codex.task_skill_allow_implicit_invocation, Some(false));\n }\n\n #[test]\n fn codex_reference_resolver_config_parses() {\n let toml = r#\"\n[codex]\nauto_resolve_references = true\nruntime_skills = true\nhome_session_path = \"~/repos/openai/codex\"\nprompt_context_budget_chars = 900\nmax_resolved_references = 1\n\n[[codex.reference_resolver]]\nname = \"linear\"\nmatch = [\"https://linear.app/*/issue/*\", \"https://linear.app/*/project/*\"]\ncommand = \"my-linear-tool inspect {{ref}} --json\"\ninject_as = \"linear\"\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"codex config should parse\");\n let codex = cfg.codex.expect(\"codex config expected\");\n assert_eq!(codex.auto_resolve_references, Some(true));\n assert_eq!(codex.runtime_skills, Some(true));\n assert_eq!(\n codex.home_session_path.as_deref(),\n Some(\"~/repos/openai/codex\")\n );\n assert_eq!(codex.prompt_context_budget_chars, Some(900));\n assert_eq!(codex.max_resolved_references, Some(1));\n assert_eq!(codex.reference_resolvers.len(), 1);\n let resolver = &codex.reference_resolvers[0];\n assert_eq!(resolver.name, \"linear\");\n assert_eq!(\n resolver.matches,\n vec![\n \"https://linear.app/*/issue/*\".to_string(),\n \"https://linear.app/*/project/*\".to_string(),\n ]\n );\n assert_eq!(resolver.command, \"my-linear-tool inspect {{ref}} --json\");\n assert_eq!(resolver.inject_as.as_deref(), Some(\"linear\"));\n }\n\n #[test]\n fn codex_skill_source_config_parses() {\n let toml = r#\"\n[codex]\n\n[[codex.skill_source]]\nname = \"vercel-labs-skills\"\npath = \"~/repos/vercel-labs/skills\"\nenabled = true\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"codex skill_source should parse\");\n let codex = cfg.codex.expect(\"codex config expected\");\n assert_eq!(codex.skill_sources.len(), 1);\n let source = &codex.skill_sources[0];\n assert_eq!(source.name, \"vercel-labs-skills\");\n assert_eq!(source.path, \"~/repos/vercel-labs/skills\");\n assert_eq!(source.enabled, Some(true));\n }\n\n #[test]\n fn git_remote_config_parses() {\n let toml = r#\"\n[git]\nremote = \"myflow-i\"\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"git config should parse\");\n let git = cfg.git.expect(\"git config expected\");\n assert_eq!(git.remote.as_deref(), Some(\"myflow-i\"));\n }\n\n #[test]\n fn preferred_git_remote_prefers_git_then_jj() {\n let mut cfg = Config::default();\n cfg.jj = Some(JjConfig {\n remote: Some(\"jj-remote\".to_string()),\n ..Default::default()\n });\n assert_eq!(\n preferred_git_remote_from_cfg(&cfg).as_deref(),\n Some(\"jj-remote\")\n );\n\n cfg.git = Some(GitConfig {\n remote: Some(\"git-remote\".to_string()),\n ..Default::default()\n });\n assert_eq!(\n preferred_git_remote_from_cfg(&cfg).as_deref(),\n Some(\"git-remote\")\n );\n }\n\n #[test]\n fn analytics_config_parses() {\n let toml = r#\"\n[analytics]\nenabled = true\nendpoint = \"http://127.0.0.1:7331/v1/trace\"\nsample_rate = 0.5\n\"#;\n let cfg: Config = toml::from_str(toml).expect(\"analytics config should parse\");\n let analytics = cfg.analytics.expect(\"analytics config expected\");\n assert_eq!(analytics.enabled, Some(true));\n assert_eq!(\n analytics.endpoint.as_deref(),\n Some(\"http://127.0.0.1:7331/v1/trace\")\n );\n assert_eq!(analytics.sample_rate, Some(0.5));\n }\n}\n" }, { "path": "src/daemon.rs", "content": "//! Generic daemon management for flow.\n//!\n//! Allows starting, stopping, and monitoring background daemons defined in flow.toml.\n\nuse std::{\n fs,\n fs::OpenOptions,\n path::{Path, PathBuf},\n process::Command,\n time::Duration,\n};\n\nuse anyhow::{Context, Result, bail};\nuse regex::Regex;\nuse reqwest::blocking::Client;\n\nuse crate::{\n cli::{DaemonAction, DaemonCommand},\n codexd,\n config::{self, DaemonConfig, DaemonRestartPolicy},\n env, supervisor,\n};\n\n/// Run the daemon command.\npub fn run(cmd: DaemonCommand) -> Result<()> {\n let action = cmd.action.unwrap_or(DaemonAction::Status { name: None });\n let config_path = resolve_flow_toml_path();\n\n if supervisor::try_handle_daemon_action(&action, config_path.as_deref())? {\n return Ok(());\n }\n\n match action {\n DaemonAction::Start { name } => start_daemon(&name)?,\n DaemonAction::Stop { name } => stop_daemon(&name)?,\n DaemonAction::Restart { name } => {\n stop_daemon(&name).ok();\n std::thread::sleep(Duration::from_millis(500));\n start_daemon(&name)?;\n }\n DaemonAction::Status { name } => {\n if let Some(name) = name {\n show_status_for(&name)?;\n } else {\n show_status()?;\n }\n }\n DaemonAction::List => list_daemons()?,\n }\n\n Ok(())\n}\n\n/// Start a daemon by name.\npub fn start_daemon(name: &str) -> Result<()> {\n start_daemon_with_path(name, resolve_flow_toml_path().as_deref())\n}\n\npub fn start_daemon_with_path(name: &str, config_path: Option<&Path>) -> Result<()> {\n let daemon = find_daemon_config_with_path(name, config_path)?;\n start_daemon_inner(&daemon)\n}\n\nfn start_daemon_inner(daemon: &DaemonConfig) -> Result<()> {\n // Check if already running\n if daemon_health_status(daemon) == Some(true) {\n println!(\"✓ {} is already running\", daemon.name);\n return Ok(());\n }\n\n // Check if there's a stale PID\n if let Some(pid) = load_daemon_pid(&daemon.name)? {\n if process_alive(pid)? {\n terminate_process(pid).ok();\n }\n remove_daemon_pid(&daemon.name).ok();\n }\n\n // Evict any foreign process squatting on this daemon's port\n if let Some(port) = daemon.port {\n kill_process_on_port(port).ok();\n } else if let Some(url) = daemon.effective_health_url() {\n if let Some(port) = extract_port_from_url(&url) {\n kill_process_on_port(port).ok();\n }\n }\n\n // Find the binary\n let binary = find_binary(&daemon.binary)?;\n\n println!(\n \"Starting {} using {}{}\",\n daemon.name,\n binary.display(),\n daemon\n .command\n .as_ref()\n .map(|c| format!(\" {}\", c))\n .unwrap_or_default()\n );\n\n let spawned = spawn_daemon_process(daemon, &binary)?;\n persist_daemon_pid(&daemon.name, spawned.pid)?;\n\n // Wait a moment and check health\n wait_for_daemon_ready(daemon, &spawned.stdout_log)?;\n\n match daemon_health_status(daemon) {\n Some(true) => println!(\"✓ {} started successfully\", daemon.name),\n Some(false) => println!(\n \"⚠ {} started but health check failed (may need more time)\",\n daemon.name\n ),\n None => println!(\"✓ {} started (no health check configured)\", daemon.name),\n }\n\n Ok(())\n}\n\n/// Stop a daemon by name.\npub fn stop_daemon(name: &str) -> Result<()> {\n stop_daemon_with_path(name, resolve_flow_toml_path().as_deref())\n}\n\npub fn stop_daemon_with_path(name: &str, config_path: Option<&Path>) -> Result<()> {\n let daemon = find_daemon_config_with_path(name, config_path).ok();\n\n if let Some(pid) = load_daemon_pid(name)? {\n if process_alive(pid)? {\n terminate_process(pid)?;\n println!(\"✓ {} stopped (PID {})\", name, pid);\n } else {\n println!(\"✓ {} was not running\", name);\n }\n remove_daemon_pid(name).ok();\n } else {\n println!(\"✓ {} was not running (no PID file)\", name);\n }\n\n // Also try to kill any process listening on the daemon's port\n // This handles cases where child processes outlive the parent\n if let Some(daemon) = daemon {\n if let Some(port) = daemon.port {\n kill_process_on_port(port).ok();\n } else if let Some(url) = &daemon.health_url {\n if let Some(port) = extract_port_from_url(url) {\n kill_process_on_port(port).ok();\n }\n }\n }\n\n Ok(())\n}\n\n/// Show status of all configured daemons.\npub fn show_status() -> Result<()> {\n show_status_with_path(resolve_flow_toml_path().as_deref())\n}\n\n/// Show status of a specific daemon.\npub fn show_status_for(name: &str) -> Result<()> {\n show_status_for_with_path(name, resolve_flow_toml_path().as_deref())\n}\n\npub fn show_status_with_path(config_path: Option<&Path>) -> Result<()> {\n let config = load_merged_config_with_path(config_path)?;\n\n if config.daemons.is_empty() {\n println!(\"No daemons configured.\");\n println!();\n println!(\"Add daemons to ~/.config/flow/flow.toml or project flow.toml:\");\n println!();\n println!(\" [[daemon]]\");\n println!(\" name = \\\"my-daemon\\\"\");\n println!(\" binary = \\\"my-app\\\"\");\n println!(\" command = \\\"serve\\\"\");\n println!(\" health_url = \\\"http://127.0.0.1:8080/health\\\"\");\n return Ok(());\n }\n\n println!(\"Daemon Status:\");\n println!();\n\n for daemon in &config.daemons {\n let status = get_daemon_status(&daemon);\n let icon = if status.running { \"✓\" } else { \"✗\" };\n let state = if status.running { \"running\" } else { \"stopped\" };\n\n print!(\" {} {}: {}\", icon, daemon.name, state);\n\n if let Some(target) = daemon.health_target_label() {\n if status.running {\n print!(\" ({})\", target);\n }\n }\n\n if let Some(pid) = status.pid {\n print!(\" [PID {}]\", pid);\n }\n\n println!();\n\n if let Some(desc) = &daemon.description {\n println!(\" {}\", desc);\n }\n }\n\n Ok(())\n}\n\npub fn show_status_for_with_path(name: &str, config_path: Option<&Path>) -> Result<()> {\n let daemon = find_daemon_config_with_path(name, config_path)?;\n let status = get_daemon_status(&daemon);\n let icon = if status.running { \"✓\" } else { \"✗\" };\n let state = if status.running { \"running\" } else { \"stopped\" };\n\n println!(\"Daemon Status:\");\n println!();\n print!(\" {} {}: {}\", icon, daemon.name, state);\n\n if let Some(target) = daemon.health_target_label() {\n if status.running {\n if status.healthy == Some(false) {\n print!(\" (unhealthy: {})\", target);\n } else {\n print!(\" ({})\", target);\n }\n }\n }\n\n if let Some(pid) = status.pid {\n print!(\" [PID {}]\", pid);\n }\n\n println!();\n if let Some(desc) = &daemon.description {\n println!(\" {}\", desc);\n }\n\n Ok(())\n}\n\n/// List available daemons.\npub fn list_daemons() -> Result<()> {\n list_daemons_with_path(resolve_flow_toml_path().as_deref())\n}\n\npub fn list_daemons_with_path(config_path: Option<&Path>) -> Result<()> {\n let config = load_merged_config_with_path(config_path)?;\n\n if config.daemons.is_empty() {\n println!(\"No daemons configured.\");\n return Ok(());\n }\n\n println!(\"Available daemons:\");\n println!();\n\n for daemon in &config.daemons {\n print!(\" {}\", daemon.name);\n if let Some(desc) = &daemon.description {\n print!(\" - {}\", desc);\n }\n println!();\n }\n\n Ok(())\n}\n\n/// Status of a daemon.\n#[derive(Debug)]\npub struct DaemonStatus {\n pub running: bool,\n pub pid: Option<u32>,\n pub healthy: Option<bool>,\n}\n\n/// Get the status of a specific daemon.\npub fn get_daemon_status(daemon: &DaemonConfig) -> DaemonStatus {\n let pid = load_daemon_pid(&daemon.name).ok().flatten();\n let pid_alive = pid\n .map(|pid| process_alive(pid).unwrap_or(false))\n .unwrap_or(false);\n\n let healthy = daemon_health_status(daemon);\n let running = if healthy.is_some() {\n // Prefer PID when available; a transient health blip shouldn't mark the process as stopped.\n if pid.is_some() {\n pid_alive\n } else {\n healthy.unwrap_or(false)\n }\n } else {\n pid_alive\n };\n\n DaemonStatus {\n running,\n pid,\n healthy,\n }\n}\n\npub fn restart_policy_for(daemon: &DaemonConfig) -> DaemonRestartPolicy {\n match daemon.restart {\n Some(ref policy) => policy.clone(),\n None => {\n if daemon.retry.unwrap_or(0) > 0 {\n DaemonRestartPolicy::OnFailure\n } else {\n DaemonRestartPolicy::Never\n }\n }\n }\n}\n\npub fn daemon_log_dir(name: &str) -> Result<PathBuf> {\n let base = config::ensure_global_state_dir()?;\n let dir = base.join(\"daemons\").join(sanitize_daemon_name(name));\n fs::create_dir_all(&dir).with_context(|| format!(\"failed to create {}\", dir.display()))?;\n Ok(dir)\n}\n\npub fn daemon_log_paths(name: &str) -> Result<(PathBuf, PathBuf)> {\n let dir = daemon_log_dir(name)?;\n Ok((dir.join(\"stdout.log\"), dir.join(\"stderr.log\")))\n}\n\nfn sanitize_daemon_name(name: &str) -> String {\n let mut out = String::new();\n for ch in name.chars() {\n if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' {\n out.push(ch);\n } else {\n out.push('_');\n }\n }\n if out.is_empty() {\n \"daemon\".to_string()\n } else {\n out\n }\n}\n\nstruct SpawnedDaemon {\n pid: u32,\n stdout_log: PathBuf,\n}\n\nfn spawn_daemon_process(daemon: &DaemonConfig, binary: &Path) -> Result<SpawnedDaemon> {\n let mut cmd = Command::new(binary);\n\n if let Some(subcommand) = &daemon.command {\n cmd.arg(subcommand);\n }\n\n for arg in &daemon.args {\n cmd.arg(arg);\n }\n\n if let Some(wd) = &daemon.working_dir {\n let expanded = config::expand_path(wd);\n if expanded.exists() {\n cmd.current_dir(&expanded);\n }\n }\n\n if let Ok(vars) = env::fetch_local_personal_env_vars(&config::global_env_keys()) {\n for (key, value) in vars {\n cmd.env(key, value);\n }\n }\n\n for (key, value) in &daemon.env {\n cmd.env(key, value);\n }\n\n let (stdout_log, stderr_log) = daemon_log_paths(&daemon.name)?;\n let stdout_file = OpenOptions::new()\n .create(true)\n .append(true)\n .open(&stdout_log)\n .with_context(|| format!(\"failed to open {}\", stdout_log.display()))?;\n let stderr_file = OpenOptions::new()\n .create(true)\n .append(true)\n .open(&stderr_log)\n .with_context(|| format!(\"failed to open {}\", stderr_log.display()))?;\n\n cmd.stdin(std::process::Stdio::null())\n .stdout(stdout_file)\n .stderr(stderr_file);\n\n #[cfg(unix)]\n {\n use std::os::unix::process::CommandExt;\n cmd.process_group(0);\n }\n\n let child = cmd\n .spawn()\n .with_context(|| format!(\"failed to start {} from {}\", daemon.name, binary.display()))?;\n\n Ok(SpawnedDaemon {\n pid: child.id(),\n stdout_log,\n })\n}\n\nfn wait_for_daemon_ready(daemon: &DaemonConfig, stdout_log: &Path) -> Result<()> {\n if let Some(delay) = daemon.ready_delay {\n std::thread::sleep(Duration::from_millis(delay));\n } else {\n std::thread::sleep(Duration::from_millis(500));\n }\n\n let timeout = Duration::from_secs(30);\n let start = std::time::Instant::now();\n let mut seen_len = 0usize;\n let mut ready_output_matched = daemon.ready_output.is_none();\n let regex = match daemon.ready_output.as_ref() {\n Some(pattern) => Some(Regex::new(pattern).with_context(|| \"invalid ready_output regex\")?),\n None => None,\n };\n\n while start.elapsed() < timeout {\n if let Some(regex) = regex.as_ref() {\n if let Ok(contents) = fs::read_to_string(stdout_log) {\n if contents.len() > seen_len {\n let slice = &contents[seen_len..];\n if regex.is_match(slice) {\n ready_output_matched = true;\n }\n seen_len = contents.len();\n }\n }\n }\n\n if ready_output_matched {\n match daemon_health_status(daemon) {\n Some(true) | None => return Ok(()),\n Some(false) => {}\n }\n }\n std::thread::sleep(Duration::from_millis(200));\n }\n\n if let Some(pattern) = daemon.ready_output.as_ref() {\n if !ready_output_matched {\n eprintln!(\n \"WARN ready_output '{}' not found for {} (continuing).\",\n pattern, daemon.name\n );\n }\n }\n Ok(())\n}\n/// Find a daemon config by name from merged configs.\nfn find_daemon_config_with_path(name: &str, config_path: Option<&Path>) -> Result<DaemonConfig> {\n let config = load_merged_config_with_path(config_path)?;\n\n config\n .daemons\n .into_iter()\n .find(|d| d.name == name)\n .ok_or_else(|| anyhow::anyhow!(\"daemon '{}' not found in config\", name))\n}\n\n/// Load merged config from global and local sources.\npub fn load_merged_config_with_path(config_path: Option<&Path>) -> Result<config::Config> {\n let mut merged = config::Config::default();\n\n // Load global config\n let global_path = config::default_config_path();\n if global_path.exists() {\n if let Ok(global_cfg) = config::load(&global_path) {\n merged.daemons.extend(global_cfg.daemons);\n for server in &global_cfg.servers {\n merged.daemons.push(server.to_daemon_config());\n }\n }\n }\n\n // Load local config if it exists\n if let Some(local_path) = config_path {\n if local_path.exists() {\n if let Ok(local_cfg) = config::load(local_path) {\n merged.daemons.extend(local_cfg.daemons);\n for server in &local_cfg.servers {\n merged.daemons.push(server.to_daemon_config());\n }\n }\n }\n }\n\n if !merged.daemons.iter().any(|daemon| daemon.name == \"codexd\") {\n if let Ok(daemon) = codexd::builtin_daemon_config() {\n merged.daemons.push(daemon);\n }\n }\n\n Ok(merged)\n}\n\nfn resolve_flow_toml_path() -> Option<PathBuf> {\n let mut current = std::env::current_dir().ok()?;\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\n/// Find a binary on PATH or as an absolute path.\nfn find_binary(name: &str) -> Result<PathBuf> {\n // If it's an absolute path, use it directly\n let path = Path::new(name);\n if path.is_absolute() && path.exists() {\n return Ok(path.to_path_buf());\n }\n\n // Expand ~ if present\n let expanded = config::expand_path(name);\n if expanded.exists() {\n return Ok(expanded);\n }\n\n // Try to find on PATH using `which`\n let output = Command::new(\"which\")\n .arg(name)\n .output()\n .with_context(|| format!(\"failed to find binary '{}'\", name))?;\n\n if output.status.success() {\n let path_str = String::from_utf8_lossy(&output.stdout);\n let path = PathBuf::from(path_str.trim());\n if path.exists() {\n return Ok(path);\n }\n }\n\n bail!(\"binary '{}' not found\", name)\n}\n\n/// Check if a health endpoint is responding.\nfn check_health(url: &str) -> bool {\n let client = Client::builder()\n .timeout(Duration::from_millis(750))\n .build();\n\n let Ok(client) = client else {\n return false;\n };\n\n client\n .get(url)\n .send()\n .and_then(|resp| resp.error_for_status())\n .map(|_| true)\n .unwrap_or(false)\n}\n\nfn check_health_socket(path: &Path) -> bool {\n #[cfg(unix)]\n {\n if !path.exists() {\n return false;\n }\n std::os::unix::net::UnixStream::connect(path).is_ok()\n }\n #[cfg(not(unix))]\n {\n let _ = path;\n false\n }\n}\n\nfn daemon_health_status(daemon: &DaemonConfig) -> Option<bool> {\n if let Some(url) = daemon.effective_health_url() {\n return Some(check_health(&url));\n }\n if let Some(socket_path) = daemon.effective_health_socket() {\n return Some(check_health_socket(&socket_path));\n }\n None\n}\n\n// ============================================================================\n// PID file management\n// ============================================================================\n\nfn daemon_pid_path(name: &str) -> PathBuf {\n if let Some(home) = std::env::var_os(\"HOME\") {\n PathBuf::from(home).join(format!(\".config/flow/{}.pid\", name))\n } else {\n PathBuf::from(format!(\".config/flow/{}.pid\", name))\n }\n}\n\nfn load_daemon_pid(name: &str) -> Result<Option<u32>> {\n let path = daemon_pid_path(name);\n if !path.exists() {\n return Ok(None);\n }\n let contents =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let pid: u32 = contents.trim().parse().ok().unwrap_or(0);\n if pid == 0 { Ok(None) } else { Ok(Some(pid)) }\n}\n\nfn persist_daemon_pid(name: &str, pid: u32) -> Result<()> {\n let path = daemon_pid_path(name);\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create pid dir {}\", parent.display()))?;\n }\n fs::write(&path, pid.to_string())\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(())\n}\n\nfn remove_daemon_pid(name: &str) -> Result<()> {\n let path = daemon_pid_path(name);\n if path.exists() {\n fs::remove_file(path).ok();\n }\n Ok(())\n}\n\n// ============================================================================\n// Process management\n// ============================================================================\n\nfn process_alive(pid: u32) -> Result<bool> {\n #[cfg(unix)]\n {\n let status = Command::new(\"kill\").arg(\"-0\").arg(pid.to_string()).status();\n return Ok(status.map(|s| s.success()).unwrap_or(false));\n }\n\n #[cfg(windows)]\n {\n let output = Command::new(\"tasklist\")\n .output()\n .context(\"failed to invoke tasklist\")?;\n if !output.status.success() {\n return Ok(false);\n }\n let needle = pid.to_string();\n let body = String::from_utf8_lossy(&output.stdout);\n Ok(body.lines().any(|line| line.contains(&needle)))\n }\n}\n\nfn terminate_process(pid: u32) -> Result<()> {\n #[cfg(unix)]\n {\n // First try to kill the process group (negative PID)\n // This ensures child processes are also terminated\n let pgid_kill = Command::new(\"kill\")\n .arg(format!(\"-{pid}\"))\n .stderr(std::process::Stdio::null())\n .status();\n\n // Also kill the process directly\n let status = Command::new(\"kill\")\n .arg(format!(\"{pid}\"))\n .stderr(std::process::Stdio::null())\n .status()\n .context(\"failed to invoke kill command\")?;\n\n // If either succeeded, we're good\n if status.success() || pgid_kill.map(|s| s.success()).unwrap_or(false) {\n return Ok(());\n }\n bail!(\n \"kill command exited with status {}\",\n status.code().unwrap_or(-1)\n );\n }\n\n #[cfg(windows)]\n {\n let status = Command::new(\"taskkill\")\n .args([\"/PID\", &pid.to_string(), \"/F\", \"/T\"]) // /T kills child processes too\n .status()\n .context(\"failed to invoke taskkill\")?;\n if status.success() {\n return Ok(());\n }\n bail!(\n \"taskkill exited with status {}\",\n status.code().unwrap_or(-1)\n );\n }\n}\n\n/// Extract port number from a URL like \"http://127.0.0.1:7201/health\"\npub fn extract_port_from_url(url: &str) -> Option<u16> {\n // Simple extraction: find the port after the last colon before any path\n let url = url\n .strip_prefix(\"http://\")\n .or_else(|| url.strip_prefix(\"https://\"))?;\n let host_port = url.split('/').next()?;\n let port_str = host_port.rsplit(':').next()?;\n port_str.parse().ok()\n}\n\n/// Kill any process listening on the given port.\n#[cfg(unix)]\npub fn kill_process_on_port(port: u16) -> Result<()> {\n // Use lsof to find the process\n let output = Command::new(\"lsof\")\n .args([\"-ti\", &format!(\":{}\", port)])\n .output()\n .context(\"failed to run lsof\")?;\n\n if !output.status.success() {\n return Ok(()); // No process found on port\n }\n\n let pids = String::from_utf8_lossy(&output.stdout);\n for pid_str in pids.lines() {\n if let Ok(pid) = pid_str.trim().parse::<u32>() {\n terminate_process(pid).ok();\n }\n }\n\n Ok(())\n}\n\n#[cfg(windows)]\npub fn kill_process_on_port(port: u16) -> Result<()> {\n // Use netstat to find the process\n let output = Command::new(\"netstat\")\n .args([\"-ano\"])\n .output()\n .context(\"failed to run netstat\")?;\n\n if !output.status.success() {\n return Ok(());\n }\n\n let port_pattern = format!(\":{}\", port);\n let lines = String::from_utf8_lossy(&output.stdout);\n for line in lines.lines() {\n if line.contains(&port_pattern) && line.contains(\"LISTENING\") {\n // Last column is PID\n if let Some(pid_str) = line.split_whitespace().last() {\n if let Ok(pid) = pid_str.parse::<u32>() {\n terminate_process(pid).ok();\n }\n }\n }\n }\n\n Ok(())\n}\n" }, { "path": "src/daemon_snapshot.rs", "content": "use std::path::Path;\n\nuse anyhow::Result;\nuse serde::{Deserialize, Serialize};\n\nuse crate::{activity_log, daemon, supervisor};\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\npub struct FlowDaemonEntry {\n pub name: String,\n pub status: String,\n pub running: bool,\n #[serde(default)]\n pub healthy: Option<bool>,\n pub pid: Option<u32>,\n pub health_target: Option<String>,\n pub description: Option<String>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\npub struct FlowDaemonSnapshot {\n pub total: usize,\n pub running: usize,\n pub healthy: usize,\n pub unhealthy: usize,\n pub stopped: usize,\n pub entries: Vec<FlowDaemonEntry>,\n}\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\npub enum FlowDaemonAction {\n Start,\n Stop,\n Restart,\n}\n\npub fn load_daemon_snapshot(config_path: Option<&Path>) -> Result<FlowDaemonSnapshot> {\n let mut entries: Vec<_> = supervisor::daemon_status_views(config_path)?\n .into_iter()\n .map(|view| {\n let status = if !view.running {\n \"stopped\"\n } else if view.healthy == Some(false) {\n \"unhealthy\"\n } else {\n \"healthy\"\n };\n FlowDaemonEntry {\n name: view.name,\n status: status.to_string(),\n running: view.running,\n healthy: view.healthy,\n pid: view.pid,\n health_target: view.health_target,\n description: view.description,\n }\n })\n .collect();\n\n entries.sort_by(|left, right| {\n right\n .running\n .cmp(&left.running)\n .then_with(|| left.status.cmp(&right.status))\n .then_with(|| left.name.cmp(&right.name))\n });\n\n let running = entries.iter().filter(|entry| entry.running).count();\n let unhealthy = entries\n .iter()\n .filter(|entry| entry.running && entry.healthy == Some(false))\n .count();\n let healthy = entries\n .iter()\n .filter(|entry| entry.running && entry.healthy != Some(false))\n .count();\n let stopped = entries.iter().filter(|entry| !entry.running).count();\n\n Ok(FlowDaemonSnapshot {\n total: entries.len(),\n running,\n healthy,\n unhealthy,\n stopped,\n entries,\n })\n}\n\npub fn run_daemon_action(\n name: &str,\n action: FlowDaemonAction,\n config_path: Option<&Path>,\n) -> Result<FlowDaemonSnapshot> {\n let action_name = match action {\n FlowDaemonAction::Start => \"start\",\n FlowDaemonAction::Stop => \"stop\",\n FlowDaemonAction::Restart => \"restart\",\n };\n match action {\n FlowDaemonAction::Start => daemon::start_daemon_with_path(name, config_path)?,\n FlowDaemonAction::Stop => daemon::stop_daemon_with_path(name, config_path)?,\n FlowDaemonAction::Restart => {\n daemon::stop_daemon_with_path(name, config_path).ok();\n daemon::start_daemon_with_path(name, config_path)?;\n }\n }\n let summary = match action_name {\n \"start\" => \"started\",\n \"stop\" => \"stopped\",\n \"restart\" => \"restarted\",\n _ => action_name,\n };\n let mut activity_event =\n activity_log::ActivityEvent::done(format!(\"daemon.{action_name}\"), summary);\n activity_event.scope = Some(name.to_string());\n activity_event.source = Some(\"daemon-control\".to_string());\n let _ = activity_log::append_daily_event(activity_event);\n load_daemon_snapshot(config_path)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn classifies_and_counts_daemon_states() {\n let snapshot = FlowDaemonSnapshot {\n total: 3,\n running: 2,\n healthy: 1,\n unhealthy: 1,\n stopped: 1,\n entries: vec![\n FlowDaemonEntry {\n name: \"codexd\".to_string(),\n status: \"healthy\".to_string(),\n running: true,\n healthy: Some(true),\n pid: Some(10),\n health_target: Some(\"unix:/tmp/codexd.sock\".to_string()),\n description: None,\n },\n FlowDaemonEntry {\n name: \"api\".to_string(),\n status: \"unhealthy\".to_string(),\n running: true,\n healthy: Some(false),\n pid: Some(11),\n health_target: Some(\"http://127.0.0.1:8780/health\".to_string()),\n description: None,\n },\n FlowDaemonEntry {\n name: \"worker\".to_string(),\n status: \"stopped\".to_string(),\n running: false,\n healthy: None,\n pid: None,\n health_target: None,\n description: None,\n },\n ],\n };\n\n assert_eq!(snapshot.total, 3);\n assert_eq!(snapshot.running, 2);\n assert_eq!(snapshot.healthy, 1);\n assert_eq!(snapshot.unhealthy, 1);\n assert_eq!(snapshot.stopped, 1);\n }\n}\n" }, { "path": "src/db.rs", "content": "use std::path::PathBuf;\n\nuse anyhow::{Context, Result};\nuse rusqlite::Connection;\n\n/// Path to the shared SQLite database.\npub fn db_path() -> PathBuf {\n std::env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".config/flow/flow.db\")\n}\n\n/// Open the SQLite database, creating parent directories if needed.\npub fn open_db() -> Result<Connection> {\n let path = db_path();\n if let Some(parent) = path.parent() {\n std::fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create db dir {}\", parent.display()))?;\n }\n Connection::open(path).context(\"failed to open flow.db\")\n}\n" }, { "path": "src/deploy.rs", "content": "//! Deploy projects to hosts and cloud platforms.\n//!\n//! Supports:\n//! - Linux hosts via SSH (with systemd + nginx)\n//! - Cloudflare Workers\n//! - Railway\n\nuse std::collections::{HashMap, HashSet};\nuse std::fs;\nuse std::io::{IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\nuse std::time::{Duration, SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result, bail};\nuse reqwest::blocking::Client;\nuse rpassword::prompt_password;\nuse serde::{Deserialize, Serialize};\nuse serde_json::Value;\n\nuse crate::cli::{DeployAction, DeployCommand, EnvAction, TaskRunOpts};\nuse crate::config::Config;\nuse crate::deploy_setup::{\n CloudflareSetupDefaults, CloudflareSetupResult, discover_wrangler_configs, run_cloudflare_setup,\n};\nuse crate::env::parse_env_file;\nuse crate::release;\nuse crate::services;\nuse crate::tasks;\n\nconst DEPLOY_HELPER_BIN: &str = \"infra\";\nconst DEPLOY_HELPER_REPO_DEFAULT: &str = \"~/infra\";\nconst DEPLOY_HELPER_ENV_BIN: &str = \"FLOW_DEPLOY_HELPER_BIN\";\nconst DEPLOY_HELPER_ENV_REPO: &str = \"FLOW_DEPLOY_HELPER_REPO\";\nconst DEPLOY_LOG_STATE_FILE: &str = \".flow/deploy-log.json\";\n\n#[derive(Debug, Deserialize)]\nstruct InfraConfig {\n linux_host: Option<String>,\n linux_port: Option<String>,\n linux_user: Option<String>,\n}\n\n/// Host configuration stored globally at ~/.config/flow/deploy.json\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\npub struct DeployConfig {\n /// SSH user@host:port for linux host deployments.\n pub host: Option<HostConnection>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct HostConnection {\n pub user: String,\n pub host: String,\n pub port: u16,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\nstruct DeployLogState {\n last_deploy_unix: Option<i64>,\n}\n\n#[derive(Debug, Clone)]\nstruct DeployProjectContext {\n project_root: PathBuf,\n config_path: PathBuf,\n flow_config: Option<Config>,\n}\n\nimpl HostConnection {\n /// Parse connection string like \"user@host:port\" or \"user@host\".\n pub fn parse(s: &str) -> Result<Self> {\n let (user_host, port) = if let Some((uh, p)) = s.rsplit_once(':') {\n (uh, p.parse::<u16>().unwrap_or(22))\n } else {\n (s, 22)\n };\n\n let (user, host) = user_host\n .split_once('@')\n .context(\"connection string must be user@host[:port]\")?;\n\n Ok(Self {\n user: user.to_string(),\n host: host.to_string(),\n port,\n })\n }\n\n /// Format as user@host for SSH commands.\n pub fn ssh_target(&self) -> String {\n format!(\"{}@{}\", self.user, self.host)\n }\n}\n\n/// Host deployment config from flow.toml [host] section.\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\npub struct HostConfig {\n /// Remote destination path (e.g., /opt/myapp).\n pub dest: Option<String>,\n /// Setup script to run after syncing.\n pub setup: Option<String>,\n /// Command to run the service.\n pub run: Option<String>,\n /// Port the service listens on.\n pub port: Option<u16>,\n /// Systemd service name.\n pub service: Option<String>,\n /// Path to .env file for secrets (used when env_source is not set).\n pub env_file: Option<String>,\n /// Env source for secrets (\"cloud\" or \"file\").\n pub env_source: Option<String>,\n /// Specific env keys to fetch when env_source = \"cloud\".\n #[serde(default)]\n pub env_keys: Vec<String>,\n /// Fetch from project-scoped env vars instead of personal (default).\n #[serde(default)]\n pub env_project: bool,\n /// Environment name for cloud (defaults to \"production\").\n pub environment: Option<String>,\n /// Service token for fetching env vars on host (set via f env token create).\n pub service_token: Option<String>,\n /// Public domain for nginx.\n pub domain: Option<String>,\n /// Enable SSL via Let's Encrypt.\n #[serde(default)]\n pub ssl: bool,\n}\n\n/// Cloudflare deployment config from flow.toml [cloudflare] section.\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\npub struct CloudflareConfig {\n /// Path to worker directory (relative to project root).\n pub path: Option<String>,\n /// Path to .env file for secrets.\n pub env_file: Option<String>,\n /// Env source for secrets (\"cloud\" or \"file\").\n pub env_source: Option<String>,\n /// Specific env keys to fetch when env_source = \"cloud\".\n #[serde(default)]\n pub env_keys: Vec<String>,\n /// Env keys to set as non-secret vars when env_source = \"cloud\".\n #[serde(default)]\n pub env_vars: Vec<String>,\n /// Default values for env vars (key/value).\n #[serde(default)]\n pub env_defaults: HashMap<String, String>,\n /// Secret keys to bootstrap directly in Cloudflare.\n #[serde(default)]\n pub bootstrap_secrets: Vec<String>,\n /// Optional Jazz sync peer for bootstrap (env store).\n pub bootstrap_jazz_peer: Option<String>,\n /// Optional Jazz worker account name for bootstrap (env store).\n pub bootstrap_jazz_name: Option<String>,\n /// Optional Jazz sync peer for bootstrap (auth store).\n pub bootstrap_jazz_auth_peer: Option<String>,\n /// Optional Jazz worker account name for bootstrap (auth store).\n pub bootstrap_jazz_auth_name: Option<String>,\n /// Env apply mode: \"always\", \"auto\", or \"never\".\n pub env_apply: Option<String>,\n /// Wrangler environment name (e.g., staging).\n #[serde(default, alias = \"env\")]\n pub environment: Option<String>,\n /// Custom deploy command.\n pub deploy: Option<String>,\n /// Custom dev command.\n pub dev: Option<String>,\n /// URL for health checks (e.g., https://my-worker.workers.dev).\n pub url: Option<String>,\n}\n\n/// Production deploy overrides from flow.toml [prod] section.\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\npub struct ProdConfig {\n /// Custom domain to serve (e.g., app.example.com).\n pub domain: Option<String>,\n /// Explicit route pattern (e.g., app.example.com/*).\n pub route: Option<String>,\n}\n\n/// Web deployment config from flow.toml [web] section.\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\npub struct WebConfig {\n /// Path to web app directory (relative to project root).\n pub path: Option<String>,\n /// Domain for the site (used to derive route).\n pub domain: Option<String>,\n /// Explicit route to add in wrangler config (e.g., example.com/*).\n pub route: Option<String>,\n /// Env source for secrets (\"cloud\" or \"file\").\n pub env_source: Option<String>,\n /// Specific env keys to fetch when env_source = \"cloud\".\n #[serde(default)]\n pub env_keys: Vec<String>,\n /// Env keys to set as non-secret vars when env_source = \"cloud\".\n #[serde(default)]\n pub env_vars: Vec<String>,\n /// Default values for env vars (key/value).\n #[serde(default)]\n pub env_defaults: HashMap<String, String>,\n /// Env apply mode: \"always\", \"auto\", or \"never\".\n pub env_apply: Option<String>,\n /// Wrangler environment name (e.g., staging).\n #[serde(default, alias = \"env\")]\n pub environment: Option<String>,\n}\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nenum EnvApplyMode {\n Always,\n Auto,\n Never,\n}\n\nfn env_apply_mode_from_str(value: Option<&str>) -> EnvApplyMode {\n match value.map(|s| s.to_ascii_lowercase()) {\n Some(ref v) if v == \"always\" => EnvApplyMode::Always,\n Some(ref v) if v == \"auto\" => EnvApplyMode::Auto,\n Some(ref v) if v == \"never\" => EnvApplyMode::Never,\n _ => EnvApplyMode::Never,\n }\n}\n\nfn is_tls_connect_error(err: &anyhow::Error) -> bool {\n let msg = format!(\"{err:#}\");\n msg.contains(\"certificate was not trusted\")\n || msg.contains(\"client error (Connect)\")\n || msg.contains(\"failed to connect to cloud\")\n}\n\n/// Railway deployment config from flow.toml [railway] section.\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\npub struct RailwayConfig {\n /// Railway project ID.\n pub project: Option<String>,\n /// Service name.\n pub service: Option<String>,\n /// Environment (production, staging).\n pub environment: Option<String>,\n /// Start command.\n pub start: Option<String>,\n /// Path to .env file.\n pub env_file: Option<String>,\n}\n\n/// Get the deploy config file path.\nfn deploy_config_path() -> PathBuf {\n dirs::config_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"flow\")\n .join(\"deploy.json\")\n}\n\n/// Load global deploy config.\npub fn load_deploy_config() -> Result<DeployConfig> {\n let path = deploy_config_path();\n if path.exists() {\n let content = fs::read_to_string(&path)?;\n Ok(serde_json::from_str(&content).unwrap_or_default())\n } else {\n Ok(DeployConfig::default())\n }\n}\n\n/// Save global deploy config.\npub fn save_deploy_config(config: &DeployConfig) -> Result<()> {\n let path = deploy_config_path();\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n let content = serde_json::to_string_pretty(config)?;\n fs::write(&path, content)?;\n Ok(())\n}\n\nfn deploy_log_state_path(project_root: &Path) -> PathBuf {\n project_root.join(DEPLOY_LOG_STATE_FILE)\n}\n\nfn load_deploy_log_state(project_root: &Path) -> DeployLogState {\n let path = deploy_log_state_path(project_root);\n if let Ok(content) = fs::read_to_string(&path) {\n if let Ok(state) = serde_json::from_str::<DeployLogState>(&content) {\n return state;\n }\n }\n DeployLogState::default()\n}\n\nfn save_deploy_log_state(project_root: &Path, state: &DeployLogState) -> Result<()> {\n let path = deploy_log_state_path(project_root);\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n let content = serde_json::to_string_pretty(state)?;\n fs::write(path, content)?;\n Ok(())\n}\n\nfn record_deploy_marker(project_root: &Path) -> Result<()> {\n let now = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .unwrap_or_default()\n .as_secs() as i64;\n let mut state = load_deploy_log_state(project_root);\n state.last_deploy_unix = Some(now);\n save_deploy_log_state(project_root, &state)\n}\n\n/// Run the deploy command.\npub fn run(cmd: DeployCommand) -> Result<()> {\n match cmd.action {\n Some(DeployAction::Config) => configure_deploy(),\n Some(DeployAction::Release(opts)) => release::run_task(opts),\n Some(DeployAction::Shell) => open_shell(),\n Some(DeployAction::SetHost { connection }) => set_host(&connection),\n Some(DeployAction::ShowHost) => show_host(),\n action => {\n let ctx = load_deploy_project_context()?;\n run_with_project_context(action, ctx)\n }\n }\n}\n\nfn run_with_project_context(action: Option<DeployAction>, ctx: DeployProjectContext) -> Result<()> {\n let DeployProjectContext {\n project_root,\n config_path,\n flow_config,\n } = ctx;\n\n match action {\n None => {\n // Auto-detect platform from flow.toml, or run deploy task if configured.\n if let Some(cfg) = flow_config.as_ref() {\n if let Some(task_name) = cfg.flow.deploy_task.as_deref() {\n if tasks::find_task(cfg, task_name).is_some() {\n return tasks::run(TaskRunOpts {\n config: config_path,\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: task_name.to_string(),\n args: Vec::new(),\n });\n }\n bail!(\n \"deploy_task '{}' not found. Available tasks: {}\",\n task_name,\n available_tasks(cfg)\n );\n }\n\n if cfg.host.is_some() || cfg.cloudflare.is_some() || cfg.railway.is_some() {\n return auto_deploy(&project_root, Some(cfg));\n }\n if tasks::find_task(cfg, \"deploy\").is_some() {\n return tasks::run(TaskRunOpts {\n config: config_path,\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: \"deploy\".to_string(),\n args: Vec::new(),\n });\n }\n bail!(\n \"No deployment config found in flow.toml and no 'deploy' task is defined.\\n\\n\\\n Add one of:\\n\\\n [host]\\n\\\n dest = \\\"/opt/myapp\\\"\\n\\\n run = \\\"./server\\\"\\n\\n\\\n [cloudflare]\\n\\\n path = \\\"worker\\\"\\n\\n\\\n [railway]\\n\\\n project = \\\"my-project\\\"\\n\\n\\\n Or run:\\n\\\n f deploy setup\"\n );\n }\n\n bail!(\"No flow.toml found. Run `f setup` first.\")\n }\n Some(DeployAction::Host {\n remote_build,\n setup,\n }) => deploy_host(&project_root, flow_config.as_ref(), remote_build, setup),\n Some(DeployAction::Cloudflare { secrets, dev }) => {\n deploy_cloudflare(&project_root, flow_config.as_ref(), secrets, dev)\n }\n Some(DeployAction::Web) => deploy_web(&project_root, flow_config.as_ref()),\n Some(DeployAction::Setup) => setup_cloudflare(&project_root, flow_config.as_ref()),\n Some(DeployAction::Railway) => deploy_railway(&project_root, flow_config.as_ref()),\n Some(DeployAction::Status) => show_status(&project_root, flow_config.as_ref()),\n Some(DeployAction::Logs {\n follow,\n since_deploy,\n all,\n lines,\n }) => show_logs(\n &project_root,\n flow_config.as_ref(),\n follow,\n since_deploy,\n all,\n lines,\n ),\n Some(DeployAction::Restart) => restart_service(&project_root, flow_config.as_ref()),\n Some(DeployAction::Stop) => stop_service(&project_root, flow_config.as_ref()),\n Some(DeployAction::Health { url, status }) => {\n check_health(&project_root, flow_config.as_ref(), url, status)\n }\n Some(DeployAction::Config)\n | Some(DeployAction::Release(_))\n | Some(DeployAction::Shell)\n | Some(DeployAction::SetHost { .. })\n | Some(DeployAction::ShowHost) => unreachable!(\"handled before project context load\"),\n }\n}\n\n/// Run a production deploy (skips flow.deploy_task and prefers deploy-prod/prod tasks).\npub fn run_prod(cmd: DeployCommand) -> Result<()> {\n match cmd.action {\n Some(DeployAction::Config) => configure_deploy(),\n Some(DeployAction::Release(opts)) => release::run_task(opts),\n Some(DeployAction::Shell) => open_shell(),\n Some(DeployAction::SetHost { connection }) => set_host(&connection),\n Some(DeployAction::ShowHost) => show_host(),\n action => {\n let ctx = load_deploy_project_context()?;\n run_prod_with_project_context(action, ctx)\n }\n }\n}\n\nfn run_prod_with_project_context(\n action: Option<DeployAction>,\n ctx: DeployProjectContext,\n) -> Result<()> {\n let DeployProjectContext {\n project_root,\n config_path,\n flow_config,\n } = ctx;\n\n match action {\n None => {\n let cfg = flow_config\n .as_ref()\n .context(\"No flow.toml found. Run `f init` first.\")?;\n\n if tasks::find_task(cfg, \"deploy-prod\").is_some() {\n return tasks::run(TaskRunOpts {\n config: config_path.clone(),\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: \"deploy-prod\".to_string(),\n args: Vec::new(),\n });\n }\n\n if tasks::find_task(cfg, \"prod\").is_some() {\n return tasks::run(TaskRunOpts {\n config: config_path.clone(),\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: \"prod\".to_string(),\n args: Vec::new(),\n });\n }\n\n if cfg.host.is_some()\n || cfg.cloudflare.is_some()\n || cfg.railway.is_some()\n || cfg.web.is_some()\n {\n if cfg.host.is_some() {\n println!(\"Detected [host] config, deploying to Linux host...\");\n return deploy_host(&project_root, Some(cfg), false, false);\n }\n\n if cfg.cloudflare.is_some() {\n println!(\"Detected [cloudflare] config, deploying to Cloudflare...\");\n if let Err(err) = ensure_prod_cloudflare_routes(&project_root, cfg) {\n eprintln!(\"WARN prod route setup skipped: {err}\");\n }\n return deploy_cloudflare(&project_root, Some(cfg), false, false);\n }\n\n if cfg.railway.is_some() {\n println!(\"Detected [railway] config, deploying to Railway...\");\n return deploy_railway(&project_root, Some(cfg));\n }\n\n if cfg.web.is_some() {\n println!(\"Detected [web] config, deploying web...\");\n return deploy_web(&project_root, Some(cfg));\n }\n }\n\n bail!(\n \"No production deploy config found in flow.toml.\\n\\n\\\n Add one of:\\n\\\n [host]\\n\\\n dest = \\\"/opt/myapp\\\"\\n\\\n run = \\\"./server\\\"\\n\\n\\\n [cloudflare]\\n\\\n path = \\\"worker\\\"\\n\\n\\\n [railway]\\n\\\n project = \\\"my-project\\\"\\n\\n\\\n [web]\\n\\\n path = \\\"packages/web\\\"\\n\\n\\\n Or define a deploy-prod/prod task.\"\n );\n }\n Some(DeployAction::Host {\n remote_build,\n setup,\n }) => deploy_host(&project_root, flow_config.as_ref(), remote_build, setup),\n Some(DeployAction::Cloudflare { secrets, dev }) => {\n if let Some(cfg) = flow_config.as_ref() {\n if let Err(err) = ensure_prod_cloudflare_routes(&project_root, cfg) {\n eprintln!(\"WARN prod route setup skipped: {err}\");\n }\n }\n deploy_cloudflare(&project_root, flow_config.as_ref(), secrets, dev)\n }\n Some(DeployAction::Web) => deploy_web(&project_root, flow_config.as_ref()),\n Some(DeployAction::Setup) => setup_cloudflare(&project_root, flow_config.as_ref()),\n Some(DeployAction::Railway) => deploy_railway(&project_root, flow_config.as_ref()),\n Some(DeployAction::Status) => show_status(&project_root, flow_config.as_ref()),\n Some(DeployAction::Logs {\n follow,\n since_deploy,\n all,\n lines,\n }) => show_logs(\n &project_root,\n flow_config.as_ref(),\n follow,\n since_deploy,\n all,\n lines,\n ),\n Some(DeployAction::Restart) => restart_service(&project_root, flow_config.as_ref()),\n Some(DeployAction::Stop) => stop_service(&project_root, flow_config.as_ref()),\n Some(DeployAction::Health { url, status }) => {\n check_health(&project_root, flow_config.as_ref(), url, status)\n }\n Some(DeployAction::Config)\n | Some(DeployAction::Release(_))\n | Some(DeployAction::Shell)\n | Some(DeployAction::SetHost { .. })\n | Some(DeployAction::ShowHost) => unreachable!(\"handled before project context load\"),\n }\n}\n\nfn configure_deploy() -> Result<()> {\n println!(\"Deploy config (Linux host via SSH).\");\n\n let existing = load_deploy_config()?.host;\n let infra_default = infra_linux_connection_string();\n\n if let Some(conn) = existing.as_ref() {\n println!(\"Current host: {}@{}:{}\", conn.user, conn.host, conn.port);\n }\n if let Some(default_conn) = infra_default.as_ref() {\n if existing.is_none() {\n println!(\"Detected infra host: {default_conn}\");\n }\n }\n\n let default_conn = existing\n .as_ref()\n .map(|conn| format!(\"{}@{}:{}\", conn.user, conn.host, conn.port))\n .or(infra_default);\n\n let prompt = \"SSH host (user@host:port)\";\n let input = prompt_line(prompt, default_conn.as_deref())?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n println!(\"No changes.\");\n return Ok(());\n }\n\n let conn = HostConnection::parse(trimmed)?;\n let mut cfg = load_deploy_config()?;\n cfg.host = Some(conn.clone());\n save_deploy_config(&cfg)?;\n\n println!(\"✓ Host set: {}@{}:{}\", conn.user, conn.host, conn.port);\n println!(\"Next: run `f setup release` to scaffold host config, then `f deploy`.\");\n Ok(())\n}\n\nfn load_deploy_project_context() -> Result<DeployProjectContext> {\n let cwd = std::env::current_dir()?;\n let config_path = crate::project_snapshot::find_flow_toml_upwards(&cwd)\n .unwrap_or_else(|| cwd.join(\"flow.toml\"));\n let project_root = config_path.parent().unwrap_or(&cwd).to_path_buf();\n let flow_config = if config_path.exists() {\n Some(crate::config::load(&config_path)?)\n } else {\n None\n };\n\n Ok(DeployProjectContext {\n project_root,\n config_path,\n flow_config,\n })\n}\n\npub fn ensure_deploy_helper() -> Result<Option<PathBuf>> {\n if let Ok(bin_override) = std::env::var(DEPLOY_HELPER_ENV_BIN) {\n let path = crate::config::expand_path(&bin_override);\n if path.exists() {\n return Ok(Some(path));\n }\n }\n\n if let Ok(path) = which::which(DEPLOY_HELPER_BIN) {\n return Ok(Some(path));\n }\n\n let repo = deploy_helper_repo();\n if !repo.exists() {\n println!(\n \"Deploy helper not found. Set {} or install it to continue.\",\n DEPLOY_HELPER_ENV_BIN\n );\n return Ok(None);\n }\n\n println!(\"Installing deploy helper...\");\n let status = Command::new(\"cargo\")\n .args([\"build\", \"--release\"])\n .current_dir(&repo)\n .status()\n .context(\"failed to build deploy helper\")?;\n\n if !status.success() {\n bail!(\"deploy helper build failed\");\n }\n\n let bin_path = repo.join(\"target/release\").join(DEPLOY_HELPER_BIN);\n let install_dir = dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".local/bin\");\n fs::create_dir_all(&install_dir)\n .with_context(|| format!(\"failed to create {}\", install_dir.display()))?;\n let install_path = install_dir.join(DEPLOY_HELPER_BIN);\n fs::copy(&bin_path, &install_path)\n .with_context(|| format!(\"failed to copy {}\", install_path.display()))?;\n #[cfg(unix)]\n {\n use std::os::unix::fs::PermissionsExt;\n let mut perms = fs::metadata(&install_path)?.permissions();\n perms.set_mode(0o755);\n fs::set_permissions(&install_path, perms)?;\n }\n\n println!(\"Deploy helper installed.\");\n Ok(Some(install_path))\n}\n\nfn deploy_helper_repo() -> PathBuf {\n if let Ok(repo_override) = std::env::var(DEPLOY_HELPER_ENV_REPO) {\n return crate::config::expand_path(&repo_override);\n }\n crate::config::expand_path(DEPLOY_HELPER_REPO_DEFAULT)\n}\n\nfn infra_linux_connection_string() -> Option<String> {\n let base = dirs::config_dir().unwrap_or_else(|| PathBuf::from(\".\"));\n let paths = [\n base.join(\"infra\").join(\"config.json\"),\n crate::config::global_config_dir().join(\"infra/config.json\"),\n ];\n\n for path in paths {\n if !path.exists() {\n continue;\n }\n let content = fs::read_to_string(&path).ok()?;\n let cfg: InfraConfig = serde_json::from_str(&content).ok()?;\n let user = cfg.linux_user?;\n let host = cfg.linux_host?;\n let port = cfg.linux_port.unwrap_or_else(|| \"22\".to_string());\n return Some(format!(\"{}@{}:{}\", user, host, port));\n }\n\n None\n}\n\npub fn default_linux_connection_string() -> Option<String> {\n infra_linux_connection_string()\n}\n\nfn prompt_line(message: &str, default: Option<&str>) -> Result<String> {\n if let Some(default) = default {\n print!(\"{message} [{default}]: \");\n } else {\n print!(\"{message}: \");\n }\n std::io::stdout().flush()?;\n let mut input = String::new();\n std::io::stdin().read_line(&mut input)?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n return Ok(default.unwrap_or(\"\").to_string());\n }\n Ok(trimmed.to_string())\n}\n\nfn prompt_yes_no(message: &str, default_yes: bool) -> Result<bool> {\n let prompt = if default_yes { \"[Y/n]\" } else { \"[y/N]\" };\n print!(\"{message} {prompt}: \");\n std::io::stdout().flush()?;\n let mut input = String::new();\n std::io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n if answer.is_empty() {\n return Ok(default_yes);\n }\n Ok(answer == \"y\" || answer == \"yes\")\n}\n\nfn prompt_secret(message: &str) -> Result<String> {\n let value = prompt_password(message)?;\n Ok(value)\n}\n\nfn available_tasks(cfg: &crate::config::Config) -> String {\n let mut names: Vec<_> = cfg.tasks.iter().map(|task| task.name.clone()).collect();\n names.sort();\n names.join(\", \")\n}\n\n/// Auto-detect platform and deploy.\nfn auto_deploy(project_root: &Path, config: Option<&Config>) -> Result<()> {\n let config = config.context(\"No flow.toml found. Run 'f init' first.\")?;\n\n // Check which platform configs exist\n if config.host.is_some() {\n println!(\"Detected [host] config, deploying to Linux host...\");\n return deploy_host(project_root, Some(config), false, false);\n }\n\n if config.cloudflare.is_some() {\n println!(\"Detected [cloudflare] config, deploying to Cloudflare...\");\n return deploy_cloudflare(project_root, Some(config), false, false);\n }\n\n if config.railway.is_some() {\n println!(\"Detected [railway] config, deploying to Railway...\");\n return deploy_railway(project_root, Some(config));\n }\n\n bail!(\n \"No deployment config found in flow.toml.\\n\\n\\\n Add one of:\\n\\\n [host]\\n\\\n dest = \\\"/opt/myapp\\\"\\n\\\n run = \\\"./server\\\"\\n\\n\\\n [cloudflare]\\n\\\n path = \\\"worker\\\"\\n\\n\\\n [railway]\\n\\\n project = \\\"my-project\\\"\\n\\n\\\n Or run:\\n\\\n f deploy setup\"\n );\n}\n\nfn deploy_web(project_root: &Path, config: Option<&Config>) -> Result<()> {\n let (web_root, flow_path, mut cfg) = resolve_deploy_root(project_root, config)?;\n\n let mut changed = false;\n if ensure_web_config(&flow_path, &web_root, &cfg)? {\n changed = true;\n cfg = crate::config::load(&flow_path)?;\n }\n\n let web_cfg = cfg.web.as_ref().context(\"No [web] section in flow.toml\")?;\n\n if ensure_web_domain_or_route(&flow_path, web_cfg)? {\n changed = true;\n cfg = crate::config::load(&flow_path)?;\n }\n let web_cfg = cfg.web.as_ref().context(\"No [web] section in flow.toml\")?;\n\n if ensure_web_env_source(&flow_path, web_cfg)? {\n changed = true;\n cfg = crate::config::load(&flow_path)?;\n }\n let web_cfg = cfg.web.as_ref().context(\"No [web] section in flow.toml\")?;\n\n if ensure_web_routes(&web_root, web_cfg)? {\n changed = true;\n }\n\n if changed {\n println!(\"Updated web deployment config.\");\n }\n\n ensure_cloudflare_api_token()?;\n ensure_web_dns(web_cfg)?;\n\n if let Err(err) = apply_web_env(&web_root, web_cfg) {\n eprintln!(\"WARN env apply skipped: {err}\");\n eprintln!(\"Hint: run `f env setup` to store missing web env vars.\");\n }\n\n if tasks::find_task(&cfg, \"deploy-web\").is_some() {\n return tasks::run(TaskRunOpts {\n config: flow_path,\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: \"deploy-web\".to_string(),\n args: Vec::new(),\n });\n }\n\n if tasks::find_task(&cfg, \"deploy\").is_some() {\n eprintln!(\"WARN deploy-web task not found; running deploy.\");\n return tasks::run(TaskRunOpts {\n config: flow_path,\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: \"deploy\".to_string(),\n args: Vec::new(),\n });\n }\n\n bail!(\"No deploy task found. Add 'deploy-web' or 'deploy' to flow.toml.\");\n}\n\nfn resolve_deploy_root(\n project_root: &Path,\n config: Option<&Config>,\n) -> Result<(PathBuf, PathBuf, Config)> {\n let Some(flow_path) = find_flow_toml_from(project_root) else {\n bail!(\"flow.toml not found. Run from your repo root.\");\n };\n\n let root = flow_path.parent().unwrap_or(project_root).to_path_buf();\n let cfg = if root == project_root {\n match config {\n Some(existing) => existing.clone(),\n None => crate::config::load(&flow_path)?,\n }\n } else {\n crate::config::load(&flow_path)?\n };\n\n Ok((root, flow_path, cfg))\n}\n\nfn find_flow_toml_from(start: &Path) -> Option<PathBuf> {\n let mut current = start.to_path_buf();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\n/// Deploy to a Linux host via SSH.\nfn deploy_host(\n project_root: &Path,\n config: Option<&Config>,\n _remote_build: bool,\n force_setup: bool,\n) -> Result<()> {\n let deploy_config = load_deploy_config()?;\n let conn = deploy_config\n .host\n .as_ref()\n .context(\"No host configured. Run: f deploy set-host user@host:port\")?;\n\n let host_cfg = config\n .and_then(|c| c.host.as_ref())\n .context(\"No [host] section in flow.toml\")?;\n\n let dest = host_cfg.dest.as_deref().unwrap_or(\"/opt/app\");\n let service_name = host_cfg\n .service\n .as_deref()\n .unwrap_or_else(|| project_root.file_name().unwrap().to_str().unwrap());\n\n println!(\"Deploying to {}:{}\", conn.ssh_target(), dest);\n\n // 1. Sync files via rsync\n println!(\"\\n==> Syncing files...\");\n rsync_upload(project_root, conn, dest)?;\n\n // 2. Handle env vars\n let use_cloud = is_cloud_source(host_cfg.env_source.as_deref());\n let use_flow = is_flow_source(host_cfg.env_source.as_deref());\n let has_service_token = host_cfg.service_token.is_some();\n\n let use_cloud_token_mode = use_cloud\n || host_cfg\n .env_source\n .as_deref()\n .map(|s| s.eq_ignore_ascii_case(\"flow\"))\n .unwrap_or(false);\n\n if use_cloud_token_mode && has_service_token {\n // Service token mode: install fetch script, host fetches env vars on startup\n let service_token = host_cfg.service_token.as_ref().unwrap();\n let env_name = host_cfg.environment.as_deref().unwrap_or(\"production\");\n let project_name = project_root.file_name().unwrap().to_str().unwrap();\n let api_base =\n crate::env::load_env_api_url().unwrap_or_else(|_| \"https://myflow.sh\".to_string());\n\n println!(\"==> Installing env-fetch script (host will fetch on startup)...\");\n install_env_fetch_script(\n conn,\n dest,\n service_token,\n &api_base,\n project_name,\n env_name,\n &host_cfg.env_keys,\n )?;\n } else if use_cloud || use_flow {\n // Deploy-time fetch mode: fetch now and copy to host\n let env_name = host_cfg.environment.as_deref().unwrap_or(\"production\");\n let keys = &host_cfg.env_keys;\n let use_project = host_cfg.env_project;\n\n if !keys.is_empty() {\n let source = if use_project {\n format!(\"project/{}\", env_name)\n } else {\n \"personal\".to_string()\n };\n let source_label = if use_cloud { \"cloud\" } else { \"flow\" };\n println!(\n \"==> Fetching env vars from {} ({})...\",\n source_label, source\n );\n\n let fetch = || {\n if use_project {\n crate::env::fetch_project_env_vars(env_name, keys)\n } else {\n crate::env::fetch_personal_env_vars(keys)\n }\n };\n\n let result = if use_flow && host_cfg.env_source.as_deref() == Some(\"local\") {\n with_local_env_backend(fetch)\n } else {\n fetch()\n };\n\n match result {\n Ok(mut vars) if !vars.is_empty() => {\n if !keys.is_empty() {\n let key_set: HashSet<_> = keys.iter().collect();\n vars.retain(|k, _| key_set.contains(k));\n }\n\n // Generate .env content\n let mut content = String::new();\n content.push_str(&format!(\n \"# Source: {} {} (fetched at deploy)\\n\",\n source_label, source\n ));\n let mut sorted_keys: Vec<_> = vars.keys().collect();\n sorted_keys.sort();\n for key in sorted_keys {\n let value = &vars[key];\n let escaped = value.replace('\\\\', \"\\\\\\\\\").replace('\"', \"\\\\\\\"\");\n content.push_str(&format!(\"{}=\\\"{}\\\"\\n\", key, escaped));\n }\n\n // Write to temp file and scp\n let temp_env =\n std::env::temp_dir().join(format!(\".env.{}\", std::process::id()));\n fs::write(&temp_env, &content)?;\n let remote_env = format!(\"{}/.env\", dest);\n println!(\"==> Copying {} env vars to remote...\", vars.len());\n scp_file(&temp_env, conn, &remote_env)?;\n let _ = fs::remove_file(&temp_env);\n }\n Ok(_) => {\n eprintln!(\"⚠ No env vars found in {} for {}\", source_label, source);\n }\n Err(err) => {\n eprintln!(\"⚠ Failed to fetch env vars from {}: {}\", source_label, err);\n }\n }\n }\n } else if let Some(env_file) = &host_cfg.env_file {\n let local_env = project_root.join(env_file);\n if local_env.exists() {\n println!(\"==> Copying {}...\", env_file);\n let remote_env = format!(\"{}/.env\", dest);\n scp_file(&local_env, conn, &remote_env)?;\n }\n }\n\n // 3. Run setup script if needed\n if let Some(setup) = &host_cfg.setup {\n if force_setup || !service_exists(conn, service_name)? {\n println!(\"==> Running setup...\");\n ssh_run(conn, &format!(\"cd {} && {}\", dest, setup))?;\n }\n }\n\n // 4. Create/update systemd service\n if let Some(run_cmd) = &host_cfg.run {\n println!(\"==> Configuring systemd service: {}\", service_name);\n create_systemd_service(conn, service_name, dest, run_cmd, host_cfg)?;\n }\n\n // 5. Configure nginx if domain specified\n if let Some(domain) = &host_cfg.domain {\n if let Some(port) = host_cfg.port {\n println!(\"==> Configuring nginx for {}\", domain);\n setup_nginx(conn, domain, port, host_cfg.ssl)?;\n }\n }\n\n // 6. Restart service\n println!(\"==> Starting service...\");\n ssh_run(conn, &format!(\"systemctl restart {}\", service_name))?;\n\n println!(\"\\n✓ Deployed successfully!\");\n if let Some(domain) = &host_cfg.domain {\n let scheme = if host_cfg.ssl { \"https\" } else { \"http\" };\n println!(\" URL: {}://{}\", scheme, domain);\n }\n\n if let Err(err) = record_deploy_marker(project_root) {\n eprintln!(\"⚠ Failed to record deploy timestamp: {err}\");\n }\n\n Ok(())\n}\n\n/// Deploy to Cloudflare Workers.\nfn deploy_cloudflare(\n project_root: &Path,\n config: Option<&Config>,\n set_secrets: bool,\n dev_mode: bool,\n) -> Result<()> {\n let default_cf = CloudflareConfig::default();\n let cf_cfg = config\n .and_then(|c| c.cloudflare.as_ref())\n .unwrap_or(&default_cf);\n\n let worker_path = cf_cfg\n .path\n .as_ref()\n .map(|p| project_root.join(p))\n .unwrap_or_else(|| project_root.to_path_buf());\n\n ensure_wrangler_config(&worker_path)?;\n\n let env_name = cf_cfg.environment.as_deref();\n\n let env_apply_mode = if set_secrets {\n EnvApplyMode::Always\n } else {\n env_apply_mode_from_str(cf_cfg.env_apply.as_deref())\n };\n let should_apply = matches!(env_apply_mode, EnvApplyMode::Always | EnvApplyMode::Auto);\n let source = cf_cfg.env_source.as_deref();\n let use_cloud = is_cloud_source(source);\n let use_flow = is_flow_source(source);\n let use_env_store = use_cloud || use_flow;\n let source_label = if use_cloud { \"cloud\" } else { \"flow\" };\n\n let cloud_env = env_name.unwrap_or(\"production\");\n let mut cloud_vars: HashMap<String, String> = HashMap::new();\n let mut cloud_loaded = false;\n\n if use_env_store {\n let keys = collect_cloudflare_env_keys(cf_cfg);\n if !cf_cfg.env_defaults.is_empty() {\n for key in &keys {\n if let Some(value) = cf_cfg.env_defaults.get(key) {\n if !value.trim().is_empty() {\n cloud_vars.insert(key.clone(), value.clone());\n }\n }\n }\n }\n\n if !keys.is_empty() {\n let fetch = || crate::env::fetch_project_env_vars(cloud_env, &keys);\n let result = if use_flow && source == Some(\"local\") {\n with_local_env_backend(fetch)\n } else {\n fetch()\n };\n match result {\n Ok(vars) => {\n if !vars.is_empty() {\n cloud_loaded = true;\n }\n cloud_vars.extend(vars);\n }\n Err(err) => {\n if env_apply_mode == EnvApplyMode::Auto {\n if is_tls_connect_error(&err) {\n eprintln!(\n \"⚠ Unable to reach cloud (TLS/connect). Skipping env sync for now.\"\n );\n } else {\n eprintln!(\"⚠ Env sync skipped: {err}\");\n }\n } else if env_apply_mode == EnvApplyMode::Always {\n eprintln!(\"⚠ Env sync skipped: {err}\");\n } else {\n eprintln!(\"⚠ Env sync skipped: {err}\");\n }\n }\n }\n }\n }\n\n if should_apply {\n if use_env_store {\n if cloud_loaded {\n apply_cloudflare_env_map(project_root, cf_cfg, &cloud_vars)?;\n } else if env_apply_mode == EnvApplyMode::Always {\n eprintln!(\n \"⚠ No env vars found in {} for environment '{}' (using defaults only).\",\n source_label, cloud_env\n );\n }\n } else if let Some(env_file) = &cf_cfg.env_file {\n let env_path = project_root.join(env_file);\n if env_path.exists() {\n println!(\"==> Setting secrets from {}...\", env_file);\n set_wrangler_secrets(&worker_path, &env_path, env_name, None)?;\n }\n }\n }\n\n // Deploy or dev\n let cmd = if dev_mode {\n cf_cfg.dev.as_deref().unwrap_or(\"wrangler dev\")\n } else {\n cf_cfg.deploy.as_deref().unwrap_or(\"wrangler deploy\")\n };\n let cmd = append_env_arg(cmd, env_name);\n\n println!(\"==> Running: {}\", cmd);\n let mut deploy_cmd = Command::new(\"sh\");\n deploy_cmd\n .arg(\"-c\")\n .arg(cmd)\n .current_dir(&worker_path)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit());\n\n if use_env_store && !cloud_vars.is_empty() {\n deploy_cmd.envs(&cloud_vars);\n }\n\n let status = deploy_cmd.status()?;\n\n if !status.success() {\n bail!(\"Cloudflare deployment failed\");\n }\n\n println!(\"\\n✓ Deployed to Cloudflare!\");\n Ok(())\n}\n\npub fn apply_cloudflare_env(project_root: &Path, config: Option<&Config>) -> Result<()> {\n let cf_cfg = config\n .and_then(|c| c.cloudflare.as_ref())\n .context(\"No [cloudflare] section in flow.toml\")?;\n apply_cloudflare_env_from_config(project_root, cf_cfg)\n}\n\npub fn set_cloudflare_secrets(\n project_root: &Path,\n config: Option<&Config>,\n secrets: &HashMap<String, String>,\n) -> Result<()> {\n let cf_cfg = config\n .and_then(|c| c.cloudflare.as_ref())\n .context(\"No [cloudflare] section in flow.toml\")?;\n let worker_path = cf_cfg\n .path\n .as_ref()\n .map(|p| project_root.join(p))\n .unwrap_or_else(|| project_root.to_path_buf());\n ensure_wrangler_config(&worker_path)?;\n\n let env_name = cf_cfg.environment.as_deref();\n let mut keys: Vec<_> = secrets.keys().cloned().collect();\n keys.sort();\n for key in keys {\n if let Some(value) = secrets.get(&key) {\n println!(\" Setting secret {}...\", key);\n set_wrangler_secret_value(&worker_path, env_name, &key, value)?;\n }\n }\n\n Ok(())\n}\n\nfn apply_cloudflare_env_from_config(project_root: &Path, cf_cfg: &CloudflareConfig) -> Result<()> {\n let source = cf_cfg.env_source.as_deref();\n if !is_cloud_source(source) && !is_flow_source(source) {\n bail!(\n \"cloudflare.env_source must be set to \\\"cloud\\\", \\\"flow\\\", or \\\"local\\\" to apply envs\"\n );\n }\n\n let cloud_env = cf_cfg.environment.as_deref().unwrap_or(\"production\");\n let keys = collect_cloudflare_env_keys(cf_cfg);\n let fetch = || crate::env::fetch_project_env_vars(cloud_env, &keys);\n let vars = if is_flow_source(source) && source == Some(\"local\") {\n with_local_env_backend(fetch)?\n } else {\n fetch()?\n };\n if vars.is_empty() {\n bail!(\n \"No env vars found in env store for environment '{}'\",\n cloud_env\n );\n }\n\n apply_cloudflare_env_map(project_root, cf_cfg, &vars)?;\n Ok(())\n}\n\nfn collect_cloudflare_env_keys(cf_cfg: &CloudflareConfig) -> Vec<String> {\n let mut keys = Vec::new();\n let mut seen = HashSet::new();\n for key in cf_cfg.env_keys.iter().chain(cf_cfg.env_vars.iter()) {\n if seen.insert(key.clone()) {\n keys.push(key.clone());\n }\n }\n keys\n}\n\nfn apply_cloudflare_env_map(\n project_root: &Path,\n cf_cfg: &CloudflareConfig,\n vars: &HashMap<String, String>,\n) -> Result<()> {\n let worker_path = cf_cfg\n .path\n .as_ref()\n .map(|p| project_root.join(p))\n .unwrap_or_else(|| project_root.to_path_buf());\n ensure_wrangler_config(&worker_path)?;\n\n let wrangler_env = cf_cfg.environment.as_deref();\n let var_keys: HashSet<String> = cf_cfg.env_vars.iter().cloned().collect();\n println!(\"==> Applying {} env var(s) from env store...\", vars.len());\n set_wrangler_env_map(&worker_path, wrangler_env, vars, &var_keys)?;\n Ok(())\n}\n\nfn ensure_wrangler_config(worker_path: &Path) -> Result<()> {\n let has_wrangler = worker_path.join(\"wrangler.toml\").exists()\n || worker_path.join(\"wrangler.jsonc\").exists()\n || worker_path.join(\"wrangler.json\").exists();\n\n if !has_wrangler {\n bail!(\n \"No wrangler config found in {}.\\n\\\n Create a wrangler.toml or run: npx wrangler init\",\n worker_path.display()\n );\n }\n\n Ok(())\n}\n\nfn wrangler_command(worker_path: &Path) -> Command {\n let local_bin = worker_path\n .join(\"node_modules\")\n .join(\".bin\")\n .join(\"wrangler\");\n let mut cmd = if local_bin.exists() {\n Command::new(local_bin)\n } else if worker_path.join(\"package.json\").exists() {\n let mut cmd = Command::new(\"pnpm\");\n cmd.args([\"exec\", \"wrangler\"]);\n cmd\n } else {\n Command::new(\"wrangler\")\n };\n cmd.current_dir(worker_path);\n cmd\n}\n\nfn is_cloud_source(source: Option<&str>) -> bool {\n matches!(\n source.map(|s| s.to_ascii_lowercase()).as_deref(),\n Some(\"cloud\") | Some(\"remote\") | Some(\"myflow\")\n )\n}\n\nfn is_flow_source(source: Option<&str>) -> bool {\n matches!(\n source.map(|s| s.to_ascii_lowercase()).as_deref(),\n Some(\"flow\") | Some(\"local\")\n )\n}\n\nfn maybe_bootstrap_secrets(\n worker_path: &Path,\n cf_cfg: &CloudflareConfig,\n env_name: &str,\n) -> Result<()> {\n if cf_cfg.bootstrap_secrets.is_empty() {\n return Ok(());\n }\n\n let mut env_store_missing = false;\n let existing = match crate::env::fetch_project_env_vars(env_name, &cf_cfg.bootstrap_secrets) {\n Ok(vars) => vars,\n Err(err) => {\n let msg = format!(\"{err:#}\");\n if msg.contains(\"Project not found.\") || msg.contains(\"Personal env vars not found.\") {\n env_store_missing = true;\n HashMap::new()\n } else {\n eprintln!(\"⚠ Unable to check bootstrap secrets: {err}\");\n println!(\"Run `f env bootstrap` later if needed.\");\n return Ok(());\n }\n }\n };\n\n let missing: Vec<String> = cf_cfg\n .bootstrap_secrets\n .iter()\n .filter(|key| {\n existing\n .get(*key)\n .map(|value| value.trim().is_empty())\n .unwrap_or(true)\n })\n .cloned()\n .collect();\n\n if missing.is_empty() {\n println!(\"Bootstrap secrets already configured; skipping.\");\n return Ok(());\n }\n\n if let Ok(present) = list_cloudflare_secret_keys(worker_path, cf_cfg.environment.as_deref()) {\n if missing.iter().all(|key| present.contains(key)) {\n println!(\n \"Bootstrap secrets missing in cloud but already present in Cloudflare; skipping.\"\n );\n println!(\"Run `f env bootstrap` if you want to rotate/store them in cloud.\");\n return Ok(());\n }\n }\n\n if env_store_missing {\n println!(\"cloud env space not found yet; bootstrap will initialize it.\");\n }\n\n println!(\"Bootstrap secrets missing: {}\", missing.join(\", \"));\n println!(\"==> Bootstrapping secrets (optional)...\");\n crate::env::run(Some(EnvAction::Bootstrap))?;\n Ok(())\n}\n\nfn list_cloudflare_secret_keys(\n worker_path: &Path,\n env_name: Option<&str>,\n) -> Result<HashSet<String>> {\n let mut cmd = wrangler_command(worker_path);\n cmd.args([\"secret\", \"list\", \"--json\"]);\n if let Some(env) = env_name {\n cmd.args([\"--env\", env]);\n }\n let output = cmd.output()?;\n if !output.status.success() {\n bail!(\"wrangler secret list failed\");\n }\n let value: serde_json::Value = serde_json::from_slice(&output.stdout)\n .context(\"failed to parse wrangler secret list output\")?;\n let mut keys = HashSet::new();\n if let Some(items) = value.as_array() {\n for item in items {\n if let Some(name) = item.get(\"name\").and_then(|val| val.as_str()) {\n keys.insert(name.to_string());\n }\n }\n }\n Ok(keys)\n}\n\nfn set_wrangler_env_map(\n worker_path: &Path,\n env_name: Option<&str>,\n vars: &HashMap<String, String>,\n var_keys: &HashSet<String>,\n) -> Result<()> {\n for (key, value) in vars {\n if var_keys.contains(key) {\n println!(\" Setting var {}...\", key);\n set_wrangler_var_value(worker_path, env_name, key, value)?;\n } else {\n println!(\" Setting secret {}...\", key);\n set_wrangler_secret_value(worker_path, env_name, key, value)?;\n }\n }\n Ok(())\n}\n\nfn set_wrangler_var_value(\n worker_path: &Path,\n env_name: Option<&str>,\n key: &str,\n value: &str,\n) -> Result<()> {\n let mut cmd = wrangler_command(worker_path);\n cmd.args([\"vars\", \"set\", key, value]);\n if let Some(env) = env_name {\n cmd.args([\"--env\", env]);\n }\n let status = cmd\n .stdin(Stdio::null())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()?;\n\n if !status.success() {\n bail!(\"Failed to set wrangler var {}\", key);\n }\n Ok(())\n}\n\nfn set_wrangler_secret_value(\n worker_path: &Path,\n env_name: Option<&str>,\n key: &str,\n value: &str,\n) -> Result<()> {\n let mut cmd = wrangler_command(worker_path);\n cmd.args([\"secret\", \"put\", key]);\n if let Some(env) = env_name {\n cmd.args([\"--env\", env]);\n }\n let mut child = cmd\n .stdin(Stdio::piped())\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .spawn()?;\n\n if let Some(mut stdin) = child.stdin.take() {\n writeln!(stdin, \"{}\", value)?;\n }\n let status = child.wait()?;\n if !status.success() {\n bail!(\"Failed to set wrangler secret {}\", key);\n }\n Ok(())\n}\n\nfn setup_cloudflare(project_root: &Path, config: Option<&Config>) -> Result<()> {\n let default_cf = CloudflareConfig::default();\n let cf_cfg = config\n .and_then(|c| c.cloudflare.as_ref())\n .unwrap_or(&default_cf);\n\n if is_cloud_source(cf_cfg.env_source.as_deref()) {\n let worker_path = if let Some(path) = cf_cfg.path.as_ref() {\n project_root.join(path)\n } else {\n let workers = discover_wrangler_configs(project_root)?;\n if workers.is_empty() {\n println!(\"No Cloudflare Worker config found (wrangler.toml/json).\");\n println!(\"Run `wrangler init` first, then try: f deploy setup\");\n return Ok(());\n }\n if workers.len() > 1 {\n bail!(\n \"Multiple Cloudflare worker configs found. Set [cloudflare].path in flow.toml.\"\n );\n }\n workers[0].clone()\n };\n\n ensure_wrangler_config(&worker_path)?;\n println!(\"Using Cloudflare worker: {}\", worker_path.display());\n\n let env_name = cf_cfg\n .environment\n .clone()\n .unwrap_or_else(|| \"production\".to_string());\n maybe_bootstrap_secrets(&worker_path, cf_cfg, &env_name)?;\n let keys = collect_cloudflare_env_keys(cf_cfg);\n let env_store_ok = if keys.is_empty() {\n true\n } else {\n match crate::env::fetch_project_env_vars(&env_name, &keys) {\n Ok(_) => true,\n Err(err) => {\n let msg = format!(\"{err:#}\");\n if msg.contains(\"Project not found.\") {\n println!(\"Project not found yet; it will be created on first set.\");\n true\n } else {\n eprintln!(\"⚠ Env store unavailable: {err}\");\n false\n }\n }\n }\n };\n\n if env_store_ok {\n if let Some(flow_cfg) = config {\n services::maybe_run_stripe_setup(project_root, flow_cfg, &env_name)?;\n }\n crate::env::run(Some(EnvAction::Guide {\n environment: env_name,\n }))?;\n crate::env::run(Some(EnvAction::Apply))?;\n } else {\n eprintln!(\"⚠ Skipping env guide/apply (cloud unavailable).\");\n }\n\n println!(\"\\n✓ Cloudflare deploy setup complete.\");\n return Ok(());\n }\n\n let defaults = CloudflareSetupDefaults {\n worker_path: cf_cfg.path.as_ref().map(|p| project_root.join(p)),\n env_file: if is_cloud_source(cf_cfg.env_source.as_deref()) {\n None\n } else {\n cf_cfg.env_file.as_ref().map(|p| project_root.join(p))\n },\n environment: cf_cfg.environment.clone(),\n };\n\n let result = run_cloudflare_setup(project_root, defaults)?;\n let Some(result) = result else {\n return Ok(());\n };\n\n let flow_path = project_root.join(\"flow.toml\");\n if !flow_path.exists() {\n bail!(\"flow.toml not found. Run `f init` first.\");\n }\n\n update_flow_toml_cloudflare(&flow_path, project_root, &result)?;\n\n if result.apply_secrets {\n if is_cloud_source(cf_cfg.env_source.as_deref()) {\n let env_name = result\n .environment\n .clone()\n .unwrap_or_else(|| \"production\".to_string());\n maybe_bootstrap_secrets(&result.worker_path, cf_cfg, &env_name)?;\n crate::env::run(Some(EnvAction::Guide {\n environment: env_name,\n }))?;\n crate::env::run(Some(EnvAction::Apply))?;\n } else if let Some(env_file) = result.env_file.as_ref() {\n let env_name = result.environment.as_deref();\n set_wrangler_secrets(\n &result.worker_path,\n env_file,\n env_name,\n Some(&result.selected_keys),\n )?;\n }\n }\n\n println!(\"\\n✓ Cloudflare deploy setup complete.\");\n Ok(())\n}\n\n/// Deploy to Railway.\nfn deploy_railway(project_root: &Path, config: Option<&Config>) -> Result<()> {\n let default_rail = RailwayConfig::default();\n let rail_cfg = config\n .and_then(|c| c.railway.as_ref())\n .unwrap_or(&default_rail);\n\n // Check railway CLI\n if which::which(\"railway\").is_err() {\n bail!(\"Railway CLI not found. Install: npm install -g @railway/cli\");\n }\n\n // Link project if specified\n if let (Some(project), Some(env)) = (&rail_cfg.project, &rail_cfg.environment) {\n println!(\"==> Linking to Railway project...\");\n let status = Command::new(\"railway\")\n .args([\"link\", project, \"--environment\", env])\n .current_dir(project_root)\n .status()?;\n if !status.success() {\n bail!(\"Failed to link Railway project\");\n }\n }\n\n // Set env vars from file\n if let Some(env_file) = &rail_cfg.env_file {\n let env_path = project_root.join(env_file);\n if env_path.exists() {\n println!(\"==> Setting environment variables...\");\n set_railway_env(&env_path)?;\n }\n }\n\n // Deploy\n println!(\"==> Deploying to Railway...\");\n let status = Command::new(\"railway\")\n .args([\"up\", \"--detach\"])\n .current_dir(project_root)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()?;\n\n if !status.success() {\n bail!(\"Railway deployment failed\");\n }\n\n println!(\"\\n✓ Deployed to Railway!\");\n Ok(())\n}\n\n/// Show deployment status.\nfn show_status(_project_root: &Path, config: Option<&Config>) -> Result<()> {\n let deploy_config = load_deploy_config()?;\n\n println!(\"Deployment Status\\n\");\n\n // Host status\n if let Some(conn) = &deploy_config.host {\n println!(\"Host: {}@{}:{}\", conn.user, conn.host, conn.port);\n if let Some(cfg) = config.and_then(|c| c.host.as_ref()) {\n if let Some(service) = &cfg.service {\n let output = ssh_capture(\n conn,\n &format!(\n \"systemctl is-active {} 2>/dev/null || echo inactive\",\n service\n ),\n )?;\n println!(\" Service '{}': {}\", service, output.trim());\n }\n }\n } else {\n println!(\"Host: not configured\");\n }\n\n Ok(())\n}\n\n/// Show deployment logs.\nfn show_logs(\n project_root: &Path,\n config: Option<&Config>,\n follow: bool,\n since_deploy: bool,\n all: bool,\n lines: usize,\n) -> Result<()> {\n if let Some(cf_cfg) = config.and_then(|c| c.cloudflare.as_ref()) {\n return show_cloudflare_logs(project_root, cf_cfg, follow, lines);\n }\n\n let deploy_config = load_deploy_config()?;\n let conn = deploy_config.host.as_ref().context(\"No host configured\")?;\n\n let service = config\n .and_then(|c| c.host.as_ref())\n .and_then(|h| h.service.as_ref())\n .context(\"No service name in [host] config\")?;\n\n let use_since_deploy = since_deploy && !all;\n let since_flag = if use_since_deploy {\n let state = load_deploy_log_state(project_root);\n if let Some(ts) = state.last_deploy_unix {\n format!(\"--since '@{}'\", ts)\n } else {\n String::new()\n }\n } else {\n String::new()\n };\n\n let follow_flag = if follow { \"-f\" } else { \"\" };\n let cmd = format!(\n \"journalctl -u {} -n {} {} {} --no-pager\",\n service, lines, follow_flag, since_flag\n );\n\n ssh_run(conn, &cmd)?;\n Ok(())\n}\n\nfn show_cloudflare_logs(\n project_root: &Path,\n cf_cfg: &CloudflareConfig,\n follow: bool,\n lines: usize,\n) -> Result<()> {\n let worker_path = cf_cfg\n .path\n .as_ref()\n .map(|p| project_root.join(p))\n .unwrap_or_else(|| project_root.to_path_buf());\n ensure_wrangler_config(&worker_path)?;\n\n if !follow {\n eprintln!(\"Note: wrangler tail streams logs until you stop it (Ctrl+C).\");\n let _ = lines;\n }\n\n let mut cmd = wrangler_command(&worker_path);\n cmd.arg(\"tail\").args([\"--format\", \"pretty\"]);\n if let Some(env) = cf_cfg.environment.as_deref() {\n cmd.args([\"--env\", env]);\n }\n\n let status = cmd\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()?;\n\n if !status.success() {\n bail!(\"Cloudflare log tail failed\");\n }\n\n Ok(())\n}\n\n/// Restart the deployed service.\nfn restart_service(_project_root: &Path, config: Option<&Config>) -> Result<()> {\n let deploy_config = load_deploy_config()?;\n let conn = deploy_config.host.as_ref().context(\"No host configured\")?;\n let service = config\n .and_then(|c| c.host.as_ref())\n .and_then(|h| h.service.as_ref())\n .context(\"No service name\")?;\n\n println!(\"Restarting {}...\", service);\n ssh_run(conn, &format!(\"systemctl restart {}\", service))?;\n println!(\"✓ Restarted\");\n Ok(())\n}\n\n/// Stop the deployed service.\nfn stop_service(_project_root: &Path, config: Option<&Config>) -> Result<()> {\n let deploy_config = load_deploy_config()?;\n let conn = deploy_config.host.as_ref().context(\"No host configured\")?;\n let service = config\n .and_then(|c| c.host.as_ref())\n .and_then(|h| h.service.as_ref())\n .context(\"No service name\")?;\n\n println!(\"Stopping {}...\", service);\n ssh_run(conn, &format!(\"systemctl stop {}\", service))?;\n println!(\"✓ Stopped\");\n Ok(())\n}\n\n/// Open SSH shell to host.\nfn open_shell() -> Result<()> {\n let deploy_config = load_deploy_config()?;\n let conn = deploy_config.host.as_ref().context(\"No host configured\")?;\n\n println!(\"Connecting to {}...\", conn.ssh_target());\n let status = Command::new(\"ssh\")\n .args([\"-p\", &conn.port.to_string(), &conn.ssh_target()])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()?;\n\n if !status.success() {\n bail!(\"SSH connection failed\");\n }\n Ok(())\n}\n\n/// Set the host connection.\nfn set_host(connection: &str) -> Result<()> {\n let conn = HostConnection::parse(connection)?;\n let mut config = load_deploy_config()?;\n config.host = Some(conn.clone());\n save_deploy_config(&config)?;\n\n println!(\"✓ Host set: {}@{}:{}\", conn.user, conn.host, conn.port);\n println!(\"\\nTest connection: f deploy shell\");\n Ok(())\n}\n\n/// Show current host.\nfn show_host() -> Result<()> {\n let config = load_deploy_config()?;\n if let Some(conn) = &config.host {\n println!(\"Host: {}@{}:{}\", conn.user, conn.host, conn.port);\n } else {\n println!(\"No host configured.\");\n println!(\"Set one with: f deploy set-host user@host:port\");\n }\n Ok(())\n}\n\n// ─────────────────────────────────────────────────────────────\n// SSH/rsync helpers\n// ─────────────────────────────────────────────────────────────\n\n/// Run SSH command with inherited stdio.\nfn ssh_run(conn: &HostConnection, cmd: &str) -> Result<()> {\n let status = Command::new(\"ssh\")\n .args([\n \"-p\",\n &conn.port.to_string(),\n \"-o\",\n \"StrictHostKeyChecking=accept-new\",\n &conn.ssh_target(),\n cmd,\n ])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"Failed to run SSH\")?;\n\n if !status.success() {\n bail!(\"SSH command failed: {}\", cmd);\n }\n Ok(())\n}\n\n/// Run SSH command and capture output.\nfn ssh_capture(conn: &HostConnection, cmd: &str) -> Result<String> {\n let output = Command::new(\"ssh\")\n .args([\n \"-p\",\n &conn.port.to_string(),\n \"-o\",\n \"StrictHostKeyChecking=accept-new\",\n &conn.ssh_target(),\n cmd,\n ])\n .output()\n .context(\"Failed to run SSH\")?;\n\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\n/// Sync directory via rsync.\nfn rsync_upload(local: &Path, conn: &HostConnection, remote_dest: &str) -> Result<()> {\n let remote = format!(\"{}:{}\", conn.ssh_target(), remote_dest);\n let ssh_cmd = format!(\"ssh -p {}\", conn.port);\n\n // Create remote directory first\n ssh_run(conn, &format!(\"mkdir -p {}\", remote_dest))?;\n\n let status = Command::new(\"rsync\")\n .args([\n \"-avz\",\n \"--delete\",\n \"--exclude=target/\",\n \"--exclude=.git/\",\n \"--exclude=node_modules/\",\n \"--exclude=.env\",\n \"--exclude=*.log\",\n \"-e\",\n &ssh_cmd,\n &format!(\"{}/\", local.display()),\n &remote,\n ])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"Failed to run rsync\")?;\n\n if !status.success() {\n bail!(\"rsync failed\");\n }\n Ok(())\n}\n\n/// Copy file via scp.\nfn scp_file(local: &Path, conn: &HostConnection, remote: &str) -> Result<()> {\n let dest = format!(\"{}:{}\", conn.ssh_target(), remote);\n let status = Command::new(\"scp\")\n .args([\n \"-P\",\n &conn.port.to_string(),\n &local.display().to_string(),\n &dest,\n ])\n .status()\n .context(\"Failed to run scp\")?;\n\n if !status.success() {\n bail!(\"scp failed\");\n }\n Ok(())\n}\n\n/// Install the env-fetch script on the host.\n/// This script fetches env vars from cloud using a service token on startup.\nfn install_env_fetch_script(\n conn: &HostConnection,\n dest: &str,\n service_token: &str,\n api_base: &str,\n project_name: &str,\n environment: &str,\n keys: &[String],\n) -> Result<()> {\n // Build the keys query parameter\n let keys_param = if keys.is_empty() {\n String::new()\n } else {\n format!(\"&keys={}\", keys.join(\",\"))\n };\n\n // Create the fetch script\n // The script fetches env vars from cloud API and writes to .env\n let api_base = api_base.trim_end_matches('/');\n let script = format!(\n r##\"#!/bin/bash\n# Auto-generated by flow - fetches env vars from cloud on startup\n# This token can ONLY read env vars for project: {project_name}\n\nset -e\n\nTOKEN_FILE=\"{dest}/.cloud-token\"\nENV_FILE=\"{dest}/.env\"\nAPI_URL=\"{api_base}/api/env/{project_name}?environment={environment}{keys_param}\"\n\nif [ ! -f \"$TOKEN_FILE\" ]; then\n echo \"ERROR: Service token not found at $TOKEN_FILE\" >&2\n exit 1\nfi\n\nTOKEN=$(cat \"$TOKEN_FILE\")\n\n# Fetch env vars from cloud\nRESPONSE=$(curl -sf -H \"Authorization: Bearer $TOKEN\" \"$API_URL\")\n\nif [ $? -ne 0 ]; then\n echo \"ERROR: Failed to fetch env vars from cloud\" >&2\n exit 1\nfi\n\n# Parse JSON and write to .env file\necho \"# Environment: {environment} (fetched from cloud)\" > \"$ENV_FILE\"\necho \"$RESPONSE\" | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nfor k, v in sorted(data.get('env', {{}}).items()):\n escaped = v.replace('\\\\', '\\\\\\\\').replace('\\\"', '\\\\\\\"')\n print(f'{{{{k}}}}=\\\"{{{{escaped}}}}\\\"')\n\" >> \"$ENV_FILE\"\n\nchmod 600 \"$ENV_FILE\"\necho \"Fetched env vars for {project_name} ({environment})\"\n\"##\n );\n\n // Write script to temp file and copy\n let temp_script = std::env::temp_dir().join(format!(\"fetch-env-{}.sh\", std::process::id()));\n fs::write(&temp_script, &script)?;\n scp_file(&temp_script, conn, &format!(\"{}/fetch-env.sh\", dest))?;\n let _ = fs::remove_file(&temp_script);\n\n // Make executable\n ssh_run(conn, &format!(\"chmod +x {}/fetch-env.sh\", dest))?;\n\n // Store the service token securely\n let temp_token = std::env::temp_dir().join(format!(\".cloud-token-{}\", std::process::id()));\n fs::write(&temp_token, service_token)?;\n scp_file(&temp_token, conn, &format!(\"{}/.cloud-token\", dest))?;\n let _ = fs::remove_file(&temp_token);\n\n // Secure the token file (only readable by root)\n ssh_run(conn, &format!(\"chmod 600 {}/.cloud-token\", dest))?;\n\n Ok(())\n}\n\n/// Check if systemd service exists.\nfn service_exists(conn: &HostConnection, name: &str) -> Result<bool> {\n let output = ssh_capture(\n conn,\n &format!(\n \"systemctl list-unit-files {} 2>/dev/null | grep -c {} || true\",\n name, name\n ),\n )?;\n Ok(output.trim() != \"0\")\n}\n\n/// Create systemd service file.\nfn create_systemd_service(\n conn: &HostConnection,\n name: &str,\n workdir: &str,\n exec_start: &str,\n config: &HostConfig,\n) -> Result<()> {\n let exec_start = normalize_exec_start(workdir, exec_start);\n\n // Determine if we're using cloud with service token (fetch on startup)\n let use_cloud = is_cloud_source(config.env_source.as_deref());\n let has_service_token = config.service_token.is_some();\n\n let env_file_line = if use_cloud || config.env_file.is_some() {\n format!(\"EnvironmentFile={}/.env\", workdir)\n } else {\n String::new()\n };\n\n // Add ExecStartPre to fetch env vars if using service token\n let exec_start_pre = if use_cloud && has_service_token {\n format!(\"ExecStartPre={}/fetch-env.sh\", workdir)\n } else {\n String::new()\n };\n\n let service = format!(\n r#\"[Unit]\nDescription={name}\nAfter=network.target\n\n[Service]\nType=simple\nWorkingDirectory={workdir}\n{exec_start_pre}\nExecStart={exec_start}\nRestart=always\nRestartSec=5\n{env_file_line}\n\n[Install]\nWantedBy=multi-user.target\n\"#\n );\n\n let escaped = service.replace('\\\"', \"\\\\\\\"\").replace('$', \"\\\\$\");\n let cmd = format!(\n \"echo \\\"{}\\\" > /etc/systemd/system/{}.service && systemctl daemon-reload && systemctl enable {}\",\n escaped, name, name\n );\n\n ssh_run(conn, &cmd)?;\n Ok(())\n}\n\nfn normalize_exec_start(workdir: &str, exec_start: &str) -> String {\n let trimmed = exec_start.trim();\n if trimmed.is_empty() {\n return String::new();\n }\n\n let mut parts = shell_words::split(trimmed)\n .unwrap_or_else(|_| trimmed.split_whitespace().map(|s| s.to_string()).collect());\n if parts.is_empty() {\n return trimmed.to_string();\n }\n\n let cmd = parts[0].as_str();\n if cmd.starts_with('/') {\n return trimmed.to_string();\n }\n\n if cmd.starts_with(\"./\") || cmd.starts_with(\"../\") || cmd.contains('/') {\n let abs = Path::new(workdir).join(cmd).to_string_lossy().to_string();\n parts[0] = abs;\n return shell_words::join(parts);\n }\n\n let mut env_parts = Vec::with_capacity(parts.len() + 1);\n env_parts.push(\"/usr/bin/env\".to_string());\n env_parts.extend(parts);\n shell_words::join(env_parts)\n}\n\n/// Set up nginx reverse proxy.\nfn setup_nginx(conn: &HostConnection, domain: &str, port: u16, ssl: bool) -> Result<()> {\n let config = format!(\n r#\"server {{\n listen 80;\n server_name {domain};\n\n location / {{\n proxy_pass http://127.0.0.1:{port};\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection 'upgrade';\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n proxy_cache_bypass $http_upgrade;\n }}\n}}\n\"#\n );\n\n let escaped = config.replace('\\\"', \"\\\\\\\"\").replace('$', \"\\\\$\");\n let cmd = format!(\n \"echo \\\"{}\\\" > /etc/nginx/sites-available/{} && \\\n ln -sf /etc/nginx/sites-available/{} /etc/nginx/sites-enabled/ && \\\n nginx -t && systemctl reload nginx\",\n escaped, domain, domain\n );\n\n ssh_run(conn, &cmd)?;\n\n // Set up SSL if requested\n if ssl {\n println!(\"==> Setting up SSL certificate...\");\n let ssl_cmd = format!(\n \"certbot --nginx -d {} --non-interactive --agree-tos -m admin@{} || true\",\n domain, domain\n );\n ssh_run(conn, &ssl_cmd)?;\n }\n\n Ok(())\n}\n\n/// Set Cloudflare Worker secrets from env file.\nfn set_wrangler_secrets(\n worker_path: &Path,\n env_file: &Path,\n env_name: Option<&str>,\n selected_keys: Option<&[String]>,\n) -> Result<()> {\n let content = fs::read_to_string(env_file)?;\n let vars = parse_env_file(&content);\n let allowlist = selected_keys.map(|keys| keys.iter().cloned().collect::<HashSet<String>>());\n\n for (key, value) in vars {\n if let Some(allowlist) = &allowlist {\n if !allowlist.contains(&key) {\n continue;\n }\n }\n println!(\" Setting {}...\", key);\n set_wrangler_secret_value(worker_path, env_name, &key, &value)?;\n }\n Ok(())\n}\n\nfn append_env_arg(cmd: &str, env_name: Option<&str>) -> String {\n if let Some(env) = env_name {\n if cmd.contains(\"--env\") {\n cmd.to_string()\n } else {\n format!(\"{cmd} --env {env}\")\n }\n } else {\n cmd.to_string()\n }\n}\n\nfn update_flow_toml_cloudflare(\n flow_path: &Path,\n project_root: &Path,\n setup: &CloudflareSetupResult,\n) -> Result<()> {\n let contents = fs::read_to_string(flow_path)?;\n let mut lines: Vec<String> = contents.lines().map(|line| line.to_string()).collect();\n let had_trailing_newline = contents.ends_with('\\n');\n\n let worker_path = relative_dir(project_root, &setup.worker_path);\n let env_file = setup\n .env_file\n .as_ref()\n .map(|path| relative_path(project_root, path));\n let environment = setup.environment.clone();\n\n if let Some(start) = lines.iter().position(|line| line.trim() == \"[cloudflare]\") {\n let end = find_section_end(&lines, start + 1);\n let mut section_lines = Vec::new();\n for line in &lines[start + 1..end] {\n if !is_cloudflare_key_line(line) {\n section_lines.push(line.clone());\n }\n }\n\n let mut updates = Vec::new();\n if let Some(path) = worker_path {\n updates.push(format!(\"path = \\\"{}\\\"\", path));\n }\n if let Some(env_file) = env_file {\n updates.push(format!(\"env_file = \\\"{}\\\"\", env_file));\n }\n if let Some(environment) = environment {\n updates.push(format!(\"environment = \\\"{}\\\"\", environment));\n }\n\n if !updates.is_empty() {\n let needs_blank = section_lines\n .last()\n .map(|line| !line.trim().is_empty())\n .unwrap_or(false);\n if needs_blank {\n section_lines.push(String::new());\n }\n section_lines.extend(updates);\n }\n\n let mut updated = Vec::new();\n updated.extend_from_slice(&lines[..start + 1]);\n updated.extend(section_lines);\n updated.extend_from_slice(&lines[end..]);\n lines = updated;\n } else {\n if !lines.is_empty()\n && !lines\n .last()\n .map(|line| line.trim().is_empty())\n .unwrap_or(false)\n {\n lines.push(String::new());\n }\n lines.push(\"[cloudflare]\".to_string());\n if let Some(path) = worker_path {\n lines.push(format!(\"path = \\\"{}\\\"\", path));\n }\n if let Some(env_file) = env_file {\n lines.push(format!(\"env_file = \\\"{}\\\"\", env_file));\n }\n if let Some(environment) = environment {\n lines.push(format!(\"environment = \\\"{}\\\"\", environment));\n }\n }\n\n let mut updated = lines.join(\"\\n\");\n if had_trailing_newline {\n updated.push('\\n');\n }\n fs::write(flow_path, updated)?;\n Ok(())\n}\n\nfn find_section_end(lines: &[String], start: usize) -> usize {\n for (idx, line) in lines.iter().enumerate().skip(start) {\n let trimmed = line.trim();\n if trimmed.starts_with('[') && trimmed.ends_with(']') {\n return idx;\n }\n }\n lines.len()\n}\n\nfn is_cloudflare_key_line(line: &str) -> bool {\n let trimmed = line.trim();\n if trimmed.starts_with('#') || trimmed.starts_with(';') {\n return false;\n }\n let Some((key, _)) = trimmed.split_once('=') else {\n return false;\n };\n matches!(key.trim(), \"path\" | \"env_file\" | \"environment\" | \"env\")\n}\n\nfn relative_path(project_root: &Path, path: &Path) -> String {\n path.strip_prefix(project_root)\n .unwrap_or(path)\n .to_string_lossy()\n .to_string()\n}\n\nfn ensure_web_config(flow_path: &Path, project_root: &Path, cfg: &Config) -> Result<bool> {\n let existing_path = cfg.web.as_ref().and_then(|web| web.path.clone());\n if existing_path.is_some() {\n return Ok(false);\n }\n\n let web_path = match detect_web_path(project_root)? {\n Some(path) => path,\n None => {\n if !std::io::stdin().is_terminal() {\n bail!(\n \"No [web] section found and unable to infer web path. Add [web] path = \\\"...\\\".\"\n );\n }\n let input = prompt_line(\"Web path (relative to repo root)\", None)?;\n if input.trim().is_empty() {\n bail!(\"Web path required. Add [web] path = \\\"...\\\" in flow.toml.\");\n }\n input\n }\n };\n\n ensure_web_path(flow_path, &web_path)\n}\n\nfn ensure_web_domain_or_route(flow_path: &Path, web_cfg: &WebConfig) -> Result<bool> {\n if web_cfg.domain.is_some() || web_cfg.route.is_some() {\n return Ok(false);\n }\n if !std::io::stdin().is_terminal() {\n bail!(\"web.domain or web.route is required in flow.toml.\");\n }\n\n println!(\"Web routing setup\");\n println!(\"-----------------\");\n let domain = prompt_line(\"Domain (e.g., example.com)\", None)?;\n if !domain.trim().is_empty() {\n return ensure_web_key(flow_path, \"domain\", &domain);\n }\n\n let route = prompt_line(\"Route (e.g., example.com/*)\", None)?;\n if route.trim().is_empty() {\n bail!(\"web.domain or web.route is required to deploy web.\");\n }\n ensure_web_key(flow_path, \"route\", &route)\n}\n\nfn ensure_web_env_source(flow_path: &Path, web_cfg: &WebConfig) -> Result<bool> {\n if web_cfg.env_source.is_some() {\n return Ok(false);\n }\n if !std::io::stdin().is_terminal() {\n return Ok(false);\n }\n\n if prompt_yes_no(\"Use cloud for web env vars?\", true)? {\n let mut changed = false;\n if ensure_web_key(flow_path, \"env_source\", \"cloud\")? {\n changed = true;\n }\n if ensure_web_key(flow_path, \"env_apply\", \"always\")? {\n changed = true;\n }\n return Ok(changed);\n }\n\n if prompt_yes_no(\"Use local env store instead?\", true)? {\n let mut changed = false;\n if ensure_web_key(flow_path, \"env_source\", \"local\")? {\n changed = true;\n }\n if ensure_web_key(flow_path, \"env_apply\", \"always\")? {\n changed = true;\n }\n return Ok(changed);\n }\n\n Ok(false)\n}\n\nfn detect_web_path(project_root: &Path) -> Result<Option<String>> {\n let packages_web = project_root.join(\"packages\").join(\"web\");\n if packages_web.join(\"wrangler.jsonc\").exists()\n || packages_web.join(\"wrangler.json\").exists()\n || packages_web.join(\"wrangler.toml\").exists()\n {\n return Ok(Some(\"packages/web\".to_string()));\n }\n\n if project_root.join(\"wrangler.jsonc\").exists()\n || project_root.join(\"wrangler.json\").exists()\n || project_root.join(\"wrangler.toml\").exists()\n {\n return Ok(Some(\".\".to_string()));\n }\n\n let configs = discover_wrangler_configs(project_root)?;\n if configs.len() == 1 {\n let rel = relative_path(project_root, &configs[0]);\n if rel.is_empty() {\n return Ok(Some(\".\".to_string()));\n }\n return Ok(Some(rel));\n }\n\n Ok(None)\n}\n\nfn ensure_web_path(flow_path: &Path, web_path: &str) -> Result<bool> {\n ensure_web_key(flow_path, \"path\", web_path)\n}\n\nfn ensure_web_key(flow_path: &Path, key: &str, value: &str) -> Result<bool> {\n let contents = fs::read_to_string(flow_path)?;\n let mut lines: Vec<String> = contents.lines().map(|line| line.to_string()).collect();\n let had_trailing_newline = contents.ends_with('\\n');\n\n let mut changed = false;\n if let Some(start) = lines.iter().position(|line| line.trim() == \"[web]\") {\n let end = find_section_end(&lines, start + 1);\n let mut section_lines = lines[start + 1..end].to_vec();\n if !section_has_key(§ion_lines, key) {\n section_lines.push(format!(\"{key} = \\\"{}\\\"\", value.trim()));\n changed = true;\n }\n\n let mut updated = Vec::new();\n updated.extend_from_slice(&lines[..start + 1]);\n updated.extend(section_lines);\n updated.extend_from_slice(&lines[end..]);\n lines = updated;\n } else {\n if !lines.is_empty()\n && !lines\n .last()\n .map(|line| line.trim().is_empty())\n .unwrap_or(false)\n {\n lines.push(String::new());\n }\n lines.push(\"[web]\".to_string());\n lines.push(format!(\"{key} = \\\"{}\\\"\", value.trim()));\n changed = true;\n }\n\n if changed {\n let mut updated = lines.join(\"\\n\");\n if had_trailing_newline {\n updated.push('\\n');\n }\n fs::write(flow_path, updated)?;\n }\n\n Ok(changed)\n}\n\nfn section_has_key(lines: &[String], key: &str) -> bool {\n let key_prefix = format!(\"{key} \");\n let key_eq = format!(\"{key}=\");\n lines.iter().any(|line| {\n let trimmed = line.trim();\n trimmed.starts_with(&key_prefix) || trimmed.starts_with(&key_eq)\n })\n}\n\nfn ensure_web_routes(project_root: &Path, web_cfg: &WebConfig) -> Result<bool> {\n let Some(route) = resolve_web_route(web_cfg) else {\n eprintln!(\"WARN web route not set. Add web.route or web.domain in flow.toml.\");\n return Ok(false);\n };\n\n let web_path = web_cfg.path.as_deref().unwrap_or(\".\");\n let web_root = project_root.join(web_path);\n ensure_wrangler_config(&web_root)?;\n\n let Some(config_path) = find_wrangler_route_file(&web_root) else {\n eprintln!(\n \"WARN No wrangler.json/jsonc found in {}; add route manually.\",\n web_root.display()\n );\n return Ok(false);\n };\n\n ensure_wrangler_routes_jsonc(&config_path, &route)\n}\n\nfn ensure_web_dns(web_cfg: &WebConfig) -> Result<()> {\n let Some(domain) = resolve_web_domain(web_cfg) else {\n return Ok(());\n };\n if !std::io::stdin().is_terminal() {\n return Ok(());\n }\n\n println!(\"DNS setup\");\n println!(\"---------\");\n println!(\"Domain: {}\", domain);\n if !prompt_yes_no(\"Manage DNS record in Cloudflare?\", true)? {\n return Ok(());\n }\n\n let token = std::env::var(\"CLOUDFLARE_API_TOKEN\")\n .context(\"Cloudflare API token missing. Run `f env new` -> Cloudflare token.\")?;\n let client = cloudflare_api_client()?;\n let lookup_domain = domain.trim_start_matches(\"*.\");\n let Some((zone_id, zone_name)) = find_cloudflare_zone(&client, &token, lookup_domain)? else {\n eprintln!(\"WARN No Cloudflare zone found for {}.\", lookup_domain);\n return Ok(());\n };\n\n let record_type = prompt_line(\"DNS record type (A or CNAME)\", Some(\"A\"))?;\n let record_type = record_type.trim().to_ascii_uppercase();\n if record_type.is_empty() {\n bail!(\"DNS record type required.\");\n }\n\n let default_target = if record_type == \"CNAME\" {\n zone_name.clone()\n } else {\n \"192.0.2.1\".to_string()\n };\n let target = prompt_line(\"DNS record target\", Some(&default_target))?;\n let target = target.trim();\n if target.is_empty() {\n bail!(\"DNS record target required.\");\n }\n let proxied = prompt_yes_no(\"Proxy through Cloudflare?\", true)?;\n\n upsert_cloudflare_dns_record(\n &client,\n &token,\n &zone_id,\n &domain,\n &record_type,\n target,\n proxied,\n )?;\n println!(\"OK DNS record configured for {}\", domain);\n Ok(())\n}\n\nfn resolve_web_route(web_cfg: &WebConfig) -> Option<String> {\n if let Some(route) = web_cfg.route.as_ref() {\n return Some(route.clone());\n }\n web_cfg\n .domain\n .as_ref()\n .map(|domain| format!(\"{}/*\", domain.trim()))\n}\n\nfn resolve_web_domain(web_cfg: &WebConfig) -> Option<String> {\n if let Some(domain) = web_cfg.domain.as_ref() {\n let trimmed = domain.trim();\n if trimmed.is_empty() {\n return None;\n }\n return Some(trimmed.to_string());\n }\n let route = web_cfg.route.as_ref()?.trim();\n if route.is_empty() {\n return None;\n }\n let route = route\n .trim_start_matches(\"https://\")\n .trim_start_matches(\"http://\");\n let host = route.split('/').next().unwrap_or(route).trim();\n if host.is_empty() || host == \"*\" {\n return None;\n }\n let host = host.trim_end_matches(\"/*\").trim_end_matches('/');\n if host.is_empty() {\n return None;\n }\n Some(host.to_string())\n}\n\nfn resolve_prod_route(prod_cfg: &ProdConfig) -> Option<String> {\n if let Some(route) = prod_cfg.route.as_ref() {\n let route = route.trim();\n if !route.is_empty() {\n return Some(route.to_string());\n }\n }\n let domain = prod_cfg.domain.as_ref()?.trim();\n if domain.is_empty() {\n return None;\n }\n let domain = domain\n .trim_start_matches(\"https://\")\n .trim_start_matches(\"http://\")\n .trim_end_matches('/');\n if domain.is_empty() || domain == \"*\" {\n return None;\n }\n Some(format!(\"{}/*\", domain))\n}\n\nfn ensure_prod_cloudflare_routes(project_root: &Path, config: &Config) -> Result<()> {\n let Some(prod_cfg) = config.prod.as_ref() else {\n return Ok(());\n };\n let Some(cf_cfg) = config.cloudflare.as_ref() else {\n return Ok(());\n };\n let Some(route) = resolve_prod_route(prod_cfg) else {\n return Ok(());\n };\n\n let worker_root = cf_cfg\n .path\n .as_ref()\n .map(|p| project_root.join(p))\n .unwrap_or_else(|| project_root.to_path_buf());\n\n let Some(config_path) = find_wrangler_route_file(&worker_root) else {\n eprintln!(\n \"WARN No wrangler.json/jsonc found in {}; add route '{}' manually.\",\n worker_root.display(),\n route\n );\n return Ok(());\n };\n\n if ensure_wrangler_routes_jsonc(&config_path, &route)? {\n println!(\"Added prod route '{}' to {}\", route, config_path.display());\n }\n if ensure_wrangler_bool_jsonc(&config_path, \"workers_dev\", true)? {\n println!(\"Enabled workers_dev in {}\", config_path.display());\n }\n if ensure_wrangler_bool_jsonc(&config_path, \"preview_urls\", true)? {\n println!(\"Enabled preview_urls in {}\", config_path.display());\n }\n\n Ok(())\n}\n\nfn find_wrangler_route_file(web_root: &Path) -> Option<PathBuf> {\n let jsonc = web_root.join(\"wrangler.jsonc\");\n if jsonc.exists() {\n return Some(jsonc);\n }\n let json = web_root.join(\"wrangler.json\");\n if json.exists() {\n return Some(json);\n }\n None\n}\n\nfn apply_web_env(project_root: &Path, web_cfg: &WebConfig) -> Result<()> {\n let env_apply_mode = env_apply_mode_from_str(web_cfg.env_apply.as_deref());\n if env_apply_mode == EnvApplyMode::Never {\n return Ok(());\n }\n let source = web_cfg.env_source.as_deref();\n if !is_cloud_source(source) && !is_local_source(source) {\n return Ok(());\n }\n\n if is_local_source(source) {\n unsafe {\n std::env::set_var(\"FLOW_ENV_BACKEND\", \"local\");\n }\n }\n\n let keys = collect_web_env_keys(web_cfg);\n if keys.is_empty() {\n return Ok(());\n }\n\n let env_name = web_cfg.environment.as_deref().unwrap_or(\"production\");\n let mut vars: HashMap<String, String> = HashMap::new();\n for key in &keys {\n if let Some(value) = web_cfg.env_defaults.get(key) {\n if !value.trim().is_empty() {\n vars.insert(key.clone(), value.clone());\n }\n }\n }\n\n match crate::env::fetch_project_env_vars(env_name, &keys) {\n Ok(fetched) => {\n vars.extend(fetched);\n }\n Err(err) => {\n if env_apply_mode == EnvApplyMode::Auto {\n eprintln!(\"WARN env sync skipped: {err}\");\n return Ok(());\n }\n return Err(err);\n }\n }\n\n let web_path = web_cfg.path.as_deref().unwrap_or(\".\");\n let web_root = project_root.join(web_path);\n ensure_wrangler_config(&web_root)?;\n\n let var_keys: HashSet<String> = web_cfg.env_vars.iter().cloned().collect();\n set_wrangler_env_map(&web_root, web_cfg.environment.as_deref(), &vars, &var_keys)?;\n Ok(())\n}\n\nfn collect_web_env_keys(web_cfg: &WebConfig) -> Vec<String> {\n let mut keys = Vec::new();\n let mut seen = HashSet::new();\n for key in web_cfg.env_keys.iter().chain(web_cfg.env_vars.iter()) {\n if seen.insert(key.clone()) {\n keys.push(key.clone());\n }\n }\n keys\n}\n\nfn is_local_source(source: Option<&str>) -> bool {\n matches!(\n source.map(|s| s.to_ascii_lowercase()).as_deref(),\n Some(\"local\")\n )\n}\n\nfn ensure_cloudflare_api_token() -> Result<()> {\n if std::env::var(\"CLOUDFLARE_API_TOKEN\")\n .map(|value| !value.trim().is_empty())\n .unwrap_or(false)\n {\n return Ok(());\n }\n\n let key = \"CLOUDFLARE_API_TOKEN\".to_string();\n let mut token = fetch_personal_env_value(&key)?;\n if token.is_none() && std::io::stdin().is_terminal() {\n println!(\"Cloudflare API token required for deploy.\");\n println!(\"How to get it:\");\n println!(\" - Open https://dash.cloudflare.com/profile/api-tokens\");\n println!(\" - Create a token (Template: Edit Cloudflare Workers or Custom)\");\n println!(\" - Permissions: Workers Scripts:Edit, Workers Routes:Edit, Pages:Edit\");\n println!(\" - Add Zone:Read + DNS:Edit for your domain\");\n println!(\" - Copy the token value\");\n println!();\n\n if !prompt_yes_no(\"Save token now?\", true)? {\n bail!(\"Cloudflare token required to deploy.\");\n }\n let default_store = if wants_local_env_backend() {\n \"local\"\n } else {\n \"cloud\"\n };\n let store = prompt_line(\"Store token in (cloud/local)\", Some(default_store))?;\n let store = store.trim().to_ascii_lowercase();\n let store_local = matches!(store.as_str(), \"local\" | \"l\");\n let store_cloud = matches!(store.as_str(), \"cloud\" | \"c\");\n if !store_local && !store_cloud {\n bail!(\"Store token in cloud or local.\");\n }\n\n let input = prompt_secret(\"Enter Cloudflare API token (input hidden): \")?;\n if input.trim().is_empty() {\n bail!(\"Cloudflare token required to deploy.\");\n }\n if store_local {\n with_local_env_backend(|| crate::env::set_personal_env_var(&key, input.trim()))?;\n } else {\n crate::env::set_personal_env_var(&key, input.trim())?;\n }\n token = Some(input);\n println!(\"Saved {} to env store.\", key);\n }\n\n let Some(token) = token else {\n bail!(\n \"Cloudflare API token required. Store it as personal env key {}.\",\n key\n );\n };\n\n unsafe {\n std::env::set_var(\"CLOUDFLARE_API_TOKEN\", token.trim());\n }\n\n Ok(())\n}\n\nfn wants_local_env_backend() -> bool {\n if let Some(backend) = crate::config::preferred_env_backend() {\n return backend == \"local\";\n }\n if let Ok(value) = std::env::var(\"FLOW_ENV_BACKEND\") {\n return value.trim().eq_ignore_ascii_case(\"local\");\n }\n std::env::var(\"FLOW_ENV_LOCAL\")\n .ok()\n .map(|value| value.trim() == \"1\" || value.trim().eq_ignore_ascii_case(\"true\"))\n .unwrap_or(false)\n}\n\nfn with_local_env_backend<T>(action: impl FnOnce() -> Result<T>) -> Result<T> {\n let previous = std::env::var(\"FLOW_ENV_BACKEND\").ok();\n unsafe {\n std::env::set_var(\"FLOW_ENV_BACKEND\", \"local\");\n }\n let result = action();\n unsafe {\n match previous {\n Some(value) => std::env::set_var(\"FLOW_ENV_BACKEND\", value),\n None => std::env::remove_var(\"FLOW_ENV_BACKEND\"),\n }\n }\n result\n}\n\nfn cloudflare_api_client() -> Result<Client> {\n Client::builder()\n .timeout(Duration::from_secs(20))\n .build()\n .context(\"failed to build Cloudflare API client\")\n}\n\nfn find_cloudflare_zone(\n client: &Client,\n token: &str,\n domain: &str,\n) -> Result<Option<(String, String)>> {\n for candidate in cloudflare_zone_candidates(domain) {\n let resp = client\n .get(\"https://api.cloudflare.com/client/v4/zones\")\n .bearer_auth(token)\n .query(&[(\"name\", candidate.as_str()), (\"status\", \"active\")])\n .send()\n .context(\"failed to query Cloudflare zones\")?;\n let json: Value = resp\n .json()\n .context(\"failed to parse Cloudflare zones response\")?;\n cloudflare_api_check(&json, \"listing zones\")?;\n if let Some(zone) = json[\"result\"].as_array().and_then(|arr| arr.first()) {\n if let (Some(id), Some(name)) = (zone[\"id\"].as_str(), zone[\"name\"].as_str()) {\n return Ok(Some((id.to_string(), name.to_string())));\n }\n }\n }\n Ok(None)\n}\n\nfn cloudflare_zone_candidates(domain: &str) -> Vec<String> {\n let trimmed = domain.trim().trim_end_matches('.');\n let parts: Vec<&str> = trimmed.split('.').filter(|part| !part.is_empty()).collect();\n if parts.len() < 2 {\n return vec![trimmed.to_string()];\n }\n let mut candidates = Vec::new();\n for i in 0..parts.len() - 1 {\n let candidate = parts[i..].join(\".\");\n if candidate.split('.').count() >= 2 {\n candidates.push(candidate);\n }\n }\n candidates\n}\n\nfn upsert_cloudflare_dns_record(\n client: &Client,\n token: &str,\n zone_id: &str,\n domain: &str,\n record_type: &str,\n target: &str,\n proxied: bool,\n) -> Result<()> {\n if let Some(existing) =\n fetch_cloudflare_dns_record(client, token, zone_id, domain, record_type)?\n {\n if existing.content == target && existing.proxied == proxied {\n println!(\"OK DNS record already set for {}\", domain);\n return Ok(());\n }\n let url = format!(\n \"https://api.cloudflare.com/client/v4/zones/{}/dns_records/{}\",\n zone_id, existing.id\n );\n let resp = client\n .put(&url)\n .bearer_auth(token)\n .json(&serde_json::json!({\n \"type\": record_type,\n \"name\": domain,\n \"content\": target,\n \"proxied\": proxied,\n \"ttl\": 1,\n }))\n .send()\n .context(\"failed to update Cloudflare DNS record\")?;\n let json: Value = resp.json().context(\"failed to parse DNS update response\")?;\n cloudflare_api_check(&json, \"updating DNS record\")?;\n return Ok(());\n }\n\n let url = format!(\n \"https://api.cloudflare.com/client/v4/zones/{}/dns_records\",\n zone_id\n );\n let resp = client\n .post(&url)\n .bearer_auth(token)\n .json(&serde_json::json!({\n \"type\": record_type,\n \"name\": domain,\n \"content\": target,\n \"proxied\": proxied,\n \"ttl\": 1,\n }))\n .send()\n .context(\"failed to create Cloudflare DNS record\")?;\n let json: Value = resp.json().context(\"failed to parse DNS create response\")?;\n cloudflare_api_check(&json, \"creating DNS record\")?;\n Ok(())\n}\n\nstruct CloudflareDnsRecord {\n id: String,\n content: String,\n proxied: bool,\n}\n\nfn fetch_cloudflare_dns_record(\n client: &Client,\n token: &str,\n zone_id: &str,\n domain: &str,\n record_type: &str,\n) -> Result<Option<CloudflareDnsRecord>> {\n let url = format!(\n \"https://api.cloudflare.com/client/v4/zones/{}/dns_records\",\n zone_id\n );\n let resp = client\n .get(&url)\n .bearer_auth(token)\n .query(&[(\"type\", record_type), (\"name\", domain)])\n .send()\n .context(\"failed to query Cloudflare DNS records\")?;\n let json: Value = resp.json().context(\"failed to parse DNS record response\")?;\n cloudflare_api_check(&json, \"listing DNS records\")?;\n let Some(record) = json[\"result\"].as_array().and_then(|arr| arr.first()) else {\n return Ok(None);\n };\n let id = record[\"id\"].as_str().unwrap_or_default().to_string();\n if id.is_empty() {\n return Ok(None);\n }\n let content = record[\"content\"].as_str().unwrap_or_default().to_string();\n let proxied = record[\"proxied\"].as_bool().unwrap_or(false);\n Ok(Some(CloudflareDnsRecord {\n id,\n content,\n proxied,\n }))\n}\n\nfn cloudflare_api_check(payload: &Value, action: &str) -> Result<()> {\n if payload[\"success\"].as_bool().unwrap_or(false) {\n return Ok(());\n }\n let message = payload[\"errors\"]\n .as_array()\n .and_then(|errs| errs.first())\n .and_then(|err| err.get(\"message\"))\n .and_then(|value| value.as_str())\n .unwrap_or(\"Unknown error\");\n bail!(\"Cloudflare API error while {}: {}\", action, message)\n}\n\nfn fetch_personal_env_value(key: &str) -> Result<Option<String>> {\n let keys = vec![key.to_string()];\n match crate::env::fetch_personal_env_vars(&keys) {\n Ok(vars) => Ok(vars.get(key).cloned()),\n Err(err) => {\n if is_not_logged_in_err(&err) || is_cloud_unavailable(&err) {\n return Ok(None);\n }\n Err(err)\n }\n }\n}\n\nfn is_not_logged_in_err(err: &anyhow::Error) -> bool {\n err.to_string()\n .to_ascii_lowercase()\n .contains(\"not logged in\")\n}\n\nfn is_cloud_unavailable(err: &anyhow::Error) -> bool {\n err.to_string()\n .to_ascii_lowercase()\n .contains(\"failed to connect to cloud\")\n}\n\nfn ensure_wrangler_routes_jsonc(path: &Path, route: &str) -> Result<bool> {\n let contents = fs::read_to_string(path)?;\n if contents.contains(route) {\n return Ok(false);\n }\n if contents.contains(\"\\\"routes\\\"\") {\n eprintln!(\n \"WARN {} has routes configured; add '{}' manually if needed.\",\n path.display(),\n route\n );\n return Ok(false);\n }\n\n let insert_block = format!(\"\\\"routes\\\": [\\n \\\"{}\\\"\\n]\", route);\n\n let mut lines: Vec<String> = contents.lines().map(|line| line.to_string()).collect();\n let had_trailing_newline = contents.ends_with('\\n');\n if let Some(pos) = lines.iter().rposition(|line| line.trim() == \"}\") {\n let needs_comma = lines\n .iter()\n .take(pos)\n .rfind(|line| !line.trim().is_empty())\n .map(|line| !line.trim_end().ends_with(',') && !line.trim_end().ends_with('{'))\n .unwrap_or(false);\n if needs_comma {\n if let Some(last) = lines\n .iter_mut()\n .take(pos)\n .rfind(|line| !line.trim().is_empty())\n {\n if !last.trim_end().ends_with(',') {\n last.push(',');\n }\n }\n }\n let mut block_lines: Vec<String> = insert_block\n .lines()\n .map(|line| format!(\" {line}\"))\n .collect();\n lines.splice(pos..pos, block_lines.drain(..));\n let mut updated = lines.join(\"\\n\");\n if had_trailing_newline {\n updated.push('\\n');\n }\n fs::write(path, updated)?;\n return Ok(true);\n }\n\n Ok(false)\n}\n\nfn ensure_wrangler_bool_jsonc(path: &Path, key: &str, value: bool) -> Result<bool> {\n let contents = fs::read_to_string(path)?;\n let needle = format!(\"\\\"{key}\\\"\");\n if contents.contains(&needle) {\n return Ok(false);\n }\n\n let insert_block = format!(\"\\\"{key}\\\": {}\", if value { \"true\" } else { \"false\" });\n\n let mut lines: Vec<String> = contents.lines().map(|line| line.to_string()).collect();\n let had_trailing_newline = contents.ends_with('\\n');\n if let Some(pos) = lines.iter().rposition(|line| line.trim() == \"}\") {\n let needs_comma = lines\n .iter()\n .take(pos)\n .rfind(|line| !line.trim().is_empty())\n .map(|line| !line.trim_end().ends_with(',') && !line.trim_end().ends_with('{'))\n .unwrap_or(false);\n if needs_comma {\n if let Some(last) = lines\n .iter_mut()\n .take(pos)\n .rfind(|line| !line.trim().is_empty())\n {\n if !last.trim_end().ends_with(',') {\n last.push(',');\n }\n }\n }\n let mut block_lines: Vec<String> = insert_block\n .lines()\n .map(|line| format!(\" {line}\"))\n .collect();\n lines.splice(pos..pos, block_lines.drain(..));\n let mut updated = lines.join(\"\\n\");\n if had_trailing_newline {\n updated.push('\\n');\n }\n fs::write(path, updated)?;\n return Ok(true);\n }\n\n Ok(false)\n}\n\nfn relative_dir(project_root: &Path, path: &Path) -> Option<String> {\n let rel = path.strip_prefix(project_root).unwrap_or(path);\n if rel.as_os_str().is_empty() || rel == Path::new(\".\") {\n None\n } else {\n Some(rel.to_string_lossy().to_string())\n }\n}\n\n/// Set Railway environment variables from env file.\nfn set_railway_env(env_file: &Path) -> Result<()> {\n let content = fs::read_to_string(env_file)?;\n for line in content.lines() {\n let line = line.trim();\n if line.is_empty() || line.starts_with('#') {\n continue;\n }\n if let Some((key, value)) = line.split_once('=') {\n let value = value.trim_matches('\"').trim_matches('\\'');\n Command::new(\"railway\")\n .args([\"variables\", \"set\", &format!(\"{}={}\", key, value)])\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()?;\n }\n }\n Ok(())\n}\n\n/// Check if deployment is healthy via HTTP.\nfn check_health(\n _project_root: &Path,\n config: Option<&Config>,\n custom_url: Option<String>,\n expected_status: u16,\n) -> Result<()> {\n use std::time::Instant;\n\n // Determine URL to check\n let url = if let Some(url) = custom_url {\n url\n } else if let Some(config) = config {\n // Try host domain first\n if let Some(host) = &config.host {\n if let Some(domain) = &host.domain {\n let scheme = if host.ssl { \"https\" } else { \"http\" };\n format!(\"{}://{}\", scheme, domain)\n } else {\n bail!(\"No domain configured. Use --url to specify a URL to check.\");\n }\n } else if let Some(cf) = &config.cloudflare {\n // Use configured URL if present\n if let Some(cf_url) = &cf.url {\n cf_url.clone()\n } else {\n bail!(\n \"No URL configured in [cloudflare]. Add 'url = \\\"https://...\\\"' or use --url.\"\n );\n }\n } else {\n bail!(\"No deployment config found. Use --url to specify a URL to check.\");\n }\n } else {\n bail!(\"No flow.toml found. Use --url to specify a URL to check.\");\n };\n\n println!(\"Checking health: {}\", url);\n let start = Instant::now();\n\n // Use curl for simplicity (available everywhere)\n let output = Command::new(\"curl\")\n .args([\n \"-sS\",\n \"-o\",\n \"/dev/null\",\n \"-w\",\n \"%{http_code}\",\n \"--max-time\",\n \"10\",\n &url,\n ])\n .output()\n .context(\"Failed to run curl\")?;\n\n let elapsed = start.elapsed();\n let status_str = String::from_utf8_lossy(&output.stdout);\n let actual_status: u16 = status_str.trim().parse().unwrap_or(0);\n\n if actual_status == expected_status {\n println!(\n \"✓ Healthy (HTTP {} in {:.2}s)\",\n actual_status,\n elapsed.as_secs_f64()\n );\n Ok(())\n } else if actual_status == 0 {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"✗ Unreachable: {}\", stderr.trim());\n } else {\n bail!(\n \"✗ Unhealthy: expected HTTP {}, got {} ({:.2}s)\",\n expected_status,\n actual_status,\n elapsed.as_secs_f64()\n );\n }\n}\n" }, { "path": "src/deploy_setup.rs", "content": "use std::fs;\nuse std::path::{Path, PathBuf};\n\nuse anyhow::{Context, Result};\nuse crossterm::{\n event::{self, Event as CEvent, KeyCode, KeyEvent},\n execute,\n terminal::{EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode},\n};\nuse ignore::WalkBuilder;\nuse ratatui::{\n Terminal,\n backend::CrosstermBackend,\n layout::{Constraint, Direction, Layout},\n style::{Color, Modifier, Style},\n text::{Line, Span},\n widgets::{Block, Borders, List, ListItem, Paragraph, Wrap},\n};\nuse regex::Regex;\n\nuse crate::env::parse_env_file;\n\n#[derive(Debug, Clone, Default)]\npub struct CloudflareSetupDefaults {\n pub worker_path: Option<PathBuf>,\n pub env_file: Option<PathBuf>,\n pub environment: Option<String>,\n}\n\n#[derive(Debug, Clone)]\npub struct CloudflareSetupResult {\n pub worker_path: PathBuf,\n pub env_file: Option<PathBuf>,\n pub environment: Option<String>,\n pub selected_keys: Vec<String>,\n pub apply_secrets: bool,\n}\n\npub fn run_cloudflare_setup(\n project_root: &Path,\n defaults: CloudflareSetupDefaults,\n) -> Result<Option<CloudflareSetupResult>> {\n let worker_paths = discover_wrangler_configs(project_root)?;\n if worker_paths.is_empty() {\n println!(\"No Cloudflare Worker config found (wrangler.toml/json).\");\n println!(\"Run `wrangler init` first, then try: f deploy setup\");\n return Ok(None);\n }\n\n let env_files = discover_env_files(project_root)?;\n let mut app = DeploySetupApp::new(project_root, worker_paths, env_files, defaults);\n\n enable_raw_mode().context(\"failed to enable raw mode\")?;\n let mut stdout = std::io::stdout();\n execute!(stdout, EnterAlternateScreen).context(\"failed to enter alternate screen\")?;\n let backend = CrosstermBackend::new(stdout);\n let mut terminal = Terminal::new(backend).context(\"failed to create terminal backend\")?;\n\n let app_result = run_app(&mut terminal, &mut app);\n\n disable_raw_mode().ok();\n let _ = terminal.show_cursor();\n drop(terminal);\n let mut stdout = std::io::stdout();\n execute!(stdout, LeaveAlternateScreen).ok();\n\n app_result\n}\n\n#[derive(Debug, Clone, Copy)]\nenum SetupStep {\n Worker,\n EnvFile,\n EnvTarget,\n CustomEnv,\n Keys,\n Confirm,\n}\n\nstruct EnvFileChoice {\n label: String,\n path: Option<PathBuf>,\n}\n\nstruct EnvTargetChoice {\n label: String,\n value: Option<String>,\n is_custom: bool,\n}\n\nstruct EnvKeyItem {\n key: String,\n selected: bool,\n suspect: bool,\n suspect_reason: Option<String>,\n value_len: usize,\n}\n\nstruct DeploySetupApp {\n project_root: PathBuf,\n step: SetupStep,\n worker_paths: Vec<PathBuf>,\n selected_worker: usize,\n env_files: Vec<EnvFileChoice>,\n selected_env_file: usize,\n env_targets: Vec<EnvTargetChoice>,\n selected_env_target: usize,\n custom_env: String,\n key_items: Vec<EnvKeyItem>,\n selected_key: usize,\n apply_secrets: bool,\n result: Option<CloudflareSetupResult>,\n}\n\nimpl DeploySetupApp {\n fn new(\n project_root: &Path,\n worker_paths: Vec<PathBuf>,\n env_files: Vec<PathBuf>,\n defaults: CloudflareSetupDefaults,\n ) -> Self {\n let selected_worker = pick_default_worker(&worker_paths, defaults.worker_path.as_ref());\n let env_file_choices = build_env_file_choices(project_root, &env_files);\n let selected_env_file = pick_default_env_file_for_worker(\n &env_file_choices,\n &worker_paths[selected_worker],\n defaults.env_file.as_ref(),\n );\n\n let mut app = Self {\n project_root: project_root.to_path_buf(),\n step: SetupStep::Worker,\n worker_paths,\n selected_worker,\n env_files: env_file_choices,\n selected_env_file,\n env_targets: Vec::new(),\n selected_env_target: 0,\n custom_env: String::new(),\n key_items: Vec::new(),\n selected_key: 0,\n apply_secrets: true,\n result: None,\n };\n\n app.refresh_env_targets(defaults.environment.as_deref());\n if matches!(\n app.env_targets.get(app.selected_env_target),\n Some(choice) if choice.is_custom\n ) {\n app.custom_env = defaults.environment.unwrap_or_default();\n }\n\n app\n }\n\n fn worker_path(&self) -> &Path {\n &self.worker_paths[self.selected_worker]\n }\n\n fn refresh_env_targets(&mut self, preferred: Option<&str>) {\n let envs = extract_wrangler_envs(self.worker_path());\n let mut targets = Vec::new();\n targets.push(EnvTargetChoice {\n label: \"production (default)\".to_string(),\n value: None,\n is_custom: false,\n });\n\n for env in envs {\n targets.push(EnvTargetChoice {\n label: env.clone(),\n value: Some(env),\n is_custom: false,\n });\n }\n\n if let Some(env) = preferred {\n if !targets\n .iter()\n .any(|choice| choice.value.as_deref() == Some(env))\n && env != \"production\"\n {\n targets.push(EnvTargetChoice {\n label: env.to_string(),\n value: Some(env.to_string()),\n is_custom: false,\n });\n }\n }\n\n targets.push(EnvTargetChoice {\n label: \"custom...\".to_string(),\n value: None,\n is_custom: true,\n });\n\n self.env_targets = targets;\n self.selected_env_target = pick_default_env_target(&self.env_targets, preferred);\n }\n\n fn select_env_file_for_worker(&mut self) {\n let worker_path = self.worker_path().to_path_buf();\n if let Some(idx) = pick_env_file_for_worker(&self.env_files, &worker_path) {\n self.selected_env_file = idx;\n }\n }\n\n fn refresh_keys(&mut self) {\n self.key_items.clear();\n self.selected_key = 0;\n\n if let Some(path) = self\n .env_files\n .get(self.selected_env_file)\n .and_then(|c| c.path.clone())\n {\n if let Ok(items) = build_key_items(&path) {\n self.key_items = items;\n }\n }\n }\n\n fn env_file_path(&self) -> Option<PathBuf> {\n self.env_files\n .get(self.selected_env_file)\n .and_then(|choice| choice.path.clone())\n }\n\n fn env_file_path_ref(&self) -> Option<&Path> {\n self.env_files\n .get(self.selected_env_file)\n .and_then(|choice| choice.path.as_deref())\n }\n\n fn selected_env_target(&self) -> Option<String> {\n self.env_targets\n .get(self.selected_env_target)\n .and_then(|choice| choice.value.clone())\n }\n\n fn finalize(&mut self) {\n let env_file = self.env_file_path();\n let mut selected_keys = Vec::new();\n if env_file.is_some() {\n selected_keys = self\n .key_items\n .iter()\n .filter(|item| item.selected)\n .map(|item| item.key.clone())\n .collect();\n }\n\n self.result = Some(CloudflareSetupResult {\n worker_path: self.worker_path().to_path_buf(),\n env_file,\n environment: self.selected_env_target(),\n selected_keys,\n apply_secrets: self.apply_secrets,\n });\n }\n}\n\nfn run_app<B: ratatui::backend::Backend>(\n terminal: &mut Terminal<B>,\n app: &mut DeploySetupApp,\n) -> Result<Option<CloudflareSetupResult>> {\n loop {\n terminal\n .draw(|f| draw_ui(f, app))\n .map_err(|err| anyhow::anyhow!(\"failed to draw deploy setup UI: {err}\"))?;\n\n if event::poll(std::time::Duration::from_millis(200))? {\n if let CEvent::Key(key) = event::read()? {\n if handle_key(app, key)? {\n return Ok(app.result.take());\n }\n }\n }\n }\n}\n\nfn handle_key(app: &mut DeploySetupApp, key: KeyEvent) -> Result<bool> {\n match key.code {\n KeyCode::Char('q') => return Ok(true),\n KeyCode::Esc => return Ok(step_back(app)),\n _ => {}\n }\n\n match app.step {\n SetupStep::Worker => match key.code {\n KeyCode::Up => {\n select_prev(&mut app.selected_worker, app.worker_paths.len());\n app.select_env_file_for_worker();\n }\n KeyCode::Down => {\n select_next(&mut app.selected_worker, app.worker_paths.len());\n app.select_env_file_for_worker();\n }\n KeyCode::Enter => {\n app.refresh_env_targets(None);\n app.select_env_file_for_worker();\n if app.env_files.len() <= 1 {\n app.step = SetupStep::EnvTarget;\n } else {\n app.step = SetupStep::EnvFile;\n }\n }\n _ => {}\n },\n SetupStep::EnvFile => match key.code {\n KeyCode::Up => select_prev(&mut app.selected_env_file, app.env_files.len()),\n KeyCode::Down => select_next(&mut app.selected_env_file, app.env_files.len()),\n KeyCode::Enter => {\n app.step = SetupStep::EnvTarget;\n }\n _ => {}\n },\n SetupStep::EnvTarget => match key.code {\n KeyCode::Up => select_prev(&mut app.selected_env_target, app.env_targets.len()),\n KeyCode::Down => select_next(&mut app.selected_env_target, app.env_targets.len()),\n KeyCode::Enter => {\n if app\n .env_targets\n .get(app.selected_env_target)\n .is_some_and(|choice| choice.is_custom)\n {\n app.custom_env.clear();\n app.step = SetupStep::CustomEnv;\n } else if app.env_file_path().is_some() {\n app.refresh_keys();\n if app.key_items.is_empty() {\n app.step = SetupStep::Confirm;\n } else {\n app.step = SetupStep::Keys;\n }\n } else {\n app.step = SetupStep::Confirm;\n }\n }\n _ => {}\n },\n SetupStep::CustomEnv => match key.code {\n KeyCode::Enter => {\n if !app.custom_env.trim().is_empty() {\n app.env_targets.push(EnvTargetChoice {\n label: app.custom_env.trim().to_string(),\n value: Some(app.custom_env.trim().to_string()),\n is_custom: false,\n });\n app.selected_env_target = app.env_targets.len().saturating_sub(2);\n if app.env_file_path().is_some() {\n app.refresh_keys();\n app.step = if app.key_items.is_empty() {\n SetupStep::Confirm\n } else {\n SetupStep::Keys\n };\n } else {\n app.step = SetupStep::Confirm;\n }\n }\n }\n KeyCode::Backspace => {\n app.custom_env.pop();\n }\n KeyCode::Char(ch) => {\n if !ch.is_control() {\n app.custom_env.push(ch);\n }\n }\n _ => {}\n },\n SetupStep::Keys => match key.code {\n KeyCode::Up => select_prev(&mut app.selected_key, app.key_items.len()),\n KeyCode::Down => select_next(&mut app.selected_key, app.key_items.len()),\n KeyCode::Char(' ') => {\n if let Some(item) = app.key_items.get_mut(app.selected_key) {\n item.selected = !item.selected;\n }\n }\n KeyCode::Enter => app.step = SetupStep::Confirm,\n _ => {}\n },\n SetupStep::Confirm => match key.code {\n KeyCode::Char(' ') => app.apply_secrets = !app.apply_secrets,\n KeyCode::Enter => {\n app.finalize();\n return Ok(true);\n }\n _ => {}\n },\n }\n\n Ok(false)\n}\n\nfn draw_ui(f: &mut ratatui::Frame<'_>, app: &DeploySetupApp) {\n let chunks = Layout::default()\n .direction(Direction::Vertical)\n .constraints(\n [\n Constraint::Length(3),\n Constraint::Min(1),\n Constraint::Length(3),\n ]\n .as_ref(),\n )\n .split(f.area());\n\n let title = match app.step {\n SetupStep::Worker => \"Deploy Setup: Cloudflare Workers\",\n SetupStep::EnvFile => \"Select .env file (optional)\",\n SetupStep::EnvTarget => \"Select Cloudflare environment\",\n SetupStep::CustomEnv => \"Enter custom environment\",\n SetupStep::Keys => \"Select secrets to push\",\n SetupStep::Confirm => \"Confirm setup\",\n };\n\n let header = Paragraph::new(Line::from(title))\n .block(Block::default().borders(Borders::ALL).title(\"flow\"))\n .alignment(ratatui::layout::Alignment::Center);\n f.render_widget(header, chunks[0]);\n\n match app.step {\n SetupStep::Worker => {\n let items = app\n .worker_paths\n .iter()\n .map(|path| {\n let label = relative_display(&app.project_root, path);\n ListItem::new(Line::from(label))\n })\n .collect::<Vec<_>>();\n\n let list = List::new(items)\n .block(Block::default().borders(Borders::ALL).title(\"Worker path\"))\n .highlight_style(\n Style::default()\n .fg(Color::Black)\n .bg(Color::Cyan)\n .add_modifier(Modifier::BOLD),\n );\n let mut state = ratatui::widgets::ListState::default();\n state.select(Some(app.selected_worker));\n f.render_stateful_widget(list, chunks[1], &mut state);\n }\n SetupStep::EnvFile => {\n let body = Layout::default()\n .direction(Direction::Horizontal)\n .constraints([Constraint::Percentage(55), Constraint::Percentage(45)].as_ref())\n .split(chunks[1]);\n let items = app\n .env_files\n .iter()\n .map(|choice| ListItem::new(Line::from(choice.label.clone())))\n .collect::<Vec<_>>();\n let list = List::new(items)\n .block(\n Block::default()\n .borders(Borders::ALL)\n .title(\"Secrets source\"),\n )\n .highlight_style(\n Style::default()\n .fg(Color::Black)\n .bg(Color::Cyan)\n .add_modifier(Modifier::BOLD),\n );\n let mut state = ratatui::widgets::ListState::default();\n state.select(Some(app.selected_env_file));\n f.render_stateful_widget(list, body[0], &mut state);\n\n let preview_lines = build_env_preview_lines(&app.project_root, app.env_file_path_ref());\n let preview = Paragraph::new(preview_lines)\n .block(Block::default().borders(Borders::ALL).title(\"Preview\"))\n .wrap(Wrap { trim: true });\n f.render_widget(preview, body[1]);\n }\n SetupStep::EnvTarget => {\n let items = app\n .env_targets\n .iter()\n .map(|choice| ListItem::new(Line::from(choice.label.clone())))\n .collect::<Vec<_>>();\n let list = List::new(items)\n .block(\n Block::default()\n .borders(Borders::ALL)\n .title(\"Wrangler --env\"),\n )\n .highlight_style(\n Style::default()\n .fg(Color::Black)\n .bg(Color::Cyan)\n .add_modifier(Modifier::BOLD),\n );\n let mut state = ratatui::widgets::ListState::default();\n state.select(Some(app.selected_env_target));\n f.render_stateful_widget(list, chunks[1], &mut state);\n }\n SetupStep::CustomEnv => {\n let prompt = format!(\"> {}\", app.custom_env);\n let input = Paragraph::new(prompt)\n .block(\n Block::default()\n .borders(Borders::ALL)\n .title(\"Environment name\"),\n )\n .wrap(Wrap { trim: true });\n f.render_widget(input, chunks[1]);\n }\n SetupStep::Keys => {\n let body = Layout::default()\n .direction(Direction::Horizontal)\n .constraints([Constraint::Percentage(60), Constraint::Percentage(40)].as_ref())\n .split(chunks[1]);\n let selected_count = app.key_items.iter().filter(|item| item.selected).count();\n let items = app\n .key_items\n .iter()\n .map(|item| {\n let indicator = if item.selected { \"[x]\" } else { \"[ ]\" };\n let flag = if item.suspect { \" suspect\" } else { \"\" };\n let label = format!(\"{indicator} {}{flag}\", item.key);\n ListItem::new(Line::from(label))\n })\n .collect::<Vec<_>>();\n let list = List::new(items)\n .block(Block::default().borders(Borders::ALL).title(format!(\n \"Secrets ({}/{})\",\n selected_count,\n app.key_items.len()\n )))\n .highlight_style(\n Style::default()\n .fg(Color::Black)\n .bg(Color::Cyan)\n .add_modifier(Modifier::BOLD),\n );\n let mut state = ratatui::widgets::ListState::default();\n state.select(Some(app.selected_key));\n f.render_stateful_widget(list, body[0], &mut state);\n\n let detail_lines = build_key_detail_lines(\n &app.project_root,\n app.env_file_path_ref(),\n app.key_items.get(app.selected_key),\n );\n let details = Paragraph::new(detail_lines)\n .block(Block::default().borders(Borders::ALL).title(\"Details\"))\n .wrap(Wrap { trim: true });\n f.render_widget(details, body[1]);\n }\n SetupStep::Confirm => {\n let worker = relative_display(&app.project_root, app.worker_path());\n let env_file = app\n .env_file_path()\n .map(|p| relative_display(&app.project_root, &p))\n .unwrap_or_else(|| \"none\".to_string());\n let env_target = app\n .selected_env_target()\n .unwrap_or_else(|| \"production (default)\".to_string());\n let selected_count = app.key_items.iter().filter(|item| item.selected).count();\n let apply = if app.apply_secrets { \"yes\" } else { \"no\" };\n let summary = vec![\n Line::from(vec![\n Span::styled(\"Worker: \", Style::default().add_modifier(Modifier::BOLD)),\n Span::raw(worker),\n ]),\n Line::from(vec![\n Span::styled(\"Env file: \", Style::default().add_modifier(Modifier::BOLD)),\n Span::raw(env_file),\n ]),\n Line::from(vec![\n Span::styled(\n \"Environment: \",\n Style::default().add_modifier(Modifier::BOLD),\n ),\n Span::raw(env_target),\n ]),\n Line::from(vec![\n Span::styled(\n \"Secrets selected: \",\n Style::default().add_modifier(Modifier::BOLD),\n ),\n Span::raw(format!(\"{}\", selected_count)),\n ]),\n Line::from(vec![\n Span::styled(\n \"Apply secrets now: \",\n Style::default().add_modifier(Modifier::BOLD),\n ),\n Span::raw(apply),\n ]),\n ];\n\n let paragraph = Paragraph::new(summary)\n .block(Block::default().borders(Borders::ALL).title(\"Review\"))\n .wrap(Wrap { trim: true });\n f.render_widget(paragraph, chunks[1]);\n }\n }\n\n let help = match app.step {\n SetupStep::Worker => \"Up/Down to move, Enter to select, Esc to cancel, q to cancel\",\n SetupStep::EnvFile => \"Up/Down to move, Enter to select, Esc to back, q to cancel\",\n SetupStep::EnvTarget => \"Up/Down to move, Enter to select, Esc to back, q to cancel\",\n SetupStep::CustomEnv => \"Type name, Enter to confirm, Esc to back, q to cancel\",\n SetupStep::Keys => {\n \"Up/Down to move, Space to toggle, Enter to continue, Esc to back, q to cancel\"\n }\n SetupStep::Confirm => \"Space to toggle apply, Enter to finish, Esc to back, q to cancel\",\n };\n let footer = Paragraph::new(help)\n .block(Block::default().borders(Borders::ALL))\n .alignment(ratatui::layout::Alignment::Center);\n f.render_widget(footer, chunks[2]);\n}\n\nfn build_env_preview_lines(project_root: &Path, env_file: Option<&Path>) -> Vec<Line<'static>> {\n let mut lines = Vec::new();\n let Some(path) = env_file else {\n lines.push(Line::from(\"No env file selected.\"));\n lines.push(Line::from(\"Secrets will not be set.\"));\n return lines;\n };\n\n lines.push(Line::from(vec![\n Span::styled(\"File: \", Style::default().add_modifier(Modifier::BOLD)),\n Span::raw(relative_display(project_root, path)),\n ]));\n lines.push(Line::from(\"Values are hidden.\"));\n\n let content = match fs::read_to_string(path) {\n Ok(content) => content,\n Err(_) => {\n lines.push(Line::from(\"Unable to read file.\"));\n return lines;\n }\n };\n\n let vars = parse_env_file(&content);\n if vars.is_empty() {\n lines.push(Line::from(\"No env vars found.\"));\n return lines;\n }\n\n let mut entries: Vec<_> = vars.into_iter().collect();\n entries.sort_by(|a, b| a.0.cmp(&b.0));\n\n let suspect_count = entries\n .iter()\n .filter(|(_, value)| suspect_reason(value).is_some())\n .count();\n let total = entries.len();\n\n lines.push(Line::from(format!(\n \"Keys: {} (suspect: {})\",\n total, suspect_count\n )));\n lines.push(Line::from(\"! = likely test/local value\"));\n\n let max_keys = 12usize;\n for (key, value) in entries.iter().take(max_keys) {\n let flag = if suspect_reason(value).is_some() {\n \" !\"\n } else {\n \"\"\n };\n lines.push(Line::from(format!(\" - {}{}\", key, flag)));\n }\n\n if total > max_keys {\n lines.push(Line::from(format!(\"... +{} more\", total - max_keys)));\n }\n\n lines\n}\n\nfn build_key_detail_lines(\n project_root: &Path,\n env_file: Option<&Path>,\n item: Option<&EnvKeyItem>,\n) -> Vec<Line<'static>> {\n let mut lines = Vec::new();\n let env_label = env_file\n .map(|path| relative_display(project_root, path))\n .unwrap_or_else(|| \"none\".to_string());\n lines.push(Line::from(format!(\"Env file: {}\", env_label)));\n\n let Some(item) = item else {\n lines.push(Line::from(\"No key selected.\"));\n return lines;\n };\n\n lines.push(Line::from(format!(\"Key: {}\", item.key)));\n lines.push(Line::from(format!(\n \"Selected: {}\",\n if item.selected { \"yes\" } else { \"no\" }\n )));\n lines.push(Line::from(format!(\n \"Status: {}\",\n if item.suspect { \"suspect\" } else { \"ok\" }\n )));\n if let Some(reason) = &item.suspect_reason {\n lines.push(Line::from(format!(\"Reason: {}\", reason)));\n }\n lines.push(Line::from(format!(\"Value length: {}\", item.value_len)));\n lines.push(Line::from(\"Values are hidden.\"));\n if item.suspect {\n lines.push(Line::from(\"Tip: suspect values default to unchecked.\"));\n }\n\n lines\n}\n\nfn select_prev(selected: &mut usize, len: usize) {\n if len == 0 {\n return;\n }\n if *selected == 0 {\n *selected = len.saturating_sub(1);\n } else {\n *selected -= 1;\n }\n}\n\nfn select_next(selected: &mut usize, len: usize) {\n if len == 0 {\n return;\n }\n if *selected + 1 >= len {\n *selected = 0;\n } else {\n *selected += 1;\n }\n}\n\nfn step_back(app: &mut DeploySetupApp) -> bool {\n match app.step {\n SetupStep::Worker => true,\n SetupStep::EnvFile => {\n app.step = SetupStep::Worker;\n false\n }\n SetupStep::EnvTarget => {\n if app.env_files.len() <= 1 {\n app.step = SetupStep::Worker;\n } else {\n app.step = SetupStep::EnvFile;\n }\n false\n }\n SetupStep::CustomEnv => {\n app.step = SetupStep::EnvTarget;\n false\n }\n SetupStep::Keys => {\n app.step = SetupStep::EnvTarget;\n false\n }\n SetupStep::Confirm => {\n if app.env_file_path().is_some() && !app.key_items.is_empty() {\n app.step = SetupStep::Keys;\n } else {\n app.step = SetupStep::EnvTarget;\n }\n false\n }\n }\n}\n\nfn relative_display(root: &Path, path: &Path) -> String {\n if let Ok(rel) = path.strip_prefix(root) {\n let rel = rel.to_string_lossy().to_string();\n if rel.is_empty() { \".\".to_string() } else { rel }\n } else {\n path.to_string_lossy().to_string()\n }\n}\n\nfn pick_default_worker(paths: &[PathBuf], preferred: Option<&PathBuf>) -> usize {\n if let Some(path) = preferred {\n if let Some((idx, _)) = paths.iter().enumerate().find(|(_, p)| *p == path) {\n return idx;\n }\n }\n 0\n}\n\nfn build_env_file_choices(project_root: &Path, env_files: &[PathBuf]) -> Vec<EnvFileChoice> {\n let mut choices = Vec::new();\n choices.push(EnvFileChoice {\n label: \"Skip (do not set secrets)\".to_string(),\n path: None,\n });\n\n for path in env_files {\n choices.push(EnvFileChoice {\n label: relative_display(project_root, path),\n path: Some(path.clone()),\n });\n }\n\n choices\n}\n\nfn pick_default_env_file_for_worker(\n choices: &[EnvFileChoice],\n worker_path: &Path,\n preferred: Option<&PathBuf>,\n) -> usize {\n if let Some(path) = preferred {\n if let Some((idx, _)) = choices\n .iter()\n .enumerate()\n .find(|(_, c)| c.path.as_ref() == Some(path))\n {\n return idx;\n }\n }\n\n if let Some(idx) = pick_env_file_for_worker(choices, worker_path) {\n return idx;\n }\n\n 0\n}\n\nfn pick_env_file_for_worker(choices: &[EnvFileChoice], worker_path: &Path) -> Option<usize> {\n let candidates = [\n \".env\",\n \".env.cloudflare\",\n \".env.production\",\n \".env.staging\",\n \".env.local\",\n ];\n\n for candidate in candidates {\n let candidate_path = worker_path.join(candidate);\n if let Some((idx, _)) = choices\n .iter()\n .enumerate()\n .find(|(_, c)| c.path.as_ref() == Some(&candidate_path))\n {\n return Some(idx);\n }\n }\n\n None\n}\n\nfn pick_default_env_target(targets: &[EnvTargetChoice], preferred: Option<&str>) -> usize {\n if let Some(env) = preferred {\n if let Some((idx, _)) = targets\n .iter()\n .enumerate()\n .find(|(_, choice)| choice.value.as_deref() == Some(env))\n {\n return idx;\n }\n }\n 0\n}\n\nfn build_key_items(path: &Path) -> Result<Vec<EnvKeyItem>> {\n let content = fs::read_to_string(path)\n .with_context(|| format!(\"failed to read env file {}\", path.display()))?;\n let env = parse_env_file(&content);\n let mut keys: Vec<_> = env.into_iter().collect();\n keys.sort_by(|a, b| a.0.cmp(&b.0));\n\n Ok(keys\n .into_iter()\n .map(|(key, value)| {\n let reason = suspect_reason(&value);\n let suspect = reason.is_some();\n EnvKeyItem {\n key,\n selected: !suspect,\n suspect: suspect || value.trim().is_empty(),\n suspect_reason: reason.map(|reason| reason.to_string()),\n value_len: value.len(),\n }\n })\n .collect())\n}\n\nfn suspect_reason(value: &str) -> Option<&'static str> {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n return Some(\"empty\");\n }\n\n let lowered = trimmed.to_lowercase();\n if lowered.contains(\"sk_test\") || lowered.contains(\"pk_test\") {\n return Some(\"stripe_test\");\n }\n if lowered.contains(\"localhost\") || lowered.contains(\"127.0.0.1\") {\n return Some(\"localhost\");\n }\n if lowered.contains(\"example.com\") || lowered.contains(\"example\") {\n return Some(\"example\");\n }\n if lowered.contains(\"dummy\") {\n return Some(\"dummy\");\n }\n if lowered.contains(\"test\") {\n return Some(\"test\");\n }\n\n None\n}\n\npub(crate) fn discover_wrangler_configs(root: &Path) -> Result<Vec<PathBuf>> {\n let walker = WalkBuilder::new(root)\n .hidden(true)\n .git_ignore(true)\n .git_global(true)\n .git_exclude(true)\n .max_depth(Some(10))\n .filter_entry(|entry| {\n if entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {\n let name = entry.file_name().to_string_lossy();\n !matches!(\n name.as_ref(),\n \"node_modules\"\n | \"target\"\n | \"dist\"\n | \"build\"\n | \".git\"\n | \".hg\"\n | \".svn\"\n | \"__pycache__\"\n | \".pytest_cache\"\n | \".mypy_cache\"\n | \"venv\"\n | \".venv\"\n | \"vendor\"\n | \"Pods\"\n | \".cargo\"\n | \".rustup\"\n )\n } else {\n true\n }\n })\n .build();\n\n let mut paths = Vec::new();\n for entry in walker.flatten() {\n if entry.file_type().map(|ft| ft.is_file()).unwrap_or(false) {\n if let Some(name) = entry.path().file_name().and_then(|s| s.to_str()) {\n if matches!(name, \"wrangler.toml\" | \"wrangler.json\" | \"wrangler.jsonc\") {\n if let Some(parent) = entry.path().parent() {\n paths.push(parent.to_path_buf());\n }\n }\n }\n }\n }\n\n paths.sort();\n paths.dedup();\n Ok(paths)\n}\n\nfn discover_env_files(root: &Path) -> Result<Vec<PathBuf>> {\n let walker = WalkBuilder::new(root)\n .hidden(false)\n .git_ignore(false)\n .git_global(false)\n .git_exclude(false)\n .max_depth(Some(10))\n .filter_entry(|entry| {\n if entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {\n let name = entry.file_name().to_string_lossy();\n !matches!(\n name.as_ref(),\n \"node_modules\"\n | \"target\"\n | \"dist\"\n | \"build\"\n | \".git\"\n | \".hg\"\n | \".svn\"\n | \"__pycache__\"\n | \".pytest_cache\"\n | \".mypy_cache\"\n | \"venv\"\n | \".venv\"\n | \"vendor\"\n | \"Pods\"\n | \".cargo\"\n | \".rustup\"\n )\n } else {\n true\n }\n })\n .build();\n\n let mut env_files = Vec::new();\n for entry in walker.flatten() {\n if entry.file_type().map(|ft| ft.is_file()).unwrap_or(false) {\n if let Some(name) = entry.path().file_name().and_then(|s| s.to_str()) {\n if name.starts_with(\".env\") && name != \".envrc\" {\n env_files.push(entry.path().to_path_buf());\n }\n }\n }\n }\n\n env_files.sort();\n env_files.dedup();\n Ok(env_files)\n}\n\nfn extract_wrangler_envs(worker_path: &Path) -> Vec<String> {\n let toml_path = worker_path.join(\"wrangler.toml\");\n if toml_path.exists() {\n if let Ok(content) = fs::read_to_string(&toml_path) {\n let re = Regex::new(r\"^\\s*\\[env\\.([^\\]]+)\\]\\s*$\").unwrap();\n let mut envs = Vec::new();\n for line in content.lines() {\n if let Some(caps) = re.captures(line) {\n let env = caps.get(1).map(|m| m.as_str().trim().to_string());\n if let Some(env) = env {\n if !env.is_empty() {\n envs.push(env);\n }\n }\n }\n }\n envs.sort();\n envs.dedup();\n return envs;\n }\n }\n\n Vec::new()\n}\n" }, { "path": "src/deps.rs", "content": "use std::collections::{BTreeMap, BTreeSet};\nuse std::io::{self, IsTerminal, Read, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\nuse ignore::WalkBuilder;\nuse serde::Deserialize;\nuse toml::Value;\nuse toml::map::Map;\n\nuse crate::cli::{\n DepsAction, DepsCommand, DepsEcosystem, DepsManager, ReposCloneOpts, UpdateDepsOpts,\n};\nuse crate::{config, opentui_prompt, repos, upstream};\n\npub fn run(cmd: DepsCommand) -> Result<()> {\n let action = cmd.action;\n let manager_override = cmd.manager;\n let project_root = project_root()?;\n\n match action {\n None | Some(DepsAction::Pick) => {\n pick_dependency(&project_root)?;\n }\n Some(DepsAction::Update(mut opts)) => {\n if opts.manager.is_none() {\n opts.manager = manager_override;\n }\n run_update_with_context(opts)?;\n }\n Some(DepsAction::Repo {\n repo,\n root,\n private,\n }) => {\n link_repo_dependency(&project_root, &repo, &root, private)?;\n }\n Some(other @ DepsAction::Install { .. }) => {\n let manager = manager_override.unwrap_or_else(|| detect_manager(&project_root));\n let (program, args) = build_command(manager, &project_root, &other)?;\n let status = Command::new(program)\n .args(&args)\n .current_dir(&project_root)\n .status()\n .with_context(|| format!(\"failed to run {}\", program))?;\n\n if !status.success() {\n bail!(\"dependency command failed\");\n }\n }\n }\n\n Ok(())\n}\n\nfn run_update_with_context(opts: UpdateDepsOpts) -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to read current directory\")?;\n let search_root = update_search_root(&cwd);\n let context = UpdateDetectContext { cwd, search_root };\n let plans = build_update_plans(&context, &opts)?;\n\n if plans.is_empty() {\n bail!(\n \"no dependency manifests found from {} up to {}\",\n context.cwd.display(),\n context.search_root.display()\n );\n }\n\n print_update_summary(&plans);\n if opts.dry_run {\n return Ok(());\n }\n\n if !opts.yes && !confirm_update_plan(&opts, &plans)? {\n println!(\"dependency update canceled\");\n return Ok(());\n }\n\n run_update_plans(&plans)\n}\n\nfn build_command(\n manager: DepsManager,\n project_root: &Path,\n action: &DepsAction,\n) -> Result<(&'static str, Vec<String>)> {\n let workspace = is_workspace(project_root);\n let (base, mut args) = match (manager, workspace) {\n (DepsManager::Pnpm, true) => (\"pnpm\", vec![\"-r\".to_string()]),\n (DepsManager::Pnpm, false) => (\"pnpm\", Vec::new()),\n (DepsManager::Yarn, _) => (\"yarn\", Vec::new()),\n (DepsManager::Bun, _) => (\"bun\", Vec::new()),\n (DepsManager::Npm, _) => (\"npm\", Vec::new()),\n };\n\n match action {\n DepsAction::Install { args: extra } => {\n args.push(\"install\".to_string());\n args.extend(extra.clone());\n }\n DepsAction::Update(_) | DepsAction::Repo { .. } | DepsAction::Pick => {\n bail!(\"dependency action is not a package manager command\");\n }\n }\n\n Ok((base, args))\n}\n\nfn detect_manager(project_root: &Path) -> DepsManager {\n if let Some(pm) = detect_manager_from_package_json(project_root) {\n return pm;\n }\n if project_root.join(\"pnpm-lock.yaml\").exists()\n || project_root.join(\"pnpm-workspace.yaml\").exists()\n {\n return DepsManager::Pnpm;\n }\n if project_root.join(\"bun.lockb\").exists() || project_root.join(\"bun.lock\").exists() {\n return DepsManager::Bun;\n }\n if project_root.join(\"yarn.lock\").exists() {\n return DepsManager::Yarn;\n }\n if project_root.join(\"package-lock.json\").exists() {\n return DepsManager::Npm;\n }\n DepsManager::Npm\n}\n\nfn detect_manager_from_package_json(project_root: &Path) -> Option<DepsManager> {\n let package_json = project_root.join(\"package.json\");\n if !package_json.exists() {\n return None;\n }\n let contents = std::fs::read_to_string(package_json).ok()?;\n let json = serde_json::from_str::<serde_json::Value>(&contents).ok()?;\n let manager = json.get(\"packageManager\")?.as_str()?;\n if manager.starts_with(\"pnpm@\") {\n return Some(DepsManager::Pnpm);\n }\n if manager.starts_with(\"bun@\") {\n return Some(DepsManager::Bun);\n }\n if manager.starts_with(\"yarn@\") {\n return Some(DepsManager::Yarn);\n }\n if manager.starts_with(\"npm@\") {\n return Some(DepsManager::Npm);\n }\n None\n}\n\nfn is_workspace(project_root: &Path) -> bool {\n project_root.join(\"pnpm-workspace.yaml\").exists()\n}\n\nfn project_root() -> Result<PathBuf> {\n let cwd = std::env::current_dir().context(\"failed to read current directory\")?;\n if let Some(flow_path) = find_flow_toml(&cwd) {\n return Ok(flow_path.parent().unwrap_or(&cwd).to_path_buf());\n }\n Ok(cwd)\n}\n\nfn find_flow_toml(start: &PathBuf) -> Option<PathBuf> {\n let mut current = start.clone();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\n#[derive(Debug, Clone)]\nstruct UpdateDetectContext {\n cwd: PathBuf,\n search_root: PathBuf,\n}\n\n#[derive(Debug, Clone)]\nstruct UpdateTarget {\n root: PathBuf,\n ecosystem: DepsEcosystem,\n detail: UpdateTargetDetail,\n}\n\n#[derive(Debug, Clone)]\nenum UpdateTargetDetail {\n Js {\n manager: DepsManager,\n workspace: bool,\n },\n Rust,\n Go,\n}\n\n#[derive(Debug, Clone)]\nstruct PlannedCommand {\n program: String,\n args: Vec<String>,\n cwd: PathBuf,\n}\n\n#[derive(Debug, Clone)]\nstruct UpdatePlan {\n target: UpdateTarget,\n commands: Vec<PlannedCommand>,\n}\n\ntrait EcosystemUpdater {\n fn ecosystem(&self) -> DepsEcosystem;\n fn detect_target(\n &self,\n ctx: &UpdateDetectContext,\n opts: &UpdateDepsOpts,\n ) -> Result<Option<UpdateTarget>>;\n fn build_commands(\n &self,\n target: &UpdateTarget,\n opts: &UpdateDepsOpts,\n ) -> Result<Vec<PlannedCommand>>;\n}\n\nstruct JavaScriptUpdater;\nstruct RustUpdater;\nstruct GoUpdater;\n\nimpl EcosystemUpdater for JavaScriptUpdater {\n fn ecosystem(&self) -> DepsEcosystem {\n DepsEcosystem::Js\n }\n\n fn detect_target(\n &self,\n ctx: &UpdateDetectContext,\n opts: &UpdateDepsOpts,\n ) -> Result<Option<UpdateTarget>> {\n let nearest = nearest_ancestor_with_file(&ctx.cwd, &ctx.search_root, \"package.json\");\n let Some(nearest_pkg) = nearest else {\n return Ok(None);\n };\n let root =\n find_js_workspace_root(&nearest_pkg, &ctx.search_root).unwrap_or(nearest_pkg.clone());\n let manager = opts.manager.unwrap_or_else(|| detect_manager(&root));\n let workspace = root != nearest_pkg || is_js_workspace_root(&root);\n\n Ok(Some(UpdateTarget {\n root,\n ecosystem: DepsEcosystem::Js,\n detail: UpdateTargetDetail::Js { manager, workspace },\n }))\n }\n\n fn build_commands(\n &self,\n target: &UpdateTarget,\n opts: &UpdateDepsOpts,\n ) -> Result<Vec<PlannedCommand>> {\n let UpdateTargetDetail::Js { manager, workspace } = target.detail else {\n bail!(\"invalid js update target\");\n };\n\n let mut args = match manager {\n DepsManager::Pnpm => {\n let mut args = Vec::new();\n if workspace {\n args.push(\"-r\".to_string());\n }\n args.push(\"up\".to_string());\n if opts.latest {\n args.push(\"--latest\".to_string());\n }\n args\n }\n DepsManager::Bun => {\n let mut args = vec![\"update\".to_string()];\n if opts.latest {\n args.push(\"--latest\".to_string());\n }\n args\n }\n DepsManager::Yarn => vec![\"up\".to_string()],\n DepsManager::Npm => vec![\"update\".to_string()],\n };\n\n args.extend(opts.args.clone());\n\n Ok(vec![PlannedCommand {\n program: manager_program(manager).to_string(),\n args,\n cwd: target.root.clone(),\n }])\n }\n}\n\nimpl EcosystemUpdater for RustUpdater {\n fn ecosystem(&self) -> DepsEcosystem {\n DepsEcosystem::Rust\n }\n\n fn detect_target(\n &self,\n ctx: &UpdateDetectContext,\n _opts: &UpdateDepsOpts,\n ) -> Result<Option<UpdateTarget>> {\n let root = find_rust_update_root(&ctx.cwd, &ctx.search_root);\n let Some(root) = root else {\n return Ok(None);\n };\n Ok(Some(UpdateTarget {\n root,\n ecosystem: DepsEcosystem::Rust,\n detail: UpdateTargetDetail::Rust,\n }))\n }\n\n fn build_commands(\n &self,\n target: &UpdateTarget,\n opts: &UpdateDepsOpts,\n ) -> Result<Vec<PlannedCommand>> {\n let mut args = vec![\"update\".to_string()];\n args.extend(opts.args.clone());\n\n Ok(vec![PlannedCommand {\n program: \"cargo\".to_string(),\n args,\n cwd: target.root.clone(),\n }])\n }\n}\n\nimpl EcosystemUpdater for GoUpdater {\n fn ecosystem(&self) -> DepsEcosystem {\n DepsEcosystem::Go\n }\n\n fn detect_target(\n &self,\n ctx: &UpdateDetectContext,\n _opts: &UpdateDepsOpts,\n ) -> Result<Option<UpdateTarget>> {\n let root = nearest_ancestor_with_file(&ctx.cwd, &ctx.search_root, \"go.mod\");\n let Some(root) = root else {\n return Ok(None);\n };\n Ok(Some(UpdateTarget {\n root,\n ecosystem: DepsEcosystem::Go,\n detail: UpdateTargetDetail::Go,\n }))\n }\n\n fn build_commands(\n &self,\n target: &UpdateTarget,\n opts: &UpdateDepsOpts,\n ) -> Result<Vec<PlannedCommand>> {\n let mut get_args = vec![\"get\".to_string(), \"-u\".to_string()];\n if opts.args.is_empty() {\n get_args.push(\"./...\".to_string());\n } else {\n get_args.extend(opts.args.clone());\n }\n\n Ok(vec![\n PlannedCommand {\n program: \"go\".to_string(),\n args: get_args,\n cwd: target.root.clone(),\n },\n PlannedCommand {\n program: \"go\".to_string(),\n args: vec![\"mod\".to_string(), \"tidy\".to_string()],\n cwd: target.root.clone(),\n },\n ])\n }\n}\n\nfn build_update_plans(ctx: &UpdateDetectContext, opts: &UpdateDepsOpts) -> Result<Vec<UpdatePlan>> {\n let updaters: Vec<Box<dyn EcosystemUpdater>> = vec![\n Box::new(JavaScriptUpdater),\n Box::new(RustUpdater),\n Box::new(GoUpdater),\n ];\n\n let mut plans = Vec::new();\n for updater in updaters {\n if let Some(requested) = opts.ecosystem\n && requested != updater.ecosystem()\n {\n continue;\n }\n\n if let Some(target) = updater.detect_target(ctx, opts)? {\n let commands = updater.build_commands(&target, opts)?;\n plans.push(UpdatePlan { target, commands });\n }\n }\n\n Ok(plans)\n}\n\nfn run_update_plans(plans: &[UpdatePlan]) -> Result<()> {\n for plan in plans {\n for cmd in &plan.commands {\n println!(\n \"→ [{}] {}\",\n ecosystem_label(plan.target.ecosystem),\n display_command(cmd)\n );\n let status = Command::new(&cmd.program)\n .args(&cmd.args)\n .current_dir(&cmd.cwd)\n .status()\n .with_context(|| format!(\"failed to run {}\", cmd.program))?;\n if !status.success() {\n bail!(\"dependency update command failed: {}\", display_command(cmd));\n }\n }\n }\n Ok(())\n}\n\nfn print_update_summary(plans: &[UpdatePlan]) {\n println!(\"Detected {} dependency update target(s):\", plans.len());\n for plan in plans {\n println!(\n \" [{}] {}\",\n ecosystem_label(plan.target.ecosystem),\n plan.target.root.display()\n );\n if let UpdateTargetDetail::Js { manager, workspace } = plan.target.detail {\n println!(\n \" manager: {}{}\",\n manager_program(manager),\n if workspace { \" (workspace)\" } else { \"\" }\n );\n }\n for cmd in &plan.commands {\n println!(\" $ {}\", display_command(cmd));\n }\n }\n}\n\nfn confirm_update_plan(opts: &UpdateDepsOpts, plans: &[UpdatePlan]) -> Result<bool> {\n let mut lines = Vec::new();\n for plan in plans {\n lines.push(format!(\n \"[{}] {}\",\n ecosystem_label(plan.target.ecosystem),\n plan.target.root.display()\n ));\n for cmd in &plan.commands {\n lines.push(format!(\" $ {}\", display_command(cmd)));\n }\n }\n\n if !opts.no_tui\n && let Some(answer) = opentui_prompt::confirm(\"Update Dependencies\", &lines, true)\n {\n return Ok(answer);\n }\n\n for line in &lines {\n println!(\"{}\", line);\n }\n confirm_default_yes(\"Proceed with dependency updates? [Y/n]: \")\n}\n\nfn confirm_default_yes(prompt: &str) -> Result<bool> {\n print!(\"{}\", prompt);\n io::stdout().flush()?;\n\n if io::stdin().is_terminal() {\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n return Ok(true);\n }\n return Ok(matches!(trimmed.to_ascii_lowercase().as_str(), \"y\" | \"yes\"));\n }\n\n let mut input = String::new();\n io::stdin().read_to_string(&mut input)?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n return Ok(true);\n }\n Ok(matches!(trimmed.to_ascii_lowercase().as_str(), \"y\" | \"yes\"))\n}\n\nfn ecosystem_label(ecosystem: DepsEcosystem) -> &'static str {\n match ecosystem {\n DepsEcosystem::Js => \"js\",\n DepsEcosystem::Rust => \"rust\",\n DepsEcosystem::Go => \"go\",\n }\n}\n\nfn manager_program(manager: DepsManager) -> &'static str {\n match manager {\n DepsManager::Pnpm => \"pnpm\",\n DepsManager::Npm => \"npm\",\n DepsManager::Yarn => \"yarn\",\n DepsManager::Bun => \"bun\",\n }\n}\n\nfn display_command(cmd: &PlannedCommand) -> String {\n if cmd.args.is_empty() {\n return cmd.program.clone();\n }\n format!(\"{} {}\", cmd.program, cmd.args.join(\" \"))\n}\n\nfn update_search_root(cwd: &Path) -> PathBuf {\n if let Some(flow_path) = find_flow_toml(&cwd.to_path_buf()) {\n return flow_path.parent().unwrap_or(cwd).to_path_buf();\n }\n filesystem_root(cwd)\n}\n\nfn filesystem_root(path: &Path) -> PathBuf {\n let mut root = path.to_path_buf();\n while let Some(parent) = root.parent() {\n if parent == root {\n break;\n }\n root = parent.to_path_buf();\n }\n root\n}\n\nfn nearest_ancestor_with_file(start: &Path, boundary: &Path, file: &str) -> Option<PathBuf> {\n let mut current = start.to_path_buf();\n loop {\n if current.join(file).exists() {\n return Some(current);\n }\n if current == boundary {\n break;\n }\n if !current.pop() {\n break;\n }\n }\n None\n}\n\nfn find_js_workspace_root(start: &Path, boundary: &Path) -> Option<PathBuf> {\n let mut current = start.to_path_buf();\n loop {\n if is_js_workspace_root(¤t) {\n return Some(current);\n }\n if current == boundary {\n break;\n }\n if !current.pop() {\n break;\n }\n }\n None\n}\n\nfn is_js_workspace_root(root: &Path) -> bool {\n if root.join(\"pnpm-workspace.yaml\").exists() {\n return true;\n }\n package_json_has_workspaces(root)\n}\n\nfn package_json_has_workspaces(root: &Path) -> bool {\n let package_json = root.join(\"package.json\");\n if !package_json.exists() {\n return false;\n }\n let Ok(contents) = std::fs::read_to_string(package_json) else {\n return false;\n };\n let Ok(value) = serde_json::from_str::<serde_json::Value>(&contents) else {\n return false;\n };\n value.get(\"workspaces\").is_some()\n}\n\nfn find_rust_update_root(start: &Path, boundary: &Path) -> Option<PathBuf> {\n let mut nearest: Option<PathBuf> = None;\n let mut workspace_root: Option<PathBuf> = None;\n let mut current = start.to_path_buf();\n\n loop {\n let cargo_toml = current.join(\"Cargo.toml\");\n if cargo_toml.exists() {\n if nearest.is_none() {\n nearest = Some(current.clone());\n }\n if workspace_root.is_none() && cargo_toml_has_workspace(&cargo_toml) {\n workspace_root = Some(current.clone());\n }\n }\n if current == boundary {\n break;\n }\n if !current.pop() {\n break;\n }\n }\n\n workspace_root.or(nearest)\n}\n\nfn cargo_toml_has_workspace(path: &Path) -> bool {\n let Ok(contents) = std::fs::read_to_string(path) else {\n return false;\n };\n let Ok(value) = toml::from_str::<toml::Value>(&contents) else {\n return false;\n };\n value.get(\"workspace\").is_some()\n}\n\n#[derive(Debug)]\nenum DepPickAction {\n RepoLink { repo: String },\n RepoOpen { owner: String, repo: String },\n Project { path: PathBuf },\n Message { text: String },\n}\n\n#[derive(Debug)]\nstruct DepPickEntry {\n display: String,\n action: DepPickAction,\n}\n\n#[derive(Debug, Deserialize)]\nstruct RepoManifest {\n root: Option<String>,\n repos: Option<Vec<RepoManifestEntry>>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct RepoManifestEntry {\n owner: String,\n repo: String,\n url: Option<String>,\n}\n\nfn pick_dependency(project_root: &Path) -> Result<()> {\n let manifest = load_repo_manifest(project_root)?;\n let default_root = manifest\n .as_ref()\n .and_then(|m| m.root.clone())\n .unwrap_or_else(|| \"~/repos\".to_string());\n\n let root_path = repos::normalize_root(&default_root)?;\n let entries = build_pick_entries(project_root, &root_path, manifest.as_ref())?;\n if entries.is_empty() {\n println!(\"No linked repos or dependency metadata found.\");\n return Ok(());\n }\n\n if which::which(\"fzf\").is_err() {\n println!(\"fzf not found on PATH – install it to use fuzzy selection.\");\n for entry in &entries {\n println!(\" {}\", entry.display);\n }\n return Ok(());\n }\n\n let Some(entry) = run_deps_fzf(&entries)? else {\n return Ok(());\n };\n\n match &entry.action {\n DepPickAction::RepoLink { repo } => {\n link_repo_dependency(project_root, repo, &default_root, false)?\n }\n DepPickAction::RepoOpen { owner, repo } => {\n let repo_ref = repos::RepoRef {\n owner: owner.clone(),\n repo: repo.clone(),\n };\n let repo_path = root_path.join(&repo_ref.owner).join(&repo_ref.repo);\n if !repo_path.exists() {\n let repo_id = format!(\"{}/{}\", repo_ref.owner, repo_ref.repo);\n link_repo_dependency(project_root, &repo_id, &default_root, false)?;\n }\n open_in_zed(&repo_path)?;\n }\n DepPickAction::Project { path } => {\n println!(\"Project path: {}\", path.display());\n println!(\"Hint: cd {}\", path.display());\n }\n DepPickAction::Message { text } => {\n println!(\"{}\", text);\n }\n }\n\n Ok(())\n}\n\nfn run_deps_fzf<'a>(entries: &'a [DepPickEntry]) -> Result<Option<&'a DepPickEntry>> {\n use std::io::Write;\n use std::process::Stdio;\n\n let mut child = Command::new(\"fzf\")\n .arg(\"--prompt\")\n .arg(\"deps> \")\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n {\n let stdin = child.stdin.as_mut().context(\"failed to open fzf stdin\")?;\n for entry in entries {\n writeln!(stdin, \"{}\", entry.display)?;\n }\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n\n let selection = String::from_utf8(output.stdout).context(\"fzf output was not valid UTF-8\")?;\n let selection = selection.trim();\n if selection.is_empty() {\n return Ok(None);\n }\n\n Ok(entries.iter().find(|entry| entry.display == selection))\n}\n\nfn build_pick_entries(\n project_root: &Path,\n root_path: &Path,\n manifest: Option<&RepoManifest>,\n) -> Result<Vec<DepPickEntry>> {\n let mut entries = Vec::new();\n\n if let Some(manifest) = manifest {\n if let Some(repos) = &manifest.repos {\n for repo in repos {\n let repo_id = format!(\"{}/{}\", repo.owner, repo.repo);\n let is_local = root_path.join(&repo.owner).join(&repo.repo).exists();\n let _repo_url = repo.url.clone().unwrap_or_else(|| repo_id.clone());\n entries.push(DepPickEntry {\n display: format!(\n \"[linked] {}{}\",\n repo_id,\n if is_local { \" (local)\" } else { \"\" }\n ),\n action: DepPickAction::RepoOpen {\n owner: repo.owner.clone(),\n repo: repo.repo.clone(),\n },\n });\n }\n }\n }\n\n let scan = scan_project_files(project_root)?;\n let mut js_deps = BTreeSet::new();\n let mut cargo_deps = BTreeSet::new();\n let mut project_entries = Vec::new();\n\n for path in scan {\n if path.file_name().and_then(|n| n.to_str()) == Some(\"package.json\") {\n if let Ok(info) = parse_package_json(&path) {\n if let Some(name) = info.name {\n let dir = path.parent().unwrap_or(&path);\n if !is_project_root(project_root, dir) {\n project_entries.push(DepPickEntry {\n display: format!(\n \"[project] {} ({})\",\n name,\n path_relative(project_root, dir)\n ),\n action: DepPickAction::Project {\n path: dir.to_path_buf(),\n },\n });\n }\n }\n for dep in info.deps {\n js_deps.insert((dep, path.parent().unwrap_or(&path).to_path_buf()));\n }\n }\n } else if path.file_name().and_then(|n| n.to_str()) == Some(\"Cargo.toml\") {\n if let Ok(info) = parse_cargo_toml(&path) {\n if let Some(name) = info.name {\n let dir = path.parent().unwrap_or(&path);\n if !is_project_root(project_root, dir) {\n project_entries.push(DepPickEntry {\n display: format!(\n \"[project] {} ({})\",\n name,\n path_relative(project_root, dir)\n ),\n action: DepPickAction::Project {\n path: dir.to_path_buf(),\n },\n });\n }\n }\n for dep in info.deps {\n cargo_deps.insert(dep);\n }\n }\n }\n }\n\n entries.extend(project_entries);\n\n let cargo_lock = load_cargo_lock(project_root).unwrap_or_default();\n for (dep, base_dir) in js_deps {\n let repo_url = resolve_js_repo(project_root, &base_dir, &dep);\n if let Some(repo_url) = repo_url {\n let is_local = local_repo_is_present(root_path, &repo_url);\n let label = if is_local { \"[linked-js]\" } else { \"[js]\" };\n let display = display_repo(&repo_url);\n let action = if is_local {\n match repos::parse_github_repo(&repo_url) {\n Ok(repo_ref) => DepPickAction::RepoOpen {\n owner: repo_ref.owner,\n repo: repo_ref.repo,\n },\n Err(_) => DepPickAction::RepoLink {\n repo: repo_url.clone(),\n },\n }\n } else {\n DepPickAction::RepoLink {\n repo: repo_url.clone(),\n }\n };\n entries.push(DepPickEntry {\n display: format!(\"{} {} -> {}\", label, dep, display),\n action,\n });\n } else {\n entries.push(DepPickEntry {\n display: format!(\"[js] {} (no repo found)\", dep),\n action: DepPickAction::Message {\n text: format!(\"No repository URL found for {}\", dep),\n },\n });\n }\n }\n\n for dep in cargo_deps {\n let repo_url = resolve_cargo_repo(&cargo_lock, &dep);\n if let Some(repo_url) = repo_url {\n let is_local = local_repo_is_present(root_path, &repo_url);\n let label = if is_local {\n \"[linked-crate]\"\n } else {\n \"[crate]\"\n };\n let display = display_repo(&repo_url);\n let action = if is_local {\n match repos::parse_github_repo(&repo_url) {\n Ok(repo_ref) => DepPickAction::RepoOpen {\n owner: repo_ref.owner,\n repo: repo_ref.repo,\n },\n Err(_) => DepPickAction::RepoLink {\n repo: repo_url.clone(),\n },\n }\n } else {\n DepPickAction::RepoLink {\n repo: repo_url.clone(),\n }\n };\n entries.push(DepPickEntry {\n display: format!(\"{} {} -> {}\", label, dep, display),\n action,\n });\n } else {\n entries.push(DepPickEntry {\n display: format!(\"[crate] {} (no repo found)\", dep),\n action: DepPickAction::Message {\n text: format!(\"No repository URL found for {}\", dep),\n },\n });\n }\n }\n\n Ok(entries)\n}\n\nfn load_repo_manifest(project_root: &Path) -> Result<Option<RepoManifest>> {\n let path = project_root.join(\".ai\").join(\"repos.toml\");\n if !path.exists() {\n return Ok(None);\n }\n let contents = std::fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n let manifest =\n toml::from_str::<RepoManifest>(&contents).context(\"failed to parse .ai/repos.toml\")?;\n Ok(Some(manifest))\n}\n\nfn scan_project_files(root: &Path) -> Result<Vec<PathBuf>> {\n let mut paths = Vec::new();\n let mut builder = WalkBuilder::new(root);\n builder.hidden(false);\n builder.filter_entry(|entry| {\n let name = entry.file_name().to_string_lossy();\n match name.as_ref() {\n \".git\" | \".ai\" | \"node_modules\" | \"target\" | \"dist\" | \"build\" | \".next\" | \".turbo\" => {\n return false;\n }\n _ => {}\n }\n true\n });\n\n for entry in builder.build() {\n let entry = match entry {\n Ok(entry) => entry,\n Err(_) => continue,\n };\n if !entry.file_type().map(|t| t.is_file()).unwrap_or(false) {\n continue;\n }\n let name = entry.file_name().to_string_lossy();\n if name == \"package.json\" || name == \"Cargo.toml\" {\n paths.push(entry.into_path());\n }\n }\n\n Ok(paths)\n}\n\nstruct PackageJsonInfo {\n name: Option<String>,\n deps: Vec<String>,\n}\n\nfn parse_package_json(path: &Path) -> Result<PackageJsonInfo> {\n let contents = std::fs::read_to_string(path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n let value: serde_json::Value = serde_json::from_str(&contents)\n .with_context(|| format!(\"failed to parse {}\", path.display()))?;\n\n let name = value\n .get(\"name\")\n .and_then(|v| v.as_str())\n .map(|s| s.to_string());\n let mut deps = BTreeSet::new();\n\n for key in [\n \"dependencies\",\n \"devDependencies\",\n \"optionalDependencies\",\n \"peerDependencies\",\n ] {\n if let Some(obj) = value.get(key).and_then(|v| v.as_object()) {\n for dep in obj.keys() {\n deps.insert(dep.to_string());\n }\n }\n }\n\n Ok(PackageJsonInfo {\n name,\n deps: deps.into_iter().collect(),\n })\n}\n\nstruct CargoTomlInfo {\n name: Option<String>,\n deps: Vec<String>,\n}\n\nfn parse_cargo_toml(path: &Path) -> Result<CargoTomlInfo> {\n let contents = std::fs::read_to_string(path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n let value: toml::Value =\n toml::from_str(&contents).with_context(|| format!(\"failed to parse {}\", path.display()))?;\n\n let name = value\n .get(\"package\")\n .and_then(Value::as_table)\n .and_then(|pkg| pkg.get(\"name\"))\n .and_then(Value::as_str)\n .map(|s| s.to_string());\n\n let mut deps = BTreeSet::new();\n for key in [\"dependencies\", \"dev-dependencies\", \"build-dependencies\"] {\n if let Some(table) = value.get(key).and_then(Value::as_table) {\n for dep in table.keys() {\n deps.insert(dep.to_string());\n }\n }\n }\n\n Ok(CargoTomlInfo {\n name,\n deps: deps.into_iter().collect(),\n })\n}\n\n#[derive(Default)]\nstruct CargoLockIndex {\n versions: BTreeMap<String, String>,\n sources: BTreeMap<String, String>,\n}\n\nfn load_cargo_lock(project_root: &Path) -> Result<CargoLockIndex> {\n let lock_path = project_root.join(\"Cargo.lock\");\n if !lock_path.exists() {\n return Ok(CargoLockIndex::default());\n }\n\n let contents = std::fs::read_to_string(&lock_path)\n .with_context(|| format!(\"failed to read {}\", lock_path.display()))?;\n let value: toml::Value = toml::from_str(&contents)\n .with_context(|| format!(\"failed to parse {}\", lock_path.display()))?;\n\n let mut index = CargoLockIndex::default();\n let packages = value\n .get(\"package\")\n .and_then(Value::as_array)\n .cloned()\n .unwrap_or_default();\n\n for pkg in packages {\n let table = match pkg.as_table() {\n Some(table) => table,\n None => continue,\n };\n let name = match table.get(\"name\").and_then(Value::as_str) {\n Some(name) => name.to_string(),\n None => continue,\n };\n if let Some(version) = table.get(\"version\").and_then(Value::as_str) {\n index\n .versions\n .entry(name.clone())\n .or_insert_with(|| version.to_string());\n }\n if let Some(source) = table.get(\"source\").and_then(Value::as_str) {\n if source.starts_with(\"registry+\") {\n continue;\n }\n if let Some(url) = normalize_github_url(source) {\n index.sources.entry(name).or_insert(url);\n }\n }\n }\n\n Ok(index)\n}\n\nfn resolve_js_repo(project_root: &Path, base_dir: &Path, dep: &str) -> Option<String> {\n let mut candidates = Vec::new();\n if base_dir.join(\"node_modules\").exists() {\n candidates.push(base_dir.join(\"node_modules\"));\n }\n if project_root.join(\"node_modules\").exists() {\n candidates.push(project_root.join(\"node_modules\"));\n }\n\n for base in candidates {\n let dep_path = join_node_modules(&base, dep).join(\"package.json\");\n if dep_path.exists() {\n if let Ok(contents) = std::fs::read_to_string(&dep_path) {\n if let Ok(value) = serde_json::from_str::<serde_json::Value>(&contents) {\n if let Some(repo) = extract_repo_url(&value) {\n if let Some(url) = normalize_github_url(&repo) {\n return Some(url);\n }\n }\n }\n }\n }\n }\n\n None\n}\n\nfn resolve_cargo_repo(index: &CargoLockIndex, dep: &str) -> Option<String> {\n if let Some(url) = index.sources.get(dep) {\n return Some(url.clone());\n }\n\n let version = index.versions.get(dep)?;\n let cargo_home = cargo_home();\n let registry_src = cargo_home.join(\"registry\").join(\"src\");\n let entries = std::fs::read_dir(®istry_src).ok()?;\n\n for entry in entries.flatten() {\n let candidate = entry\n .path()\n .join(format!(\"{}-{}\", dep, version))\n .join(\"Cargo.toml\");\n if candidate.exists() {\n if let Ok(contents) = std::fs::read_to_string(&candidate) {\n if let Ok(value) = toml::from_str::<toml::Value>(&contents) {\n if let Some(repo) = value\n .get(\"package\")\n .and_then(Value::as_table)\n .and_then(|pkg| pkg.get(\"repository\"))\n .and_then(Value::as_str)\n {\n if let Some(url) = normalize_github_url(repo) {\n return Some(url);\n }\n }\n }\n }\n }\n }\n\n None\n}\n\nfn cargo_home() -> PathBuf {\n let raw = std::env::var(\"CARGO_HOME\").unwrap_or_else(|_| \"~/.cargo\".to_string());\n config::expand_path(&raw)\n}\n\nfn join_node_modules(base: &Path, dep: &str) -> PathBuf {\n if let Some((scope, name)) = dep.split_once('/') {\n if scope.starts_with('@') {\n return base.join(scope).join(name);\n }\n }\n base.join(dep)\n}\n\nfn extract_repo_url(value: &serde_json::Value) -> Option<String> {\n match value.get(\"repository\") {\n Some(serde_json::Value::String(url)) => Some(url.to_string()),\n Some(serde_json::Value::Object(map)) => map\n .get(\"url\")\n .and_then(|v| v.as_str())\n .map(|s| s.to_string()),\n _ => None,\n }\n}\n\nfn normalize_github_url(raw: &str) -> Option<String> {\n let trimmed = raw.trim().trim_start_matches(\"git+\");\n let cleaned = trimmed.trim_end_matches('/').trim_end_matches(\".git\");\n if cleaned.contains(\"crates.io-index\") {\n return None;\n }\n\n if let Ok(repo_ref) = repos::parse_github_repo(cleaned) {\n return Some(format!(\n \"https://github.com/{}/{}\",\n repo_ref.owner, repo_ref.repo\n ));\n }\n None\n}\n\nfn display_repo(url: &str) -> String {\n if let Ok(repo_ref) = repos::parse_github_repo(url) {\n return format!(\"{}/{}\", repo_ref.owner, repo_ref.repo);\n }\n url.to_string()\n}\n\nfn local_repo_is_present(root_path: &Path, url: &str) -> bool {\n if let Ok(repo_ref) = repos::parse_github_repo(url) {\n if root_path.join(repo_ref.owner).join(repo_ref.repo).exists() {\n return true;\n }\n }\n false\n}\n\nfn open_in_zed(path: &Path) -> Result<()> {\n let status = Command::new(\"open\")\n .args([\"-a\", \"/Applications/Zed.app\"])\n .arg(path)\n .status()\n .context(\"failed to launch Zed\")?;\n\n if status.success() {\n Ok(())\n } else {\n bail!(\"failed to open {}\", path.display());\n }\n}\n\nfn path_relative(root: &Path, path: &Path) -> String {\n path.strip_prefix(root)\n .unwrap_or(path)\n .display()\n .to_string()\n}\n\nfn is_project_root(root: &Path, candidate: &Path) -> bool {\n let root = root.canonicalize().unwrap_or_else(|_| root.to_path_buf());\n let candidate = candidate\n .canonicalize()\n .unwrap_or_else(|_| candidate.to_path_buf());\n root == candidate\n}\n\nfn link_repo_dependency(\n project_root: &Path,\n repo: &str,\n root: &str,\n private_origin: bool,\n) -> Result<()> {\n let ai_dir = project_root.join(\".ai\");\n let repos_dir = ai_dir.join(\"repos\");\n std::fs::create_dir_all(&repos_dir)\n .with_context(|| format!(\"failed to create {}\", repos_dir.display()))?;\n\n let root_path = repos::normalize_root(root)?;\n let repo_ref = if looks_like_repo_ref(repo) {\n repos::parse_github_repo(repo)?\n } else {\n resolve_repo_by_name(&root_path, repo)?\n };\n\n let target_dir = root_path.join(&repo_ref.owner).join(&repo_ref.repo);\n let mut cloned = false;\n if !target_dir.exists() {\n let opts = ReposCloneOpts {\n url: repo.to_string(),\n root: root.to_string(),\n full: false,\n no_upstream: false,\n upstream_url: None,\n };\n repos::clone_repo(opts)?;\n cloned = true;\n } else {\n println!(\"✓ found repo at {}\", target_dir.display());\n }\n\n let origin_url = format!(\"git@github.com:{}/{}.git\", repo_ref.owner, repo_ref.repo);\n if cloned {\n if let Err(err) = ensure_upstream(&target_dir, &origin_url) {\n println!(\"⚠ upstream setup skipped: {}\", err);\n }\n }\n\n if private_origin {\n if let Err(err) = maybe_setup_private_origin(&target_dir, &repo_ref, &origin_url) {\n println!(\"⚠ private origin setup skipped: {}\", err);\n }\n }\n\n let owner_dir = repos_dir.join(&repo_ref.owner);\n std::fs::create_dir_all(&owner_dir)\n .with_context(|| format!(\"failed to create {}\", owner_dir.display()))?;\n let link_path = owner_dir.join(&repo_ref.repo);\n if link_path.exists() {\n println!(\"✓ link already exists: {}\", link_path.display());\n } else {\n #[cfg(unix)]\n {\n std::os::unix::fs::symlink(&target_dir, &link_path)\n .with_context(|| format!(\"failed to link {}\", link_path.display()))?;\n }\n #[cfg(windows)]\n {\n std::os::windows::fs::symlink_dir(&target_dir, &link_path)\n .with_context(|| format!(\"failed to link {}\", link_path.display()))?;\n }\n println!(\"✓ linked {}\", link_path.display());\n }\n\n let manifest_path = ai_dir.join(\"repos.toml\");\n upsert_repo_manifest(&manifest_path, root, &repo_ref, repo)?;\n\n Ok(())\n}\n\nfn looks_like_repo_ref(input: &str) -> bool {\n let trimmed = input.trim();\n trimmed.contains(\"github.com/\")\n || trimmed.starts_with(\"git@github.com:\")\n || trimmed.contains('/')\n || trimmed.ends_with(\".git\")\n}\n\nfn resolve_repo_by_name(root: &Path, name: &str) -> Result<repos::RepoRef> {\n let mut matches = Vec::new();\n let root_entries =\n std::fs::read_dir(root).with_context(|| format!(\"failed to read {}\", root.display()))?;\n\n for owner_entry in root_entries.flatten() {\n if !owner_entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {\n continue;\n }\n let owner = owner_entry.file_name().to_string_lossy().to_string();\n let repo_path = owner_entry.path().join(name);\n if repo_path.is_dir() {\n matches.push(repos::RepoRef {\n owner,\n repo: name.to_string(),\n });\n }\n }\n\n if matches.is_empty() {\n bail!(\n \"repo '{}' not found under {}. Use owner/repo or run: f repos clone <url>\",\n name,\n root.display()\n );\n }\n\n if matches.len() > 1 {\n let options = matches\n .iter()\n .map(|repo| format!(\"{}/{}\", repo.owner, repo.repo))\n .collect::<Vec<_>>()\n .join(\", \");\n bail!(\n \"multiple matches for '{}': {}. Use owner/repo.\",\n name,\n options\n );\n }\n\n Ok(matches.remove(0))\n}\n\nfn upsert_repo_manifest(path: &Path, root: &str, repo: &repos::RepoRef, url: &str) -> Result<()> {\n let mut doc = if path.exists() {\n let contents = std::fs::read_to_string(path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n toml::from_str::<Value>(&contents).unwrap_or(Value::Table(Map::new()))\n } else {\n Value::Table(Map::new())\n };\n\n let table = doc\n .as_table_mut()\n .ok_or_else(|| anyhow::anyhow!(\"invalid repos.toml\"))?;\n table\n .entry(\"root\".to_string())\n .or_insert_with(|| Value::String(root.to_string()));\n\n let repos_value = table\n .entry(\"repos\".to_string())\n .or_insert_with(|| Value::Array(Vec::new()));\n let repos_array = repos_value\n .as_array_mut()\n .ok_or_else(|| anyhow::anyhow!(\"invalid repos list\"))?;\n\n let exists = repos_array.iter().any(|entry| {\n entry.get(\"owner\").and_then(Value::as_str) == Some(repo.owner.as_str())\n && entry.get(\"repo\").and_then(Value::as_str) == Some(repo.repo.as_str())\n });\n\n if !exists {\n let mut entry = Map::new();\n entry.insert(\"owner\".to_string(), Value::String(repo.owner.clone()));\n entry.insert(\"repo\".to_string(), Value::String(repo.repo.clone()));\n entry.insert(\"url\".to_string(), Value::String(url.to_string()));\n repos_array.push(Value::Table(entry));\n }\n\n let rendered = toml::to_string_pretty(&doc)?;\n std::fs::write(path, rendered)\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n println!(\"✓ updated {}\", path.display());\n Ok(())\n}\n\nfn maybe_setup_private_origin(\n repo_dir: &Path,\n repo_ref: &repos::RepoRef,\n origin_url: &str,\n) -> Result<()> {\n if !gh_available() {\n return Ok(());\n }\n\n if !gh_authenticated()? {\n println!(\"gh not authenticated; skipping private origin setup\");\n println!(\"Authenticate with: gh auth login\");\n return Ok(());\n }\n\n let gh_user = gh_username()?;\n if gh_user.is_empty() || repo_ref.owner == gh_user {\n return Ok(());\n }\n\n if !repo_dir.join(\".git\").exists() {\n return Ok(());\n }\n\n let origin_remote = git_remote_get(repo_dir, \"origin\")?;\n if let Some(origin_remote) = origin_remote {\n if origin_remote.contains(&format!(\"github.com:{}/\", gh_user))\n || origin_remote.contains(&format!(\"github.com/{}/\", gh_user))\n {\n return Ok(());\n }\n }\n\n let private_repo = format!(\"{}/{}\", gh_user, repo_ref.repo);\n let private_url = format!(\"git@github.com:{}.git\", private_repo);\n\n if !gh_repo_exists(&private_repo)? {\n println!(\"Creating private repo: {}\", private_repo);\n let status = Command::new(\"gh\")\n .args([\"repo\", \"create\", &private_repo, \"--private\"])\n .status()\n .context(\"failed to create private repo\")?;\n if !status.success() {\n bail!(\"failed to create private repo {}\", private_repo);\n }\n }\n\n set_origin_remote(repo_dir, &private_url)?;\n let upstream_remote = git_remote_get(repo_dir, \"upstream\")?;\n if upstream_remote.is_none() {\n configure_upstream(repo_dir, origin_url)?;\n } else if upstream_remote.as_deref() != Some(origin_url) {\n println!(\n \"⚠ upstream already set to {} (expected {})\",\n upstream_remote.unwrap_or_default(),\n origin_url\n );\n }\n println!(\"✓ origin -> {}\", private_repo);\n\n Ok(())\n}\n\nfn ensure_upstream(repo_dir: &Path, origin_url: &str) -> Result<()> {\n if !repo_dir.join(\".git\").exists() {\n return Ok(());\n }\n\n if git_remote_get(repo_dir, \"upstream\")?.is_some() {\n return Ok(());\n }\n\n configure_upstream(repo_dir, origin_url)?;\n Ok(())\n}\n\nfn gh_available() -> bool {\n Command::new(\"gh\").arg(\"--version\").output().is_ok()\n}\n\nfn gh_authenticated() -> Result<bool> {\n let status = Command::new(\"gh\").args([\"auth\", \"status\"]).output()?;\n Ok(status.status.success())\n}\n\nfn gh_username() -> Result<String> {\n let output = Command::new(\"gh\")\n .args([\"api\", \"user\", \"-q\", \".login\"])\n .output()\n .context(\"failed to get GitHub username\")?;\n Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())\n}\n\nfn gh_repo_exists(full_name: &str) -> Result<bool> {\n let output = Command::new(\"gh\")\n .args([\"repo\", \"view\", full_name])\n .output()\n .context(\"failed to check repo\")?;\n Ok(output.status.success())\n}\n\nfn git_remote_get(repo_dir: &Path, name: &str) -> Result<Option<String>> {\n let output = Command::new(\"git\")\n .args([\"remote\", \"get-url\", name])\n .current_dir(repo_dir)\n .output();\n\n let output = match output {\n Ok(output) if output.status.success() => output,\n _ => return Ok(None),\n };\n\n Ok(Some(\n String::from_utf8_lossy(&output.stdout).trim().to_string(),\n ))\n}\n\nfn set_origin_remote(repo_dir: &Path, url: &str) -> Result<()> {\n if git_remote_get(repo_dir, \"origin\")?.is_some() {\n Command::new(\"git\")\n .args([\"remote\", \"set-url\", \"origin\", url])\n .current_dir(repo_dir)\n .status()\n .context(\"failed to set origin\")?;\n } else {\n Command::new(\"git\")\n .args([\"remote\", \"add\", \"origin\", url])\n .current_dir(repo_dir)\n .status()\n .context(\"failed to add origin\")?;\n }\n Ok(())\n}\n\nfn configure_upstream(repo_dir: &Path, upstream_url: &str) -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to capture current directory\")?;\n std::env::set_current_dir(repo_dir)\n .with_context(|| format!(\"failed to enter {}\", repo_dir.display()))?;\n\n let result = upstream::setup_upstream_with_depth(Some(upstream_url), None, None);\n\n if let Err(err) = std::env::set_current_dir(&cwd) {\n println!(\"warning: failed to restore working directory: {}\", err);\n }\n\n result\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn detect_manager_prefers_package_manager_field() {\n let dir = tempfile::tempdir().expect(\"tempdir\");\n std::fs::write(\n dir.path().join(\"package.json\"),\n r#\"{\"name\":\"x\",\"packageManager\":\"bun@1.2.3\"}\"#,\n )\n .expect(\"write package.json\");\n std::fs::write(dir.path().join(\"pnpm-lock.yaml\"), \"\").expect(\"write lock\");\n\n let manager = detect_manager(dir.path());\n assert!(matches!(manager, DepsManager::Bun));\n }\n\n #[test]\n fn rust_update_root_prefers_workspace_ancestor() {\n let dir = tempfile::tempdir().expect(\"tempdir\");\n let root = dir.path();\n std::fs::write(\n root.join(\"Cargo.toml\"),\n \"[workspace]\\nmembers=[\\\"crates/app\\\"]\\n\",\n )\n .expect(\"write root Cargo.toml\");\n let crate_dir = root.join(\"crates\").join(\"app\");\n std::fs::create_dir_all(&crate_dir).expect(\"mkdir\");\n std::fs::write(\n crate_dir.join(\"Cargo.toml\"),\n \"[package]\\nname=\\\"app\\\"\\nversion=\\\"0.1.0\\\"\\n\",\n )\n .expect(\"write crate Cargo.toml\");\n\n let selected = find_rust_update_root(&crate_dir, root).expect(\"root\");\n assert_eq!(selected, root);\n }\n\n #[test]\n fn build_update_plans_detects_js_workspace_root() {\n let dir = tempfile::tempdir().expect(\"tempdir\");\n let root = dir.path().to_path_buf();\n std::fs::write(\n root.join(\"package.json\"),\n r#\"{\"name\":\"mono\",\"workspaces\":[\"packages/*\"],\"packageManager\":\"pnpm@10.0.0\"}\"#,\n )\n .expect(\"write root package.json\");\n let app_dir = root.join(\"packages\").join(\"app\");\n std::fs::create_dir_all(&app_dir).expect(\"mkdir\");\n std::fs::write(app_dir.join(\"package.json\"), r#\"{\"name\":\"app\"}\"#).expect(\"write app pkg\");\n\n let ctx = UpdateDetectContext {\n cwd: app_dir,\n search_root: root.clone(),\n };\n\n let plans = build_update_plans(&ctx, &UpdateDepsOpts::default()).expect(\"plan\");\n let js_plan = plans\n .iter()\n .find(|p| p.target.ecosystem == DepsEcosystem::Js)\n .expect(\"js plan\");\n assert_eq!(js_plan.target.root, root);\n }\n}\n" }, { "path": "src/discover.rs", "content": "//! Fast discovery of nested flow.toml files in a project.\n\nuse std::fs;\nuse std::path::{Path, PathBuf};\n\nuse anyhow::{Context, Result};\nuse ignore::WalkBuilder;\nuse serde::{Deserialize, Serialize};\n\nuse crate::config::{self, CommandFileConfig, TaskConfig, TaskResolutionConfig};\nuse crate::fixup;\n\n/// A task with its source location information.\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct DiscoveredTask {\n /// The task configuration.\n pub task: TaskConfig,\n /// Absolute path to the flow.toml containing this task.\n pub config_path: PathBuf,\n /// Relative path from the discovery root to the config file's directory.\n /// Empty string for root-level tasks.\n pub relative_dir: String,\n /// Depth from the discovery root (0 = root, 1 = immediate subdirectory, etc.)\n pub depth: usize,\n /// Primary scope label used for display and selector prefixes (e.g. \"mobile\", \"root\").\n pub scope: String,\n /// Scope aliases accepted during selector matching.\n pub scope_aliases: Vec<String>,\n}\n\nimpl DiscoveredTask {\n /// Format a display label showing the relative path for nested tasks.\n pub fn path_label(&self) -> Option<String> {\n if self.relative_dir.is_empty() {\n None\n } else {\n Some(self.relative_dir.clone())\n }\n }\n\n /// Case-insensitive scope match against discovered aliases.\n pub fn matches_scope(&self, scope: &str) -> bool {\n let needle = normalize_scope_token(scope);\n if needle.is_empty() {\n return false;\n }\n self.scope_aliases.iter().any(|alias| alias == &needle)\n }\n}\n\n/// Result of discovering flow.toml files in a directory tree.\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct DiscoveryResult {\n /// All discovered tasks, sorted by depth (root first).\n pub tasks: Vec<DiscoveredTask>,\n /// The root config path (if exists).\n pub root_config: Option<PathBuf>,\n /// Root task-resolution policy (if configured).\n pub root_task_resolution: Option<TaskResolutionConfig>,\n}\n\n#[derive(Debug, Clone)]\npub(crate) struct DiscoveryArtifacts {\n pub result: DiscoveryResult,\n pub watched_paths: Vec<PathBuf>,\n}\n\n#[derive(Debug, Clone, Deserialize)]\nstruct DiscoveryConfigFile {\n #[serde(\n default,\n rename = \"name\",\n alias = \"project_name\",\n alias = \"project-name\"\n )]\n project_name: Option<String>,\n #[serde(default)]\n tasks: Vec<TaskConfig>,\n #[serde(\n default,\n rename = \"task_resolution\",\n alias = \"task-resolution\",\n alias = \"taskResolution\"\n )]\n task_resolution: Option<TaskResolutionConfig>,\n #[serde(default, rename = \"commands\")]\n command_files: Vec<CommandFileConfig>,\n}\n\n#[derive(Debug, Clone)]\nstruct LoadedDiscoveryConfig {\n project_name: Option<String>,\n tasks: Vec<TaskConfig>,\n task_resolution: Option<TaskResolutionConfig>,\n}\n\n/// Discover all flow.toml files starting from the given root directory.\n/// Uses the `ignore` crate for fast, gitignore-aware traversal.\n///\n/// Tasks are returned sorted by depth (root-level first, then nested).\npub fn discover_tasks(root: &Path) -> Result<DiscoveryResult> {\n let root = if root.is_absolute() {\n root.to_path_buf()\n } else {\n std::env::current_dir()?.join(root)\n };\n let root = root.canonicalize().unwrap_or(root);\n discover_tasks_from_root(root)\n}\n\npub(crate) fn discover_tasks_from_root(root: PathBuf) -> Result<DiscoveryResult> {\n Ok(discover_tasks_from_root_artifacts(root)?.result)\n}\n\npub(crate) fn discover_tasks_from_root_artifacts(root: PathBuf) -> Result<DiscoveryArtifacts> {\n let mut discovered: Vec<DiscoveredTask> = Vec::new();\n let mut root_config: Option<PathBuf> = None;\n let mut root_task_resolution: Option<TaskResolutionConfig> = None;\n let mut watched_paths = Vec::new();\n push_watched_path(&mut watched_paths, &root);\n\n // Check if root itself has a flow.toml\n let root_flow_toml = root.join(\"flow.toml\");\n if root_flow_toml.exists() {\n match load_discovery_config(&root_flow_toml, &mut Vec::new(), &mut watched_paths) {\n Ok(cfg) => {\n let (scope, scope_aliases) = infer_scope_metadata(\"\", cfg.project_name.as_deref());\n root_config = Some(root_flow_toml.clone());\n root_task_resolution = cfg.task_resolution.clone();\n for task in &cfg.tasks {\n discovered.push(DiscoveredTask {\n task: task.clone(),\n config_path: root_flow_toml.clone(),\n relative_dir: String::new(),\n depth: 0,\n scope: scope.clone(),\n scope_aliases: scope_aliases.clone(),\n });\n }\n }\n Err(e) => {\n eprintln!(\n \"Warning: failed to parse {}: {:#}\",\n root_flow_toml.display(),\n e\n );\n }\n }\n }\n\n // Walk subdirectories looking for flow.toml files\n // Use the ignore crate which respects .gitignore and is very fast\n let walker = WalkBuilder::new(&root)\n .hidden(true) // skip hidden directories\n .git_ignore(true) // respect .gitignore\n .git_global(true) // respect global gitignore\n .git_exclude(true) // respect .git/info/exclude\n .max_depth(Some(10)) // reasonable depth limit\n .filter_entry(|entry| {\n // Skip common directories that won't have flow.toml we care about\n if entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {\n let name = entry.file_name().to_string_lossy();\n // Skip these directories entirely\n !matches!(\n name.as_ref(),\n \"node_modules\"\n | \"target\"\n | \"dist\"\n | \"build\"\n | \".git\"\n | \".hg\"\n | \".svn\"\n | \"__pycache__\"\n | \".pytest_cache\"\n | \".mypy_cache\"\n | \"venv\"\n | \".venv\"\n | \"vendor\"\n | \"Pods\"\n | \".cargo\"\n | \".rustup\"\n )\n } else {\n true\n }\n })\n .build();\n\n for entry in walker.flatten() {\n let path = entry.path();\n if path.is_dir() {\n push_watched_path(&mut watched_paths, path);\n }\n\n // Skip the root (already handled above)\n if path == root {\n continue;\n }\n\n // We're looking for directories that contain flow.toml\n if !path.is_dir() {\n continue;\n }\n\n let flow_toml = path.join(\"flow.toml\");\n if !flow_toml.exists() {\n continue;\n }\n\n // Parse the config\n let cfg = match load_discovery_config(&flow_toml, &mut Vec::new(), &mut watched_paths) {\n Ok(c) => c,\n Err(_) => continue, // Skip invalid configs\n };\n\n // Calculate relative path from root\n let relative_dir = path\n .strip_prefix(&root)\n .map(|p| p.to_string_lossy().to_string())\n .unwrap_or_default();\n\n // Calculate depth\n let depth = relative_dir.matches('/').count()\n + relative_dir.matches('\\\\').count()\n + if relative_dir.is_empty() { 0 } else { 1 };\n let (scope, scope_aliases) =\n infer_scope_metadata(&relative_dir, cfg.project_name.as_deref());\n\n for task in cfg.tasks {\n discovered.push(DiscoveredTask {\n task,\n config_path: flow_toml.clone(),\n relative_dir: relative_dir.clone(),\n depth,\n scope: scope.clone(),\n scope_aliases: scope_aliases.clone(),\n });\n }\n }\n\n // Sort by depth (root first), then by task name for stability\n discovered.sort_by(|a, b| {\n a.depth\n .cmp(&b.depth)\n .then_with(|| a.relative_dir.cmp(&b.relative_dir))\n .then_with(|| a.task.name.cmp(&b.task.name))\n });\n\n Ok(DiscoveryArtifacts {\n result: DiscoveryResult {\n tasks: discovered,\n root_config,\n root_task_resolution,\n },\n watched_paths,\n })\n}\n\nfn normalize_scope_token(raw: &str) -> String {\n let mut out = String::new();\n for ch in raw.trim().chars() {\n let ch = ch.to_ascii_lowercase();\n if ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_' | '/' | '.') {\n out.push(ch);\n } else if ch.is_whitespace() {\n out.push('-');\n }\n }\n out.trim_matches('-').trim_matches('/').to_string()\n}\n\nfn infer_scope_metadata(relative_dir: &str, project_name: Option<&str>) -> (String, Vec<String>) {\n let mut aliases: Vec<String> = Vec::new();\n let mut push_alias = |raw: &str| {\n let normalized = normalize_scope_token(raw);\n if !normalized.is_empty() && !aliases.iter().any(|v| v == &normalized) {\n aliases.push(normalized);\n }\n };\n\n if let Some(name) = project_name {\n push_alias(name);\n } else if relative_dir.trim().is_empty() {\n push_alias(\"root\");\n } else {\n if let Some(leaf) = std::path::Path::new(relative_dir)\n .file_name()\n .and_then(|s| s.to_str())\n {\n push_alias(leaf);\n }\n push_alias(relative_dir);\n }\n\n let primary = aliases\n .first()\n .cloned()\n .unwrap_or_else(|| \"root\".to_string());\n (primary, aliases)\n}\n\nfn push_watched_path(paths: &mut Vec<PathBuf>, path: &Path) {\n if !paths.iter().any(|existing| existing == path) {\n paths.push(path.to_path_buf());\n }\n}\n\nfn load_discovery_config(\n path: &Path,\n visited: &mut Vec<PathBuf>,\n watched_paths: &mut Vec<PathBuf>,\n) -> Result<LoadedDiscoveryConfig> {\n let canonical = path.canonicalize()?;\n if visited.contains(&canonical) {\n anyhow::bail!(\n \"cycle detected while loading config includes: {}\",\n path.display()\n );\n }\n visited.push(canonical.clone());\n push_watched_path(watched_paths, &canonical);\n\n let contents = fs::read_to_string(&canonical)?;\n let mut cfg = parse_discovery_config(&canonical, &contents)?;\n\n let mut project_name = cfg.project_name.take();\n let mut tasks = cfg.tasks;\n let mut task_resolution = cfg.task_resolution.take();\n\n for include in cfg.command_files {\n let include_path = config::resolve_include_path(&canonical, &include.path);\n let included = load_discovery_config(&include_path, visited, watched_paths)?;\n if project_name.is_none() {\n project_name = included.project_name;\n }\n if task_resolution.is_none() {\n task_resolution = included.task_resolution;\n }\n tasks.extend(included.tasks);\n }\n\n visited.pop();\n Ok(LoadedDiscoveryConfig {\n project_name,\n tasks,\n task_resolution,\n })\n}\n\nfn parse_discovery_config(path: &Path, contents: &str) -> Result<DiscoveryConfigFile> {\n match toml::from_str(contents) {\n Ok(cfg) => Ok(cfg),\n Err(err) => {\n let fix = fixup::fix_toml_content(contents);\n if fix.fixes_applied.is_empty() {\n Err(err).with_context(|| {\n format!(\n \"failed to parse flow discovery config at {}\",\n path.display()\n )\n })\n } else {\n let fixed = fixup::apply_fixes_to_content(contents, &fix.fixes_applied);\n fs::write(path, &fixed).with_context(|| {\n format!(\n \"failed to write auto-fixed discovery config at {}\",\n path.display()\n )\n })?;\n toml::from_str(&fixed).with_context(|| {\n format!(\n \"failed to parse flow discovery config at {} (after auto-fix)\",\n path.display()\n )\n })\n }\n }\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use std::fs;\n use tempfile::TempDir;\n\n fn write_flow_toml(dir: &Path, content: &str) {\n fs::write(dir.join(\"flow.toml\"), content).unwrap();\n }\n\n #[test]\n fn discovers_root_tasks() {\n let tmp = TempDir::new().unwrap();\n write_flow_toml(\n tmp.path(),\n r#\"\n[[tasks]]\nname = \"test\"\ncommand = \"echo test\"\n\"#,\n );\n\n let result = discover_tasks(tmp.path()).unwrap();\n assert_eq!(result.tasks.len(), 1);\n assert_eq!(result.tasks[0].task.name, \"test\");\n assert_eq!(result.tasks[0].depth, 0);\n assert!(result.tasks[0].relative_dir.is_empty());\n assert_eq!(result.tasks[0].scope, \"root\");\n }\n\n #[test]\n fn discovers_nested_tasks() {\n let tmp = TempDir::new().unwrap();\n write_flow_toml(\n tmp.path(),\n r#\"\n[[tasks]]\nname = \"root-task\"\ncommand = \"echo root\"\n\"#,\n );\n\n let nested = tmp.path().join(\"packages/api\");\n fs::create_dir_all(&nested).unwrap();\n write_flow_toml(\n &nested,\n r#\"\n[[tasks]]\nname = \"api-task\"\ncommand = \"echo api\"\n\"#,\n );\n\n let result = discover_tasks(tmp.path()).unwrap();\n assert_eq!(result.tasks.len(), 2);\n\n // Root task should come first\n assert_eq!(result.tasks[0].task.name, \"root-task\");\n assert_eq!(result.tasks[0].depth, 0);\n\n // Nested task second\n assert_eq!(result.tasks[1].task.name, \"api-task\");\n assert!(result.tasks[1].depth > 0);\n assert!(result.tasks[1].relative_dir.contains(\"packages\"));\n assert_eq!(result.tasks[1].scope, \"api\");\n }\n\n #[test]\n fn skips_node_modules() {\n let tmp = TempDir::new().unwrap();\n write_flow_toml(\n tmp.path(),\n r#\"\n[[tasks]]\nname = \"root\"\ncommand = \"echo root\"\n\"#,\n );\n\n let node_modules = tmp.path().join(\"node_modules/some-pkg\");\n fs::create_dir_all(&node_modules).unwrap();\n write_flow_toml(\n &node_modules,\n r#\"\n[[tasks]]\nname = \"should-skip\"\ncommand = \"echo skip\"\n\"#,\n );\n\n let result = discover_tasks(tmp.path()).unwrap();\n assert_eq!(result.tasks.len(), 1);\n assert_eq!(result.tasks[0].task.name, \"root\");\n }\n}\n" }, { "path": "src/docs.rs", "content": "//! Auto-generated documentation management.\n//!\n//! Maintains documentation in `.ai/docs/` that stays in sync with the codebase.\n\nuse std::fs;\nuse std::io::{self, IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\nuse which::which;\n\nuse crate::cli::{\n DeployCommand, DocsAction, DocsCommand, DocsDeployOpts, DocsHubOpts, DocsNewOpts,\n};\nuse crate::{config, deploy};\n\n/// Docs directory relative to project root.\nconst DOCS_DIR: &str = \".ai/docs\";\nconst PROJECT_DOCS_DIR: &str = \"docs\";\nconst DEFAULT_DOCS_TEMPLATE_ROOT: &str = \"~/new/docs\";\nconst HUB_CONTENT_ROOT: &str = \"content/docs\";\nconst DOCS_HUB_FOCUS_FILE: &str = \".flow-focus\";\n\n/// Run the docs command.\npub fn run(cmd: DocsCommand) -> Result<()> {\n let project_root = std::env::current_dir()?;\n let docs_dir = project_root.join(DOCS_DIR);\n\n match cmd.action {\n Some(DocsAction::New(opts)) => create_docs_scaffold(&project_root, opts),\n Some(DocsAction::Hub(opts)) => run_docs_hub(opts),\n None => open_project_docs(&project_root),\n Some(DocsAction::Deploy(opts)) => deploy_docs_hub(&project_root, opts),\n Some(DocsAction::List) => list_docs(&docs_dir),\n Some(DocsAction::Status) => show_status(&project_root, &docs_dir),\n Some(DocsAction::Sync { commits, dry }) => {\n sync_docs(&project_root, &docs_dir, commits, dry)\n }\n Some(DocsAction::Edit { name }) => edit_doc(&docs_dir, &name),\n }\n}\n\n/// List all documentation files.\nfn list_docs(docs_dir: &Path) -> Result<()> {\n if !docs_dir.exists() {\n println!(\"No docs directory. Run `f setup` to create .ai/docs/\");\n return Ok(());\n }\n\n let entries: Vec<_> = fs::read_dir(docs_dir)?\n .filter_map(|e| e.ok())\n .filter(|e| e.path().extension().map(|ext| ext == \"md\").unwrap_or(false))\n .collect();\n\n if entries.is_empty() {\n println!(\"No documentation files in .ai/docs/\");\n return Ok(());\n }\n\n println!(\"Documentation files in .ai/docs/:\\n\");\n for entry in entries {\n let path = entry.path();\n let name = path.file_stem().unwrap_or_default().to_string_lossy();\n\n // Read first line as title\n let title = fs::read_to_string(&path)\n .ok()\n .and_then(|content| {\n content\n .lines()\n .find(|l| l.starts_with(\"# \"))\n .map(|l| l.trim_start_matches(\"# \").to_string())\n })\n .unwrap_or_default();\n\n let size = entry.metadata().map(|m| m.len()).unwrap_or(0);\n let size_str = if size > 1024 {\n format!(\"{:.1}KB\", size as f64 / 1024.0)\n } else {\n format!(\"{}B\", size)\n };\n\n println!(\" {:<15} {:>8} {}\", name, size_str, title);\n }\n\n Ok(())\n}\n\n/// Show documentation status.\nfn show_status(project_root: &Path, docs_dir: &Path) -> Result<()> {\n if !docs_dir.exists() {\n println!(\"No docs directory. Run `f setup` to create .ai/docs/\");\n return Ok(());\n }\n\n // Get recent commits\n let output = Command::new(\"git\")\n .args([\"log\", \"--oneline\", \"-10\"])\n .current_dir(project_root)\n .output()\n .context(\"failed to run git log\")?;\n\n let commits = String::from_utf8_lossy(&output.stdout);\n\n println!(\"Recent commits (may need documentation):\\n\");\n for line in commits.lines() {\n println!(\" {}\", line);\n }\n\n // Check last sync marker\n let marker_path = docs_dir.join(\".last_sync\");\n if marker_path.exists() {\n let last_sync = fs::read_to_string(&marker_path)?;\n println!(\"\\nLast sync: {}\", last_sync.trim());\n } else {\n println!(\"\\nNo sync marker found. Run `f docs sync` to update.\");\n }\n\n // List doc files with modification times\n println!(\"\\nDoc files:\");\n let entries: Vec<_> = fs::read_dir(docs_dir)?\n .filter_map(|e| e.ok())\n .filter(|e| e.path().extension().map(|ext| ext == \"md\").unwrap_or(false))\n .collect();\n\n for entry in entries {\n let path = entry.path();\n let name = path.file_name().unwrap_or_default().to_string_lossy();\n let modified = entry\n .metadata()\n .and_then(|m| m.modified())\n .map(|t| {\n let duration = t.elapsed().unwrap_or_default();\n format_duration(duration)\n })\n .unwrap_or_else(|_| \"unknown\".to_string());\n\n println!(\" {:<20} modified {}\", name, modified);\n }\n\n Ok(())\n}\n\n/// Sync documentation with recent commits.\nfn sync_docs(project_root: &Path, docs_dir: &Path, commits: usize, dry: bool) -> Result<()> {\n if !docs_dir.exists() {\n bail!(\"No docs directory. Run `f setup` to create .ai/docs/\");\n }\n\n // Get recent commit messages and diffs\n let output = Command::new(\"git\")\n .args([\"log\", \"--oneline\", &format!(\"-{}\", commits)])\n .current_dir(project_root)\n .output()\n .context(\"failed to run git log\")?;\n\n let commit_list = String::from_utf8_lossy(&output.stdout);\n\n println!(\"Analyzing {} recent commits...\\n\", commits);\n\n for line in commit_list.lines() {\n println!(\" {}\", line);\n }\n\n if dry {\n println!(\"\\n[Dry run] Would analyze commits and update:\");\n println!(\" - commands.md (if new commands added)\");\n println!(\" - changelog.md (add entries for new features)\");\n println!(\" - architecture.md (if structure changed)\");\n return Ok(());\n }\n\n // Update sync marker\n let marker_path = docs_dir.join(\".last_sync\");\n let now = chrono::Local::now().format(\"%Y-%m-%d %H:%M:%S\").to_string();\n\n // Get current HEAD\n let head = Command::new(\"git\")\n .args([\"rev-parse\", \"--short\", \"HEAD\"])\n .current_dir(project_root)\n .output()\n .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())\n .unwrap_or_default();\n\n fs::write(&marker_path, format!(\"{} ({})\\n\", now, head))?;\n\n println!(\"\\n✓ Sync marker updated\");\n println!(\"\\nTo fully sync docs, use an AI assistant to:\");\n println!(\" 1. Review recent commits\");\n println!(\" 2. Update changelog.md with new features\");\n println!(\" 3. Update commands.md if CLI changed\");\n println!(\" 4. Update architecture.md if structure changed\");\n\n Ok(())\n}\n\n/// Open a doc file in the editor.\nfn edit_doc(docs_dir: &Path, name: &str) -> Result<()> {\n let doc_path = docs_dir.join(format!(\"{}.md\", name));\n\n if !doc_path.exists() {\n bail!(\"Doc file not found: {}.md\", name);\n }\n\n let editor = std::env::var(\"EDITOR\").unwrap_or_else(|_| \"vim\".to_string());\n\n Command::new(&editor)\n .arg(&doc_path)\n .status()\n .with_context(|| format!(\"failed to open {} with {}\", doc_path.display(), editor))?;\n\n Ok(())\n}\n\n/// Format a duration as a human-readable string.\nfn format_duration(duration: std::time::Duration) -> String {\n let secs = duration.as_secs();\n if secs < 60 {\n format!(\"{}s ago\", secs)\n } else if secs < 3600 {\n format!(\"{}m ago\", secs / 60)\n } else if secs < 86400 {\n format!(\"{}h ago\", secs / 3600)\n } else {\n format!(\"{}d ago\", secs / 86400)\n }\n}\n\nfn create_docs_scaffold(project_root: &Path, opts: DocsNewOpts) -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to read current directory\")?;\n let target_root = match opts.path {\n Some(path) => {\n let raw = path.to_string_lossy();\n let expanded = config::expand_path(&raw);\n if expanded.is_absolute() {\n expanded\n } else {\n cwd.join(expanded)\n }\n }\n None => project_root.to_path_buf(),\n };\n create_docs_scaffold_at(&target_root, opts.force)\n}\n\npub fn create_docs_scaffold_at(project_root: &Path, force: bool) -> Result<()> {\n let docs_dir = project_root.join(PROJECT_DOCS_DIR);\n if docs_dir.exists() {\n if docs_dir.is_file() {\n bail!(\"docs/ exists but is a file: {}\", docs_dir.display());\n }\n if !force {\n let template_root = config::expand_path(DEFAULT_DOCS_TEMPLATE_ROOT);\n let template_docs = template_root.join(HUB_CONTENT_ROOT);\n if !template_docs.exists() {\n bail!(\"Docs template not found at {}\", template_docs.display());\n }\n merge_docs_scaffold(&docs_dir, &template_docs)?;\n ensure_index_file(&docs_dir, \"Docs\")?;\n println!(\n \"Docs already exists; merged template into {}\",\n docs_dir.display()\n );\n return Ok(());\n }\n fs::remove_dir_all(&docs_dir)\n .with_context(|| format!(\"failed to remove {}\", docs_dir.display()))?;\n }\n\n let template_root = config::expand_path(DEFAULT_DOCS_TEMPLATE_ROOT);\n let template_docs = template_root.join(HUB_CONTENT_ROOT);\n if !template_docs.exists() {\n bail!(\"Docs template not found at {}\", template_docs.display());\n }\n\n fs::create_dir_all(&docs_dir)\n .with_context(|| format!(\"failed to create {}\", docs_dir.display()))?;\n copy_dir_filtered(&template_docs, &docs_dir, true)?;\n ensure_index_file(&docs_dir, \"Docs\")?;\n\n println!(\"Created {}\", docs_dir.display());\n Ok(())\n}\n\nfn run_docs_hub(opts: DocsHubOpts) -> Result<()> {\n let hub_root = config::expand_path(&opts.hub_root);\n let template_root = config::expand_path(&opts.template_root);\n ensure_docs_hub(&hub_root, &template_root)?;\n\n let code_root = config::expand_path(&opts.code_root);\n let org_root = config::expand_path(&opts.org_root);\n let projects = collect_projects(&code_root, &org_root, !opts.no_ai)?;\n sync_docs_hub_content(&hub_root, &projects)?;\n\n if opts.sync_only {\n println!(\"Docs hub content synced.\");\n return Ok(());\n }\n\n ensure_docs_hub_deps(&hub_root)?;\n run_docs_hub_dev(&hub_root, &opts.host, opts.port, opts.no_open)\n}\n\nfn ensure_docs_hub(hub_root: &Path, template_root: &Path) -> Result<()> {\n if hub_root.join(\"package.json\").exists() {\n sync_docs_hub_template_file(hub_root, template_root, \"mdx-components.tsx\", true)?;\n sync_docs_hub_template_file(hub_root, template_root, \"next.config.mjs\", true)?;\n sync_docs_hub_template_file(hub_root, template_root, \"public/favicon.ico\", false)?;\n sync_docs_hub_template_file(hub_root, template_root, \"wrangler.toml\", false)?;\n ensure_docs_hub_flow_toml(hub_root, template_root)?;\n ensure_docs_hub_config(hub_root)?;\n ensure_docs_hub_layout(hub_root)?;\n return Ok(());\n }\n if !template_root.exists() {\n bail!(\"Docs template root not found: {}\", template_root.display());\n }\n fs::create_dir_all(hub_root)\n .with_context(|| format!(\"failed to create {}\", hub_root.display()))?;\n copy_template_dir(template_root, hub_root)?;\n ensure_docs_hub_config(hub_root)?;\n ensure_docs_hub_layout(hub_root)?;\n Ok(())\n}\n\npub fn ensure_docs_hub_daemon(opts: &DocsHubOpts) -> Result<()> {\n let focus_root = focus_project_root_from_env();\n ensure_docs_hub_daemon_with_focus(opts, focus_root.as_deref())\n}\n\nfn ensure_docs_hub_daemon_with_focus(opts: &DocsHubOpts, focus_root: Option<&Path>) -> Result<()> {\n let hub_root = config::expand_path(&opts.hub_root);\n let template_root = config::expand_path(&opts.template_root);\n println!(\n \"Docs hub: root={} template={}\",\n hub_root.display(),\n template_root.display()\n );\n ensure_docs_hub(&hub_root, &template_root)?;\n\n let code_root = config::expand_path(&opts.code_root);\n let org_root = config::expand_path(&opts.org_root);\n let focus_project =\n focus_root.and_then(|root| project_docs_for_root(root, &code_root, &org_root, !opts.no_ai));\n\n if let Some(project) = focus_project {\n println!(\n \"Docs hub: syncing focused project {} ({})\",\n project.name, project.slug\n );\n let expected_path = hub_root.join(HUB_CONTENT_ROOT).join(&project.slug);\n let focus_match = read_docs_hub_focus_marker(&hub_root)\n .map(|slug| slug == project.slug)\n .unwrap_or(false);\n let hub_running = docs_hub_healthy(&opts.host, opts.port);\n if !(focus_match && expected_path.exists() && hub_running) {\n sync_docs_hub_content_focus(&hub_root, &project)?;\n } else {\n println!(\"Docs hub: already running; skipping sync.\");\n }\n } else {\n let projects = collect_projects(&code_root, &org_root, !opts.no_ai)?;\n println!(\n \"Docs hub: syncing {} project(s) from {} and {}\",\n projects.len(),\n code_root.display(),\n org_root.display()\n );\n sync_docs_hub_content(&hub_root, &projects)?;\n }\n\n let needs_reset = docs_hub_needs_reset(&hub_root)?;\n let was_running = docs_hub_healthy(&opts.host, opts.port);\n if needs_reset {\n println!(\"Docs hub: stale index detected; resetting cache.\");\n if let Some(pid) = load_docs_hub_pid()? {\n terminate_process(pid).ok();\n remove_docs_hub_pid().ok();\n }\n kill_docs_hub_by_port(opts.port).ok();\n remove_docs_hub_cache(&hub_root).ok();\n }\n\n if was_running && !needs_reset && focus_root.is_none() {\n println!(\"Docs hub: restarting to apply latest docs.\");\n if let Some(pid) = load_docs_hub_pid()? {\n terminate_process(pid).ok();\n remove_docs_hub_pid().ok();\n }\n kill_docs_hub_by_port(opts.port).ok();\n remove_docs_hub_cache(&hub_root).ok();\n }\n\n if !needs_reset && !was_running {\n if let Some(pid) = load_docs_hub_pid()? {\n if process_alive(pid)? {\n println!(\n \"Docs hub: already running at http://{}:{}\",\n opts.host, opts.port\n );\n return Ok(());\n }\n remove_docs_hub_pid().ok();\n }\n }\n\n if was_running && !needs_reset {\n return Ok(());\n }\n\n ensure_docs_hub_deps(&hub_root)?;\n start_docs_hub_daemon(&hub_root, &opts.host, opts.port)?;\n println!(\n \"Docs hub: starting dev server on http://{}:{}\",\n opts.host, opts.port\n );\n wait_for_port(&opts.host, opts.port, std::time::Duration::from_secs(10));\n Ok(())\n}\n\npub fn stop_docs_hub_daemon() -> Result<()> {\n if let Some(pid) = load_docs_hub_pid()? {\n terminate_process(pid).ok();\n remove_docs_hub_pid().ok();\n }\n kill_docs_hub_by_port(4410).ok();\n Ok(())\n}\n\nfn ensure_docs_hub_deps(hub_root: &Path) -> Result<()> {\n let node_modules = hub_root.join(\"node_modules\");\n if node_modules.exists() {\n return Ok(());\n }\n if which(\"bun\").is_ok() {\n run_command(\"bun\", &[\"install\"], hub_root)\n } else if which(\"npm\").is_ok() {\n run_command(\"npm\", &[\"install\"], hub_root)\n } else {\n bail!(\"bun or npm is required to install docs hub dependencies\");\n }\n}\n\nfn run_docs_hub_dev(hub_root: &Path, host: &str, port: u16, no_open: bool) -> Result<()> {\n let mut cmd = if which(\"bun\").is_ok() {\n let port_arg = port.to_string();\n let host_arg = host.to_string();\n let mut cmd = Command::new(\"bun\");\n cmd.args([\n \"run\",\n \"dev\",\n \"--\",\n \"--port\",\n &port_arg,\n \"--hostname\",\n &host_arg,\n ]);\n cmd\n } else if which(\"npm\").is_ok() {\n let port_arg = port.to_string();\n let host_arg = host.to_string();\n let mut cmd = Command::new(\"npm\");\n cmd.args([\n \"run\",\n \"dev\",\n \"--\",\n \"--port\",\n &port_arg,\n \"--hostname\",\n &host_arg,\n ]);\n cmd\n } else {\n bail!(\"bun or npm is required to run docs hub dev server\");\n };\n\n let mut child = cmd\n .current_dir(hub_root)\n .stdout(std::process::Stdio::inherit())\n .stderr(std::process::Stdio::inherit())\n .spawn()\n .context(\"failed to start docs hub dev server\")?;\n\n if !no_open {\n let url = format!(\"http://{}:{}\", host, port);\n wait_for_port(host, port, std::time::Duration::from_secs(10));\n open_in_browser(&url);\n }\n\n let status = child.wait().context(\"failed to wait on docs hub\")?;\n if !status.success() {\n bail!(\"docs hub dev server exited with error\");\n }\n Ok(())\n}\n\nfn start_docs_hub_daemon(hub_root: &Path, host: &str, port: u16) -> Result<()> {\n let mut cmd = if which(\"bun\").is_ok() {\n let port_arg = port.to_string();\n let host_arg = host.to_string();\n let mut cmd = Command::new(\"bun\");\n cmd.args([\n \"run\",\n \"dev\",\n \"--\",\n \"--port\",\n &port_arg,\n \"--hostname\",\n &host_arg,\n ]);\n cmd\n } else if which(\"npm\").is_ok() {\n let port_arg = port.to_string();\n let host_arg = host.to_string();\n let mut cmd = Command::new(\"npm\");\n cmd.args([\n \"run\",\n \"dev\",\n \"--\",\n \"--port\",\n &port_arg,\n \"--hostname\",\n &host_arg,\n ]);\n cmd\n } else {\n bail!(\"bun or npm is required to run docs hub dev server\");\n };\n\n let child = cmd\n .current_dir(hub_root)\n .stdin(std::process::Stdio::null())\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .spawn()\n .context(\"failed to start docs hub daemon\")?;\n persist_docs_hub_pid(child.id())?;\n Ok(())\n}\n\nfn open_in_browser(url: &str) {\n let _ = Command::new(\"open\").arg(url).status();\n}\n\nstruct DirGuard {\n previous: PathBuf,\n}\n\nimpl DirGuard {\n fn new(path: &Path) -> Result<Self> {\n let previous = std::env::current_dir().context(\"failed to read current directory\")?;\n std::env::set_current_dir(path)\n .with_context(|| format!(\"failed to switch to {}\", path.display()))?;\n Ok(Self { previous })\n }\n}\n\nimpl Drop for DirGuard {\n fn drop(&mut self) {\n let _ = std::env::set_current_dir(&self.previous);\n }\n}\n\nfn run_command(cmd: &str, args: &[&str], cwd: &Path) -> Result<()> {\n let status = Command::new(cmd)\n .args(args)\n .current_dir(cwd)\n .status()\n .with_context(|| format!(\"failed to run {}\", cmd))?;\n if !status.success() {\n bail!(\"{} failed\", cmd);\n }\n Ok(())\n}\n\nfn attach_pages_domain(hub_root: &Path, project: &str, domain: &str) -> Result<()> {\n println!(\"Attaching custom domain {domain} to {project}...\");\n let mut cmd = if which(\"bun\").is_ok() {\n let mut cmd = Command::new(\"bun\");\n cmd.args([\"x\", \"wrangler\", \"pages\", \"domain\", \"add\", project, domain]);\n cmd\n } else if which(\"npx\").is_ok() {\n let mut cmd = Command::new(\"npx\");\n cmd.args([\"wrangler\", \"pages\", \"domain\", \"add\", project, domain]);\n cmd\n } else if which(\"npm\").is_ok() {\n let mut cmd = Command::new(\"npm\");\n cmd.args([\n \"exec\", \"wrangler\", \"--\", \"pages\", \"domain\", \"add\", project, domain,\n ]);\n cmd\n } else {\n bail!(\"bun, npx, or npm is required to run wrangler\");\n };\n let status = cmd\n .current_dir(hub_root)\n .stdin(std::process::Stdio::inherit())\n .stdout(std::process::Stdio::inherit())\n .stderr(std::process::Stdio::inherit())\n .status()\n .context(\"failed to run wrangler pages domain add\")?;\n if !status.success() {\n bail!(\"wrangler pages domain add failed\");\n }\n Ok(())\n}\n\nfn prompt_line(message: &str, default: Option<&str>) -> Result<String> {\n if let Some(default) = default {\n print!(\"{message} [{default}]: \");\n } else {\n print!(\"{message}: \");\n }\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n return Ok(default.unwrap_or(\"\").to_string());\n }\n Ok(trimmed.to_string())\n}\n\nfn prompt_yes_no(message: &str, default_yes: bool) -> Result<bool> {\n let prompt = if default_yes { \"[Y/n]\" } else { \"[y/N]\" };\n print!(\"{message} {prompt}: \");\n io::stdout().flush()?;\n if io::stdin().is_terminal() {\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n if answer.is_empty() {\n return Ok(default_yes);\n }\n return Ok(answer == \"y\" || answer == \"yes\");\n }\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n if answer.is_empty() {\n return Ok(default_yes);\n }\n Ok(answer == \"y\" || answer == \"yes\")\n}\n\nfn wait_for_port(host: &str, port: u16, timeout: std::time::Duration) {\n let start = std::time::Instant::now();\n while start.elapsed() < timeout {\n if std::net::TcpStream::connect((host, port)).is_ok() {\n return;\n }\n std::thread::sleep(std::time::Duration::from_millis(200));\n }\n}\n\nfn docs_hub_healthy(host: &str, port: u16) -> bool {\n std::net::TcpStream::connect((host, port)).is_ok()\n}\n\nfn docs_hub_pid_path() -> PathBuf {\n config::global_state_dir().join(\"docs-hub.pid\")\n}\n\nfn load_docs_hub_pid() -> Result<Option<u32>> {\n let path = docs_hub_pid_path();\n if !path.exists() {\n return Ok(None);\n }\n let contents =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let pid: u32 = contents.trim().parse().ok().unwrap_or(0);\n if pid == 0 { Ok(None) } else { Ok(Some(pid)) }\n}\n\nfn persist_docs_hub_pid(pid: u32) -> Result<()> {\n let path = docs_hub_pid_path();\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n fs::write(&path, pid.to_string())\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(())\n}\n\nfn remove_docs_hub_pid() -> Result<()> {\n let path = docs_hub_pid_path();\n if path.exists() {\n fs::remove_file(path).ok();\n }\n Ok(())\n}\n\nfn process_alive(pid: u32) -> Result<bool> {\n #[cfg(unix)]\n {\n let status = Command::new(\"kill\").arg(\"-0\").arg(pid.to_string()).status();\n return Ok(status.map(|s| s.success()).unwrap_or(false));\n }\n\n #[cfg(windows)]\n {\n let output = Command::new(\"tasklist\")\n .output()\n .context(\"failed to invoke tasklist\")?;\n if !output.status.success() {\n return Ok(false);\n }\n let needle = pid.to_string();\n let body = String::from_utf8_lossy(&output.stdout);\n Ok(body.lines().any(|line| line.contains(&needle)))\n }\n}\n\nfn terminate_process(pid: u32) -> Result<()> {\n #[cfg(unix)]\n {\n Command::new(\"kill\")\n .arg(pid.to_string())\n .status()\n .context(\"failed to invoke kill\")?;\n return Ok(());\n }\n\n #[cfg(windows)]\n {\n Command::new(\"taskkill\")\n .args([\"/PID\", &pid.to_string(), \"/F\"])\n .status()\n .context(\"failed to invoke taskkill\")?;\n Ok(())\n }\n}\n\nfn open_project_docs(project_root: &Path) -> Result<()> {\n let code_root = config::expand_path(\"~/code\");\n let org_root = config::expand_path(\"~/org\");\n let Some(project) = project_docs_for_root(project_root, &code_root, &org_root, false) else {\n bail!(\"Unable to resolve docs for {}\", project_root.display());\n };\n\n let hub_opts = DocsHubOpts {\n host: \"127.0.0.1\".to_string(),\n port: 4410,\n hub_root: \"~/.config/flow/docs-hub\".to_string(),\n template_root: DEFAULT_DOCS_TEMPLATE_ROOT.to_string(),\n code_root: \"~/code\".to_string(),\n org_root: \"~/org\".to_string(),\n no_ai: true,\n no_open: true,\n sync_only: false,\n };\n ensure_docs_hub_daemon_with_focus(&hub_opts, Some(project_root))?;\n\n if !(project_root.starts_with(&code_root) || project_root.starts_with(&org_root)) {\n println!(\n \"Docs hub only indexes ~/code and ~/org; {} may not be available.\",\n project_root.display()\n );\n }\n\n let url = format!(\n \"http://{}:{}/{}\",\n hub_opts.host, hub_opts.port, project.slug\n );\n println!(\n \"Docs hub open: project={} slug={}\",\n project_root.display(),\n project.slug\n );\n open_in_browser(&url);\n println!(\"Opened {url}\");\n Ok(())\n}\n\nfn deploy_docs_hub(project_root: &Path, opts: DocsDeployOpts) -> Result<()> {\n let code_root = config::expand_path(\"~/code\");\n let org_root = config::expand_path(\"~/org\");\n let Some(project) = project_docs_for_root(project_root, &code_root, &org_root, false) else {\n bail!(\"Unable to resolve docs for {}\", project_root.display());\n };\n\n let default_project = if !project.slug.is_empty() {\n project.slug.clone()\n } else {\n slugify_token(&project.name)\n };\n let project_name = opts.project.as_deref().unwrap_or(&default_project).trim();\n let project_name = if project_name.is_empty() {\n default_project.clone()\n } else {\n slugify_token(project_name)\n };\n\n let domain = if let Some(domain) = opts.domain.as_deref() {\n let trimmed = domain.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n }\n } else if opts.yes {\n None\n } else {\n let input = prompt_line(\"Custom domain (leave blank to skip)\", None)?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n }\n };\n\n if !opts.yes {\n println!(\"Docs deploy:\");\n println!(\" Project: {}\", project_name);\n println!(\" Source: {}\", project_root.display());\n if let Some(domain) = &domain {\n println!(\" Domain: {}\", domain);\n } else {\n println!(\" Domain: (none)\");\n }\n if !prompt_yes_no(\"Proceed with deploy?\", true)? {\n println!(\"Canceled.\");\n return Ok(());\n }\n }\n\n let hub_root = config::expand_path(\"~/.config/flow/docs-hub\");\n let template_root = config::expand_path(DEFAULT_DOCS_TEMPLATE_ROOT);\n ensure_docs_hub(&hub_root, &template_root)?;\n println!(\n \"Docs hub: syncing focused project {} ({})\",\n project.name, project.slug\n );\n sync_docs_hub_content_focus(&hub_root, &project)?;\n ensure_docs_hub_deps(&hub_root)?;\n\n let _guard = DirGuard::new(&hub_root)?;\n unsafe {\n std::env::set_var(\"FLOW_DOCS_PROJECT\", &project_name);\n }\n deploy::run(DeployCommand { action: None })?;\n\n if let Some(domain) = &domain {\n attach_pages_domain(&hub_root, &project_name, domain)?;\n }\n\n println!(\"Docs deploy complete.\");\n Ok(())\n}\n\n#[derive(Debug, Clone)]\nstruct ProjectDocs {\n name: String,\n slug: String,\n slug_base: String,\n slug_path: String,\n root: PathBuf,\n docs_dir: Option<PathBuf>,\n ai_docs_dir: Option<PathBuf>,\n ai_web_dir: Option<PathBuf>,\n}\n\nfn collect_projects(\n code_root: &Path,\n org_root: &Path,\n include_ai: bool,\n) -> Result<Vec<ProjectDocs>> {\n let mut projects = Vec::new();\n collect_projects_from_root(&mut projects, code_root, \"code\", include_ai)?;\n collect_projects_from_root(&mut projects, org_root, \"org\", include_ai)?;\n resolve_project_slugs(&mut projects);\n projects.sort_by(|a, b| a.slug.cmp(&b.slug));\n Ok(projects)\n}\n\nfn collect_projects_from_root(\n projects: &mut Vec<ProjectDocs>,\n root: &Path,\n scope: &str,\n include_ai: bool,\n) -> Result<()> {\n if !root.exists() {\n return Ok(());\n }\n\n let mut stack = vec![root.to_path_buf()];\n while let Some(dir) = stack.pop() {\n let name = dir.file_name().and_then(|s| s.to_str()).unwrap_or(\"\");\n if should_skip_dir(name) {\n continue;\n }\n\n let docs_dir = dir.join(PROJECT_DOCS_DIR);\n let ai_docs_dir = dir.join(\".ai\").join(\"docs\");\n let ai_web_dir = dir.join(\".ai\").join(\"web\");\n let has_docs = docs_dir.is_dir();\n let has_ai = include_ai && ai_docs_dir.is_dir();\n let has_web = include_ai && ai_web_dir.is_dir();\n\n if has_docs || has_ai || has_web {\n let path_slug = slug_for_path(&dir, root, Some(scope));\n let name = project_name_from_flow_toml(&dir).unwrap_or_else(|| {\n dir.file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(&path_slug)\n .to_string()\n });\n let slug_base = slugify_project_name(&name, &path_slug);\n projects.push(ProjectDocs {\n name,\n slug: slug_base.clone(),\n slug_base,\n slug_path: path_slug,\n root: dir.clone(),\n docs_dir: if has_docs { Some(docs_dir) } else { None },\n ai_docs_dir: if has_ai { Some(ai_docs_dir) } else { None },\n ai_web_dir: if has_web { Some(ai_web_dir) } else { None },\n });\n continue;\n }\n\n let entries = match fs::read_dir(&dir) {\n Ok(entries) => entries,\n Err(_) => continue,\n };\n\n for entry in entries.flatten() {\n let path = entry.path();\n let file_type = match entry.file_type() {\n Ok(ft) => ft,\n Err(_) => continue,\n };\n if !file_type.is_dir() {\n continue;\n }\n let child_name = entry.file_name().to_string_lossy().to_string();\n if should_skip_dir(&child_name) {\n continue;\n }\n stack.push(path);\n }\n }\n\n Ok(())\n}\n\nfn slug_for_path(path: &Path, root: &Path, prefix: Option<&str>) -> String {\n let relative = path.strip_prefix(root).unwrap_or(path);\n let mut slug = relative.to_string_lossy().replace('\\\\', \"/\");\n slug = slug.trim().trim_start_matches('/').to_string();\n if let Some(prefix) = prefix {\n if slug.is_empty() {\n return prefix.to_string();\n }\n return format!(\"{prefix}/{slug}\");\n }\n if slug.is_empty() {\n \"root\".to_string()\n } else {\n slug\n }\n}\n\nfn project_name_from_flow_toml(project_root: &Path) -> Option<String> {\n let flow_path = project_root.join(\"flow.toml\");\n if !flow_path.exists() {\n return None;\n }\n let cfg = config::load(&flow_path).ok()?;\n cfg.project_name\n}\n\nfn slugify_project_name(name: &str, fallback: &str) -> String {\n let slug = slugify_token(name);\n if slug.is_empty() {\n slugify_token(fallback)\n } else {\n slug\n }\n}\n\nfn slugify_token(input: &str) -> String {\n let mut out = String::new();\n let mut last_dash = false;\n for ch in input.chars() {\n let ch = ch.to_ascii_lowercase();\n if ch.is_ascii_alphanumeric() {\n out.push(ch);\n last_dash = false;\n } else if matches!(ch, '-' | '_' | ' ' | '.' | '/' | '\\\\') {\n if !last_dash {\n out.push('-');\n last_dash = true;\n }\n }\n }\n let trimmed = out.trim_matches('-').to_string();\n trimmed\n}\n\nfn resolve_project_slugs(projects: &mut [ProjectDocs]) {\n let mut counts = std::collections::HashMap::new();\n for project in projects.iter() {\n *counts.entry(project.slug_base.clone()).or_insert(0usize) += 1;\n }\n let mut used = std::collections::HashSet::new();\n for project in projects.iter_mut() {\n let mut slug = if project.slug_base.is_empty() {\n project.slug_path.clone()\n } else if counts.get(&project.slug_base).copied().unwrap_or(0) > 1 {\n project.slug_path.clone()\n } else {\n project.slug_base.clone()\n };\n if slug.is_empty() {\n slug = project.slug_path.clone();\n }\n let mut candidate = slug.clone();\n let mut counter = 2usize;\n while used.contains(&candidate) {\n candidate = format!(\"{}-{}\", slug, counter);\n counter += 1;\n }\n used.insert(candidate.clone());\n project.slug = candidate;\n }\n}\n\nfn project_slug_candidates(\n project_root: &Path,\n code_root: &Path,\n org_root: &Path,\n) -> (String, String) {\n let scope = if project_root.starts_with(org_root) {\n \"org\"\n } else if project_root.starts_with(code_root) {\n \"code\"\n } else {\n \"project\"\n };\n let path_slug = if scope == \"project\" {\n project_root\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(\"project\")\n .to_string()\n } else {\n slug_for_path(\n project_root,\n if scope == \"org\" { org_root } else { code_root },\n Some(scope),\n )\n };\n let name = project_name_from_flow_toml(project_root).unwrap_or_else(|| {\n project_root\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(&path_slug)\n .to_string()\n });\n let slug_base = slugify_project_name(&name, &path_slug);\n (slug_base, path_slug)\n}\n\nfn focus_project_root_from_env() -> Option<PathBuf> {\n let raw = std::env::var(\"FLOW_DOCS_FOCUS\").ok()?;\n let value = raw.trim();\n if value.is_empty() {\n return None;\n }\n let lower = value.to_ascii_lowercase();\n let root = if matches!(lower.as_str(), \"1\" | \"true\" | \"yes\") {\n resolve_project_root_from_cwd()\n } else {\n let expanded = config::expand_path(value);\n if expanded.is_file() && expanded.file_name().and_then(|s| s.to_str()) == Some(\"flow.toml\")\n {\n expanded.parent().map(|p| p.to_path_buf())\n } else if expanded.is_dir() {\n Some(expanded)\n } else {\n None\n }\n }?;\n Some(root)\n}\n\nfn resolve_project_root_from_cwd() -> Option<PathBuf> {\n let cwd = std::env::current_dir().ok()?;\n if cwd.join(\"flow.toml\").exists() {\n return Some(cwd);\n }\n let flow_path = find_flow_toml(&cwd)?;\n flow_path.parent().map(|p| p.to_path_buf())\n}\n\nfn find_flow_toml(start: &Path) -> Option<PathBuf> {\n let mut current = start.to_path_buf();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\nfn project_docs_for_root(\n project_root: &Path,\n code_root: &Path,\n org_root: &Path,\n include_ai: bool,\n) -> Option<ProjectDocs> {\n if !project_root.exists() {\n return None;\n }\n let docs_dir = project_root.join(PROJECT_DOCS_DIR);\n let ai_docs_dir = project_root.join(\".ai\").join(\"docs\");\n let ai_web_dir = project_root.join(\".ai\").join(\"web\");\n let has_docs = docs_dir.is_dir();\n let has_ai = include_ai && ai_docs_dir.is_dir();\n let has_web = include_ai && ai_web_dir.is_dir();\n\n let name = project_name_from_flow_toml(project_root).unwrap_or_else(|| {\n project_root\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(\"project\")\n .to_string()\n });\n let (slug_base, slug_path) = project_slug_candidates(project_root, code_root, org_root);\n let mut project = ProjectDocs {\n name,\n slug: slug_base.clone(),\n slug_base,\n slug_path,\n root: project_root.to_path_buf(),\n docs_dir: if has_docs { Some(docs_dir) } else { None },\n ai_docs_dir: if has_ai { Some(ai_docs_dir) } else { None },\n ai_web_dir: if has_web { Some(ai_web_dir) } else { None },\n };\n if project.slug.is_empty() {\n project.slug = project.slug_path.clone();\n }\n let mut projects = vec![project];\n resolve_project_slugs(&mut projects);\n projects.into_iter().next()\n}\n\nfn should_skip_dir(name: &str) -> bool {\n if name.starts_with('.') {\n return true;\n }\n matches!(\n name,\n \"node_modules\"\n | \"target\"\n | \"dist\"\n | \"build\"\n | \".git\"\n | \".hg\"\n | \".svn\"\n | \"__pycache__\"\n | \".pytest_cache\"\n | \".mypy_cache\"\n | \"venv\"\n | \".venv\"\n | \"vendor\"\n | \"Pods\"\n | \".cargo\"\n | \".rustup\"\n | \".next\"\n | \".turbo\"\n | \".cache\"\n )\n}\n\nfn sync_docs_hub_content(hub_root: &Path, projects: &[ProjectDocs]) -> Result<()> {\n let content_root = hub_root.join(HUB_CONTENT_ROOT);\n let projects_root = content_root.clone();\n clear_docs_hub_focus_marker(hub_root).ok();\n\n if content_root.exists() {\n fs::remove_dir_all(&content_root)\n .with_context(|| format!(\"failed to remove {}\", content_root.display()))?;\n }\n fs::create_dir_all(&projects_root)\n .with_context(|| format!(\"failed to create {}\", projects_root.display()))?;\n\n println!(\n \"Docs hub: writing {} project(s) to {}\",\n projects.len(),\n projects_root.display()\n );\n for project in projects {\n let project_root = projects_root.join(&project.slug);\n fs::create_dir_all(&project_root)\n .with_context(|| format!(\"failed to create {}\", project_root.display()))?;\n\n if let Some(docs_dir) = &project.docs_dir {\n copy_docs_dir_with_frontmatter(docs_dir, &project_root, true)?;\n }\n if let Some(ai_docs_dir) = &project.ai_docs_dir {\n copy_docs_dir_with_frontmatter(ai_docs_dir, &project_root, false)?;\n }\n if let Some(ai_web_dir) = &project.ai_web_dir {\n copy_docs_dir_with_frontmatter(ai_web_dir, &project_root, false)?;\n }\n\n let index_path = project_root.join(\"index.mdx\");\n if let Some(content) = project_readme_content(&project.root, &project.name)? {\n let index_md = project_root.join(\"index.md\");\n if index_md.exists() {\n fs::remove_file(&index_md).ok();\n }\n fs::write(&index_path, content)\n .with_context(|| format!(\"failed to write {}\", index_path.display()))?;\n } else if !index_path.exists() {\n let mut lines = Vec::new();\n lines.push(\"---\".to_string());\n lines.push(format!(\"title: {}\", quote_yaml_string(&project.name)));\n lines.push(\"---\".to_string());\n lines.push(String::new());\n fs::write(&index_path, lines.join(\"\\n\"))\n .with_context(|| format!(\"failed to write {}\", index_path.display()))?;\n }\n }\n\n let root_index = content_root.join(\"index.mdx\");\n fs::write(&root_index, render_root_index(projects))\n .with_context(|| format!(\"failed to write {}\", root_index.display()))?;\n\n Ok(())\n}\n\nfn sync_docs_hub_content_focus(hub_root: &Path, project: &ProjectDocs) -> Result<()> {\n let content_root = hub_root.join(HUB_CONTENT_ROOT);\n let projects_root = content_root.clone();\n\n if content_root.exists() {\n fs::remove_dir_all(&content_root)\n .with_context(|| format!(\"failed to remove {}\", content_root.display()))?;\n }\n fs::create_dir_all(&projects_root)\n .with_context(|| format!(\"failed to create {}\", projects_root.display()))?;\n\n let project_root = projects_root.join(&project.slug);\n fs::create_dir_all(&project_root)\n .with_context(|| format!(\"failed to create {}\", project_root.display()))?;\n\n if let Some(docs_dir) = &project.docs_dir {\n copy_docs_dir_with_frontmatter(docs_dir, &project_root, true)?;\n }\n if let Some(ai_docs_dir) = &project.ai_docs_dir {\n copy_docs_dir_with_frontmatter(ai_docs_dir, &project_root, false)?;\n }\n if let Some(ai_web_dir) = &project.ai_web_dir {\n copy_docs_dir_with_frontmatter(ai_web_dir, &project_root, false)?;\n }\n\n let index_path = project_root.join(\"index.mdx\");\n if let Some(content) = project_readme_content(&project.root, &project.name)? {\n let index_md = project_root.join(\"index.md\");\n if index_md.exists() {\n fs::remove_file(&index_md).ok();\n }\n fs::write(&index_path, content)\n .with_context(|| format!(\"failed to write {}\", index_path.display()))?;\n } else if !index_path.exists() {\n let mut lines = Vec::new();\n lines.push(\"---\".to_string());\n lines.push(format!(\"title: {}\", quote_yaml_string(&project.name)));\n lines.push(\"---\".to_string());\n lines.push(String::new());\n fs::write(&index_path, lines.join(\"\\n\"))\n .with_context(|| format!(\"failed to write {}\", index_path.display()))?;\n }\n\n let root_index = content_root.join(\"index.mdx\");\n fs::write(&root_index, render_root_index(&[project.clone()]))\n .with_context(|| format!(\"failed to write {}\", root_index.display()))?;\n write_docs_hub_focus_marker(hub_root, &project.slug)?;\n Ok(())\n}\n\nfn render_root_index(projects: &[ProjectDocs]) -> String {\n let mut lines = Vec::new();\n lines.push(\"---\".to_string());\n lines.push(\"title: Docs\".to_string());\n lines.push(\"---\".to_string());\n lines.push(String::new());\n lines.push(\"# Docs Hub\".to_string());\n lines.push(String::new());\n if projects.is_empty() {\n lines.push(\"No docs found yet.\".to_string());\n lines.push(String::new());\n lines\n .push(\"Add `docs/` or `.ai/docs` to a project and run `f docs hub` again.\".to_string());\n lines.push(String::new());\n return lines.join(\"\\n\");\n }\n lines.push(\"Projects:\".to_string());\n lines.push(String::new());\n for project in projects {\n lines.push(format!(\"- [{}](./{})\", project.name, project.slug));\n }\n lines.push(String::new());\n lines.join(\"\\n\")\n}\n\nfn read_docs_hub_focus_marker(hub_root: &Path) -> Option<String> {\n let path = hub_root.join(DOCS_HUB_FOCUS_FILE);\n let value = fs::read_to_string(path).ok()?;\n let trimmed = value.trim();\n if trimmed.is_empty() {\n return None;\n }\n Some(trimmed.to_string())\n}\n\nfn write_docs_hub_focus_marker(hub_root: &Path, slug: &str) -> Result<()> {\n let path = hub_root.join(DOCS_HUB_FOCUS_FILE);\n fs::write(&path, slug).with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(())\n}\n\nfn clear_docs_hub_focus_marker(hub_root: &Path) -> Result<()> {\n let path = hub_root.join(DOCS_HUB_FOCUS_FILE);\n if path.exists() {\n fs::remove_file(&path).ok();\n }\n Ok(())\n}\n\nfn project_readme_content(project_root: &Path, title: &str) -> Result<Option<String>> {\n let readme_path = find_project_readme(project_root);\n let Some(readme_path) = readme_path else {\n return Ok(None);\n };\n let content = fs::read_to_string(&readme_path)\n .with_context(|| format!(\"failed to read {}\", readme_path.display()))?;\n let sanitized = sanitize_markdown_content(&content);\n let stripped = strip_frontmatter(&sanitized);\n let updated = ensure_frontmatter_title(&stripped, title);\n Ok(Some(updated))\n}\n\nfn find_project_readme(project_root: &Path) -> Option<PathBuf> {\n let candidates = [\"README.mdx\", \"README.md\", \"readme.mdx\", \"readme.md\"];\n for candidate in candidates {\n let path = project_root.join(candidate);\n if path.exists() {\n return Some(path);\n }\n }\n None\n}\n\nfn ensure_index_file(dir: &Path, title: &str) -> Result<()> {\n let index_md = dir.join(\"index.md\");\n let index_mdx = dir.join(\"index.mdx\");\n if index_md.exists() || index_mdx.exists() {\n return Ok(());\n }\n let content = format!(\"---\\ntitle: {}\\n---\\n\", title);\n fs::write(&index_mdx, content)\n .with_context(|| format!(\"failed to write {}\", index_mdx.display()))?;\n Ok(())\n}\n\nfn copy_dir_filtered(from: &Path, to: &Path, allow_assets: bool) -> Result<()> {\n fs::create_dir_all(to).with_context(|| format!(\"failed to create {}\", to.display()))?;\n for entry in fs::read_dir(from).with_context(|| format!(\"failed to read {}\", from.display()))? {\n let entry = entry?;\n let path = entry.path();\n let file_type = entry.file_type()?;\n let name = entry.file_name().to_string_lossy().to_string();\n if should_skip_dir(&name) {\n continue;\n }\n let dest = to.join(entry.file_name());\n if file_type.is_dir() {\n copy_dir_filtered(&path, &dest, allow_assets)?;\n } else if file_type.is_file() {\n if should_copy_doc_file(&path, allow_assets) {\n fs::copy(&path, &dest)\n .with_context(|| format!(\"failed to copy {}\", path.display()))?;\n }\n }\n }\n Ok(())\n}\n\nfn should_copy_doc_file(path: &Path, allow_assets: bool) -> bool {\n match path.extension().and_then(|ext| ext.to_str()) {\n Some(\"md\") | Some(\"mdx\") => true,\n _ => allow_assets,\n }\n}\n\nfn merge_docs_scaffold(from: &Path, to: &Path) -> Result<()> {\n copy_dir_filtered_missing(from, to, true)\n}\n\nfn copy_dir_filtered_missing(from: &Path, to: &Path, allow_assets: bool) -> Result<()> {\n fs::create_dir_all(to).with_context(|| format!(\"failed to create {}\", to.display()))?;\n for entry in fs::read_dir(from).with_context(|| format!(\"failed to read {}\", from.display()))? {\n let entry = entry?;\n let path = entry.path();\n let file_type = entry.file_type()?;\n let name = entry.file_name().to_string_lossy().to_string();\n if should_skip_dir(&name) {\n continue;\n }\n let dest = to.join(entry.file_name());\n if file_type.is_dir() {\n copy_dir_filtered_missing(&path, &dest, allow_assets)?;\n } else if file_type.is_file() {\n if dest.exists() {\n continue;\n }\n if should_copy_doc_file(&path, allow_assets) {\n fs::copy(&path, &dest)\n .with_context(|| format!(\"failed to copy {}\", path.display()))?;\n }\n }\n }\n Ok(())\n}\n\nfn copy_docs_dir_with_frontmatter(from: &Path, to: &Path, overwrite: bool) -> Result<()> {\n fs::create_dir_all(to).with_context(|| format!(\"failed to create {}\", to.display()))?;\n for entry in fs::read_dir(from).with_context(|| format!(\"failed to read {}\", from.display()))? {\n let entry = entry?;\n let path = entry.path();\n let file_type = entry.file_type()?;\n let name = entry.file_name().to_string_lossy().to_string();\n if should_skip_dir(&name) {\n continue;\n }\n let dest = to.join(entry.file_name());\n if file_type.is_dir() {\n copy_docs_dir_with_frontmatter(&path, &dest, overwrite)?;\n } else if file_type.is_file() {\n if !overwrite && dest.exists() {\n continue;\n }\n let ext = path.extension().and_then(|ext| ext.to_str()).unwrap_or(\"\");\n if ext == \"toml\" {\n let dest = dest.with_extension(\"mdx\");\n if !overwrite && dest.exists() {\n continue;\n }\n let content = fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n let body = format!(\"```toml\\n{}\\n```\", content.trim_end_matches('\\n'));\n let title = title_from_filename(&path);\n let updated = ensure_frontmatter_title(&body, &title);\n fs::write(&dest, updated.as_bytes())\n .with_context(|| format!(\"failed to write {}\", dest.display()))?;\n continue;\n }\n if !matches!(ext, \"md\" | \"mdx\") {\n continue;\n }\n let content = fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n let sanitized = sanitize_markdown_content(&content);\n let stripped = strip_frontmatter(&sanitized);\n let title = derive_title(&stripped, &path);\n let updated = ensure_frontmatter_title(&stripped, &title);\n fs::write(&dest, updated.as_bytes())\n .with_context(|| format!(\"failed to write {}\", dest.display()))?;\n }\n }\n Ok(())\n}\n\nfn derive_title(content: &str, path: &Path) -> String {\n if let Some(title) = extract_title_from_frontmatter(content) {\n return sanitize_title(&title, path);\n }\n if let Some(title) = first_heading(content) {\n return sanitize_title(&title, path);\n }\n title_from_filename(path)\n}\n\nfn extract_title_from_frontmatter(content: &str) -> Option<String> {\n let Some((frontmatter, _)) = split_frontmatter(content) else {\n return None;\n };\n for line in frontmatter.lines() {\n let trimmed = line.trim();\n if let Some(value) = trimmed.strip_prefix(\"title:\") {\n let title = value.trim().trim_matches('\"').trim_matches('\\'');\n if !title.is_empty() {\n return Some(title.to_string());\n }\n }\n }\n None\n}\n\nfn first_heading(content: &str) -> Option<String> {\n let rest = split_frontmatter(content)\n .map(|(_, rest)| rest)\n .unwrap_or_else(|| content.to_string());\n for line in rest.lines() {\n let trimmed = line.trim_start();\n if let Some(title) = trimmed.strip_prefix(\"# \") {\n let title = title.trim();\n if !title.is_empty() {\n return Some(title.to_string());\n }\n }\n }\n None\n}\n\nfn title_from_filename(path: &Path) -> String {\n let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"Doc\");\n let mut title = stem.replace('-', \" \").replace('_', \" \");\n if let Some(first) = title.get(0..1) {\n title.replace_range(0..1, &first.to_uppercase());\n }\n title\n}\n\nfn strip_leading_heading(content: &str, title: &str) -> String {\n let mut lines: Vec<&str> = content.lines().collect();\n let mut idx = 0usize;\n while idx < lines.len() && lines[idx].trim().is_empty() {\n idx += 1;\n }\n if idx < lines.len() {\n if let Some(heading) = lines[idx].trim().strip_prefix(\"# \") {\n if normalize_title(heading) == normalize_title(title) {\n lines.remove(idx);\n while idx < lines.len() && lines[idx].trim().is_empty() {\n lines.remove(idx);\n }\n }\n }\n }\n let mut out = lines.join(\"\\n\");\n if content.ends_with('\\n') {\n out.push('\\n');\n }\n out\n}\n\nfn normalize_title(value: &str) -> String {\n value.trim().to_ascii_lowercase()\n}\n\nfn ensure_frontmatter_title(content: &str, title: &str) -> String {\n let ends_with_newline = content.ends_with('\\n');\n let raw_title = title;\n let title = quote_yaml_string(title);\n if let Some((frontmatter, rest)) = split_frontmatter(content) {\n let rest = strip_leading_heading(&rest, raw_title);\n let cleaned = frontmatter\n .lines()\n .filter(|line| !line.trim_start().starts_with(\"title:\"))\n .collect::<Vec<_>>()\n .join(\"\\n\");\n let mut updated = String::new();\n updated.push_str(\"---\\n\");\n updated.push_str(&format!(\"title: {}\\n\", title));\n if !cleaned.trim().is_empty() {\n updated.push_str(&cleaned);\n if !cleaned.ends_with('\\n') {\n updated.push('\\n');\n }\n }\n updated.push_str(\"---\\n\");\n if !rest.is_empty() {\n updated.push_str(rest.trim_start_matches('\\n'));\n if ends_with_newline && !updated.ends_with('\\n') {\n updated.push('\\n');\n }\n }\n return updated;\n }\n\n let mut updated = String::new();\n updated.push_str(\"---\\n\");\n updated.push_str(&format!(\"title: {}\\n\", title));\n updated.push_str(\"---\\n\");\n if !content.is_empty() {\n let rest = strip_leading_heading(content, raw_title);\n updated.push_str(rest.trim_start_matches('\\n'));\n if ends_with_newline && !updated.ends_with('\\n') {\n updated.push('\\n');\n }\n }\n updated\n}\n\nfn split_frontmatter(content: &str) -> Option<(String, String)> {\n let mut lines = content.lines();\n let first = lines.next()?;\n if first.trim() != \"---\" {\n return None;\n }\n\n let mut frontmatter_lines = Vec::new();\n let mut in_frontmatter = true;\n let mut rest_lines = Vec::new();\n for line in lines {\n if in_frontmatter && line.trim() == \"---\" {\n in_frontmatter = false;\n continue;\n }\n if in_frontmatter {\n frontmatter_lines.push(line);\n } else {\n rest_lines.push(line);\n }\n }\n if in_frontmatter {\n return None;\n }\n\n let frontmatter = frontmatter_lines.join(\"\\n\");\n let rest = rest_lines.join(\"\\n\");\n Some((frontmatter, rest))\n}\n\nfn strip_frontmatter(content: &str) -> String {\n if let Some((_, rest)) = split_frontmatter(content) {\n let mut out = rest;\n if content.ends_with('\\n') && !out.ends_with('\\n') {\n out.push('\\n');\n }\n return out;\n }\n content.to_string()\n}\n\nfn sanitize_title(title: &str, path: &Path) -> String {\n let mut out = String::new();\n let mut chars = title.chars().peekable();\n while let Some(ch) = chars.next() {\n if ch == '`' {\n continue;\n }\n if ch == '[' {\n let mut text = String::new();\n while let Some(c) = chars.next() {\n if c == ']' {\n break;\n }\n text.push(c);\n }\n if matches!(chars.peek(), Some('(')) {\n chars.next();\n let mut depth = 1;\n while let Some(c) = chars.next() {\n if c == '(' {\n depth += 1;\n } else if c == ')' {\n depth -= 1;\n if depth == 0 {\n break;\n }\n }\n }\n }\n out.push_str(&text);\n continue;\n }\n out.push(ch);\n }\n let trimmed = out.trim();\n if trimmed.is_empty() {\n return title_from_filename(path);\n }\n trimmed.to_string()\n}\n\nfn quote_yaml_string(value: &str) -> String {\n let mut out = String::new();\n out.push('\"');\n for ch in value.chars() {\n match ch {\n '\"' => out.push_str(\"\\\\\\\"\"),\n '\\\\' => out.push_str(\"\\\\\\\\\"),\n '\\n' => out.push_str(\"\\\\n\"),\n '\\r' => out.push_str(\"\\\\r\"),\n '\\t' => out.push_str(\"\\\\t\"),\n _ => out.push(ch),\n }\n }\n out.push('\"');\n out\n}\n\nfn is_mdx_declaration_line(trimmed: &str) -> bool {\n if trimmed.starts_with(\"import \") {\n return true;\n }\n if trimmed.starts_with(\"export \") {\n let rest = trimmed.trim_start_matches(\"export \").trim_start();\n return rest.starts_with(\"const \")\n || rest.starts_with(\"default\")\n || rest.starts_with(\"function \")\n || rest.starts_with(\"type \")\n || rest.starts_with(\"interface \")\n || rest.starts_with(\"{\");\n }\n false\n}\n\nfn sanitize_markdown_content(content: &str) -> String {\n let mut out = Vec::new();\n let mut in_code = false;\n let mut fence = String::new();\n let mut in_frontmatter = false;\n let mut frontmatter_checked = false;\n\n for line in content.lines() {\n let trimmed = line.trim_start();\n if !frontmatter_checked {\n frontmatter_checked = true;\n if trimmed == \"---\" {\n in_frontmatter = true;\n out.push(line.to_string());\n continue;\n }\n }\n\n if in_frontmatter {\n out.push(line.to_string());\n if trimmed == \"---\" {\n in_frontmatter = false;\n }\n continue;\n }\n\n if !in_code && is_mdx_declaration_line(trimmed) {\n continue;\n }\n\n if trimmed.starts_with(\"```\") || trimmed.starts_with(\"~~~\") {\n let marker = trimmed.chars().take(3).collect::<String>();\n if !in_code {\n in_code = true;\n fence = marker.clone();\n out.push(normalize_code_fence_line(line));\n continue;\n }\n if trimmed.starts_with(&fence) {\n in_code = false;\n fence.clear();\n out.push(line.to_string());\n continue;\n }\n }\n\n if in_code {\n out.push(line.to_string());\n continue;\n }\n\n let rewritten = rewrite_markdown_images(line);\n if contains_html_tag(&rewritten) {\n out.push(escape_html_line(&rewritten));\n continue;\n }\n\n out.push(rewritten);\n }\n\n let mut joined = out.join(\"\\n\");\n if content.ends_with('\\n') {\n joined.push('\\n');\n }\n joined\n}\n\nfn rewrite_markdown_images(line: &str) -> String {\n let mut out = String::with_capacity(line.len());\n let mut rest = line;\n while let Some(start) = rest.find(\"![\") {\n out.push_str(&rest[..start]);\n let after_start = &rest[start + 2..];\n let Some(end_bracket) = after_start.find(']') else {\n out.push_str(&rest[start..]);\n return out;\n };\n let alt = &after_start[..end_bracket];\n let after_bracket = &after_start[end_bracket + 1..];\n let after_bracket_trim = after_bracket.trim_start();\n if !after_bracket_trim.starts_with('(') {\n out.push_str(&rest[start..start + 2 + end_bracket + 1]);\n rest = &after_start[end_bracket + 1..];\n continue;\n }\n let paren_offset = after_bracket.len() - after_bracket_trim.len();\n let after_paren = &after_bracket[paren_offset + 1..];\n let Some(end_paren) = after_paren.find(')') else {\n out.push_str(&rest[start..]);\n return out;\n };\n let inner = &after_paren[..end_paren];\n let dest = extract_markdown_dest(inner);\n if is_remote_image_dest(dest) {\n out.push_str(\"![\");\n out.push_str(alt);\n out.push_str(\"](\");\n out.push_str(inner);\n out.push(')');\n } else {\n let label = if alt.trim().is_empty() { \"image\" } else { alt };\n out.push('[');\n out.push_str(label);\n out.push_str(\"](\");\n out.push_str(inner);\n out.push(')');\n }\n rest = &after_paren[end_paren + 1..];\n }\n out.push_str(rest);\n out\n}\n\nfn extract_markdown_dest(inner: &str) -> &str {\n let trimmed = inner.trim_start();\n if let Some(rest) = trimmed.strip_prefix('<') {\n if let Some(end) = rest.find('>') {\n return &rest[..end];\n }\n }\n let mut end = trimmed.len();\n for (idx, ch) in trimmed.char_indices() {\n if ch.is_whitespace() {\n end = idx;\n break;\n }\n }\n &trimmed[..end]\n}\n\nfn is_remote_image_dest(dest: &str) -> bool {\n let lower = dest.to_ascii_lowercase();\n lower.starts_with(\"http://\")\n || lower.starts_with(\"https://\")\n || lower.starts_with(\"data:\")\n || lower.starts_with(\"mailto:\")\n}\n\nfn normalize_code_fence_line(line: &str) -> String {\n let idx = line\n .char_indices()\n .find(|(_, ch)| !ch.is_whitespace())\n .map(|(i, _)| i)\n .unwrap_or(0);\n let (prefix, trimmed) = line.split_at(idx);\n let fence = if trimmed.starts_with(\"```\") {\n \"```\"\n } else if trimmed.starts_with(\"~~~\") {\n \"~~~\"\n } else {\n return line.to_string();\n };\n let rest = &trimmed[fence.len()..];\n let rest_trim_start = rest\n .char_indices()\n .find(|(_, ch)| !ch.is_whitespace())\n .map(|(i, _)| i)\n .unwrap_or(rest.len());\n let rest_trim = &rest[rest_trim_start..];\n if rest_trim.is_empty() {\n return line.to_string();\n }\n let (lang_token, _) = split_lang_token(rest_trim);\n let normalized = normalize_code_lang(lang_token);\n let Some(normalized) = normalized else {\n return line.to_string();\n };\n let after_lang = &rest[rest_trim_start + lang_token.len()..];\n let before_lang = &rest[..rest_trim_start];\n format!(\"{prefix}{fence}{before_lang}{normalized}{after_lang}\")\n}\n\nfn split_lang_token(rest_trim: &str) -> (&str, &str) {\n let mut end = rest_trim.len();\n for (idx, ch) in rest_trim.char_indices() {\n if ch.is_whitespace() || matches!(ch, '{' | '[' | '(') {\n end = idx;\n break;\n }\n }\n (&rest_trim[..end], &rest_trim[end..])\n}\n\nfn normalize_code_lang(lang: &str) -> Option<&'static str> {\n let lower = lang.to_ascii_lowercase();\n if lower.is_empty() {\n return None;\n }\n if matches!(\n lower.as_str(),\n \"text\"\n | \"txt\"\n | \"plaintext\"\n | \"bash\"\n | \"sh\"\n | \"zsh\"\n | \"fish\"\n | \"shell\"\n | \"shellscript\"\n | \"console\"\n | \"json\"\n | \"yaml\"\n | \"yml\"\n | \"toml\"\n | \"ini\"\n | \"md\"\n | \"markdown\"\n | \"mdx\"\n | \"js\"\n | \"jsx\"\n | \"ts\"\n | \"tsx\"\n | \"py\"\n | \"python\"\n | \"rs\"\n | \"rust\"\n | \"go\"\n | \"c\"\n | \"cpp\"\n | \"cxx\"\n | \"java\"\n | \"kotlin\"\n | \"swift\"\n | \"rb\"\n | \"ruby\"\n | \"php\"\n | \"html\"\n | \"css\"\n | \"scss\"\n | \"less\"\n | \"sql\"\n | \"graphql\"\n | \"graphqls\"\n | \"dockerfile\"\n | \"make\"\n | \"makefile\"\n ) {\n return None;\n }\n Some(\"text\")\n}\n\nfn contains_html_tag(line: &str) -> bool {\n let bytes = line.as_bytes();\n for i in 0..bytes.len() {\n if bytes[i] == b'<' {\n if i + 1 >= bytes.len() {\n continue;\n }\n let next = bytes[i + 1] as char;\n if next.is_ascii_alphabetic() || matches!(next, '/' | '!') {\n if line[i + 1..].contains('>') {\n return true;\n }\n }\n }\n }\n false\n}\n\nfn escape_html_line(line: &str) -> String {\n line.replace('<', \"<\").replace('>', \">\")\n}\n\nfn ensure_docs_hub_config(hub_root: &Path) -> Result<()> {\n let ts_path = hub_root.join(\"source.config.ts\");\n let mjs_path = hub_root.join(\".source\").join(\"source.config.mjs\");\n if ts_path.exists() {\n rewrite_source_config(&ts_path, true)?;\n }\n if mjs_path.exists() {\n rewrite_source_config(&mjs_path, false)?;\n }\n Ok(())\n}\n\nfn ensure_docs_hub_layout(hub_root: &Path) -> Result<()> {\n let page_path = hub_root\n .join(\"app\")\n .join(\"(docs)\")\n .join(\"[[...slug]]\")\n .join(\"page.tsx\");\n if !page_path.exists() {\n return Ok(());\n }\n fs::write(&page_path, DOCS_HUB_PAGE_TEMPLATE.as_bytes())\n .with_context(|| format!(\"failed to write {}\", page_path.display()))?;\n Ok(())\n}\n\nconst DOCS_HUB_PAGE_TEMPLATE: &str = r#\"import { source } from \"@/lib/source\"\nimport { DocsLayout } from \"fumadocs-ui/layouts/docs\"\nimport { DocsPage, DocsBody, DocsDescription, DocsTitle } from \"fumadocs-ui/page\"\nimport { notFound } from \"next/navigation\"\nimport { useMDXComponents } from \"@/mdx-components\"\nimport type { Metadata } from \"next\"\n\ntype TreeNode = {\n name?: string\n url?: string\n path?: string\n slug?: string\n children?: TreeNode[]\n}\n\nfunction pickProjectTree(tree: TreeNode, slug?: string) {\n if (!slug || !tree || !Array.isArray(tree.children)) return tree\n const target = slug.toLowerCase()\n const child = tree.children.find((node) => {\n const url = String(node?.url ?? node?.path ?? \"\")\n if (url === `/${target}` || url === `${target}`) return true\n if (node?.slug && String(node.slug).toLowerCase() === target) return true\n if (node?.name && String(node.name).toLowerCase() === target) return true\n return false\n })\n if (!child) return tree\n if (Array.isArray(child.children) && child.children.length > 0) {\n return { ...tree, children: child.children }\n }\n return { ...tree, children: [child] }\n}\n\nfunction navTitleForSlug(slug?: string) {\n if (!slug) return \"Docs\"\n const root = source.getPage([slug])\n return root?.data?.title ?? slug\n}\n\nexport default async function Page(props: {\n params: Promise<{ slug?: string[] }>\n}) {\n const params = await props.params\n const page = source.getPage(params.slug)\n if (!page) notFound()\n\n const rootSlug = params.slug?.[0]\n const tree = pickProjectTree(source.pageTree as TreeNode, rootSlug)\n const navTitle = navTitleForSlug(rootSlug)\n const MDX = page.data.body\n const mdxComponents = useMDXComponents()\n\n const navUrl = rootSlug ? `/${rootSlug}` : \"/\"\n\n return (\n <DocsLayout\n tree={tree}\n nav={{ title: navTitle, url: navUrl }}\n sidebar={{ defaultOpenLevel: 1 }}\n >\n <DocsPage toc={page.data.toc} full={page.data.full}>\n <DocsTitle>{page.data.title}</DocsTitle>\n <DocsDescription>{page.data.description}</DocsDescription>\n <DocsBody>\n <MDX components={mdxComponents} />\n </DocsBody>\n </DocsPage>\n </DocsLayout>\n )\n}\n\nexport const dynamicParams = false\n\nexport async function generateStaticParams() {\n return source.generateParams()\n}\n\nexport async function generateMetadata(props: {\n params: Promise<{ slug?: string[] }>\n}): Promise<Metadata> {\n const params = await props.params\n const page = source.getPage(params.slug)\n if (!page) notFound()\n\n return {\n title: page.data.title,\n description: page.data.description,\n }\n}\n\"#;\n\nfn rewrite_source_config(path: &Path, is_ts: bool) -> Result<()> {\n let contents = if is_ts {\n r#\"import { defineDocs, defineConfig } from \"fumadocs-mdx/config\"\n\nexport const docs = defineDocs({\n dir: \"content/docs\",\n})\n\nexport default defineConfig({\n mdxOptions: {\n remarkImageOptions: {\n onError: \"hide\",\n external: { timeout: 1500 },\n useImport: false,\n },\n },\n})\n\"#\n } else {\n r#\"import { defineDocs, defineConfig } from \"fumadocs-mdx/config\"\n\nexport const docs = defineDocs({\n dir: \"content/docs\",\n})\n\nexport default defineConfig({\n mdxOptions: {\n remarkImageOptions: {\n onError: \"ignore\",\n external: false,\n },\n },\n})\n\"#\n };\n fs::write(path, contents.as_bytes())\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(())\n}\n\nfn docs_hub_needs_reset(hub_root: &Path) -> Result<bool> {\n let server_path = hub_root.join(\".source\").join(\"server.ts\");\n if !server_path.exists() {\n return Ok(false);\n }\n let contents = fs::read_to_string(&server_path)\n .with_context(|| format!(\"failed to read {}\", server_path.display()))?;\n Ok(contents.contains(\"content/docs/projects/\"))\n}\n\nfn remove_docs_hub_cache(hub_root: &Path) -> Result<()> {\n let source_root = hub_root.join(\".source\");\n if source_root.exists() {\n fs::remove_dir_all(&source_root)\n .with_context(|| format!(\"failed to remove {}\", source_root.display()))?;\n }\n let next_root = hub_root.join(\".next\");\n if next_root.exists() {\n fs::remove_dir_all(&next_root)\n .with_context(|| format!(\"failed to remove {}\", next_root.display()))?;\n }\n Ok(())\n}\n\nfn kill_docs_hub_by_port(port: u16) -> Result<()> {\n #[cfg(unix)]\n {\n let port_arg = format!(\"tcp:{port}\");\n let output = Command::new(\"lsof\").args([\"-ti\", &port_arg]).output();\n let Ok(output) = output else {\n return Ok(());\n };\n if !output.status.success() {\n return Ok(());\n }\n let pids = String::from_utf8_lossy(&output.stdout);\n for pid in pids.lines().map(str::trim).filter(|line| !line.is_empty()) {\n let _ = Command::new(\"kill\").arg(pid).status();\n }\n }\n Ok(())\n}\n\nfn copy_template_dir(from: &Path, to: &Path) -> Result<()> {\n fs::create_dir_all(to).with_context(|| format!(\"failed to create {}\", to.display()))?;\n for entry in fs::read_dir(from).with_context(|| format!(\"failed to read {}\", from.display()))? {\n let entry = entry?;\n let path = entry.path();\n let file_type = entry.file_type()?;\n let name = entry.file_name().to_string_lossy().to_string();\n if file_type.is_dir() && should_skip_template_dir(&name) {\n continue;\n }\n let dest = to.join(entry.file_name());\n if file_type.is_dir() {\n copy_template_dir(&path, &dest)?;\n } else if file_type.is_file() {\n fs::copy(&path, &dest).with_context(|| format!(\"failed to copy {}\", path.display()))?;\n }\n }\n Ok(())\n}\n\nfn sync_docs_hub_template_file(\n hub_root: &Path,\n template_root: &Path,\n rel_path: &str,\n overwrite: bool,\n) -> Result<()> {\n let src = template_root.join(rel_path);\n if !src.exists() {\n return Ok(());\n }\n let dest = hub_root.join(rel_path);\n if !overwrite && dest.exists() {\n return Ok(());\n }\n if let Some(parent) = dest.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n fs::copy(&src, &dest).with_context(|| format!(\"failed to copy {}\", src.display()))?;\n Ok(())\n}\n\nfn ensure_docs_hub_flow_toml(hub_root: &Path, template_root: &Path) -> Result<()> {\n let src = template_root.join(\"flow.toml\");\n if !src.exists() {\n return Ok(());\n }\n let dest = hub_root.join(\"flow.toml\");\n if !dest.exists() {\n fs::copy(&src, &dest).with_context(|| format!(\"failed to copy {}\", src.display()))?;\n return Ok(());\n }\n let dest_contents =\n fs::read_to_string(&dest).with_context(|| format!(\"failed to read {}\", dest.display()))?;\n if dest_contents.contains(\"[cloudflare]\") {\n return Ok(());\n }\n let src_contents =\n fs::read_to_string(&src).with_context(|| format!(\"failed to read {}\", src.display()))?;\n let Some(idx) = src_contents.find(\"[cloudflare]\") else {\n return Ok(());\n };\n let mut updated = dest_contents;\n if !updated.ends_with('\\n') {\n updated.push('\\n');\n }\n if !updated.trim().is_empty() {\n updated.push('\\n');\n }\n updated.push_str(src_contents[idx..].trim_start());\n updated.push('\\n');\n fs::write(&dest, updated).with_context(|| format!(\"failed to write {}\", dest.display()))?;\n Ok(())\n}\n\nfn should_skip_template_dir(name: &str) -> bool {\n if matches!(name, \".source\") {\n return false;\n }\n if name.starts_with('.') {\n return true;\n }\n matches!(name, \"node_modules\" | \"dist\" | \"build\" | \".next\")\n}\n" }, { "path": "src/doctor.rs", "content": "use std::{\n env,\n fs::{self, OpenOptions},\n io::{IsTerminal, Write},\n path::{Path, PathBuf},\n process::Command,\n};\n\nuse anyhow::{Context, Result, bail};\nuse crossterm::{event, terminal};\n\nuse crate::cli::DoctorOpts;\nuse crate::vcs;\n\n/// Ensure the lin watcher daemon is available, prompting to install a bundled\n/// copy if it is missing from PATH. Returns the resolved binary path.\npub fn ensure_lin_available_interactive() -> Result<PathBuf> {\n if let Ok(path) = which::which(\"lin\") {\n println!(\"✅ lin watcher daemon found at {}\", path.display());\n return Ok(path);\n }\n\n if let Some(bundled) = find_bundled_lin() {\n if prompt_install_lin(&bundled)? {\n let installed = install_lin(&bundled)?;\n println!(\"✅ Installed lin to {}\", installed.display());\n return Ok(installed);\n }\n }\n\n bail!(\n \"lin is not on PATH. Build/install from this repo (scripts/deploy.sh) so flow can delegate watchers to it.\"\n );\n}\n\npub fn run(_opts: DoctorOpts) -> Result<()> {\n println!(\"Running flow doctor checks...\\n\");\n\n let zerobrew_available = ensure_zerobrew_available_interactive()?;\n\n ensure_flox_available(zerobrew_available)?;\n ensure_jj_available(zerobrew_available)?;\n let _ = ensure_lin_available_interactive();\n ensure_direnv_on_path(zerobrew_available)?;\n\n match detect_shell()? {\n Some(shell) => ensure_shell_hook(shell)?,\n None => println!(\n \"⚠️ Unable to detect your shell from $SHELL. Add the direnv hook manually (see https://direnv.net).\"\n ),\n }\n\n println!(\"\\n✅ flow doctor is done. Re-run it any time after changing shells or machines.\");\n Ok(())\n}\n\nfn ensure_flox_available(zerobrew_available: bool) -> Result<()> {\n if which::which(\"flox\").is_ok() {\n println!(\"✅ flox found on PATH\");\n return Ok(());\n }\n\n if maybe_install_with_zerobrew(zerobrew_available, \"flox\", \"flox\")? {\n if which::which(\"flox\").is_ok() {\n println!(\"✅ flox installed via zerobrew\");\n return Ok(());\n }\n }\n\n // Heuristic: flox-managed env leaves a .flox directory or ~/.flox directory.\n let home = home_dir();\n if home.join(\".flox\").exists() {\n println!(\n \"✅ flox environment directory detected at {}\",\n home.join(\".flox\").display()\n );\n return Ok(());\n }\n\n bail!(\n \"flox is not installed. Install it from https://flox.dev/docs/install-flox/install/ and re-run `f doctor`.\"\n );\n}\n\nfn ensure_jj_available(zerobrew_available: bool) -> Result<()> {\n if which::which(\"jj\").is_ok() {\n println!(\"✅ jj found on PATH\");\n return Ok(());\n }\n\n if maybe_install_with_zerobrew(zerobrew_available, \"jj\", \"jj\")? {\n if which::which(\"jj\").is_ok() {\n println!(\"✅ jj installed via zerobrew\");\n return Ok(());\n }\n }\n\n vcs::ensure_jj_installed()?;\n println!(\"✅ jj found on PATH\");\n Ok(())\n}\n\nfn ensure_direnv_on_path(zerobrew_available: bool) -> Result<()> {\n match which::which(\"direnv\") {\n Ok(path) => {\n println!(\"✅ direnv found at {}\", path.display());\n Ok(())\n }\n Err(_) => {\n if maybe_install_with_zerobrew(zerobrew_available, \"direnv\", \"direnv\")? {\n if let Ok(path) = which::which(\"direnv\") {\n println!(\"✅ direnv installed via zerobrew at {}\", path.display());\n return Ok(());\n }\n }\n bail!(\n \"direnv is not on PATH. Install it from https://direnv.net/#installation and rerun `flow doctor`.\"\n )\n }\n }\n}\n\nfn find_bundled_lin() -> Option<PathBuf> {\n let exe_dir = std::env::current_exe()\n .ok()\n .and_then(|p| p.parent().map(PathBuf::from))?;\n let candidate = exe_dir.join(\"lin\");\n if candidate.exists() {\n Some(candidate)\n } else {\n None\n }\n}\n\nfn prompt_install_lin(bundled: &Path) -> Result<bool> {\n println!(\n \"lin was not found on PATH. A bundled copy was found at {}.\",\n bundled.display()\n );\n print!(\n \"Install lin to {}? [Y/n]: \",\n default_install_dir().display()\n );\n let _ = std::io::stdout().flush();\n let mut input = String::new();\n std::io::stdin().read_line(&mut input).ok();\n let normalized = input.trim().to_ascii_lowercase();\n Ok(normalized.is_empty() || normalized == \"y\" || normalized == \"yes\")\n}\n\nfn ensure_zerobrew_available_interactive() -> Result<bool> {\n if which::which(\"zb\").is_ok() {\n println!(\"✅ zerobrew (zb) found on PATH\");\n return Ok(true);\n }\n\n if !std::io::stdin().is_terminal() {\n println!(\"⚠️ zerobrew (zb) not found; skipping interactive install.\");\n return Ok(false);\n }\n\n let install = prompt_yes(\"zerobrew (zb) not found. Install it now? [y/N]: \", false);\n\n if !install {\n return Ok(false);\n }\n\n let status = Command::new(\"/bin/sh\")\n .arg(\"-c\")\n .arg(\"curl -sSL https://raw.githubusercontent.com/lucasgelfond/zerobrew/main/install.sh | bash\")\n .status()\n .context(\"failed to run zerobrew install script\")?;\n\n if status.success() {\n if which::which(\"zb\").is_ok() {\n println!(\"✅ zerobrew installed\");\n return Ok(true);\n }\n println!(\"⚠️ zerobrew installed but not on PATH yet; restart your shell.\");\n return Ok(false);\n }\n\n println!(\"⚠️ zerobrew install failed\");\n Ok(false)\n}\n\nfn maybe_install_with_zerobrew(\n zerobrew_available: bool,\n tool: &str,\n package: &str,\n) -> Result<bool> {\n if !zerobrew_available {\n return Ok(false);\n }\n\n if !std::io::stdin().is_terminal() {\n return Ok(false);\n }\n\n let prompt = format!(\"Install {} via zerobrew? [y/N]: \", tool);\n if !prompt_yes(&prompt, false) {\n return Ok(false);\n }\n\n let status = Command::new(\"zb\")\n .arg(\"install\")\n .arg(package)\n .status()\n .context(\"failed to run zb install\")?;\n\n Ok(status.success())\n}\n\nfn prompt_yes(prompt: &str, default_yes: bool) -> bool {\n print!(\"{}\", prompt);\n let _ = std::io::stdout().flush();\n if std::io::stdin().is_terminal() {\n if terminal::enable_raw_mode().is_ok() {\n let read = event::read();\n let _ = terminal::disable_raw_mode();\n if let Ok(event::Event::Key(key)) = read {\n let decision = match key.code {\n event::KeyCode::Char('y') | event::KeyCode::Char('Y') => Some(true),\n event::KeyCode::Char('n') | event::KeyCode::Char('N') => Some(false),\n event::KeyCode::Enter => Some(default_yes),\n event::KeyCode::Esc => Some(false),\n _ => None,\n };\n if let Some(choice) = decision {\n println!();\n return choice;\n }\n }\n }\n }\n\n let mut input = String::new();\n std::io::stdin().read_line(&mut input).ok();\n let normalized = input.trim().to_ascii_lowercase();\n if normalized.is_empty() {\n return default_yes;\n }\n normalized == \"y\" || normalized == \"yes\"\n}\n\nfn install_lin(bundled: &Path) -> Result<PathBuf> {\n let dest_dir = default_install_dir();\n std::fs::create_dir_all(&dest_dir).with_context(|| {\n format!(\n \"failed to create lin install directory {}\",\n dest_dir.display()\n )\n })?;\n\n let dest = dest_dir.join(\"lin\");\n std::fs::copy(bundled, &dest).with_context(|| {\n format!(\n \"failed to copy bundled lin from {} to {}\",\n bundled.display(),\n dest.display()\n )\n })?;\n\n #[cfg(unix)]\n {\n use std::os::unix::fs::PermissionsExt;\n let mut perms = std::fs::metadata(&dest)\n .context(\"failed to stat installed lin\")?\n .permissions();\n perms.set_mode(0o755);\n std::fs::set_permissions(&dest, perms).context(\"failed to mark lin executable\")?;\n }\n\n Ok(dest)\n}\n\nfn default_install_dir() -> PathBuf {\n std::env::var_os(\"HOME\")\n .map(PathBuf::from)\n .map(|home| home.join(\"bin\"))\n .unwrap_or_else(|| PathBuf::from(\".\"))\n}\n\nfn detect_shell() -> Result<Option<ShellKind>> {\n if let Ok(shell_path) = env::var(\"SHELL\") {\n if let Some(kind) = ShellKind::from_path(shell_path) {\n println!(\"✅ Detected shell: {}\", kind.display());\n return Ok(Some(kind));\n }\n }\n Ok(None)\n}\n\nfn ensure_shell_hook(shell: ShellKind) -> Result<()> {\n let config_path = shell.config_path();\n let indicator = shell.hook_indicator();\n let snippet = shell.hook_snippet();\n\n let existing = fs::read_to_string(&config_path).unwrap_or_default();\n if existing.contains(indicator) {\n println!(\n \"✅ {} already sources direnv ({}).\",\n shell.display(),\n config_path.display()\n );\n return Ok(());\n }\n\n println!(\n \"ℹ️ Adding direnv hook to {} ({}).\",\n shell.display(),\n config_path.display()\n );\n\n if let Some(parent) = config_path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create directory {}\", parent.to_string_lossy()))?;\n }\n\n let mut file = OpenOptions::new()\n .create(true)\n .append(true)\n .open(&config_path)\n .with_context(|| format!(\"failed to open {}\", config_path.display()))?;\n\n if !existing.is_empty() && !existing.ends_with('\\n') {\n writeln!(file)?;\n }\n\n writeln!(file, \"\\n# Added by flow doctor\")?;\n writeln!(file, \"{snippet}\")?;\n\n println!(\n \"✅ Added direnv hook for {}. Restart your shell or source {}.\",\n shell.display(),\n config_path.display()\n );\n Ok(())\n}\n\n#[derive(Clone, Copy, Debug, PartialEq, Eq)]\nenum ShellKind {\n Bash,\n Zsh,\n Fish,\n}\n\nimpl ShellKind {\n fn from_path<P: AsRef<Path>>(path: P) -> Option<Self> {\n let name = path\n .as_ref()\n .file_name()\n .map(|os| os.to_string_lossy().to_ascii_lowercase())?;\n match name.as_str() {\n \"bash\" => Some(Self::Bash),\n \"zsh\" => Some(Self::Zsh),\n \"fish\" => Some(Self::Fish),\n _ => None,\n }\n }\n\n fn display(&self) -> &'static str {\n match self {\n ShellKind::Bash => \"bash\",\n ShellKind::Zsh => \"zsh\",\n ShellKind::Fish => \"fish\",\n }\n }\n\n fn config_path(&self) -> PathBuf {\n let home = home_dir();\n self.config_path_with_base(&home)\n }\n\n fn config_path_with_base(&self, home: &Path) -> PathBuf {\n match self {\n ShellKind::Bash => home.join(\".bashrc\"),\n ShellKind::Zsh => home.join(\".zshrc\"),\n ShellKind::Fish => home.join(\".config/fish/config.fish\"),\n }\n }\n\n fn hook_indicator(&self) -> &'static str {\n match self {\n ShellKind::Bash => \"direnv hook bash\",\n ShellKind::Zsh => \"direnv hook zsh\",\n ShellKind::Fish => \"direnv hook fish\",\n }\n }\n\n fn hook_snippet(&self) -> &'static str {\n match self {\n ShellKind::Bash => {\n r#\"if command -v direnv >/dev/null 2>&1; then\n eval \"$(direnv hook bash)\"\nfi\"#\n }\n ShellKind::Zsh => {\n r#\"if command -v direnv >/dev/null 2>&1; then\n eval \"$(direnv hook zsh)\"\nfi\"#\n }\n ShellKind::Fish => {\n r#\"if type -q direnv\n direnv hook fish | source\nend\"#\n }\n }\n }\n}\n\nfn home_dir() -> PathBuf {\n env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn shell_detection_from_path() {\n assert_eq!(ShellKind::from_path(\"/bin/bash\"), Some(ShellKind::Bash));\n assert_eq!(ShellKind::from_path(\"zsh\"), Some(ShellKind::Zsh));\n assert_eq!(\n ShellKind::from_path(\"/usr/local/bin/fish\"),\n Some(ShellKind::Fish)\n );\n assert_eq!(ShellKind::from_path(\"/bin/sh\"), None);\n }\n\n #[test]\n fn config_paths_follow_home_env() {\n let base = Path::new(\"/tmp/drflow\");\n assert_eq!(\n ShellKind::Zsh.config_path_with_base(base),\n PathBuf::from(\"/tmp/drflow/.zshrc\")\n );\n assert_eq!(\n ShellKind::Bash.config_path_with_base(base),\n PathBuf::from(\"/tmp/drflow/.bashrc\")\n );\n assert_eq!(\n ShellKind::Fish.config_path_with_base(base),\n PathBuf::from(\"/tmp/drflow/.config/fish/config.fish\")\n );\n }\n}\n" }, { "path": "src/domains.rs", "content": "use std::collections::BTreeMap;\nuse std::fs;\nuse std::io::{Read, Write};\nuse std::net::TcpStream;\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Output};\nuse std::thread;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::{\n DomainsAction, DomainsAddOpts, DomainsCommand, DomainsEngineArg, DomainsGetOpts, DomainsRmOpts,\n};\n\nconst PROXY_CONTAINER_NAME: &str = \"flow-local-domains-proxy\";\nconst NATIVE_PROXY_HEADER: &str = \"x-flow-domainsd: 1\";\nconst MACOS_DOMAINSD_LABEL: &str = \"dev.flow.domainsd\";\n\nconst COMPOSE_FILE: &str = r#\"services:\n proxy:\n container_name: flow-local-domains-proxy\n image: nginx:1.27-alpine\n restart: unless-stopped\n ports:\n - \"80:80\"\n volumes:\n - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro\n - ./routes:/etc/nginx/conf.d/routes:ro\n\"#;\n\nconst NGINX_MAIN_CONF: &str = r#\"map $http_upgrade $connection_upgrade {\n default upgrade;\n \"\" close;\n}\n\nserver {\n listen 80 default_server;\n server_name _;\n return 404 \"No local Flow domain route configured for this host.\\n\";\n}\n\ninclude /etc/nginx/conf.d/routes/*.conf;\n\"#;\n\n#[derive(Debug)]\nstruct DomainsPaths {\n root: PathBuf,\n compose: PathBuf,\n nginx_main: PathBuf,\n routes_dir: PathBuf,\n routes_state: PathBuf,\n native_pid: PathBuf,\n native_log: PathBuf,\n native_bin: PathBuf,\n}\n\nimpl DomainsPaths {\n fn resolve() -> Result<Self> {\n let cfg = dirs::config_dir().context(\"Could not find config directory\")?;\n let root = cfg.join(\"flow\").join(\"local-domains\");\n Ok(Self {\n compose: root.join(\"docker-compose.yml\"),\n nginx_main: root.join(\"nginx\").join(\"default.conf\"),\n routes_dir: root.join(\"routes\"),\n routes_state: root.join(\"routes.json\"),\n native_pid: root.join(\"domainsd.pid\"),\n native_log: root.join(\"domainsd.log\"),\n native_bin: root.join(\"domainsd-cpp\"),\n root,\n })\n }\n}\n\npub fn run(cmd: DomainsCommand) -> Result<()> {\n let paths = DomainsPaths::resolve()?;\n let engine = resolve_engine(cmd.engine);\n match cmd.action {\n Some(DomainsAction::Up) => run_up(&paths, engine),\n Some(DomainsAction::Down) => run_down(&paths, engine),\n Some(DomainsAction::List) | None => run_list(&paths),\n Some(DomainsAction::Get(opts)) => run_get(&paths, opts),\n Some(DomainsAction::Add(opts)) => run_add(&paths, opts, engine),\n Some(DomainsAction::Rm(opts)) => run_rm(&paths, opts, engine),\n Some(DomainsAction::Doctor) => run_doctor(&paths, engine),\n }\n}\n\n#[derive(Debug, Clone, Copy, Eq, PartialEq)]\nenum DomainsEngine {\n Docker,\n Native,\n}\n\nfn resolve_engine(cli_engine: Option<DomainsEngineArg>) -> DomainsEngine {\n if let Some(engine) = cli_engine {\n return match engine {\n DomainsEngineArg::Docker => DomainsEngine::Docker,\n DomainsEngineArg::Native => DomainsEngine::Native,\n };\n }\n match std::env::var(\"FLOW_DOMAINS_ENGINE\") {\n Ok(v) if v.eq_ignore_ascii_case(\"native\") => DomainsEngine::Native,\n _ => DomainsEngine::Docker,\n }\n}\n\nfn run_up(paths: &DomainsPaths, engine: DomainsEngine) -> Result<()> {\n if engine == DomainsEngine::Native {\n return run_up_native(paths);\n }\n ensure_docker_available()?;\n ensure_layout(paths)?;\n let routes = load_routes(paths)?;\n write_route_files(paths, &routes)?;\n assert_no_port_80_conflict()?;\n\n run_compose(paths, &[\"up\", \"-d\"])?;\n println!(\"Local domains proxy is up (container: {PROXY_CONTAINER_NAME}).\");\n println!(\"Config root: {}\", paths.root.display());\n println!(\"Routes: {}\", routes.len());\n if routes.is_empty() {\n println!(\"No routes yet. Add one with:\");\n println!(\" f domains add linsa.localhost 127.0.0.1:3481\");\n }\n Ok(())\n}\n\nfn run_down(paths: &DomainsPaths, engine: DomainsEngine) -> Result<()> {\n if engine == DomainsEngine::Native {\n return run_down_native(paths);\n }\n ensure_docker_available()?;\n ensure_layout(paths)?;\n run_compose(paths, &[\"down\"])?;\n println!(\"Local domains proxy stopped.\");\n Ok(())\n}\n\nfn run_list(paths: &DomainsPaths) -> Result<()> {\n ensure_layout(paths)?;\n let routes = load_routes(paths)?;\n if routes.is_empty() {\n println!(\"No local domain routes configured.\");\n println!(\"Add one with: f domains add linsa.localhost 127.0.0.1:3481\");\n return Ok(());\n }\n\n println!(\"{:<32} {}\", \"HOST\", \"TARGET\");\n println!(\"{}\", \"-\".repeat(58));\n for (host, target) in routes {\n println!(\"{:<32} {}\", host, target);\n }\n Ok(())\n}\n\nfn run_get(paths: &DomainsPaths, opts: DomainsGetOpts) -> Result<()> {\n ensure_layout(paths)?;\n let host = normalize_host(&opts.host)?;\n let routes = load_routes(paths)?;\n let target = routes.get(&host).with_context(|| {\n format!(\n \"Route not found: {}. Add it with `f domains add {} 127.0.0.1:<port>`.\",\n host, host\n )\n })?;\n if opts.target {\n println!(\"{target}\");\n } else {\n println!(\"http://{host}\");\n }\n Ok(())\n}\n\nfn run_add(paths: &DomainsPaths, opts: DomainsAddOpts, engine: DomainsEngine) -> Result<()> {\n ensure_layout(paths)?;\n let host = normalize_host(&opts.host)?;\n let target = normalize_target(&opts.target)?;\n\n let mut routes = load_routes(paths)?;\n if let Some(existing) = routes.get(&host) {\n if existing == &target {\n println!(\"Route already exists: {host} -> {target}\");\n maybe_reload_running_proxy(paths, engine)?;\n return Ok(());\n }\n if !opts.replace {\n bail!(\n \"Route already exists: {} -> {}. Use --replace to update.\",\n host,\n existing\n );\n }\n }\n\n routes.insert(host.clone(), target.clone());\n save_routes(paths, &routes)?;\n write_route_files(paths, &routes)?;\n maybe_reload_running_proxy(paths, engine)?;\n println!(\"Added route: {host} -> {target}\");\n Ok(())\n}\n\nfn run_rm(paths: &DomainsPaths, opts: DomainsRmOpts, engine: DomainsEngine) -> Result<()> {\n ensure_layout(paths)?;\n let host = normalize_host(&opts.host)?;\n let mut routes = load_routes(paths)?;\n if routes.remove(&host).is_none() {\n bail!(\"Route not found: {}\", host);\n }\n save_routes(paths, &routes)?;\n write_route_files(paths, &routes)?;\n maybe_reload_running_proxy(paths, engine)?;\n println!(\"Removed route: {host}\");\n Ok(())\n}\n\nfn run_doctor(paths: &DomainsPaths, engine: DomainsEngine) -> Result<()> {\n if engine == DomainsEngine::Native {\n return run_doctor_native(paths);\n }\n ensure_layout(paths)?;\n let routes = load_routes(paths)?;\n\n println!(\"Local domains doctor\");\n println!(\"--------------------\");\n println!(\"Config root: {}\", paths.root.display());\n println!(\"Routes: {}\", routes.len());\n println!(\n \"Docker: {}\",\n if docker_available() {\n \"available\"\n } else {\n \"missing\"\n }\n );\n\n let running = proxy_is_running()?;\n println!(\n \"Proxy container: {}\",\n if running { \"running\" } else { \"stopped\" }\n );\n\n if let Some(owner) = docker_container_owning_port_80()? {\n if owner == PROXY_CONTAINER_NAME {\n println!(\"Port 80 owner: {} (expected)\", owner);\n } else {\n println!(\"Port 80 owner: {} (conflict)\", owner);\n }\n } else if let Some(listener) = port_80_listener_summary()? {\n println!(\"Port 80 listener: {}\", listener);\n } else {\n println!(\"Port 80 listener: none\");\n }\n\n if !routes.is_empty() {\n println!();\n println!(\"{:<32} {}\", \"HOST\", \"TARGET\");\n println!(\"{}\", \"-\".repeat(58));\n for (host, target) in routes {\n println!(\"{:<32} {}\", host, target);\n }\n }\n\n Ok(())\n}\n\nfn normalize_host(raw: &str) -> Result<String> {\n let mut host = raw.trim().to_ascii_lowercase();\n if let Some(stripped) = host.strip_prefix(\"http://\") {\n host = stripped.to_string();\n } else if let Some(stripped) = host.strip_prefix(\"https://\") {\n host = stripped.to_string();\n }\n host = host.trim_end_matches('/').to_string();\n if host.is_empty() {\n bail!(\"Host is empty\");\n }\n if host.contains('/') || host.contains(':') || host.contains(char::is_whitespace) {\n bail!(\"Host must be a hostname like linsa.localhost\");\n }\n if !host.ends_with(\".localhost\") {\n bail!(\"Host must end with .localhost\");\n }\n if host == \".localhost\" || host == \"localhost\" {\n bail!(\"Host must include a subdomain (for example: linsa.localhost)\");\n }\n Ok(host)\n}\n\nfn normalize_target(raw: &str) -> Result<String> {\n let mut target = raw.trim().to_string();\n if let Some(stripped) = target.strip_prefix(\"http://\") {\n target = stripped.to_string();\n } else if let Some(stripped) = target.strip_prefix(\"https://\") {\n target = stripped.to_string();\n }\n target = target.trim_end_matches('/').to_string();\n if target.is_empty() {\n bail!(\"Target is empty\");\n }\n if target.contains('/') || target.contains('?') || target.contains('#') {\n bail!(\"Target must be host:port\");\n }\n\n let (host, port) = target\n .rsplit_once(':')\n .context(\"Target must include port (for example: 127.0.0.1:3481)\")?;\n if host.trim().is_empty() {\n bail!(\"Target host is empty\");\n }\n let port_num = port\n .trim()\n .parse::<u16>()\n .context(\"Target port must be a valid number\")?;\n Ok(format!(\"{}:{}\", host.trim(), port_num))\n}\n\nfn ensure_layout(paths: &DomainsPaths) -> Result<()> {\n fs::create_dir_all(paths.routes_dir.as_path())?;\n if let Some(parent) = paths.nginx_main.parent() {\n fs::create_dir_all(parent)?;\n }\n fs::write(&paths.compose, COMPOSE_FILE)?;\n fs::write(&paths.nginx_main, NGINX_MAIN_CONF)?;\n\n if !paths.routes_state.exists() {\n fs::write(&paths.routes_state, \"{}\\n\")?;\n }\n Ok(())\n}\n\nfn load_routes(paths: &DomainsPaths) -> Result<BTreeMap<String, String>> {\n if !paths.routes_state.exists() {\n return Ok(BTreeMap::new());\n }\n let raw = fs::read_to_string(&paths.routes_state)?;\n let parsed: BTreeMap<String, String> =\n serde_json::from_str(&raw).context(\"Failed to parse routes.json\")?;\n Ok(parsed)\n}\n\nfn save_routes(paths: &DomainsPaths, routes: &BTreeMap<String, String>) -> Result<()> {\n let payload = serde_json::to_string_pretty(routes)?;\n fs::write(&paths.routes_state, format!(\"{payload}\\n\"))?;\n Ok(())\n}\n\nfn write_route_files(paths: &DomainsPaths, routes: &BTreeMap<String, String>) -> Result<()> {\n fs::create_dir_all(&paths.routes_dir)?;\n for entry in fs::read_dir(&paths.routes_dir)? {\n let entry = entry?;\n let path = entry.path();\n if path\n .extension()\n .and_then(|ext| ext.to_str())\n .map(|ext| ext == \"conf\")\n .unwrap_or(false)\n {\n fs::remove_file(path)?;\n }\n }\n\n for (host, target) in routes {\n let file = paths.routes_dir.join(route_file_name(host));\n fs::write(file, render_route(host, target))?;\n }\n Ok(())\n}\n\nfn route_file_name(host: &str) -> String {\n let mut safe = String::with_capacity(host.len());\n for ch in host.chars() {\n if ch.is_ascii_alphanumeric() || ch == '-' {\n safe.push(ch);\n } else {\n safe.push('_');\n }\n }\n format!(\"{safe}.conf\")\n}\n\nfn render_route(host: &str, target: &str) -> String {\n let (upstream_target, host_header) = docker_upstream(target);\n format!(\n r#\"server {{\n listen 80;\n server_name {host};\n\n location / {{\n proxy_pass http://{upstream_target};\n proxy_http_version 1.1;\n proxy_set_header Host {host_header};\n proxy_set_header X-Forwarded-Host $host;\n proxy_set_header X-Forwarded-Proto $scheme;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection $connection_upgrade;\n }}\n}}\n\"#\n )\n}\n\nfn docker_upstream(target: &str) -> (String, String) {\n let Some((host, port)) = target.rsplit_once(':') else {\n return (target.to_string(), target.to_string());\n };\n match host {\n \"127.0.0.1\" | \"localhost\" | \"::1\" => (\n format!(\"host.docker.internal:{}\", port),\n \"localhost\".to_string(),\n ),\n _ => (format!(\"{}:{}\", host, port), host.to_string()),\n }\n}\n\nfn ensure_docker_available() -> Result<()> {\n if docker_available() {\n Ok(())\n } else {\n bail!(\"docker is required for local domains. Install Docker/OrbStack first.\")\n }\n}\n\nfn docker_available() -> bool {\n which::which(\"docker\").is_ok()\n}\n\nfn run_compose(paths: &DomainsPaths, args: &[&str]) -> Result<()> {\n let output = Command::new(\"docker\")\n .arg(\"compose\")\n .arg(\"-f\")\n .arg(&paths.compose)\n .args(args)\n .output()\n .context(\"Failed to run docker compose\")?;\n ensure_success(output, \"docker compose command failed\")\n}\n\nfn ensure_success(output: Output, context_msg: &str) -> Result<()> {\n if output.status.success() {\n return Ok(());\n }\n let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();\n let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();\n let detail = if !stderr.is_empty() { stderr } else { stdout };\n if detail.is_empty() {\n bail!(\"{context_msg}\");\n }\n bail!(\"{context_msg}: {detail}\");\n}\n\nfn maybe_reload_running_proxy(paths: &DomainsPaths, engine: DomainsEngine) -> Result<()> {\n match engine {\n DomainsEngine::Docker => maybe_reload_running_proxy_docker(),\n DomainsEngine::Native => {\n if native_proxy_running(paths)? {\n // Native daemon reloads routes.json lazily on mtime change.\n return Ok(());\n }\n println!(\"Native proxy not running yet. Start it with: f domains --engine native up\");\n Ok(())\n }\n }\n}\n\nfn maybe_reload_running_proxy_docker() -> Result<()> {\n if !docker_available() {\n return Ok(());\n }\n if !proxy_is_running()? {\n println!(\"Proxy not running yet. Start it with: f domains up\");\n return Ok(());\n }\n\n let output = Command::new(\"docker\")\n .args([\"exec\", PROXY_CONTAINER_NAME, \"nginx\", \"-s\", \"reload\"])\n .output()\n .context(\"Failed to reload proxy\")?;\n ensure_success(output, \"Failed to reload running proxy\")\n}\n\nfn proxy_is_running() -> Result<bool> {\n if !docker_available() {\n return Ok(false);\n }\n let output = Command::new(\"docker\")\n .args([\n \"ps\",\n \"--filter\",\n &format!(\"name=^/{}$\", PROXY_CONTAINER_NAME),\n \"--format\",\n \"{{.Names}}\",\n ])\n .output()\n .context(\"Failed to check docker container status\")?;\n if !output.status.success() {\n return Ok(false);\n }\n let names = String::from_utf8_lossy(&output.stdout);\n Ok(names\n .lines()\n .any(|line| line.trim() == PROXY_CONTAINER_NAME))\n}\n\nfn docker_container_owning_port_80() -> Result<Option<String>> {\n if !docker_available() {\n return Ok(None);\n }\n let output = Command::new(\"docker\")\n .args([\"ps\", \"--format\", \"{{.Names}}\\t{{.Ports}}\"])\n .output()\n .context(\"Failed to inspect docker port bindings\")?;\n if !output.status.success() {\n return Ok(None);\n }\n let text = String::from_utf8_lossy(&output.stdout);\n for line in text.lines() {\n let mut parts = line.splitn(2, '\\t');\n let name = parts.next().unwrap_or(\"\").trim();\n let ports = parts.next().unwrap_or(\"\");\n if ports.contains(\":80->80/tcp\") {\n return Ok(Some(name.to_string()));\n }\n }\n Ok(None)\n}\n\nfn assert_no_port_80_conflict() -> Result<()> {\n if let Some(owner) = docker_container_owning_port_80()? {\n if owner != PROXY_CONTAINER_NAME {\n bail!(\n \"Port 80 is already owned by docker container '{}'. Stop it first (for example: docker stop {}).\",\n owner,\n owner\n );\n }\n return Ok(());\n }\n\n if proxy_is_running()? {\n return Ok(());\n }\n\n if let Some(listener) = port_80_listener_summary()? {\n bail!(\n \"Port 80 is already in use by '{}'. Stop that listener, then retry `f domains up`.\",\n listener\n );\n }\n Ok(())\n}\n\nfn port_80_listener_summary() -> Result<Option<String>> {\n if which::which(\"lsof\").is_err() {\n return Ok(None);\n }\n let output = Command::new(\"lsof\")\n .args([\"-nP\", \"-iTCP:80\", \"-sTCP:LISTEN\"])\n .output()\n .context(\"Failed to inspect port 80 listeners\")?;\n if !output.status.success() {\n return Ok(None);\n }\n let text = String::from_utf8_lossy(&output.stdout);\n let mut lines = text.lines();\n let _header = lines.next();\n if let Some(line) = lines.next() {\n let compact = line.split_whitespace().collect::<Vec<_>>().join(\" \");\n return Ok(Some(compact));\n }\n Ok(None)\n}\n\nfn run_up_native(paths: &DomainsPaths) -> Result<()> {\n ensure_layout(paths)?;\n let routes = load_routes(paths)?;\n assert_no_port_80_conflict_native(paths)?;\n ensure_native_binary(paths)?;\n\n if native_proxy_running(paths)? {\n println!(\"Native local domains proxy is already running.\");\n println!(\"Config root: {}\", paths.root.display());\n println!(\"Routes: {}\", routes.len());\n return Ok(());\n }\n\n start_native_proxy(paths)?;\n println!(\"Native local domains proxy is up (binary: domainsd-cpp).\");\n println!(\"Config root: {}\", paths.root.display());\n println!(\"Routes: {}\", routes.len());\n if routes.is_empty() {\n println!(\"No routes yet. Add one with:\");\n println!(\" f domains add linsa.localhost 127.0.0.1:3481\");\n }\n Ok(())\n}\n\nfn run_down_native(paths: &DomainsPaths) -> Result<()> {\n ensure_layout(paths)?;\n if cfg!(target_os = \"macos\") {\n let launchd_plist = macos_launchd_plist_path();\n if launchd_plist.exists() {\n println!(\n \"Native local domains appears launchd-managed: {}\",\n launchd_plist.display()\n );\n println!(\n \"To stop/uninstall launchd mode, run:\\n sudo {}\",\n macos_launchd_uninstall_script_path().display()\n );\n return Ok(());\n }\n }\n let Some(pid) = read_native_pid(paths)? else {\n println!(\"Native local domains proxy is not running.\");\n return Ok(());\n };\n\n if !pid_alive(pid) {\n let _ = fs::remove_file(&paths.native_pid);\n println!(\"Native local domains proxy was not running (removed stale pid file).\");\n return Ok(());\n }\n\n let output = Command::new(\"kill\")\n .args([\"-TERM\", &pid.to_string()])\n .output()\n .context(\"Failed to stop native local domains proxy\")?;\n if !output.status.success() {\n ensure_success(output, \"Failed to stop native local domains proxy\")?;\n }\n\n for _ in 0..40 {\n if !pid_alive(pid) {\n break;\n }\n thread::sleep(Duration::from_millis(50));\n }\n\n let _ = fs::remove_file(&paths.native_pid);\n println!(\"Native local domains proxy stopped.\");\n Ok(())\n}\n\nfn run_doctor_native(paths: &DomainsPaths) -> Result<()> {\n ensure_layout(paths)?;\n let routes = load_routes(paths)?;\n let running = native_proxy_running(paths)?;\n\n println!(\"Local domains doctor\");\n println!(\"--------------------\");\n println!(\"Engine: native\");\n println!(\"Config root: {}\", paths.root.display());\n println!(\"Routes: {}\", routes.len());\n println!(\n \"Native daemon: {}\",\n if running { \"running\" } else { \"stopped\" }\n );\n println!(\"Native binary: {}\", paths.native_bin.display());\n println!(\"Native pid file: {}\", paths.native_pid.display());\n println!(\"Native log file: {}\", paths.native_log.display());\n\n if let Some(owner) = docker_container_owning_port_80()? {\n println!(\"Port 80 docker owner: {}\", owner);\n } else if let Some(listener) = port_80_listener_summary()? {\n println!(\"Port 80 listener: {}\", listener);\n } else {\n println!(\"Port 80 listener: none\");\n }\n\n println!(\n \"Native health: {}\",\n if native_healthcheck().unwrap_or(false) {\n \"ok\"\n } else {\n \"unreachable\"\n }\n );\n\n if !routes.is_empty() {\n println!();\n println!(\"{:<32} {}\", \"HOST\", \"TARGET\");\n println!(\"{}\", \"-\".repeat(58));\n for (host, target) in routes {\n println!(\"{:<32} {}\", host, target);\n }\n }\n\n Ok(())\n}\n\nfn native_source_path() -> PathBuf {\n PathBuf::from(env!(\"CARGO_MANIFEST_DIR\"))\n .join(\"tools\")\n .join(\"domainsd-cpp\")\n .join(\"domainsd.cpp\")\n}\n\nfn domainsd_tools_dir() -> PathBuf {\n PathBuf::from(env!(\"CARGO_MANIFEST_DIR\"))\n .join(\"tools\")\n .join(\"domainsd-cpp\")\n}\n\nfn macos_launchd_install_script_path() -> PathBuf {\n domainsd_tools_dir().join(\"install-macos-launchd.sh\")\n}\n\nfn macos_launchd_uninstall_script_path() -> PathBuf {\n domainsd_tools_dir().join(\"uninstall-macos-launchd.sh\")\n}\n\nfn macos_launchd_plist_path() -> PathBuf {\n PathBuf::from(\"/Library/LaunchDaemons\").join(format!(\"{MACOS_DOMAINSD_LABEL}.plist\"))\n}\n\nfn log_contains_permission_denied(path: &Path) -> Result<bool> {\n if !path.exists() {\n return Ok(false);\n }\n let content = fs::read_to_string(path)\n .with_context(|| format!(\"Failed to read native log {}\", path.display()))?;\n Ok(content.contains(\"Permission denied\"))\n}\n\nfn ensure_native_binary(paths: &DomainsPaths) -> Result<()> {\n let source = native_source_path();\n if !source.exists() {\n bail!(\n \"Native domains daemon source not found at {}\",\n source.display()\n );\n }\n\n let rebuild = if !paths.native_bin.exists() {\n true\n } else {\n let src_mtime = fs::metadata(&source)\n .and_then(|m| m.modified())\n .context(\"Failed to read native daemon source mtime\")?;\n let bin_mtime = fs::metadata(&paths.native_bin)\n .and_then(|m| m.modified())\n .context(\"Failed to read native daemon binary mtime\")?;\n src_mtime > bin_mtime\n };\n\n if !rebuild {\n return Ok(());\n }\n\n let compiler = if std::path::Path::new(\"/usr/bin/clang++\").exists() {\n PathBuf::from(\"/usr/bin/clang++\")\n } else {\n which::which(\"clang++\")\n .context(\"clang++ is required for --engine native (install Xcode command line tools)\")?\n };\n\n let output = Command::new(&compiler)\n .args([\n \"-std=c++20\",\n \"-O3\",\n \"-DNDEBUG\",\n \"-Wall\",\n \"-Wextra\",\n \"-pthread\",\n source.to_string_lossy().as_ref(),\n \"-o\",\n paths.native_bin.to_string_lossy().as_ref(),\n ])\n .output()\n .context(\"Failed to build native local domains daemon\")?;\n ensure_success(output, \"Failed to build native local domains daemon\")?;\n Ok(())\n}\n\nfn assert_no_port_80_conflict_native(paths: &DomainsPaths) -> Result<()> {\n if native_proxy_running(paths)? {\n return Ok(());\n }\n\n if let Some(owner) = docker_container_owning_port_80()? {\n bail!(\n \"Port 80 is owned by docker container '{}'. Stop it first before starting native domains proxy.\",\n owner\n );\n }\n if let Some(listener) = port_80_listener_summary()? {\n bail!(\n \"Port 80 is already in use by '{}'. Stop that listener, then retry `f domains --engine native up`.\",\n listener\n );\n }\n Ok(())\n}\n\nfn start_native_proxy(paths: &DomainsPaths) -> Result<()> {\n let log_file = fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(&paths.native_log)\n .with_context(|| format!(\"Failed to open log file {}\", paths.native_log.display()))?;\n let err_file = log_file\n .try_clone()\n .context(\"Failed to duplicate native proxy log file handle\")?;\n\n let mut cmd = Command::new(&paths.native_bin);\n cmd.arg(\"--listen\")\n .arg(\"127.0.0.1:80\")\n .arg(\"--routes\")\n .arg(&paths.routes_state)\n .arg(\"--pidfile\")\n .arg(&paths.native_pid);\n\n for (flag, value) in native_tuning_args()? {\n cmd.arg(flag).arg(value);\n }\n\n let child = cmd\n .stdout(log_file)\n .stderr(err_file)\n .spawn()\n .context(\"Failed to spawn native local domains daemon\")?;\n\n let pid = child.id();\n for _ in 0..50 {\n if native_healthcheck().unwrap_or(false) {\n return Ok(());\n }\n thread::sleep(Duration::from_millis(100));\n }\n if cfg!(target_os = \"macos\") && log_contains_permission_denied(&paths.native_log)? {\n bail!(\n \"Native local domains proxy failed to bind port 80 (permission denied).\\n\\\nmacOS requires privileged socket ownership for :80 in native mode.\\n\\\nRun once:\\n sudo {}\\n\\\nThen retry: f domains --engine native up\\n\\\nLog: {}\",\n macos_launchd_install_script_path().display(),\n paths.native_log.display()\n );\n }\n bail!(\n \"Native local domains proxy failed to become healthy (pid {}). Check logs: {}\",\n pid,\n paths.native_log.display()\n )\n}\n\nfn native_tuning_args() -> Result<Vec<(&'static str, String)>> {\n const MAPPINGS: [(&str, &str); 8] = [\n (\n \"FLOW_DOMAINS_NATIVE_MAX_ACTIVE_CLIENTS\",\n \"--max-active-clients\",\n ),\n (\n \"FLOW_DOMAINS_NATIVE_UPSTREAM_CONNECT_TIMEOUT_MS\",\n \"--upstream-connect-timeout-ms\",\n ),\n (\n \"FLOW_DOMAINS_NATIVE_UPSTREAM_IO_TIMEOUT_MS\",\n \"--upstream-io-timeout-ms\",\n ),\n (\n \"FLOW_DOMAINS_NATIVE_CLIENT_IO_TIMEOUT_MS\",\n \"--client-io-timeout-ms\",\n ),\n (\n \"FLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_PER_KEY\",\n \"--pool-max-idle-per-key\",\n ),\n (\n \"FLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_TOTAL\",\n \"--pool-max-idle-total\",\n ),\n (\n \"FLOW_DOMAINS_NATIVE_POOL_IDLE_TIMEOUT_MS\",\n \"--pool-idle-timeout-ms\",\n ),\n (\"FLOW_DOMAINS_NATIVE_POOL_MAX_AGE_MS\", \"--pool-max-age-ms\"),\n ];\n\n let mut out = Vec::new();\n for (env_name, flag) in MAPPINGS {\n if let Ok(raw) = std::env::var(env_name) {\n let parsed = raw\n .trim()\n .parse::<u64>()\n .with_context(|| format!(\"Invalid {} value: {}\", env_name, raw))?;\n if parsed == 0 {\n bail!(\"{} must be > 0\", env_name);\n }\n out.push((flag, parsed.to_string()));\n }\n }\n Ok(out)\n}\n\nfn read_native_pid(paths: &DomainsPaths) -> Result<Option<u32>> {\n if !paths.native_pid.exists() {\n return Ok(None);\n }\n let raw = fs::read_to_string(&paths.native_pid)\n .with_context(|| format!(\"Failed to read {}\", paths.native_pid.display()))?;\n let parsed = raw\n .trim()\n .parse::<u32>()\n .with_context(|| format!(\"Invalid pid in {}\", paths.native_pid.display()))?;\n Ok(Some(parsed))\n}\n\nfn pid_alive(pid: u32) -> bool {\n Command::new(\"kill\")\n .args([\"-0\", &pid.to_string()])\n .status()\n .map(|s| s.success())\n .unwrap_or(false)\n}\n\nfn native_proxy_running(paths: &DomainsPaths) -> Result<bool> {\n let Some(pid) = read_native_pid(paths)? else {\n return Ok(false);\n };\n if !pid_alive(pid) {\n return Ok(false);\n }\n Ok(native_healthcheck().unwrap_or(false))\n}\n\nfn native_healthcheck() -> Result<bool> {\n let mut stream = match TcpStream::connect(\"127.0.0.1:80\") {\n Ok(s) => s,\n Err(_) => return Ok(false),\n };\n stream.set_read_timeout(Some(Duration::from_millis(250)))?;\n stream.set_write_timeout(Some(Duration::from_millis(250)))?;\n stream.write_all(\n b\"GET /_flow/domains/health HTTP/1.1\\r\\nHost: flow-domains-health.localhost\\r\\nConnection: close\\r\\n\\r\\n\",\n )?;\n let mut buf = [0_u8; 2048];\n let n = stream.read(&mut buf)?;\n if n == 0 {\n return Ok(false);\n }\n let response = String::from_utf8_lossy(&buf[..n]).to_ascii_lowercase();\n Ok(response.contains(NATIVE_PROXY_HEADER))\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn render_route_uses_localhost_host_header_for_loopback_targets() {\n let rendered = render_route(\"linsa.localhost\", \"127.0.0.1:3481\");\n assert!(rendered.contains(\"proxy_pass http://host.docker.internal:3481;\"));\n assert!(rendered.contains(\"proxy_set_header Host localhost;\"));\n }\n\n #[test]\n fn normalize_host_requires_localhost_suffix() {\n assert!(normalize_host(\"linsa.localhost\").is_ok());\n assert!(normalize_host(\"linsa.dev\").is_err());\n }\n\n #[test]\n fn normalize_target_requires_port() {\n assert!(normalize_target(\"127.0.0.1:3481\").is_ok());\n assert!(normalize_target(\"127.0.0.1\").is_err());\n }\n}\n" }, { "path": "src/env.rs", "content": "//! Environment variable management via the cloud backend with local fallback.\n//!\n//! Fetches, sets, and manages environment variables for projects\n//! using the cloud API, with optional local storage when needed.\n\nuse std::collections::{HashMap, HashSet};\nuse std::fs::{self, OpenOptions};\nuse std::io::{self, IsTerminal, Write};\n#[cfg(unix)]\nuse std::os::unix::fs::{OpenOptionsExt, PermissionsExt};\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\nuse base64::{Engine as _, engine::general_purpose::STANDARD};\nuse chrono::{DateTime, Local, TimeZone, Utc};\nuse crypto_secretbox::{\n XSalsa20Poly1305,\n aead::{Aead, KeyInit},\n};\nuse rand::{TryRng, rngs::SysRng};\nuse reqwest::Url;\nuse serde::{Deserialize, Serialize};\nuse which::which;\n\nuse crate::agent_setup;\nuse crate::cli::{EnvAction, ProjectEnvAction, TokenAction};\nuse crate::config;\nuse crate::deploy;\nuse crate::env_setup::{EnvSetupDefaults, run_env_setup};\nuse crate::sealer_crypto::{get_sealer_id, new_x25519_private_key, seal, unseal};\nuse crate::storage::{\n create_jazz_app_credentials, get_project_name as storage_project_name, sanitize_name,\n};\nuse uuid::Uuid;\n\nconst DEFAULT_API_URL: &str = \"https://myflow.sh\";\nconst LOCAL_ENV_DIR: &str = \"env-local\";\nconst LOCAL_KEYCHAIN_REF_PREFIX: &str = \"flow-keychain-ref://v1/\";\nconst ENV_SEALER_SECRET_PREFIX: &str = \"sealerSecret_z\";\nconst SEALED_ENV_ALGORITHM: &str = \"xsalsa20poly1305+flow-sealer-v1\";\n\n/// Auth config stored in ~/.config/flow/auth.toml\n#[derive(Debug, Serialize, Deserialize, Default)]\nstruct AuthConfig {\n token: Option<String>,\n api_url: Option<String>,\n token_source: Option<String>,\n ai_token: Option<String>,\n ai_api_url: Option<String>,\n ai_token_source: Option<String>,\n}\n\n#[derive(Debug, Serialize, Deserialize)]\nstruct EnvReadUnlock {\n expires_at: i64,\n}\n\n/// An env var with optional description.\n#[derive(Debug, Serialize, Deserialize, Clone)]\npub struct EnvVar {\n pub value: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub description: Option<String>,\n}\n\n/// Response from /api/env/:projectName\n#[derive(Debug, Deserialize)]\nstruct EnvResponse {\n env: HashMap<String, String>,\n #[serde(default)]\n descriptions: HashMap<String, String>,\n}\n\n/// Response from POST /api/env/:projectName\n#[derive(Debug, Deserialize)]\n#[allow(dead_code)]\nstruct SetEnvResponse {\n success: bool,\n project: String,\n environment: String,\n}\n\n/// Response from /api/env/personal\n#[derive(Debug, Deserialize)]\nstruct PersonalEnvResponse {\n env: HashMap<String, String>,\n}\n\n#[derive(Debug, Serialize, Deserialize)]\nstruct EnvSealerIdentity {\n sealer_secret: String,\n sealer_id: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ProjectSealersResponse {\n members: Vec<ProjectSealerMember>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ProjectSealerMember {\n #[serde(default)]\n sealers: Vec<ProjectSealerEntry>,\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct ProjectSealerEntry {\n sealer_id: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct SealedEnvResponse {\n items: HashMap<String, SealedEnvItem>,\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct SealedEnvItem {\n #[serde(default)]\n description: Option<String>,\n #[serde(default)]\n available_recipient_count: usize,\n content: Option<SealedEnvContent>,\n #[serde(default)]\n recipients: Vec<SealedEnvRecipientGrant>,\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct SealedEnvContent {\n algorithm: String,\n ciphertext_b64: String,\n nonce_b64: String,\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct SealedEnvRecipientGrant {\n recipient_id: String,\n sender_id: Option<String>,\n wrapped_key_b64: String,\n nonce_material_b64: String,\n}\n\n#[derive(Debug, Serialize)]\nstruct SealedEnvWriteRequest {\n environment: String,\n items: HashMap<String, SealedEnvWriteItem>,\n}\n\n#[derive(Debug, Serialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct SealedEnvWriteItem {\n #[serde(skip_serializing_if = \"Option::is_none\")]\n description: Option<String>,\n classification: String,\n content: SealedEnvWriteContent,\n recipients: Vec<SealedEnvWriteRecipient>,\n}\n\n#[derive(Debug, Serialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct SealedEnvWriteContent {\n algorithm: String,\n ciphertext_b64: String,\n nonce_b64: String,\n}\n\n#[derive(Debug, Serialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct SealedEnvWriteRecipient {\n recipient_id: String,\n recipient_kind: String,\n sender_id: String,\n wrapped_key_b64: String,\n nonce_material_b64: String,\n}\n\n#[derive(Debug, Default)]\nstruct ProjectCloudEnvEntries {\n vars: HashMap<String, String>,\n descriptions: HashMap<String, String>,\n}\n\n/// Get the auth config path.\nfn get_auth_config_path() -> PathBuf {\n let config_dir = dirs::config_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"flow\");\n config_dir.join(\"auth.toml\")\n}\n\n/// Load auth config.\nfn load_auth_config_raw() -> Result<AuthConfig> {\n let path = get_auth_config_path();\n if !path.exists() {\n return Ok(AuthConfig::default());\n }\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n toml::from_str(&content).context(\"failed to parse auth.toml\")\n}\n\n/// Load auth config and hydrate token from Keychain on macOS when configured.\nfn load_auth_config() -> Result<AuthConfig> {\n let mut auth = load_auth_config_raw()?;\n if auth.token.is_none()\n && auth\n .token_source\n .as_deref()\n .map(|source| source == \"keychain\")\n .unwrap_or(false)\n {\n require_env_read_unlock()?;\n if let Some(token) = get_keychain_token(&get_api_url(&auth))? {\n auth.token = Some(token);\n }\n }\n Ok(auth)\n}\n\nfn load_ai_auth_config() -> Result<AuthConfig> {\n let mut auth = load_auth_config_raw()?;\n if auth.ai_token.is_none()\n && auth\n .ai_token_source\n .as_deref()\n .map(|source| source == \"keychain\")\n .unwrap_or(false)\n {\n if let Some(token) = get_keychain_ai_token(&get_ai_api_url(&auth))? {\n auth.ai_token = Some(token);\n }\n }\n Ok(auth)\n}\n\n/// Save auth config.\nfn save_auth_config(config: &AuthConfig) -> Result<()> {\n let path = get_auth_config_path();\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n let content = toml::to_string_pretty(config)?;\n fs::write(&path, content)?;\n Ok(())\n}\n\nfn keychain_service(api_url: &str) -> String {\n format!(\"flow-cloud-token:{}\", api_url)\n}\n\nfn keychain_service_ai(api_url: &str) -> String {\n format!(\"flow-ai-token:{}\", api_url)\n}\n\nfn local_env_keychain_service(target: &EnvTarget, environment: &str) -> String {\n let env_name = if environment.trim().is_empty() {\n \"production\"\n } else {\n environment\n };\n format!(\n \"flow-local-env:{}:{}\",\n sanitize_env_segment(&env_target_label(target)),\n sanitize_env_segment(env_name)\n )\n}\n\nfn set_keychain_token(api_url: &str, token: &str) -> Result<()> {\n let service = keychain_service(api_url);\n let status = Command::new(\"security\")\n .args([\n \"add-generic-password\",\n \"-a\",\n \"flow\",\n \"-s\",\n &service,\n \"-w\",\n token,\n \"-U\",\n ])\n .status()\n .context(\"failed to store token in Keychain\")?;\n if !status.success() {\n bail!(\"failed to store token in Keychain\");\n }\n Ok(())\n}\n\nfn set_keychain_ai_token(api_url: &str, token: &str) -> Result<()> {\n let service = keychain_service_ai(api_url);\n let status = Command::new(\"security\")\n .args([\n \"add-generic-password\",\n \"-a\",\n \"flow\",\n \"-s\",\n &service,\n \"-w\",\n token,\n \"-U\",\n ])\n .status()\n .context(\"failed to store AI token in Keychain\")?;\n if !status.success() {\n bail!(\"failed to store AI token in Keychain\");\n }\n Ok(())\n}\n\nfn get_keychain_token(api_url: &str) -> Result<Option<String>> {\n if !cfg!(target_os = \"macos\") {\n return Ok(None);\n }\n\n let service = keychain_service(api_url);\n let output = Command::new(\"security\")\n .args([\"find-generic-password\", \"-a\", \"flow\", \"-s\", &service, \"-w\"])\n .output()\n .context(\"failed to read token from Keychain\")?;\n\n if output.status.success() {\n let token = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if token.is_empty() {\n return Ok(None);\n }\n return Ok(Some(token));\n }\n\n let stderr = String::from_utf8_lossy(&output.stderr);\n if stderr.contains(\"could not be found\") || stderr.contains(\"SecKeychainSearchCopyNext\") {\n return Ok(None);\n }\n\n bail!(\"failed to read token from Keychain: {}\", stderr.trim());\n}\n\nfn get_keychain_ai_token(api_url: &str) -> Result<Option<String>> {\n if !cfg!(target_os = \"macos\") {\n return Ok(None);\n }\n\n let service = keychain_service_ai(api_url);\n let output = Command::new(\"security\")\n .args([\"find-generic-password\", \"-a\", \"flow\", \"-s\", &service, \"-w\"])\n .output()\n .context(\"failed to read AI token from Keychain\")?;\n\n if output.status.success() {\n let token = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if token.is_empty() {\n return Ok(None);\n }\n return Ok(Some(token));\n }\n\n let stderr = String::from_utf8_lossy(&output.stderr);\n if stderr.contains(\"could not be found\") || stderr.contains(\"SecKeychainSearchCopyNext\") {\n return Ok(None);\n }\n\n bail!(\"failed to read AI token from Keychain: {}\", stderr.trim());\n}\n\nfn set_local_keychain_env_var(\n target: &EnvTarget,\n environment: &str,\n key: &str,\n value: &str,\n) -> Result<()> {\n if !cfg!(target_os = \"macos\") {\n bail!(\"local keychain-backed envs require macOS\");\n }\n\n let service = local_env_keychain_service(target, environment);\n let status = Command::new(\"security\")\n .args([\n \"add-generic-password\",\n \"-a\",\n key,\n \"-s\",\n &service,\n \"-w\",\n value,\n \"-U\",\n ])\n .status()\n .context(\"failed to store local env var in Keychain\")?;\n if !status.success() {\n bail!(\"failed to store local env var in Keychain\");\n }\n Ok(())\n}\n\nfn get_local_keychain_env_var(\n target: &EnvTarget,\n environment: &str,\n key: &str,\n) -> Result<Option<String>> {\n if !cfg!(target_os = \"macos\") {\n return Ok(None);\n }\n\n let service = local_env_keychain_service(target, environment);\n let output = Command::new(\"security\")\n .args([\"find-generic-password\", \"-a\", key, \"-s\", &service, \"-w\"])\n .output()\n .context(\"failed to read local env var from Keychain\")?;\n\n if output.status.success() {\n let value = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if value.is_empty() {\n return Ok(None);\n }\n return Ok(Some(value));\n }\n\n let stderr = String::from_utf8_lossy(&output.stderr);\n if stderr.contains(\"could not be found\") || stderr.contains(\"SecKeychainSearchCopyNext\") {\n return Ok(None);\n }\n\n bail!(\n \"failed to read local env var from Keychain: {}\",\n stderr.trim()\n );\n}\n\nfn delete_local_keychain_env_var(target: &EnvTarget, environment: &str, key: &str) -> Result<()> {\n if !cfg!(target_os = \"macos\") {\n return Ok(());\n }\n\n let service = local_env_keychain_service(target, environment);\n let output = Command::new(\"security\")\n .args([\"delete-generic-password\", \"-a\", key, \"-s\", &service])\n .output()\n .context(\"failed to delete local env var from Keychain\")?;\n\n if output.status.success() {\n return Ok(());\n }\n\n let stderr = String::from_utf8_lossy(&output.stderr);\n if stderr.contains(\"could not be found\") || stderr.contains(\"SecKeychainSearchCopyNext\") {\n return Ok(());\n }\n\n bail!(\n \"failed to delete local env var from Keychain: {}\",\n stderr.trim()\n );\n}\n\nfn store_auth_token(auth: &mut AuthConfig, token: String) -> Result<()> {\n let api_url = get_api_url(auth);\n if cfg!(target_os = \"macos\") {\n if let Err(err) = set_keychain_token(&api_url, &token) {\n eprintln!(\"⚠ Failed to store token in Keychain: {}\", err);\n eprintln!(\" Falling back to auth.toml storage.\");\n auth.token = Some(token);\n auth.token_source = None;\n return Ok(());\n }\n auth.token = None;\n auth.token_source = Some(\"keychain\".to_string());\n } else {\n auth.token = Some(token);\n auth.token_source = None;\n }\n Ok(())\n}\n\nfn store_ai_auth_token(auth: &mut AuthConfig, token: String) -> Result<()> {\n let api_url = get_ai_api_url(auth);\n if cfg!(target_os = \"macos\") {\n if let Err(err) = set_keychain_ai_token(&api_url, &token) {\n eprintln!(\"⚠ Failed to store AI token in Keychain: {}\", err);\n eprintln!(\" Falling back to auth.toml storage.\");\n auth.ai_token = Some(token);\n auth.ai_token_source = None;\n return Ok(());\n }\n auth.ai_token = None;\n auth.ai_token_source = Some(\"keychain\".to_string());\n } else {\n auth.ai_token = Some(token);\n auth.ai_token_source = None;\n }\n Ok(())\n}\n\nfn get_env_unlock_path() -> PathBuf {\n let config_dir = dirs::config_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"flow\");\n config_dir.join(\"env_read_unlock.json\")\n}\n\nfn load_env_unlock() -> Option<EnvReadUnlock> {\n let path = get_env_unlock_path();\n let content = fs::read_to_string(&path).ok()?;\n serde_json::from_str(&content).ok()\n}\n\nfn unlock_expires_at(entry: &EnvReadUnlock) -> Option<DateTime<Utc>> {\n Utc.timestamp_opt(entry.expires_at, 0).single()\n}\n\nfn save_env_unlock(expires_at: DateTime<Utc>) -> Result<()> {\n let path = get_env_unlock_path();\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n let entry = EnvReadUnlock {\n expires_at: expires_at.timestamp(),\n };\n let content = serde_json::to_string_pretty(&entry)?;\n fs::write(&path, content)?;\n Ok(())\n}\n\nfn next_local_midnight_utc() -> Result<DateTime<Utc>> {\n let now = Local::now();\n let tomorrow = now\n .date_naive()\n .succ_opt()\n .ok_or_else(|| anyhow::anyhow!(\"failed to calculate next day\"))?;\n let naive = tomorrow\n .and_hms_opt(0, 0, 0)\n .ok_or_else(|| anyhow::anyhow!(\"failed to build midnight time\"))?;\n let local_dt = Local\n .from_local_datetime(&naive)\n .single()\n .or_else(|| Local.from_local_datetime(&naive).earliest())\n .ok_or_else(|| anyhow::anyhow!(\"failed to resolve local midnight\"))?;\n Ok(local_dt.with_timezone(&Utc))\n}\n\nfn prompt_touch_id() -> Result<()> {\n if !cfg!(target_os = \"macos\") {\n bail!(\"Touch ID is not available on this OS\");\n }\n if std::env::var(\"FLOW_NO_TOUCH_ID\").is_ok() || !std::io::stdin().is_terminal() {\n bail!(\"Touch ID prompt requires an interactive terminal\");\n }\n\n let reason = \"Flow needs Touch ID to read env vars.\";\n let reason = reason.replace('\\\\', \"\\\\\\\\\").replace('\"', \"\\\\\\\"\");\n let script = format!(\n r#\"ObjC.import('stdlib');\nObjC.import('Foundation');\nObjC.import('LocalAuthentication');\nconst context = $.LAContext.alloc.init;\nconst policy = $.LAPolicyDeviceOwnerAuthenticationWithBiometrics;\nconst error = Ref();\nif (!context.canEvaluatePolicyError(policy, error)) {{\n $.exit(2);\n}}\nlet ok = false;\nlet done = false;\ncontext.evaluatePolicyLocalizedReasonReply(policy, \"{reason}\", function(success, err) {{\n ok = success;\n done = true;\n}});\nconst runLoop = $.NSRunLoop.currentRunLoop;\nwhile (!done) {{\n runLoop.runUntilDate($.NSDate.dateWithTimeIntervalSinceNow(0.1));\n}}\n$.exit(ok ? 0 : 1);\"#\n );\n\n let status = Command::new(\"osascript\")\n .args([\"-l\", \"JavaScript\", \"-e\", &script])\n .status()\n .context(\"failed to launch Touch ID prompt\")?;\n\n match status.code() {\n Some(0) => Ok(()),\n Some(1) => bail!(\"Touch ID verification failed\"),\n Some(2) => bail!(\"Touch ID is not available on this device\"),\n _ => bail!(\"Touch ID verification failed\"),\n }\n}\n\nfn unlock_env_read() -> Result<()> {\n if !cfg!(target_os = \"macos\") {\n println!(\"Touch ID unlock is not available on this OS.\");\n return Ok(());\n }\n\n if let Some(entry) = load_env_unlock() {\n if let Some(expires_at) = unlock_expires_at(&entry) {\n if expires_at > Utc::now() {\n let local_expiry = expires_at.with_timezone(&Local);\n println!(\n \"Env read access already unlocked until {}\",\n local_expiry.format(\"%Y-%m-%d %H:%M %Z\")\n );\n return Ok(());\n }\n }\n }\n\n println!(\"Touch ID required to read env vars.\");\n prompt_touch_id()?;\n let expires_at = next_local_midnight_utc()?;\n save_env_unlock(expires_at)?;\n let local_expiry = expires_at.with_timezone(&Local);\n println!(\n \"✓ Env read access unlocked until {}\",\n local_expiry.format(\"%Y-%m-%d %H:%M %Z\")\n );\n Ok(())\n}\n\nfn require_env_read_unlock() -> Result<()> {\n if !cfg!(target_os = \"macos\") {\n return Ok(());\n }\n\n if let Some(entry) = load_env_unlock() {\n if let Some(expires_at) = unlock_expires_at(&entry) {\n if expires_at > Utc::now() {\n return Ok(());\n }\n }\n }\n\n unlock_env_read()\n}\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nenum EnvScope {\n Project,\n Personal,\n}\n\n#[derive(Debug, Clone)]\nstruct EnvTargetConfig {\n project_name: String,\n env_space: Option<String>,\n env_space_kind: EnvScope,\n}\n\n#[derive(Debug, Clone)]\nenum EnvTarget {\n Project { name: String },\n Personal { space: Option<String> },\n}\n\nfn parse_env_space_kind(value: Option<&str>) -> EnvScope {\n match value.map(|s| s.trim().to_ascii_lowercase()) {\n Some(ref v) if v == \"personal\" || v == \"user\" || v == \"private\" => EnvScope::Personal,\n _ => EnvScope::Project,\n }\n}\n\nfn load_env_target_config() -> Result<EnvTargetConfig> {\n let cwd = std::env::current_dir()?;\n if let Some(flow_path) = find_flow_toml(&cwd) {\n let cfg = config::load(&flow_path)?;\n let project_name = if let Some(name) = cfg.project_name {\n name\n } else if let Some(parent) = flow_path.parent() {\n parent\n .file_name()\n .and_then(|n| n.to_str())\n .map(|s| s.to_string())\n .unwrap_or_else(|| \"unnamed\".to_string())\n } else {\n \"unnamed\".to_string()\n };\n let env_space = cfg.env_space.and_then(|value| {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n }\n });\n let env_space_kind = parse_env_space_kind(cfg.env_space_kind.as_deref());\n return Ok(EnvTargetConfig {\n project_name,\n env_space,\n env_space_kind,\n });\n }\n\n let project_name = cwd\n .file_name()\n .and_then(|n| n.to_str())\n .map(|s| s.to_string())\n .unwrap_or_else(|| \"unnamed\".to_string());\n Ok(EnvTargetConfig {\n project_name,\n env_space: None,\n env_space_kind: EnvScope::Project,\n })\n}\n\nfn resolve_env_target() -> Result<EnvTarget> {\n let cfg = load_env_target_config()?;\n Ok(match cfg.env_space_kind {\n EnvScope::Personal => EnvTarget::Personal {\n space: cfg.env_space,\n },\n EnvScope::Project => EnvTarget::Project {\n name: cfg.env_space.unwrap_or(cfg.project_name),\n },\n })\n}\n\nfn resolve_personal_target() -> Result<EnvTarget> {\n let cfg = load_env_target_config()?;\n Ok(EnvTarget::Personal {\n space: cfg.env_space,\n })\n}\n\nfn env_target_label(target: &EnvTarget) -> String {\n match target {\n EnvTarget::Project { name } => name.clone(),\n EnvTarget::Personal { space } => space.clone().unwrap_or_else(|| \"personal\".to_string()),\n }\n}\n\nfn normalize_env_backend_name(value: &str) -> Option<&'static str> {\n match value.trim().to_ascii_lowercase().as_str() {\n \"local\" => Some(\"local\"),\n \"cloud\" | \"remote\" | \"myflow\" => Some(\"cloud\"),\n _ => None,\n }\n}\n\nfn project_env_backend_from_config(cfg: &config::Config) -> Option<&'static str> {\n let mut resolved: Option<&'static str> = None;\n\n for source in [\n cfg.host\n .as_ref()\n .and_then(|host| host.env_source.as_deref()),\n cfg.cloudflare\n .as_ref()\n .and_then(|cloudflare| cloudflare.env_source.as_deref()),\n cfg.web.as_ref().and_then(|web| web.env_source.as_deref()),\n ] {\n let Some(backend) = source.and_then(normalize_env_backend_name) else {\n continue;\n };\n\n match resolved {\n Some(existing) if existing != backend => return None,\n Some(_) => {}\n None => resolved = Some(backend),\n }\n }\n\n resolved\n}\n\nfn project_env_backend_from_current_dir() -> Option<&'static str> {\n let cwd = std::env::current_dir().ok()?;\n let flow_path = find_flow_toml(&cwd)?;\n let cfg = config::load(&flow_path).ok()?;\n project_env_backend_from_config(&cfg)\n}\n\nfn local_env_enabled() -> bool {\n match std::env::var(\"FLOW_ENV_BACKEND\")\n .ok()\n .as_deref()\n .and_then(normalize_env_backend_name)\n {\n Some(\"local\") => return true,\n Some(\"cloud\") => return false,\n _ => {}\n }\n\n if let Some(backend) = config::preferred_env_backend() {\n match normalize_env_backend_name(&backend) {\n Some(\"local\") => return true,\n Some(\"cloud\") => return false,\n _ => {}\n }\n }\n\n if let Some(backend) = project_env_backend_from_current_dir() {\n return backend == \"local\";\n }\n\n std::env::var(\"FLOW_ENV_LOCAL\")\n .ok()\n .map(|v| {\n let v = v.to_ascii_lowercase();\n v == \"1\" || v == \"true\" || v == \"yes\"\n })\n .unwrap_or(false)\n}\n\nfn local_env_root() -> Result<PathBuf> {\n let base = config::ensure_global_config_dir()?;\n let path = base.join(LOCAL_ENV_DIR);\n ensure_private_dir(&path)?;\n Ok(path)\n}\n\nfn ensure_private_dir(path: &Path) -> Result<()> {\n fs::create_dir_all(path)?;\n #[cfg(unix)]\n fs::set_permissions(path, fs::Permissions::from_mode(0o700))?;\n Ok(())\n}\n\nfn write_private_file(path: &Path, content: &str) -> Result<()> {\n if let Some(parent) = path.parent() {\n ensure_private_dir(parent)?;\n }\n\n #[cfg(unix)]\n {\n let mut file = OpenOptions::new()\n .create(true)\n .truncate(true)\n .write(true)\n .mode(0o600)\n .open(path)?;\n file.write_all(content.as_bytes())?;\n fs::set_permissions(path, fs::Permissions::from_mode(0o600))?;\n }\n\n #[cfg(not(unix))]\n {\n fs::write(path, content)?;\n }\n\n Ok(())\n}\n\nfn env_sealer_state_dir() -> Result<PathBuf> {\n let path = config::ensure_global_state_dir()?.join(\"env\");\n ensure_private_dir(&path)?;\n Ok(path)\n}\n\nfn env_sealer_identity_path() -> Result<PathBuf> {\n Ok(env_sealer_state_dir()?.join(\"sealer.json\"))\n}\n\nfn load_env_sealer_identity() -> Result<Option<EnvSealerIdentity>> {\n let path = env_sealer_identity_path()?;\n if !path.exists() {\n return Ok(None);\n }\n\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let mut identity: EnvSealerIdentity =\n serde_json::from_str(&content).context(\"failed to parse env sealer identity\")?;\n if identity.sealer_secret.trim().is_empty() {\n bail!(\"env sealer identity is missing its secret\");\n }\n\n let derived_id = get_sealer_id(&identity.sealer_secret).context(\"invalid env sealer secret\")?;\n if identity.sealer_id != derived_id {\n identity.sealer_id = derived_id;\n let updated = serde_json::to_string_pretty(&identity)?;\n write_private_file(&path, &updated)?;\n }\n\n Ok(Some(identity))\n}\n\nfn load_or_create_env_sealer_identity() -> Result<EnvSealerIdentity> {\n if let Some(identity) = load_env_sealer_identity()? {\n return Ok(identity);\n }\n\n let identity = create_env_sealer_identity()?;\n let path = env_sealer_identity_path()?;\n let content = serde_json::to_string_pretty(&identity)?;\n write_private_file(&path, &content)?;\n Ok(identity)\n}\n\nfn create_env_sealer_identity() -> Result<EnvSealerIdentity> {\n let private_key = new_x25519_private_key();\n let sealer_secret = format!(\n \"{}{}\",\n ENV_SEALER_SECRET_PREFIX,\n bs58::encode(&private_key).into_string()\n );\n let sealer_id = get_sealer_id(&sealer_secret).context(\"failed to derive env sealer id\")?;\n Ok(EnvSealerIdentity {\n sealer_secret,\n sealer_id,\n })\n}\n\nfn default_env_sealer_label() -> Option<String> {\n let host = std::env::var(\"FLOW_ENV_SEALER_LABEL\")\n .ok()\n .filter(|value| !value.trim().is_empty())\n .or_else(|| std::env::var(\"HOSTNAME\").ok())\n .or_else(|| std::env::var(\"COMPUTERNAME\").ok());\n let user = std::env::var(\"USER\")\n .ok()\n .filter(|value| !value.trim().is_empty())\n .or_else(|| std::env::var(\"USERNAME\").ok());\n\n match (host, user) {\n (Some(host), Some(user)) => Some(format!(\"{} ({})\", host.trim(), user.trim())),\n (Some(host), None) => Some(host.trim().to_string()),\n (None, Some(user)) => Some(format!(\"Flow ({})\", user.trim())),\n (None, None) => None,\n }\n}\n\nfn seal_project_env_value(\n value: &str,\n identity: &EnvSealerIdentity,\n recipient_ids: &[String],\n) -> Result<SealedEnvWriteItem> {\n let mut content_key = [0u8; 32];\n SysRng\n .try_fill_bytes(&mut content_key)\n .context(\"failed to generate env content key\")?;\n let mut content_nonce = [0u8; 24];\n SysRng\n .try_fill_bytes(&mut content_nonce)\n .context(\"failed to generate env content nonce\")?;\n\n let cipher = XSalsa20Poly1305::new(&content_key.into());\n let ciphertext = cipher\n .encrypt(&content_nonce.into(), value.as_bytes())\n .map_err(|_| anyhow::anyhow!(\"failed to encrypt env value\"))?;\n\n let mut recipients = Vec::new();\n let mut seen = HashSet::new();\n for recipient_id in recipient_ids {\n if !seen.insert(recipient_id.clone()) {\n continue;\n }\n\n let mut nonce_material = [0u8; 32];\n SysRng\n .try_fill_bytes(&mut nonce_material)\n .context(\"failed to generate env recipient nonce\")?;\n let wrapped_key = seal(\n &content_key,\n &identity.sealer_secret,\n recipient_id,\n &nonce_material,\n )\n .context(\"failed to wrap env content key\")?;\n recipients.push(SealedEnvWriteRecipient {\n recipient_id: recipient_id.clone(),\n recipient_kind: \"sealer\".to_string(),\n sender_id: identity.sealer_id.clone(),\n wrapped_key_b64: STANDARD.encode(&wrapped_key),\n nonce_material_b64: STANDARD.encode(nonce_material),\n });\n }\n\n Ok(SealedEnvWriteItem {\n description: None,\n classification: \"secret\".to_string(),\n content: SealedEnvWriteContent {\n algorithm: SEALED_ENV_ALGORITHM.to_string(),\n ciphertext_b64: STANDARD.encode(ciphertext),\n nonce_b64: STANDARD.encode(content_nonce),\n },\n recipients,\n })\n}\n\nfn decrypt_project_env_value(\n item: &SealedEnvItem,\n identity: &EnvSealerIdentity,\n) -> Result<Option<String>> {\n let content = item\n .content\n .as_ref()\n .ok_or_else(|| anyhow::anyhow!(\"sealed env item is missing content\"))?;\n if content.algorithm != SEALED_ENV_ALGORITHM {\n bail!(\"unsupported sealed env algorithm: {}\", content.algorithm);\n }\n\n let grant = match item\n .recipients\n .iter()\n .find(|grant| grant.recipient_id == identity.sealer_id)\n {\n Some(grant) => grant,\n None => return Ok(None),\n };\n\n let sender_id = grant\n .sender_id\n .as_deref()\n .ok_or_else(|| anyhow::anyhow!(\"sealed env grant is missing sender id\"))?;\n let wrapped_key = STANDARD\n .decode(grant.wrapped_key_b64.as_bytes())\n .context(\"failed to decode sealed env wrapped key\")?;\n let nonce_material = STANDARD\n .decode(grant.nonce_material_b64.as_bytes())\n .context(\"failed to decode sealed env nonce material\")?;\n let content_key = unseal(\n &wrapped_key,\n &identity.sealer_secret,\n sender_id,\n &nonce_material,\n )\n .context(\"failed to unwrap env content key\")?;\n let content_key: [u8; 32] = content_key\n .as_slice()\n .try_into()\n .map_err(|_| anyhow::anyhow!(\"invalid env content key length\"))?;\n\n let ciphertext = STANDARD\n .decode(content.ciphertext_b64.as_bytes())\n .context(\"failed to decode sealed env ciphertext\")?;\n let nonce = STANDARD\n .decode(content.nonce_b64.as_bytes())\n .context(\"failed to decode sealed env nonce\")?;\n let nonce: [u8; 24] = nonce\n .as_slice()\n .try_into()\n .map_err(|_| anyhow::anyhow!(\"invalid env content nonce length\"))?;\n let cipher = XSalsa20Poly1305::new(&content_key.into());\n let plaintext = cipher\n .decrypt(&nonce.into(), ciphertext.as_ref())\n .map_err(|_| anyhow::anyhow!(\"failed to decrypt sealed env value\"))?;\n let value = String::from_utf8(plaintext).context(\"sealed env value is not valid UTF-8\")?;\n Ok(Some(value))\n}\n\nfn sanitize_env_segment(value: &str) -> String {\n let mut out = String::new();\n let mut last_sep = false;\n for ch in value.chars() {\n if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || ch == '.' {\n out.push(ch);\n last_sep = false;\n } else if !last_sep {\n out.push('_');\n last_sep = true;\n }\n }\n let trimmed = out.trim_matches('_').to_string();\n if trimmed.is_empty() {\n \"unnamed\".to_string()\n } else {\n trimmed\n }\n}\n\nfn local_env_path(target: &EnvTarget, environment: &str) -> Result<PathBuf> {\n let root = local_env_root()?;\n let target_label = sanitize_env_segment(&env_target_label(target));\n let env_label = sanitize_env_segment(if environment.trim().is_empty() {\n \"production\"\n } else {\n environment\n });\n let dir = root.join(target_label);\n ensure_private_dir(&dir)?;\n Ok(dir.join(format!(\"{env_label}.env\")))\n}\n\nfn local_personal_keychain_supported(target: &EnvTarget) -> bool {\n cfg!(target_os = \"macos\") && matches!(target, EnvTarget::Personal { .. })\n}\n\nfn local_personal_keychain_write_enabled(target: &EnvTarget) -> bool {\n if !local_personal_keychain_supported(target) {\n return false;\n }\n\n !std::env::var(\"FLOW_ENV_LOCAL_PLAINTEXT\")\n .ok()\n .map(|value| {\n let value = value.to_ascii_lowercase();\n value == \"1\" || value == \"true\" || value == \"yes\"\n })\n .unwrap_or(false)\n}\n\nfn local_keychain_ref(key: &str) -> String {\n format!(\"{LOCAL_KEYCHAIN_REF_PREFIX}{key}\")\n}\n\nfn is_local_keychain_ref(value: &str) -> bool {\n value.starts_with(LOCAL_KEYCHAIN_REF_PREFIX)\n}\n\nfn read_local_env_vars_raw(\n target: &EnvTarget,\n environment: &str,\n) -> Result<HashMap<String, String>> {\n let path = local_env_path(target, environment)?;\n if !path.exists() {\n return Ok(HashMap::new());\n }\n let content = fs::read_to_string(&path)?;\n Ok(parse_env_file(&content))\n}\n\nfn migrate_local_env_vars_to_keychain_if_needed(\n target: &EnvTarget,\n environment: &str,\n vars: &mut HashMap<String, String>,\n) -> Result<()> {\n if !local_personal_keychain_write_enabled(target) {\n return Ok(());\n }\n\n let mut changed = false;\n let snapshot = vars.clone();\n for (key, value) in snapshot {\n if is_local_keychain_ref(&value) {\n continue;\n }\n set_local_keychain_env_var(target, environment, &key, &value)?;\n vars.insert(key.clone(), local_keychain_ref(&key));\n changed = true;\n }\n\n if changed {\n write_local_env_vars_raw(target, environment, vars)?;\n }\n\n Ok(())\n}\n\nfn resolve_local_env_vars(\n target: &EnvTarget,\n environment: &str,\n vars: &HashMap<String, String>,\n) -> Result<HashMap<String, String>> {\n if !local_personal_keychain_supported(target)\n || !vars.values().any(|value| is_local_keychain_ref(value))\n {\n return Ok(vars.clone());\n }\n\n require_env_read_unlock()?;\n\n let mut resolved = HashMap::new();\n for (key, value) in vars {\n if is_local_keychain_ref(value) {\n let secret = get_local_keychain_env_var(target, environment, key)?.ok_or_else(|| {\n anyhow::anyhow!(\n \"local env var '{}' is referenced from Keychain but the Keychain entry is missing\",\n key\n )\n })?;\n resolved.insert(key.clone(), secret);\n } else {\n resolved.insert(key.clone(), value.clone());\n }\n }\n\n Ok(resolved)\n}\n\nfn read_local_env_vars(target: &EnvTarget, environment: &str) -> Result<HashMap<String, String>> {\n let mut vars = read_local_env_vars_raw(target, environment)?;\n migrate_local_env_vars_to_keychain_if_needed(target, environment, &mut vars)?;\n resolve_local_env_vars(target, environment, &vars)\n}\n\n/// Returns true if the user has a cloud auth token configured.\npub fn has_cloud_auth_token() -> bool {\n load_auth_config().ok().and_then(|a| a.token).is_some()\n}\n\n/// Read keys from the local personal env store without cloud access.\npub fn fetch_local_personal_env_vars(keys: &[String]) -> Result<HashMap<String, String>> {\n let target = resolve_personal_target()?;\n let vars = read_local_env_vars(&target, \"production\")?;\n if keys.is_empty() {\n return Ok(vars);\n }\n let mut filtered = HashMap::new();\n let mut missing = Vec::new();\n for key in keys {\n if let Some(value) = vars.get(key) {\n filtered.insert(key.clone(), value.clone());\n } else {\n missing.push(key.clone());\n }\n }\n\n if !missing.is_empty() && local_personal_keychain_supported(&target) {\n require_env_read_unlock()?;\n for key in missing {\n if let Some(value) = get_local_keychain_env_var(&target, \"production\", &key)? {\n filtered.insert(key, value);\n }\n }\n }\n\n Ok(filtered)\n}\n\nfn write_local_env_vars_raw(\n target: &EnvTarget,\n environment: &str,\n vars: &HashMap<String, String>,\n) -> Result<PathBuf> {\n let path = local_env_path(target, environment)?;\n let mut keys: Vec<_> = vars.keys().collect();\n keys.sort();\n\n let mut content = String::new();\n content.push_str(&format!(\n \"# Local env store (flow)\\n# Target: {}\\n# Environment: {}\\n\",\n env_target_label(target),\n environment\n ));\n for key in keys {\n let value = &vars[key];\n let escaped = value.replace('\\\\', \"\\\\\\\\\").replace('\"', \"\\\\\\\"\");\n content.push_str(&format!(\"{key}=\\\"{escaped}\\\"\\n\"));\n }\n write_private_file(&path, &content)?;\n Ok(path)\n}\n\nfn set_local_env_var(\n target: &EnvTarget,\n environment: &str,\n key: &str,\n value: &str,\n) -> Result<PathBuf> {\n let mut vars = read_local_env_vars_raw(target, environment)?;\n\n if local_personal_keychain_write_enabled(target) {\n migrate_local_env_vars_to_keychain_if_needed(target, environment, &mut vars)?;\n set_local_keychain_env_var(target, environment, key, value)?;\n vars.insert(key.to_string(), local_keychain_ref(key));\n } else {\n vars.insert(key.to_string(), value.to_string());\n }\n\n write_local_env_vars_raw(target, environment, &vars)\n}\n\nfn delete_local_env_vars(\n target: &EnvTarget,\n environment: &str,\n keys: &[String],\n) -> Result<PathBuf> {\n if keys.is_empty() {\n bail!(\"No keys specified\");\n }\n\n let mut vars = read_local_env_vars_raw(target, environment)?;\n for key in keys {\n vars.remove(key);\n if local_personal_keychain_supported(target) {\n delete_local_keychain_env_var(target, environment, key)?;\n }\n }\n migrate_local_env_vars_to_keychain_if_needed(target, environment, &mut vars)?;\n write_local_env_vars_raw(target, environment, &vars)\n}\n\nfn is_local_fallback_error(err: &anyhow::Error) -> bool {\n let msg = err.to_string().to_ascii_lowercase();\n msg.contains(\"not logged in\")\n || msg.contains(\"failed to connect to cloud\")\n || msg.contains(\"unauthorized\")\n}\n\nfn env_target_name_for_tokens(target: &EnvTarget) -> Result<String> {\n match target {\n EnvTarget::Project { name } => Ok(name.clone()),\n EnvTarget::Personal { space } => space.clone().ok_or_else(|| {\n anyhow::anyhow!(\n \"Personal env space name required for service tokens. Set env_space in flow.toml.\"\n )\n }),\n }\n}\n\nfn resolve_env_file_path() -> Result<PathBuf> {\n let cwd = std::env::current_dir()?;\n\n if let Some(flow_path) = find_flow_toml(&cwd) {\n let project_root = flow_path.parent().unwrap_or(&cwd);\n let cfg = config::load(&flow_path)?;\n if let Some(cf_cfg) = cfg.cloudflare {\n if let Some(env_file) = cf_cfg.env_file {\n let env_file = env_file.trim();\n if !env_file.is_empty() {\n let expanded = config::expand_path(env_file);\n return Ok(project_root.join(expanded));\n }\n }\n }\n return Ok(project_root.join(\".env\"));\n }\n\n Ok(cwd.join(\".env\"))\n}\n\n/// Get API URL from config or default.\nfn get_api_url(auth: &AuthConfig) -> String {\n auth.api_url\n .clone()\n .unwrap_or_else(|| DEFAULT_API_URL.to_string())\n}\n\nfn get_ai_api_url(auth: &AuthConfig) -> String {\n auth.ai_api_url\n .clone()\n .unwrap_or_else(|| DEFAULT_API_URL.to_string())\n}\n\npub fn load_ai_auth_token() -> Result<Option<String>> {\n let auth = load_ai_auth_config()?;\n Ok(auth.ai_token)\n}\n\npub fn load_ai_api_url() -> Result<String> {\n let auth = load_auth_config_raw()?;\n Ok(get_ai_api_url(&auth))\n}\n\n/// Load the base URL for the cloud env API (defaults to https://myflow.sh).\n/// This is used for host deploy integrations where the remote host needs to fetch envs.\npub fn load_env_api_url() -> Result<String> {\n let auth = load_auth_config_raw()?;\n Ok(get_api_url(&auth))\n}\n\npub fn save_ai_auth_token(token: String, api_url: Option<String>) -> Result<()> {\n let mut auth = load_auth_config_raw()?;\n if let Some(api_url) = api_url {\n auth.ai_api_url = Some(api_url);\n }\n store_ai_auth_token(&mut auth, token)?;\n save_auth_config(&auth)?;\n Ok(())\n}\n\nfn find_flow_toml(start: &PathBuf) -> Option<PathBuf> {\n let mut current = start.clone();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\nfn is_cloud_source(source: Option<&str>) -> bool {\n matches!(\n source.map(|s| s.to_ascii_lowercase()).as_deref(),\n Some(\"cloud\") | Some(\"remote\") | Some(\"myflow\")\n )\n}\n\nfn project_plaintext_cloud_mirror_required_for_config(cfg: &config::Config) -> bool {\n cfg.host\n .as_ref()\n .map(|host| {\n is_cloud_source(host.env_source.as_deref())\n && host\n .service_token\n .as_deref()\n .map(|value| !value.trim().is_empty())\n .unwrap_or(false)\n })\n .unwrap_or(false)\n}\n\nfn project_plaintext_cloud_mirror_required() -> bool {\n if std::env::var(\"FLOW_ENV_CLOUD_PLAINTEXT_MIRROR\")\n .ok()\n .map(|value| {\n let normalized = value.trim().to_ascii_lowercase();\n normalized == \"1\" || normalized == \"true\" || normalized == \"yes\"\n })\n .unwrap_or(false)\n {\n return true;\n }\n\n let Ok(cwd) = std::env::current_dir() else {\n return false;\n };\n let Some(flow_path) = find_flow_toml(&cwd) else {\n return false;\n };\n let Ok(cfg) = config::load(&flow_path) else {\n return false;\n };\n project_plaintext_cloud_mirror_required_for_config(&cfg)\n}\n\nfn select_requested_env_keys(\n vars: HashMap<String, String>,\n keys: &[String],\n) -> HashMap<String, String> {\n if keys.is_empty() {\n return vars;\n }\n\n let requested: HashSet<_> = keys.iter().cloned().collect();\n vars.into_iter()\n .filter(|(key, _)| requested.contains(key))\n .collect()\n}\n\nfn ensure_cloud_env_sealer_registered(\n api_url: &str,\n token: &str,\n client: &reqwest::blocking::Client,\n) -> Result<EnvSealerIdentity> {\n let identity = load_or_create_env_sealer_identity()?;\n let url = Url::parse(&format!(\"{}/api/env/sealers/self\", api_url))?;\n let mut body = serde_json::json!({\n \"sealerId\": identity.sealer_id,\n });\n if let Some(label) = default_env_sealer_label() {\n body[\"label\"] = serde_json::json!(label);\n }\n\n let resp = client\n .post(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 404 {\n return Ok(identity);\n }\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n Ok(identity)\n}\n\nfn fetch_project_member_sealer_ids(\n project_name: &str,\n self_sealer_id: &str,\n api_url: &str,\n token: &str,\n client: &reqwest::blocking::Client,\n) -> Result<Vec<String>> {\n let url = Url::parse(&format!(\n \"{}/api/env/projects/{}/sealers\",\n api_url, project_name\n ))?;\n let resp = client\n .get(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 404 {\n return Ok(vec![self_sealer_id.to_string()]);\n }\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n let data: ProjectSealersResponse = resp.json().context(\"failed to parse response\")?;\n let mut recipient_ids = Vec::new();\n let mut seen = HashSet::new();\n for member in data.members {\n for sealer in member.sealers {\n if seen.insert(sealer.sealer_id.clone()) {\n recipient_ids.push(sealer.sealer_id);\n }\n }\n }\n if seen.insert(self_sealer_id.to_string()) {\n recipient_ids.push(self_sealer_id.to_string());\n }\n Ok(recipient_ids)\n}\n\nfn fetch_sealed_project_env_payload(\n project_name: &str,\n environment: &str,\n keys: &[String],\n api_url: &str,\n token: &str,\n client: &reqwest::blocking::Client,\n) -> Result<Option<SealedEnvResponse>> {\n let mut url = Url::parse(&format!(\"{}/api/env/sealed/{}\", api_url, project_name))?;\n url.query_pairs_mut()\n .append_pair(\"environment\", environment);\n if !keys.is_empty() {\n url.query_pairs_mut().append_pair(\"keys\", &keys.join(\",\"));\n }\n\n let resp = client\n .get(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 404 {\n return Ok(None);\n }\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n let data: SealedEnvResponse = resp.json().context(\"failed to parse response\")?;\n Ok(Some(data))\n}\n\nfn fetch_legacy_project_cloud_entries(\n project_name: &str,\n environment: &str,\n keys: &[String],\n api_url: &str,\n token: &str,\n client: &reqwest::blocking::Client,\n) -> Result<ProjectCloudEnvEntries> {\n let mut url = Url::parse(&format!(\"{}/api/env/{}\", api_url, project_name))?;\n url.query_pairs_mut()\n .append_pair(\"environment\", environment);\n if !keys.is_empty() {\n url.query_pairs_mut().append_pair(\"keys\", &keys.join(\",\"));\n }\n\n let resp = client\n .get(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 404 {\n return Ok(ProjectCloudEnvEntries::default());\n }\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n let data: EnvResponse = resp.json().context(\"failed to parse response\")?;\n Ok(ProjectCloudEnvEntries {\n vars: data.env,\n descriptions: data.descriptions,\n })\n}\n\nfn write_legacy_project_cloud_entries(\n project_name: &str,\n environment: &str,\n vars: &HashMap<String, String>,\n descriptions: &HashMap<String, String>,\n api_url: &str,\n token: &str,\n client: &reqwest::blocking::Client,\n) -> Result<()> {\n if vars.is_empty() {\n return Ok(());\n }\n\n let url = Url::parse(&format!(\"{}/api/env/{}\", api_url, project_name))?;\n let mut body = serde_json::json!({\n \"vars\": vars,\n \"environment\": environment,\n });\n if !descriptions.is_empty() {\n body[\"descriptions\"] = serde_json::json!(descriptions);\n }\n\n let resp = client\n .post(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n let _: SetEnvResponse = resp.json().context(\"failed to parse response\")?;\n Ok(())\n}\n\nfn delete_legacy_project_cloud_entries(\n project_name: &str,\n environment: &str,\n keys: &[String],\n api_url: &str,\n token: &str,\n client: &reqwest::blocking::Client,\n ignore_missing_project: bool,\n) -> Result<()> {\n if keys.is_empty() {\n return Ok(());\n }\n\n let url = Url::parse(&format!(\"{}/api/env/{}\", api_url, project_name))?;\n let body = serde_json::json!({\n \"keys\": keys,\n \"environment\": environment,\n });\n\n let resp = client\n .delete(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 404 && ignore_missing_project {\n return Ok(());\n }\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n Ok(())\n}\n\nfn fetch_project_cloud_env_entries(\n project_name: &str,\n environment: &str,\n keys: &[String],\n api_url: &str,\n token: &str,\n client: &reqwest::blocking::Client,\n) -> Result<ProjectCloudEnvEntries> {\n let identity = ensure_cloud_env_sealer_registered(api_url, token, client)?;\n let sealed =\n fetch_sealed_project_env_payload(project_name, environment, keys, api_url, token, client)?;\n\n let mut entries = ProjectCloudEnvEntries::default();\n let mut inaccessible_keys = Vec::new();\n\n if let Some(sealed) = sealed {\n for (key, item) in sealed.items {\n if item.content.is_none() {\n continue;\n }\n\n match decrypt_project_env_value(&item, &identity)? {\n Some(value) => {\n entries.vars.insert(key.clone(), value);\n if let Some(description) = item.description {\n entries.descriptions.insert(key, description);\n }\n }\n None => {\n if item.available_recipient_count > 0 || !item.recipients.is_empty() {\n inaccessible_keys.push(key);\n }\n }\n }\n }\n }\n\n let legacy_keys: Vec<String> = if keys.is_empty() {\n Vec::new()\n } else {\n keys.iter()\n .filter(|key| !entries.vars.contains_key(key.as_str()))\n .cloned()\n .collect()\n };\n let legacy = fetch_legacy_project_cloud_entries(\n project_name,\n environment,\n &legacy_keys,\n api_url,\n token,\n client,\n )?;\n for (key, value) in legacy.vars {\n entries.vars.entry(key).or_insert(value);\n }\n for (key, description) in legacy.descriptions {\n entries.descriptions.entry(key).or_insert(description);\n }\n\n inaccessible_keys.retain(|key| !entries.vars.contains_key(key));\n inaccessible_keys.sort();\n inaccessible_keys.dedup();\n if !inaccessible_keys.is_empty() {\n bail!(\n \"Some project env vars exist but are not shared with this device: {}. Re-save them from a device with access, or register this device's sealer and re-share them.\",\n inaccessible_keys.join(\", \")\n );\n }\n\n Ok(entries)\n}\n\nfn write_project_cloud_env_entries(\n project_name: &str,\n environment: &str,\n vars: &HashMap<String, String>,\n descriptions: &HashMap<String, String>,\n api_url: &str,\n token: &str,\n client: &reqwest::blocking::Client,\n) -> Result<bool> {\n if vars.is_empty() {\n return Ok(false);\n }\n\n let identity = ensure_cloud_env_sealer_registered(api_url, token, client)?;\n let recipient_ids =\n fetch_project_member_sealer_ids(project_name, &identity.sealer_id, api_url, token, client)?;\n\n let mut items = HashMap::new();\n for (key, value) in vars {\n let mut item = seal_project_env_value(value, &identity, &recipient_ids)?;\n item.description = descriptions.get(key).cloned();\n items.insert(key.clone(), item);\n }\n\n let url = Url::parse(&format!(\"{}/api/env/sealed/{}\", api_url, project_name))?;\n let body = SealedEnvWriteRequest {\n environment: environment.to_string(),\n items,\n };\n let resp = client\n .post(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 404 {\n bail!(\n \"The cloud env server does not support sealed project env storage yet. Deploy the updated MyFlow env API before writing project envs.\"\n );\n }\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n let mirror_plaintext = project_plaintext_cloud_mirror_required();\n if mirror_plaintext {\n write_legacy_project_cloud_entries(\n project_name,\n environment,\n vars,\n descriptions,\n api_url,\n token,\n client,\n )\n .context(\"sealed write succeeded, but writing the required plaintext host mirror failed\")?;\n } else {\n let keys: Vec<String> = vars.keys().cloned().collect();\n delete_legacy_project_cloud_entries(\n project_name,\n environment,\n &keys,\n api_url,\n token,\n client,\n true,\n )\n .context(\"sealed write succeeded, but removing the legacy plaintext mirror failed\")?;\n }\n\n Ok(mirror_plaintext)\n}\n\nfn delete_project_cloud_env_entries(\n project_name: &str,\n environment: &str,\n keys: &[String],\n api_url: &str,\n token: &str,\n client: &reqwest::blocking::Client,\n) -> Result<()> {\n if keys.is_empty() {\n return Ok(());\n }\n\n let url = Url::parse(&format!(\"{}/api/env/sealed/{}\", api_url, project_name))?;\n let body = serde_json::json!({\n \"keys\": keys,\n \"environment\": environment,\n });\n let resp = client\n .delete(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n match resp.status() {\n status if status == 404 => {}\n status if status == 401 => bail!(\"Unauthorized. Check your token with `f env login`.\"),\n status if !status.is_success() => {\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n _ => {}\n }\n\n delete_legacy_project_cloud_entries(\n project_name,\n environment,\n keys,\n api_url,\n token,\n client,\n true,\n )\n}\n\nfn format_default_hint(value: &str) -> String {\n value.to_string()\n}\n\npub fn get_personal_env_var(key: &str) -> Result<Option<String>> {\n if local_env_enabled() {\n let vars = fetch_local_personal_env_vars(&[key.to_string()])?;\n return Ok(vars.get(key).cloned());\n }\n\n let auth = load_auth_config()?;\n let token = match auth.token.as_ref() {\n Some(t) => t,\n None => return Ok(None),\n };\n require_env_read_unlock()?;\n\n let api_url = get_api_url(&auth);\n let target = resolve_personal_target()?;\n let mut url = Url::parse(&format!(\"{}/api/env/personal\", api_url))?;\n url.query_pairs_mut().append_pair(\"keys\", key);\n if let EnvTarget::Personal { ref space } = target {\n if let Some(space) = space.as_ref() {\n url.query_pairs_mut().append_pair(\"space\", &space);\n }\n }\n\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(15))?;\n\n let resp = client\n .get(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 401 {\n return Ok(None);\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n let data: PersonalEnvResponse = resp.json().context(\"failed to parse response\")?;\n Ok(data.env.get(key).cloned())\n}\n\n/// Fuzzy search personal env vars and copy selected value to clipboard.\nfn fuzzy_select_env() -> Result<()> {\n require_env_read_unlock()?;\n\n // Fetch all personal env vars\n let target = resolve_personal_target()?;\n let vars = fetch_env_vars(&target, \"production\", &[], false)?;\n if vars.is_empty() {\n println!(\"No personal env vars found.\");\n println!(\"Set one with: f env set KEY=VALUE\");\n return Ok(());\n }\n\n // Format for fzf: KEY=VALUE (showing first 40 chars of value)\n let mut lines: Vec<String> = vars\n .iter()\n .map(|(k, v)| {\n let preview = if v.len() > 40 {\n format!(\"{}...\", &v[..40])\n } else {\n v.clone()\n };\n format!(\"{}\\t{}\", k, preview)\n })\n .collect();\n lines.sort();\n\n let input = lines.join(\"\\n\");\n\n // Run fzf\n let mut child = Command::new(\"fzf\")\n .args([\n \"--height=40%\",\n \"--reverse\",\n \"--delimiter=\\t\",\n \"--with-nth=1\",\n ])\n .stdin(std::process::Stdio::piped())\n .stdout(std::process::Stdio::piped())\n .spawn()\n .context(\"Failed to run fzf. Is it installed?\")?;\n\n if let Some(stdin) = child.stdin.as_mut() {\n use std::io::Write;\n stdin.write_all(input.as_bytes())?;\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n // User cancelled\n return Ok(());\n }\n\n let selected = String::from_utf8_lossy(&output.stdout);\n let selected = selected.trim();\n if selected.is_empty() {\n return Ok(());\n }\n\n // Extract key from selection\n let key = selected.split('\\t').next().unwrap_or(selected);\n\n // Get the full value\n if let Some(value) = vars.get(key) {\n if std::env::var(\"FLOW_NO_CLIPBOARD\").is_ok() || !std::io::stdin().is_terminal() {\n println!(\"Clipboard disabled; skipping copy.\");\n } else {\n // Copy to clipboard\n let mut pbcopy = Command::new(\"pbcopy\")\n .stdin(std::process::Stdio::piped())\n .spawn()\n .context(\"Failed to run pbcopy\")?;\n\n if let Some(stdin) = pbcopy.stdin.as_mut() {\n use std::io::Write;\n stdin.write_all(value.as_bytes())?;\n }\n pbcopy.wait()?;\n\n println!(\"Copied {} to clipboard\", key);\n }\n }\n\n Ok(())\n}\n\n/// Run the env subcommand.\npub fn run(action: Option<EnvAction>) -> Result<()> {\n // No action = fuzzy search personal envs and copy value\n let Some(action) = action else {\n let auth = load_auth_config()?;\n if auth.token.is_some() {\n return fuzzy_select_env();\n }\n return status();\n };\n\n match action {\n EnvAction::Sync => agent_setup::run()?,\n EnvAction::Unlock => unlock_env_read()?,\n EnvAction::Login => login()?,\n EnvAction::New => new_env_template()?,\n EnvAction::Pull { environment } => pull(&environment)?,\n EnvAction::Push { environment } => push(&environment)?,\n EnvAction::Guide { environment } => guide(&environment)?,\n EnvAction::Apply => {\n let cwd = std::env::current_dir()?;\n let flow_path = find_flow_toml(&cwd)\n .ok_or_else(|| anyhow::anyhow!(\"flow.toml not found. Run `f init` first.\"))?;\n let project_root = flow_path.parent().map(|p| p.to_path_buf()).unwrap_or(cwd);\n let flow_config = config::load(&flow_path)?;\n deploy::apply_cloudflare_env(&project_root, Some(&flow_config))?;\n }\n EnvAction::Bootstrap => {\n let cwd = std::env::current_dir()?;\n let flow_path = find_flow_toml(&cwd)\n .ok_or_else(|| anyhow::anyhow!(\"flow.toml not found. Run `f init` first.\"))?;\n let project_root = flow_path.parent().map(|p| p.to_path_buf()).unwrap_or(cwd);\n let flow_config = config::load(&flow_path)?;\n bootstrap_cloudflare_secrets(&project_root, &flow_config)?;\n }\n EnvAction::Keys => {\n show_keys()?;\n }\n EnvAction::Setup {\n env_file,\n environment,\n } => setup(env_file, environment)?,\n EnvAction::List { environment } => list(&environment)?,\n EnvAction::Set { pair, personal } => {\n let _ = personal;\n set_personal_env_var_from_pair(&pair)?;\n }\n EnvAction::Delete { keys } => delete_personal_env_vars(&keys)?,\n EnvAction::Project { action } => run_project_env_action(action)?,\n EnvAction::Status => status()?,\n EnvAction::Get {\n keys,\n personal,\n environment,\n format,\n } => get_vars(&keys, personal, &environment, &format)?,\n EnvAction::Run {\n personal,\n environment,\n keys,\n command,\n } => run_with_env(personal, &environment, &keys, &command)?,\n EnvAction::Token { action } => run_token_action(action)?,\n }\n\n Ok(())\n}\n\nfn run_token_action(action: TokenAction) -> Result<()> {\n match action {\n TokenAction::Create { name, permissions } => token_create(name.as_deref(), &permissions)?,\n TokenAction::List => token_list()?,\n TokenAction::Revoke { name } => token_revoke(&name)?,\n }\n Ok(())\n}\n\n#[derive(Clone, Copy)]\nstruct EnvTemplate {\n id: &'static str,\n title: &'static str,\n key: &'static str,\n description: &'static str,\n instructions: &'static [&'static str],\n}\n\nfn env_templates() -> Vec<EnvTemplate> {\n vec![EnvTemplate {\n id: \"cloudflare\",\n title: \"Cloudflare API token\",\n key: \"CLOUDFLARE_API_TOKEN\",\n description: \"Token used by wrangler to deploy Workers/Pages.\",\n instructions: &[\n \"Open https://dash.cloudflare.com/profile/api-tokens\",\n \"Create a token (Template: Edit Cloudflare Workers or Custom)\",\n \"Permissions: Workers Scripts:Edit, Workers Routes:Edit, Pages:Edit\",\n \"Add Zone:Read + DNS:Edit for your domain\",\n \"Copy the token value\",\n ],\n }]\n}\n\nfn new_env_template() -> Result<()> {\n ensure_env_login()?;\n\n let templates = env_templates();\n if templates.is_empty() {\n println!(\"No env templates available.\");\n return Ok(());\n }\n let Some(template) = select_env_template(&templates)? else {\n println!(\"No template selected.\");\n return Ok(());\n };\n\n println!(\"Template: {}\", template.title);\n println!(\"Key: {}\", template.key);\n println!(\"{}\", template.description);\n println!();\n println!(\"How to get it:\");\n for step in template.instructions {\n println!(\" - {}\", step);\n }\n println!();\n\n let label = format!(\"Enter {} token (input hidden): \", template.id);\n let value = prompt_secret(&label)?;\n let Some(value) = value else {\n println!(\"No token entered; nothing saved.\");\n return Ok(());\n };\n\n set_personal_env_var(template.key, &value)?;\n\n println!();\n println!(\"Saved {} to personal envs.\", template.key);\n Ok(())\n}\n\nfn select_env_template(templates: &[EnvTemplate]) -> Result<Option<EnvTemplate>> {\n if templates.is_empty() {\n return Ok(None);\n }\n\n let use_fzf = std::io::stdin().is_terminal() && which(\"fzf\").is_ok();\n if use_fzf {\n let mut lines = Vec::new();\n for template in templates {\n lines.push(format!(\"{}\\t{}\", template.id, template.title));\n }\n let input = lines.join(\"\\n\");\n\n let mut child = Command::new(\"fzf\")\n .args([\n \"--height=40%\",\n \"--reverse\",\n \"--delimiter=\\t\",\n \"--with-nth=1,2\",\n ])\n .stdin(std::process::Stdio::piped())\n .stdout(std::process::Stdio::piped())\n .spawn()\n .context(\"Failed to run fzf. Is it installed?\")?;\n\n if let Some(stdin) = child.stdin.as_mut() {\n use std::io::Write;\n stdin.write_all(input.as_bytes())?;\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n\n let selected = String::from_utf8_lossy(&output.stdout);\n let selected = selected.trim();\n if selected.is_empty() {\n return Ok(None);\n }\n let id = selected.split('\\t').next().unwrap_or(selected);\n return Ok(templates.iter().copied().find(|t| t.id == id));\n }\n\n println!(\"Available templates:\");\n for (idx, template) in templates.iter().enumerate() {\n println!(\" {}. {} ({})\", idx + 1, template.title, template.key);\n }\n println!();\n let selection = prompt_line(\"Select a template number (blank to cancel): \")?;\n let Some(selection) = selection else {\n return Ok(None);\n };\n let idx: usize = selection.trim().parse().context(\"Invalid selection\")?;\n if idx == 0 || idx > templates.len() {\n bail!(\"Selection out of range\");\n }\n Ok(Some(templates[idx - 1]))\n}\n\nfn ensure_env_login() -> Result<()> {\n let auth = load_auth_config()?;\n if auth.token.is_some() {\n return Ok(());\n }\n\n if !std::io::stdin().is_terminal() {\n bail!(\"Not logged in. Run `f env login` first.\");\n }\n\n if prompt_confirm(\"Not logged in. Run `f env login` now? (y/N): \")? {\n login()?;\n return Ok(());\n }\n\n bail!(\"Not logged in. Run `f env login` first.\");\n}\n\nfn run_project_env_action(action: ProjectEnvAction) -> Result<()> {\n match action {\n ProjectEnvAction::Set { pair, environment } => {\n set_project_env_var_from_pair(&pair, &environment)?\n }\n ProjectEnvAction::Delete { keys, environment } => {\n delete_project_env_vars(&keys, &environment)?\n }\n ProjectEnvAction::List { environment } => list(&environment)?,\n }\n Ok(())\n}\n\nfn set_personal_env_var_from_pair(pair: &str) -> Result<()> {\n let (key, value) = pair\n .split_once('=')\n .ok_or_else(|| anyhow::anyhow!(\"Invalid format. Use KEY=VALUE\"))?;\n set_personal_env_var(key.trim(), value.trim())\n}\n\nfn set_project_env_var_from_pair(pair: &str, environment: &str) -> Result<()> {\n let (key, value) = pair\n .split_once('=')\n .ok_or_else(|| anyhow::anyhow!(\"Invalid format. Use KEY=VALUE\"))?;\n set_project_env_var_internal(key.trim(), value.trim(), environment, None)\n}\n\npub(crate) fn delete_personal_env_vars(keys: &[String]) -> Result<()> {\n if local_env_enabled() {\n let target = resolve_personal_target()?;\n let path = delete_local_env_vars(&target, \"production\", keys)?;\n println!(\n \"✓ Deleted {} key(s) from personal envs (stored at {})\",\n keys.len(),\n path.display()\n );\n return Ok(());\n }\n\n let auth = load_auth_config()?;\n if keys.is_empty() {\n bail!(\"No keys specified\");\n }\n\n let target = resolve_personal_target()?;\n let token = match auth.token.as_ref() {\n Some(token) => token,\n None => {\n let path = delete_local_env_vars(&target, \"production\", keys)?;\n println!(\n \"✓ Deleted {} key(s) from personal envs (stored at {})\",\n keys.len(),\n path.display()\n );\n return Ok(());\n }\n };\n\n let api_url = get_api_url(&auth);\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(30))?;\n let mut url = Url::parse(&format!(\"{}/api/env/personal\", api_url))?;\n if let EnvTarget::Personal { ref space } = target {\n if let Some(space) = space.as_ref() {\n url.query_pairs_mut().append_pair(\"space\", space);\n }\n }\n let body = serde_json::json!({ \"keys\": keys });\n\n let resp = client\n .delete(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n println!(\"✓ Deleted {} key(s)\", keys.len());\n Ok(())\n}\n\nfn delete_project_env_vars(keys: &[String], environment: &str) -> Result<()> {\n if local_env_enabled() {\n let target = resolve_env_target()?;\n let target_label = env_target_label(&target);\n let path = delete_local_env_vars(&target, environment, keys)?;\n println!(\n \"✓ Deleted {} key(s) from {} ({}) locally at {}\",\n keys.len(),\n target_label,\n environment,\n path.display()\n );\n return Ok(());\n }\n\n let auth = load_auth_config()?;\n let token = auth\n .token\n .as_ref()\n .ok_or_else(|| anyhow::anyhow!(\"Not logged in. Run `f env login` first.\"))?;\n\n if keys.is_empty() {\n bail!(\"No keys specified\");\n }\n\n let api_url = get_api_url(&auth);\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(30))?;\n let target = resolve_env_target()?;\n match &target {\n EnvTarget::Personal { space } => {\n let mut url = Url::parse(&format!(\"{}/api/env/personal\", api_url))?;\n if let Some(space) = space {\n url.query_pairs_mut().append_pair(\"space\", space);\n }\n let body = serde_json::json!({\n \"keys\": keys,\n \"environment\": environment,\n });\n\n let resp = client\n .delete(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n }\n EnvTarget::Project { name } => {\n delete_project_cloud_env_entries(name, environment, keys, &api_url, token, &client)?;\n }\n }\n\n let target_label = match target {\n EnvTarget::Personal { space } => {\n format!(\n \"personal{}\",\n space.map(|s| format!(\":{}\", s)).unwrap_or_default()\n )\n }\n EnvTarget::Project { name } => name,\n };\n println!(\n \"✓ Deleted {} key(s) from {} ({})\",\n keys.len(),\n target_label,\n environment\n );\n Ok(())\n}\n\n/// Login / set token.\nfn login() -> Result<()> {\n let mut auth = load_auth_config_raw()?;\n\n println!(\"Cloud Environment Manager\");\n println!(\"─────────────────────────────\");\n println!();\n println!(\"To get a token:\");\n println!(\" 1. Go to {} and sign in\", DEFAULT_API_URL);\n println!(\" 2. Go to Settings → API Tokens\");\n println!(\" 3. Create a new token\");\n println!();\n\n let api_url = prompt_line_default(\"API base URL\", Some(DEFAULT_API_URL))?;\n if let Some(api_url) = api_url {\n auth.api_url = Some(api_url);\n }\n\n print!(\"Enter your API token: \");\n io::stdout().flush()?;\n\n let mut token = String::new();\n io::stdin().read_line(&mut token)?;\n let token = token.trim().to_string();\n\n if token.is_empty() {\n bail!(\"Token cannot be empty\");\n }\n\n if !token.starts_with(\"cloud_\") && !token.starts_with(\"flow_\") {\n println!(\n \"Warning: Token doesn't start with 'cloud_' or 'flow_' - are you sure this is correct?\"\n );\n }\n\n store_auth_token(&mut auth, token)?;\n save_auth_config(&auth)?;\n\n println!();\n if auth.token_source.as_deref() == Some(\"keychain\") {\n println!(\"✓ Token saved to Keychain\");\n } else {\n println!(\"✓ Token saved to {}\", get_auth_config_path().display());\n }\n println!();\n println!(\"You can now use:\");\n println!(\" f env pull - Fetch env vars for this project\");\n println!(\" f env push - Push local .env to cloud\");\n println!(\" f env list - List env vars\");\n\n Ok(())\n}\n\n/// Pull env vars from cloud and write to .env.\nfn pull(environment: &str) -> Result<()> {\n let target = resolve_env_target()?;\n let label = env_target_label(&target);\n println!(\"Fetching envs for '{}' ({})...\", label, environment);\n\n let vars = fetch_env_vars(&target, environment, &[], true)?;\n\n if vars.is_empty() {\n println!(\"No env vars found for '{}' ({})\", label, environment);\n return Ok(());\n }\n\n // Write to .env\n let mut content = String::new();\n content.push_str(&format!(\n \"# Environment: {} (pulled from cloud)\\n\",\n environment\n ));\n content.push_str(&format!(\"# Space: {}\\n\", label));\n content.push_str(\"#\\n\");\n\n let mut keys: Vec<_> = vars.keys().collect();\n keys.sort();\n\n for key in keys {\n let value = &vars[key];\n // Escape quotes in value\n let escaped = value.replace('\\\"', \"\\\\\\\"\");\n content.push_str(&format!(\"{}=\\\"{}\\\"\\n\", key, escaped));\n }\n\n let env_path = resolve_env_file_path()?;\n if let Some(parent) = env_path.parent() {\n fs::create_dir_all(parent)?;\n }\n fs::write(&env_path, &content)?;\n\n println!(\"✓ Wrote {} env vars to {}\", vars.len(), env_path.display());\n\n Ok(())\n}\n\n/// Push local .env to cloud.\nfn push(environment: &str) -> Result<()> {\n let env_path = resolve_env_file_path()?;\n if !env_path.exists() {\n bail!(\"env file not found: {}\", env_path.display());\n }\n\n let content = fs::read_to_string(&env_path)?;\n let vars = parse_env_file(&content);\n\n if vars.is_empty() {\n println!(\"No env vars found in .env\");\n return Ok(());\n }\n\n push_vars(environment, vars)\n}\n\nfn push_vars(environment: &str, vars: HashMap<String, String>) -> Result<()> {\n if vars.is_empty() {\n println!(\"No env vars selected.\");\n return Ok(());\n }\n\n let auth = load_auth_config()?;\n let token = auth\n .token\n .as_ref()\n .ok_or_else(|| anyhow::anyhow!(\"Not logged in. Run `f env login` first.\"))?;\n let api_url = get_api_url(&auth);\n let target = resolve_env_target()?;\n let label = env_target_label(&target);\n\n println!(\n \"Pushing {} env vars to '{}' ({})...\",\n vars.len(),\n label,\n environment\n );\n\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(30))?;\n let mirrored_plaintext = match &target {\n EnvTarget::Personal { space } => {\n let mut url = Url::parse(&format!(\"{}/api/env/personal\", api_url))?;\n if let Some(space) = space {\n url.query_pairs_mut().append_pair(\"space\", space);\n }\n let body = serde_json::json!({\n \"vars\": &vars,\n \"environment\": environment,\n });\n\n let resp = client\n .post(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n false\n }\n EnvTarget::Project { name } => write_project_cloud_env_entries(\n name,\n environment,\n &vars,\n &HashMap::new(),\n &api_url,\n token,\n &client,\n )?,\n };\n\n if mirrored_plaintext {\n println!(\n \"✓ Pushed {} env vars to cloud (sealed, plus required plaintext host mirror)\",\n vars.len()\n );\n } else if matches!(target, EnvTarget::Project { .. }) {\n println!(\"✓ Pushed {} env vars to cloud (sealed)\", vars.len());\n } else {\n println!(\"✓ Pushed {} env vars to cloud\", vars.len());\n }\n\n Ok(())\n}\n\nfn guide(environment: &str) -> Result<()> {\n let cwd = std::env::current_dir()?;\n let flow_path = find_flow_toml(&cwd)\n .ok_or_else(|| anyhow::anyhow!(\"flow.toml not found. Run `f init` first.\"))?;\n let cfg = config::load(&flow_path)?;\n\n let cf_cfg = cfg\n .cloudflare\n .as_ref()\n .context(\"No [cloudflare] section in flow.toml\")?;\n\n let mut required = Vec::new();\n let mut seen = HashSet::new();\n for key in cf_cfg.env_keys.iter().chain(cf_cfg.env_vars.iter()) {\n if seen.insert(key.clone()) {\n required.push(key.clone());\n }\n }\n\n if required.is_empty() {\n bail!(\n \"No env keys configured. Add cloudflare.env_keys or cloudflare.env_vars to flow.toml.\"\n );\n }\n\n println!(\"Checking required env vars for '{}'...\", environment);\n let existing = match fetch_project_env_vars(environment, &required) {\n Ok(vars) => vars,\n Err(err) => {\n let msg = format!(\"{err:#}\");\n if msg.contains(\"Project not found.\") {\n println!(\" (project not found yet; will create on first set)\");\n HashMap::new()\n } else {\n return Err(err);\n }\n }\n };\n let var_keys: HashSet<String> = cf_cfg.env_vars.iter().cloned().collect();\n\n let mut missing = Vec::new();\n for key in &required {\n if existing\n .get(key)\n .map(|v| !v.trim().is_empty())\n .unwrap_or(false)\n {\n println!(\" ✓ {}\", key);\n } else {\n println!(\" ✗ {} (missing)\", key);\n missing.push(key.clone());\n }\n }\n\n if missing.is_empty() {\n println!(\"✓ All required env vars are set.\");\n return Ok(());\n }\n\n println!();\n println!(\"Enter missing values (leave empty to skip).\");\n for key in missing {\n let default_value = cf_cfg.env_defaults.get(&key).map(|value| value.as_str());\n let is_secret = !var_keys.contains(&key);\n let value = prompt_value(&key, default_value, is_secret)?;\n\n if let Some(value) = value {\n set_project_env_var(&key, &value, environment, None)?;\n }\n }\n\n Ok(())\n}\n\nfn bootstrap_cloudflare_secrets(project_root: &Path, cfg: &config::Config) -> Result<()> {\n let cf_cfg = cfg\n .cloudflare\n .as_ref()\n .context(\"No [cloudflare] section in flow.toml\")?;\n\n if cf_cfg.bootstrap_secrets.is_empty() {\n bail!(\"No bootstrap secrets configured. Add cloudflare.bootstrap_secrets to flow.toml.\");\n }\n\n println!(\"Bootstrap Cloudflare secrets\");\n println!(\"─────────────────────────────\");\n println!(\"Enter values (leave empty to skip).\");\n\n let mut values = HashMap::new();\n let mut generated_env_token: Option<String> = None;\n let needs_env_account = cf_cfg.bootstrap_secrets.iter().any(|key| {\n key == \"JAZZ_APP_ID\"\n || key == \"JAZZ_BACKEND_SECRET\"\n || key == \"JAZZ_ADMIN_SECRET\"\n || key == \"JAZZ_WORKER_ACCOUNT\"\n || key == \"JAZZ_WORKER_SECRET\"\n });\n let needs_auth_account = cf_cfg.bootstrap_secrets.iter().any(|key| {\n key == \"JAZZ_AUTH_APP_ID\"\n || key == \"JAZZ_AUTH_BACKEND_SECRET\"\n || key == \"JAZZ_AUTH_ADMIN_SECRET\"\n || key == \"JAZZ_AUTH_WORKER_ACCOUNT_ID\"\n || key == \"JAZZ_AUTH_WORKER_ACCOUNT_SECRET\"\n });\n\n if needs_env_account || needs_auth_account {\n let project = storage_project_name()?;\n let default_env_name = format!(\"{}-jazz2-env\", sanitize_name(&project));\n let default_auth_name = format!(\"{}-jazz2-auth\", sanitize_name(&project));\n let default_server = \"https://cloud.jazz.tools\";\n\n if needs_env_account {\n if prompt_confirm(\"Generate new Jazz2 env-store app credentials now? (y/N): \")? {\n println!(\"Creating Jazz2 env-store app credentials...\");\n let name = cf_cfg\n .bootstrap_jazz_name\n .as_deref()\n .unwrap_or(&default_env_name);\n let server = cf_cfg\n .bootstrap_jazz_peer\n .as_deref()\n .unwrap_or(default_server);\n let creds = create_jazz_app_credentials(name)?;\n if cf_cfg.bootstrap_secrets.iter().any(|k| k == \"JAZZ_APP_ID\") {\n values.insert(\"JAZZ_APP_ID\".to_string(), creds.app_id.clone());\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_BACKEND_SECRET\")\n {\n values.insert(\n \"JAZZ_BACKEND_SECRET\".to_string(),\n creds.backend_secret.clone(),\n );\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_ADMIN_SECRET\")\n {\n values.insert(\"JAZZ_ADMIN_SECRET\".to_string(), creds.admin_secret.clone());\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_WORKER_ACCOUNT\")\n {\n values.insert(\"JAZZ_WORKER_ACCOUNT\".to_string(), creds.app_id);\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_WORKER_SECRET\")\n {\n values.insert(\"JAZZ_WORKER_SECRET\".to_string(), creds.backend_secret);\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_SERVER_URL\")\n {\n values.insert(\"JAZZ_SERVER_URL\".to_string(), server.to_string());\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_SYNC_SERVER\")\n {\n values.insert(\"JAZZ_SYNC_SERVER\".to_string(), server.to_string());\n }\n println!(\"✓ Jazz2 env-store credentials created\");\n }\n }\n\n if needs_auth_account {\n if prompt_confirm(\"Generate new Jazz2 auth app credentials now? (y/N): \")? {\n println!(\"Creating Jazz2 auth app credentials...\");\n let name = cf_cfg\n .bootstrap_jazz_auth_name\n .as_deref()\n .unwrap_or(&default_auth_name);\n let server = cf_cfg\n .bootstrap_jazz_auth_peer\n .as_deref()\n .unwrap_or(default_server);\n let creds = create_jazz_app_credentials(name)?;\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_AUTH_APP_ID\")\n {\n values.insert(\"JAZZ_AUTH_APP_ID\".to_string(), creds.app_id.clone());\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_AUTH_BACKEND_SECRET\")\n {\n values.insert(\n \"JAZZ_AUTH_BACKEND_SECRET\".to_string(),\n creds.backend_secret.clone(),\n );\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_AUTH_ADMIN_SECRET\")\n {\n values.insert(\n \"JAZZ_AUTH_ADMIN_SECRET\".to_string(),\n creds.admin_secret.clone(),\n );\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_AUTH_WORKER_ACCOUNT_ID\")\n {\n values.insert(\"JAZZ_AUTH_WORKER_ACCOUNT_ID\".to_string(), creds.app_id);\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_AUTH_WORKER_ACCOUNT_SECRET\")\n {\n values.insert(\n \"JAZZ_AUTH_WORKER_ACCOUNT_SECRET\".to_string(),\n creds.backend_secret,\n );\n }\n if cf_cfg\n .bootstrap_secrets\n .iter()\n .any(|k| k == \"JAZZ_AUTH_SERVER_URL\")\n {\n values.insert(\"JAZZ_AUTH_SERVER_URL\".to_string(), server.to_string());\n }\n println!(\"✓ Jazz2 auth credentials created\");\n }\n }\n }\n\n for key in &cf_cfg.bootstrap_secrets {\n if values.contains_key(key) {\n continue;\n }\n if key == \"ENV_API_TOKEN\" || key == \"FLOW_ENV_TOKEN\" {\n let value = prompt_secret(&format!(\"{} (leave empty to auto-generate): \", key))?;\n let value = match value {\n Some(value) => value,\n None => {\n if let Some(existing) = generated_env_token.clone() {\n existing\n } else {\n let token = generate_env_api_token();\n generated_env_token = Some(token.clone());\n token\n }\n }\n };\n values.insert(key.clone(), value);\n continue;\n }\n\n let value = prompt_secret(&format!(\"{}: \", key))?;\n if let Some(value) = value {\n values.insert(key.clone(), value);\n }\n }\n\n values.retain(|_, value| !value.trim().is_empty());\n\n if values.is_empty() {\n println!(\"No secrets provided; nothing to set.\");\n return Ok(());\n }\n\n println!(\"Setting Cloudflare secrets...\");\n deploy::set_cloudflare_secrets(project_root, Some(cfg), &values)?;\n println!(\"✓ Cloudflare secrets updated\");\n\n let mut auth = load_auth_config_raw()?;\n let bootstrap_token = values\n .get(\"ENV_API_TOKEN\")\n .or_else(|| values.get(\"FLOW_ENV_TOKEN\"))\n .cloned();\n if let Some(token) = bootstrap_token {\n store_auth_token(&mut auth, token)?;\n let needs_default_api = auth\n .api_url\n .as_deref()\n .map(|url| url.contains(\"workers.dev\"))\n .unwrap_or(true);\n if needs_default_api {\n auth.api_url = Some(DEFAULT_API_URL.to_string());\n }\n save_auth_config(&auth)?;\n }\n\n let env_name = cf_cfg\n .environment\n .clone()\n .unwrap_or_else(|| \"production\".to_string());\n let mut env_key_set: HashSet<String> = HashSet::new();\n for key in cf_cfg.env_keys.iter().chain(cf_cfg.env_vars.iter()) {\n env_key_set.insert(key.clone());\n }\n for (key, value) in &values {\n if env_key_set.contains(key) {\n if let Err(err) = set_project_env_var(key, value, &env_name, None) {\n eprintln!(\"⚠ Failed to store {} in env store: {}\", key, err);\n }\n }\n }\n\n if generated_env_token.is_some() {\n if auth.token_source.as_deref() == Some(\"keychain\") {\n println!(\"✓ Saved ENV_API_TOKEN to Keychain\");\n } else {\n println!(\n \"✓ Saved ENV_API_TOKEN to {}\",\n get_auth_config_path().display()\n );\n }\n }\n\n Ok(())\n}\n\nfn prompt_line(label: &str) -> Result<Option<String>> {\n print!(\"{}\", label);\n io::stdout().flush()?;\n\n let mut value = String::new();\n io::stdin().read_line(&mut value)?;\n let value = value.trim().to_string();\n if value.is_empty() {\n Ok(None)\n } else {\n Ok(Some(value))\n }\n}\n\nfn prompt_line_default(key: &str, default_value: Option<&str>) -> Result<Option<String>> {\n let label = if let Some(default_value) = default_value {\n format!(\"{} [{}]: \", key, default_value)\n } else {\n format!(\"{}: \", key)\n };\n let value = prompt_line(&label)?;\n if value.is_none() {\n Ok(default_value.map(|value| value.to_string()))\n } else {\n Ok(value)\n }\n}\n\nfn prompt_value(key: &str, default_value: Option<&str>, secret: bool) -> Result<Option<String>> {\n if secret {\n return prompt_secret(&format!(\"{}: \", key));\n }\n\n let default_value = default_value.and_then(|value| {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed)\n }\n });\n\n let label = if let Some(default_value) = default_value {\n format!(\"{} [{}]: \", key, default_value)\n } else {\n format!(\"{}: \", key)\n };\n\n let value = prompt_line(&label)?;\n if value.is_none() {\n Ok(default_value.map(|value| value.to_string()))\n } else {\n Ok(value)\n }\n}\n\nfn prompt_confirm(label: &str) -> Result<bool> {\n print!(\"{}\", label);\n io::stdout().flush()?;\n\n if std::io::stdin().is_terminal() {\n if let Ok(()) = crossterm::terminal::enable_raw_mode() {\n let read = crossterm::event::read();\n let _ = crossterm::terminal::disable_raw_mode();\n if let Ok(crossterm::event::Event::Key(key)) = read {\n println!();\n return Ok(matches!(\n key.code,\n crossterm::event::KeyCode::Char('y' | 'Y')\n ));\n }\n }\n }\n\n let value = prompt_line(\"\")?;\n Ok(matches!(\n value\n .unwrap_or_default()\n .trim()\n .to_ascii_lowercase()\n .as_str(),\n \"y\" | \"yes\"\n ))\n}\n\nfn generate_env_api_token() -> String {\n format!(\"cloud_{}\", Uuid::new_v4().simple())\n}\n\nfn prompt_secret(label: &str) -> Result<Option<String>> {\n let value = rpassword::prompt_password(label)?;\n let value = value.trim().to_string();\n if value.is_empty() {\n Ok(None)\n } else {\n Ok(Some(value))\n }\n}\n\nfn setup(env_file: Option<PathBuf>, environment: Option<String>) -> Result<()> {\n let cwd = std::env::current_dir()?;\n let flow_path = find_flow_toml(&cwd);\n let (project_root, flow_cfg) = if let Some(path) = flow_path {\n let cfg = config::load(&path)?;\n let root = path.parent().unwrap_or(&cwd).to_path_buf();\n (root, Some(cfg))\n } else {\n (cwd, None)\n };\n\n let cf_cfg = flow_cfg.as_ref().and_then(|cfg| cfg.cloudflare.as_ref());\n let default_env = environment\n .clone()\n .or_else(|| cf_cfg.and_then(|cfg| cfg.environment.clone()));\n\n if env_file.is_none() {\n if let Some(cfg) = cf_cfg {\n if is_cloud_source(cfg.env_source.as_deref()) {\n let env = default_env.unwrap_or_else(|| \"production\".to_string());\n return guide(&env);\n }\n }\n }\n\n let defaults = EnvSetupDefaults {\n env_file,\n environment: default_env,\n };\n\n let Some(result) = run_env_setup(&project_root, defaults)? else {\n return Ok(());\n };\n\n if !result.apply {\n println!(\"Env setup canceled.\");\n return Ok(());\n }\n\n let Some(env_file) = result.env_file else {\n println!(\"No env file selected; nothing to push.\");\n return Ok(());\n };\n\n let content = fs::read_to_string(&env_file)\n .with_context(|| format!(\"failed to read {}\", env_file.display()))?;\n let vars = parse_env_file(&content);\n\n if vars.is_empty() {\n println!(\"No env vars found in {}\", env_file.display());\n return Ok(());\n }\n\n if result.selected_keys.is_empty() {\n println!(\"No keys selected; nothing to push.\");\n return Ok(());\n }\n\n let mut selected = HashMap::new();\n for key in result.selected_keys {\n if let Some(value) = vars.get(&key) {\n selected.insert(key, value.clone());\n }\n }\n\n if selected.is_empty() {\n println!(\"No matching keys found in {}\", env_file.display());\n return Ok(());\n }\n\n push_vars(&result.environment, selected)\n}\n\nfn show_keys() -> Result<()> {\n let cwd = std::env::current_dir()?;\n let flow_path = find_flow_toml(&cwd)\n .ok_or_else(|| anyhow::anyhow!(\"flow.toml not found. Run `f init` first.\"))?;\n let cfg = config::load(&flow_path)?;\n\n let label = resolve_env_target()\n .map(|target| env_target_label(&target))\n .unwrap_or_else(|_| {\n cfg.project_name\n .clone()\n .unwrap_or_else(|| \"unknown\".to_string())\n });\n\n if let Some(cf_cfg) = cfg.cloudflare.as_ref() {\n println!(\"Env keys for {}\", label);\n println!(\"─────────────────────────────\");\n if let Some(source) = cf_cfg.env_source.as_deref() {\n println!(\"Source: {}\", source);\n }\n if let Some(environment) = cf_cfg.environment.as_deref() {\n println!(\"Environment: {}\", environment);\n }\n if let Some(apply) = cf_cfg.env_apply.as_deref() {\n println!(\"Apply: {}\", apply);\n }\n println!();\n\n let mut secrets = cf_cfg.env_keys.clone();\n secrets.sort();\n let mut vars = cf_cfg.env_vars.clone();\n vars.sort();\n\n if secrets.is_empty() && vars.is_empty() {\n println!(\"No env keys configured.\");\n return Ok(());\n }\n\n if !secrets.is_empty() {\n println!(\"Secrets:\");\n for key in &secrets {\n if cf_cfg.env_defaults.contains_key(key) {\n println!(\" {} (default set)\", key);\n } else {\n println!(\" {}\", key);\n }\n }\n println!();\n }\n\n if !vars.is_empty() {\n println!(\"Vars:\");\n for key in &vars {\n let default_value = cf_cfg\n .env_defaults\n .get(key)\n .map(|value| format_default_hint(value));\n if let Some(default_value) = default_value {\n println!(\" {} = {}\", key, default_value);\n } else {\n println!(\" {}\", key);\n }\n }\n println!();\n }\n\n let mut extra_defaults: Vec<_> = cf_cfg\n .env_defaults\n .keys()\n .filter(|key| !secrets.contains(*key) && !vars.contains(*key))\n .cloned()\n .collect();\n extra_defaults.sort();\n\n if !extra_defaults.is_empty() {\n println!(\"Defaults (not in env_keys/env_vars):\");\n for key in extra_defaults {\n if let Some(value) = cf_cfg.env_defaults.get(&key) {\n println!(\" {} = {}\", key, format_default_hint(value));\n }\n }\n }\n\n return Ok(());\n }\n\n if let Some(storage) = cfg.storage.as_ref() {\n println!(\"Storage env keys for {}\", label);\n println!(\"─────────────────────────────\");\n println!(\"Provider: {}\", storage.provider);\n println!();\n\n if storage.envs.is_empty() {\n println!(\"No storage envs configured.\");\n return Ok(());\n }\n\n for env_cfg in &storage.envs {\n println!(\"{}\", env_cfg.name);\n if let Some(description) = env_cfg.description.as_deref() {\n println!(\" {}\", description);\n }\n if env_cfg.variables.is_empty() {\n println!(\" (no variables)\");\n } else {\n for variable in &env_cfg.variables {\n match variable.default.as_deref() {\n Some(default) if !default.is_empty() => {\n println!(\" {} = {}\", variable.key, format_default_hint(default));\n }\n Some(_) => println!(\" {} (default: empty)\", variable.key),\n None => println!(\" {}\", variable.key),\n }\n }\n }\n println!();\n }\n\n return Ok(());\n }\n\n anyhow::bail!(\"No [cloudflare] or [storage] env keys configured in flow.toml\");\n}\n\n/// List env vars for this project.\nfn list(environment: &str) -> Result<()> {\n if local_env_enabled() {\n let target = resolve_env_target()?;\n let label = env_target_label(&target);\n let vars = read_local_env_vars(&target, environment)?;\n\n println!(\"Space: {}\", label);\n println!(\"Environment: {}\", environment);\n println!(\"Backend: local\");\n println!(\"─────────────────────────────\");\n\n if vars.is_empty() {\n println!(\"No env vars set.\");\n return Ok(());\n }\n\n let mut keys: Vec<_> = vars.keys().collect();\n keys.sort();\n\n for key in keys {\n let value = &vars[key];\n let masked = if value.len() > 8 {\n format!(\"{}...\", &value[..4])\n } else {\n \"****\".to_string()\n };\n println!(\" {} = {}\", key, masked);\n }\n\n println!();\n println!(\"{} env var(s)\", vars.len());\n return Ok(());\n }\n\n let target = resolve_env_target()?;\n let label = env_target_label(&target);\n\n let auth = load_auth_config()?;\n let token = auth\n .token\n .as_ref()\n .ok_or_else(|| anyhow::anyhow!(\"Not logged in. Run `f env login` first.\"))?;\n require_env_read_unlock()?;\n\n let api_url = get_api_url(&auth);\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(30))?;\n let (vars, descriptions, backend_label) = match &target {\n EnvTarget::Personal { space } => {\n let mut url = Url::parse(&format!(\"{}/api/env/personal\", api_url))?;\n url.query_pairs_mut()\n .append_pair(\"environment\", environment);\n if let Some(space) = space {\n url.query_pairs_mut().append_pair(\"space\", space);\n }\n let resp = client\n .get(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if resp.status() == 404 {\n bail!(\"Personal env vars not found.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n let data: PersonalEnvResponse = resp.json().context(\"failed to parse response\")?;\n (data.env, None, \"cloud\")\n }\n EnvTarget::Project { name } => {\n let entries =\n fetch_project_cloud_env_entries(name, environment, &[], &api_url, token, &client)?;\n (entries.vars, Some(entries.descriptions), \"cloud (sealed)\")\n }\n };\n\n println!(\"Space: {}\", label);\n println!(\"Environment: {}\", environment);\n println!(\"Backend: {}\", backend_label);\n println!(\"─────────────────────────────\");\n\n if vars.is_empty() {\n println!(\"No env vars set.\");\n return Ok(());\n }\n\n let mut keys: Vec<_> = vars.keys().collect();\n keys.sort();\n\n for key in keys {\n let value = &vars[key];\n // Mask the value (show first 4 chars if long enough)\n let masked = if value.len() > 8 {\n format!(\"{}...\", &value[..4])\n } else {\n \"****\".to_string()\n };\n\n // Show description if available\n if let Some(desc) = descriptions.as_ref().and_then(|map| map.get(key)) {\n println!(\" {} = {} # {}\", key, masked, desc);\n } else {\n println!(\" {} = {}\", key, masked);\n }\n }\n\n println!();\n println!(\"{} env var(s)\", vars.len());\n\n Ok(())\n}\n\n/// Set a personal (global) env var.\npub(crate) fn set_personal_env_var(key: &str, value: &str) -> Result<()> {\n if key.is_empty() {\n bail!(\"Key cannot be empty\");\n }\n\n let target = resolve_personal_target()?;\n let environment = \"production\";\n\n if local_env_enabled() {\n let path = set_local_env_var(&target, environment, key, value)?;\n println!(\n \"✓ Set personal env var locally: {} (stored at {})\",\n key,\n path.display()\n );\n return Ok(());\n }\n\n let auth = load_auth_config()?;\n let token = match auth.token.as_ref() {\n Some(token) => token,\n None => {\n let path = set_local_env_var(&target, environment, key, value)?;\n println!(\n \"✓ Set personal env var locally: {} (stored at {})\",\n key,\n path.display()\n );\n return Ok(());\n }\n };\n\n let api_url = get_api_url(&auth);\n\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(30))?;\n\n let mut url = Url::parse(&format!(\"{}/api/env/personal\", api_url))?;\n if let EnvTarget::Personal { ref space } = target {\n if let Some(space) = space.as_ref() {\n url.query_pairs_mut().append_pair(\"space\", space);\n }\n }\n let mut vars = HashMap::new();\n vars.insert(key.to_string(), value.to_string());\n\n let body = serde_json::json!({\n \"vars\": vars,\n });\n\n let resp = client\n .post(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 401 {\n if std::io::stdin().is_terminal()\n && prompt_confirm(\"Cloud auth failed. Store locally instead? (y/N): \")?\n {\n let path = set_local_env_var(&target, environment, key, value)?;\n println!(\n \"✓ Set personal env var locally: {} (stored at {})\",\n key,\n path.display()\n );\n return Ok(());\n }\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n let err = anyhow::anyhow!(\"API error {}: {}\", status, body);\n if is_local_fallback_error(&err)\n && std::io::stdin().is_terminal()\n && prompt_confirm(\"Cloud unavailable. Store locally instead? (y/N): \")?\n {\n let path = set_local_env_var(&target, environment, key, value)?;\n println!(\n \"✓ Set personal env var locally: {} (stored at {})\",\n key,\n path.display()\n );\n return Ok(());\n }\n return Err(err);\n }\n\n println!(\"✓ Set personal env var: {}\", key);\n Ok(())\n}\n\npub fn set_project_env_var(\n key: &str,\n value: &str,\n environment: &str,\n description: Option<&str>,\n) -> Result<()> {\n set_project_env_var_internal(key, value, environment, description)\n}\n\nfn set_project_env_var_internal(\n key: &str,\n value: &str,\n environment: &str,\n description: Option<&str>,\n) -> Result<()> {\n if key.is_empty() {\n bail!(\"Key cannot be empty\");\n }\n\n let target = resolve_env_target()?;\n if local_env_enabled() {\n let path = set_local_env_var(&target, environment, key, value)?;\n println!(\n \"✓ Set env var locally: {} ({} stored at {})\",\n key,\n environment,\n path.display()\n );\n return Ok(());\n }\n\n let auth = load_auth_config()?;\n let token = match auth.token.as_ref() {\n Some(token) => token,\n None => {\n if std::io::stdin().is_terminal()\n && prompt_confirm(\"Not logged in to cloud. Store locally instead? (y/N): \")?\n {\n let path = set_local_env_var(&target, environment, key, value)?;\n println!(\n \"✓ Set env var locally: {} ({} stored at {})\",\n key,\n environment,\n path.display()\n );\n return Ok(());\n }\n bail!(\"Not logged in. Run `f env login` first.\");\n }\n };\n\n let api_url = get_api_url(&auth);\n let resolved_value = value.to_string();\n\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(30))?;\n let mut vars = HashMap::new();\n vars.insert(key.to_string(), resolved_value.clone());\n let mut descriptions = HashMap::new();\n if let Some(desc) = description {\n descriptions.insert(key.to_string(), desc.to_string());\n }\n\n let mirrored_plaintext = match &target {\n EnvTarget::Personal { space } => {\n let mut url = Url::parse(&format!(\"{}/api/env/personal\", api_url))?;\n if let Some(space) = space {\n url.query_pairs_mut().append_pair(\"space\", space);\n }\n\n let body = serde_json::json!({\n \"vars\": &vars,\n \"environment\": environment,\n });\n\n let resp = client\n .post(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n let err = anyhow::anyhow!(\"API error {}: {}\", status, body);\n if is_local_fallback_error(&err)\n && std::io::stdin().is_terminal()\n && prompt_confirm(\"Cloud unavailable. Store locally instead? (y/N): \")?\n {\n let path = set_local_env_var(&target, environment, key, value)?;\n println!(\n \"✓ Set env var locally: {} ({} stored at {})\",\n key,\n environment,\n path.display()\n );\n return Ok(());\n }\n return Err(err);\n }\n\n false\n }\n EnvTarget::Project { name } => match write_project_cloud_env_entries(\n name,\n environment,\n &vars,\n &descriptions,\n &api_url,\n token,\n &client,\n ) {\n Ok(mirror) => mirror,\n Err(err) => {\n if is_local_fallback_error(&err)\n && std::io::stdin().is_terminal()\n && prompt_confirm(\"Cloud unavailable. Store locally instead? (y/N): \")?\n {\n let path = set_local_env_var(&target, environment, key, value)?;\n println!(\n \"✓ Set env var locally: {} ({} stored at {})\",\n key,\n environment,\n path.display()\n );\n return Ok(());\n }\n return Err(err);\n }\n },\n };\n\n let masked = if resolved_value.len() > 8 {\n format!(\"{}...\", &resolved_value[..4])\n } else {\n \"****\".to_string()\n };\n\n if let Some(desc) = description {\n if mirrored_plaintext && matches!(target, EnvTarget::Project { .. }) {\n println!(\n \"✓ Set {}={} ({}) - {} [sealed + plaintext host mirror]\",\n key, masked, environment, desc\n );\n } else if matches!(target, EnvTarget::Project { .. }) {\n println!(\n \"✓ Set {}={} ({}) - {} [sealed]\",\n key, masked, environment, desc\n );\n } else {\n println!(\"✓ Set {}={} ({}) - {}\", key, masked, environment, desc);\n }\n } else {\n if mirrored_plaintext && matches!(target, EnvTarget::Project { .. }) {\n println!(\n \"✓ Set {}={} ({}) [sealed + plaintext host mirror]\",\n key, masked, environment\n );\n } else if matches!(target, EnvTarget::Project { .. }) {\n println!(\"✓ Set {}={} ({}) [sealed]\", key, masked, environment);\n } else {\n println!(\"✓ Set {}={} ({})\", key, masked, environment);\n }\n }\n\n Ok(())\n}\n\n/// Show current auth status.\nfn status() -> Result<()> {\n if local_env_enabled() {\n println!(\"Local Environment Manager\");\n println!(\"─────────────────────────────\");\n if let Ok(root) = local_env_root() {\n println!(\"Root: {}\", root.display());\n }\n if let Ok(target) = resolve_env_target() {\n println!(\"Space: {}\", env_target_label(&target));\n }\n println!();\n println!(\"Commands:\");\n println!(\" f env list - List env vars\");\n println!(\" f env set K=V - Set personal env var\");\n println!(\" f env project set -e <env> K=V - Set project env var\");\n println!(\" f env get ... - Read env vars\");\n println!(\" f env run -- <cmd> - Run with env vars injected\");\n println!(\" f env keys - Show configured env keys\");\n println!(\" f env guide - Guided env setup from flow.toml\");\n return Ok(());\n }\n\n let auth = load_auth_config_raw()?;\n\n println!(\"Cloud Environment Manager\");\n println!(\"─────────────────────────────\");\n\n let api_url = get_api_url(&auth);\n if let Some(ref token) = auth.token {\n let masked = format!(\"{}...\", &token[..7.min(token.len())]);\n println!(\"Token: {}\", masked);\n println!(\"API: {}\", api_url);\n } else if auth.token_source.as_deref() == Some(\"keychain\") {\n println!(\"Token: stored in Keychain\");\n println!(\"API: {}\", api_url);\n } else {\n println!(\"Status: Not logged in\");\n println!();\n println!(\"Run `f env login` to authenticate.\");\n return Ok(());\n }\n\n if let Ok(target) = resolve_env_target() {\n println!(\"Space: {}\", env_target_label(&target));\n }\n\n println!();\n println!(\"Commands:\");\n println!(\" f env sync - Sync project settings\");\n println!(\" f env unlock - Unlock env reads (Touch ID on macOS)\");\n println!(\" f env pull - Fetch env vars\");\n println!(\" f env push - Push .env to cloud\");\n println!(\" f env guide - Guided env setup from flow.toml\");\n println!(\" f env apply - Apply cloud envs to Cloudflare\");\n println!(\" f env bootstrap - Bootstrap Cloudflare secrets\");\n println!(\" f env setup - Interactive env setup\");\n println!(\" f env list - List env vars\");\n println!(\" f env keys - Show configured env keys\");\n println!(\" f env set K=V - Set personal env var\");\n println!(\" f env project set -e <env> K=V - Set project env var\");\n\n Ok(())\n}\n\n/// Parse a .env file into key-value pairs.\npub(crate) fn parse_env_file(content: &str) -> HashMap<String, String> {\n let mut vars = HashMap::new();\n\n for line in content.lines() {\n let line = line.trim();\n\n // Skip empty lines and comments\n if line.is_empty() || line.starts_with('#') {\n continue;\n }\n\n // Parse KEY=VALUE\n if let Some((key, value)) = line.split_once('=') {\n let key = key.trim();\n let value = value.trim();\n\n // Remove surrounding quotes\n let value = value\n .strip_prefix('\"')\n .and_then(|s| s.strip_suffix('\"'))\n .or_else(|| value.strip_prefix('\\'').and_then(|s| s.strip_suffix('\\'')))\n .unwrap_or(value);\n\n if !key.is_empty() {\n vars.insert(key.to_string(), value.to_string());\n }\n }\n }\n\n vars\n}\n\n/// Fetch env vars from cloud (personal or project).\nfn fetch_env_vars(\n target: &EnvTarget,\n environment: &str,\n keys: &[String],\n include_environment: bool,\n) -> Result<HashMap<String, String>> {\n if local_env_enabled() {\n if matches!(target, EnvTarget::Personal { .. }) && !keys.is_empty() {\n return fetch_local_personal_env_vars(keys);\n }\n let vars = read_local_env_vars(target, environment)?;\n return Ok(select_requested_env_keys(vars, keys));\n }\n\n if matches!(target, EnvTarget::Personal { .. }) {\n match fetch_local_personal_env_vars(keys) {\n Ok(vars) if !vars.is_empty() => return Ok(vars),\n Ok(_) => {}\n Err(err) => {\n if !has_cloud_auth_token() {\n return Err(err);\n }\n }\n }\n }\n\n let auth = load_auth_config()?;\n let token = match auth.token.as_ref() {\n Some(token) => token,\n None => {\n if std::io::stdin().is_terminal()\n && prompt_confirm(\"Not logged in to cloud. Read local envs instead? (y/N): \")?\n {\n let vars = read_local_env_vars(target, environment)?;\n return Ok(select_requested_env_keys(vars, keys));\n }\n bail!(\"Not logged in. Run `f env login` first.\");\n }\n };\n require_env_read_unlock()?;\n\n let api_url = get_api_url(&auth);\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(30))?;\n\n if let EnvTarget::Project { name } = target {\n let entries = match fetch_project_cloud_env_entries(\n name,\n environment,\n keys,\n &api_url,\n token,\n &client,\n ) {\n Ok(entries) => entries,\n Err(err) => {\n if is_local_fallback_error(&err)\n && std::io::stdin().is_terminal()\n && prompt_confirm(\"Cloud unavailable. Read local envs instead? (y/N): \")?\n {\n let vars = read_local_env_vars(target, environment)?;\n return Ok(select_requested_env_keys(vars, keys));\n }\n return Err(err);\n }\n };\n return Ok(entries.vars);\n }\n\n let mut url = match target {\n EnvTarget::Personal { space } => {\n let mut url = Url::parse(&format!(\"{}/api/env/personal\", api_url))?;\n if include_environment {\n url.query_pairs_mut()\n .append_pair(\"environment\", environment);\n }\n if let Some(space) = space {\n url.query_pairs_mut().append_pair(\"space\", space);\n }\n url\n }\n EnvTarget::Project { name } => {\n let mut url = Url::parse(&format!(\"{}/api/env/{}\", api_url, name))?;\n url.query_pairs_mut()\n .append_pair(\"environment\", environment);\n url\n }\n };\n\n if !keys.is_empty() {\n url.query_pairs_mut().append_pair(\"keys\", &keys.join(\",\"));\n }\n\n let resp = client\n .get(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 401 {\n if std::io::stdin().is_terminal()\n && prompt_confirm(\"Cloud auth failed. Read local envs instead? (y/N): \")?\n {\n let vars = read_local_env_vars(target, environment)?;\n return Ok(select_requested_env_keys(vars, keys));\n }\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if resp.status() == 404 {\n match target {\n EnvTarget::Personal { .. } => bail!(\"Personal env vars not found.\"),\n EnvTarget::Project { .. } => {\n bail!(\"Project not found. Create it with `f env push` first.\")\n }\n }\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n let err = anyhow::anyhow!(\"API error {}: {}\", status, body);\n if is_local_fallback_error(&err)\n && std::io::stdin().is_terminal()\n && prompt_confirm(\"Cloud unavailable. Read local envs instead? (y/N): \")?\n {\n let vars = read_local_env_vars(target, environment)?;\n return Ok(select_requested_env_keys(vars, keys));\n }\n return Err(err);\n }\n\n match target {\n EnvTarget::Personal { .. } => {\n let data: PersonalEnvResponse = resp.json().context(\"failed to parse response\")?;\n Ok(data.env)\n }\n EnvTarget::Project { .. } => {\n let data: EnvResponse = resp.json().context(\"failed to parse response\")?;\n Ok(data.env)\n }\n }\n}\n\npub fn fetch_project_env_vars(\n environment: &str,\n keys: &[String],\n) -> Result<HashMap<String, String>> {\n let target = resolve_env_target()?;\n fetch_env_vars(&target, environment, keys, true)\n}\n\npub fn fetch_personal_env_vars(keys: &[String]) -> Result<HashMap<String, String>> {\n let target = resolve_personal_target()?;\n fetch_env_vars(&target, \"production\", keys, false)\n}\n\n/// Get specific env vars and print to stdout.\nfn get_vars(keys: &[String], personal: bool, environment: &str, format: &str) -> Result<()> {\n let target = if personal {\n resolve_personal_target()?\n } else {\n resolve_env_target()?\n };\n let vars = fetch_env_vars(&target, environment, keys, !personal)?;\n\n if vars.is_empty() {\n bail!(\"No env vars found\");\n }\n\n match format {\n \"json\" => {\n let json = serde_json::to_string_pretty(&vars)?;\n println!(\"{}\", json);\n }\n \"value\" => {\n if keys.len() != 1 {\n bail!(\"'value' format requires exactly one key\");\n }\n let key = &keys[0];\n if let Some(value) = vars.get(key) {\n print!(\"{}\", value); // No newline for piping\n } else {\n bail!(\"Key '{}' not found\", key);\n }\n }\n \"env\" | _ => {\n // Default: KEY=VALUE format\n let mut sorted_keys: Vec<_> = vars.keys().collect();\n sorted_keys.sort();\n for key in sorted_keys {\n let value = &vars[key];\n // Escape for shell\n let escaped = value.replace('\\\\', \"\\\\\\\\\").replace('\"', \"\\\\\\\"\");\n println!(\"{}=\\\"{}\\\"\", key, escaped);\n }\n }\n }\n\n Ok(())\n}\n\n/// Run a command with env vars injected from cloud.\nfn run_with_env(\n personal: bool,\n environment: &str,\n keys: &[String],\n command: &[String],\n) -> Result<()> {\n if command.is_empty() {\n bail!(\"No command specified\");\n }\n\n let target = if personal {\n resolve_personal_target()?\n } else {\n resolve_env_target()?\n };\n let vars = fetch_env_vars(&target, environment, keys, !personal)?;\n\n let (cmd, args) = command.split_first().unwrap();\n\n let mut child = Command::new(cmd);\n child.args(args);\n\n // Inject env vars\n for (key, value) in &vars {\n child.env(key, value);\n }\n\n let status = child\n .status()\n .with_context(|| format!(\"failed to run '{}'\", cmd))?;\n\n std::process::exit(status.code().unwrap_or(1));\n}\n\n// =============================================================================\n// Service Token Management\n// =============================================================================\n\n#[derive(Debug, Deserialize)]\nstruct CreateTokenResponse {\n #[allow(dead_code)]\n success: bool,\n token: String,\n #[serde(rename = \"projectName\")]\n project_name: String,\n name: String,\n permissions: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct TokenEntry {\n name: String,\n #[serde(rename = \"projectName\")]\n project_name: String,\n permissions: String,\n #[serde(rename = \"createdAt\")]\n #[allow(dead_code)]\n created_at: Option<String>,\n #[serde(rename = \"lastUsedAt\")]\n last_used_at: Option<String>,\n revoked: bool,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ListTokensResponse {\n tokens: Vec<TokenEntry>,\n}\n\n/// Create a new service token for the current project.\nfn token_create(name: Option<&str>, permissions: &str) -> Result<()> {\n let auth = load_auth_config()?;\n let token = auth\n .token\n .as_ref()\n .ok_or_else(|| anyhow::anyhow!(\"Not logged in. Run `f env login` first.\"))?;\n\n let target = resolve_env_target()?;\n let project = env_target_name_for_tokens(&target)?;\n let default_name = format!(\"{}-service\", project);\n let token_name = name.unwrap_or(&default_name);\n let api_url = get_api_url(&auth);\n\n println!(\"Creating service token for '{}'...\", project);\n\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(30))?;\n\n let url = format!(\"{}/api/env/tokens\", api_url);\n let body = serde_json::json!({\n \"projectName\": project,\n \"name\": token_name,\n \"permissions\": permissions,\n });\n\n let resp = client\n .post(&url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if resp.status() == 403 {\n bail!(\"You don't own this project.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n let data: CreateTokenResponse = resp.json().context(\"failed to parse response\")?;\n\n println!();\n println!(\"✓ Service token created!\");\n println!();\n println!(\"Token: {}\", data.token);\n println!(\"Project: {}\", data.project_name);\n println!(\"Name: {}\", data.name);\n println!(\"Permissions: {}\", data.permissions);\n println!();\n println!(\"IMPORTANT: Save this token now. It won't be shown again.\");\n println!();\n println!(\n \"This token can ONLY access env vars for '{}'.\",\n data.project_name\n );\n println!(\"If the host is compromised, revoke it with:\");\n println!(\" f env token revoke {}\", data.name);\n\n Ok(())\n}\n\n/// List service tokens for the current user.\nfn token_list() -> Result<()> {\n let auth = load_auth_config()?;\n let token = auth\n .token\n .as_ref()\n .ok_or_else(|| anyhow::anyhow!(\"Not logged in. Run `f env login` first.\"))?;\n\n let api_url = get_api_url(&auth);\n\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(30))?;\n\n let url = format!(\"{}/api/env/tokens\", api_url);\n\n let resp = client\n .get(&url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n let data: ListTokensResponse = resp.json().context(\"failed to parse response\")?;\n\n if data.tokens.is_empty() {\n println!(\"No service tokens found.\");\n println!();\n println!(\"Create one with: f env token create\");\n return Ok(());\n }\n\n println!(\"Service Tokens\");\n println!(\"─────────────────────────────\");\n\n for entry in &data.tokens {\n let status = if entry.revoked { \" (revoked)\" } else { \"\" };\n println!(\n \" {} → {} [{}]{}\",\n entry.name, entry.project_name, entry.permissions, status\n );\n if let Some(last_used) = &entry.last_used_at {\n println!(\" Last used: {}\", last_used);\n }\n }\n\n println!();\n println!(\"{} token(s)\", data.tokens.len());\n\n Ok(())\n}\n\n/// Revoke a service token.\nfn token_revoke(name: &str) -> Result<()> {\n let auth = load_auth_config()?;\n let token = auth\n .token\n .as_ref()\n .ok_or_else(|| anyhow::anyhow!(\"Not logged in. Run `f env login` first.\"))?;\n\n let target = resolve_env_target()?;\n let project = env_target_name_for_tokens(&target)?;\n let api_url = get_api_url(&auth);\n\n println!(\"Revoking token '{}' for project '{}'...\", name, project);\n\n let client = crate::http_client::blocking_with_timeout(std::time::Duration::from_secs(30))?;\n\n let url = format!(\"{}/api/env/tokens\", api_url);\n let body = serde_json::json!({\n \"name\": name,\n \"projectName\": project,\n });\n\n let resp = client\n .delete(&url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .json(&body)\n .send()\n .context(\"failed to connect to cloud\")?;\n\n if resp.status() == 401 {\n bail!(\"Unauthorized. Check your token with `f env login`.\");\n }\n\n if resp.status() == 404 {\n bail!(\"Token '{}' not found for project '{}'.\", name, project);\n }\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body = resp.text().unwrap_or_default();\n bail!(\"API error {}: {}\", status, body);\n }\n\n println!(\"✓ Token '{}' revoked.\", name);\n println!();\n println!(\"Any host using this token will no longer be able to fetch env vars.\");\n\n Ok(())\n}\n\n#[cfg(test)]\nmod tests {\n use super::{\n SealedEnvContent, SealedEnvItem, SealedEnvRecipientGrant, create_env_sealer_identity,\n decrypt_project_env_value, ensure_private_dir, is_local_keychain_ref, local_keychain_ref,\n project_env_backend_from_config, project_plaintext_cloud_mirror_required_for_config,\n seal_project_env_value, write_private_file,\n };\n use crate::config::Config;\n #[cfg(unix)]\n use std::os::unix::fs::PermissionsExt;\n use tempfile::tempdir;\n\n #[test]\n fn project_env_backend_detects_local_host_source() {\n let cfg: Config = toml::from_str(\n r#\"\n[host]\nenv_source = \"local\"\n\"#,\n )\n .expect(\"host env_source should parse\");\n\n assert_eq!(project_env_backend_from_config(&cfg), Some(\"local\"));\n }\n\n #[test]\n fn project_env_backend_detects_cloud_source() {\n let cfg: Config = toml::from_str(\n r#\"\n[cloudflare]\nenv_source = \"cloud\"\n\"#,\n )\n .expect(\"cloudflare env_source should parse\");\n\n assert_eq!(project_env_backend_from_config(&cfg), Some(\"cloud\"));\n }\n\n #[test]\n fn project_env_backend_requires_unambiguous_sources() {\n let cfg: Config = toml::from_str(\n r#\"\n[host]\nenv_source = \"local\"\n\n[cloudflare]\nenv_source = \"cloud\"\n\"#,\n )\n .expect(\"mixed env_source config should parse\");\n\n assert_eq!(project_env_backend_from_config(&cfg), None);\n }\n\n #[test]\n fn plaintext_cloud_mirror_requires_cloud_host_with_service_token() {\n let cfg: Config = toml::from_str(\n r#\"\n[host]\nenv_source = \"cloud\"\nservice_token = \"cloud_test_123\"\n\"#,\n )\n .expect(\"host cloud config should parse\");\n\n assert!(project_plaintext_cloud_mirror_required_for_config(&cfg));\n }\n\n #[test]\n fn plaintext_cloud_mirror_ignores_non_cloud_or_missing_token() {\n let no_token: Config = toml::from_str(\n r#\"\n[host]\nenv_source = \"cloud\"\n\"#,\n )\n .expect(\"host cloud config without token should parse\");\n let local: Config = toml::from_str(\n r#\"\n[host]\nenv_source = \"local\"\nservice_token = \"cloud_test_123\"\n\"#,\n )\n .expect(\"host local config should parse\");\n\n assert!(!project_plaintext_cloud_mirror_required_for_config(\n &no_token\n ));\n assert!(!project_plaintext_cloud_mirror_required_for_config(&local));\n }\n\n #[test]\n fn local_keychain_refs_use_reserved_prefix() {\n let reference = local_keychain_ref(\"DESIGNER_LINEAR_API_KEY\");\n assert!(is_local_keychain_ref(&reference));\n assert!(!is_local_keychain_ref(\"example_secret_value\"));\n }\n\n #[test]\n fn sealed_project_env_roundtrip_decrypts_for_registered_recipient() {\n let identity = create_env_sealer_identity().expect(\"create identity\");\n let write_item = seal_project_env_value(\n \"example_secret_value\",\n &identity,\n std::slice::from_ref(&identity.sealer_id),\n )\n .expect(\"seal env value\");\n let read_item = SealedEnvItem {\n description: Some(\"Linear API key\".to_string()),\n available_recipient_count: write_item.recipients.len(),\n content: Some(SealedEnvContent {\n algorithm: write_item.content.algorithm,\n ciphertext_b64: write_item.content.ciphertext_b64,\n nonce_b64: write_item.content.nonce_b64,\n }),\n recipients: write_item\n .recipients\n .into_iter()\n .map(|recipient| SealedEnvRecipientGrant {\n recipient_id: recipient.recipient_id,\n sender_id: Some(recipient.sender_id),\n wrapped_key_b64: recipient.wrapped_key_b64,\n nonce_material_b64: recipient.nonce_material_b64,\n })\n .collect(),\n };\n\n let value = decrypt_project_env_value(&read_item, &identity).expect(\"decrypt env value\");\n assert_eq!(value.as_deref(), Some(\"example_secret_value\"));\n }\n\n #[cfg(unix)]\n #[test]\n fn ensure_private_dir_enforces_owner_only_permissions() {\n let dir = tempdir().expect(\"tempdir\");\n let nested = dir.path().join(\"a\").join(\"b\");\n\n ensure_private_dir(&nested).expect(\"create private dir\");\n\n let mode = nested.metadata().expect(\"metadata\").permissions().mode() & 0o777;\n assert_eq!(mode, 0o700);\n }\n\n #[cfg(unix)]\n #[test]\n fn write_private_file_enforces_owner_only_permissions() {\n let dir = tempdir().expect(\"tempdir\");\n let path = dir.path().join(\"secrets\").join(\"production.env\");\n\n write_private_file(&path, \"API_KEY=\\\"secret\\\"\\n\").expect(\"write private file\");\n\n let file_mode = path.metadata().expect(\"metadata\").permissions().mode() & 0o777;\n let dir_mode = path\n .parent()\n .expect(\"parent\")\n .metadata()\n .expect(\"dir metadata\")\n .permissions()\n .mode()\n & 0o777;\n\n assert_eq!(file_mode, 0o600);\n assert_eq!(dir_mode, 0o700);\n }\n}\n" }, { "path": "src/env_setup.rs", "content": "use std::fs;\nuse std::path::{Path, PathBuf};\n\nuse anyhow::{Context, Result};\nuse crossterm::{\n event::{self, Event as CEvent, KeyCode, KeyEvent},\n execute,\n terminal::{EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode},\n};\nuse ignore::WalkBuilder;\nuse ratatui::{\n Terminal,\n backend::CrosstermBackend,\n layout::{Constraint, Direction, Layout},\n style::{Color, Modifier, Style},\n text::{Line, Span},\n widgets::{Block, Borders, List, ListItem, Paragraph, Wrap},\n};\n\nuse crate::env::parse_env_file;\n\n#[derive(Debug, Clone, Default)]\npub struct EnvSetupDefaults {\n pub env_file: Option<PathBuf>,\n pub environment: Option<String>,\n}\n\n#[derive(Debug, Clone)]\npub struct EnvSetupResult {\n pub env_file: Option<PathBuf>,\n pub environment: String,\n pub selected_keys: Vec<String>,\n pub apply: bool,\n}\n\npub fn run_env_setup(\n project_root: &Path,\n defaults: EnvSetupDefaults,\n) -> Result<Option<EnvSetupResult>> {\n let env_files = discover_env_files(project_root)?;\n if env_files.is_empty() {\n println!(\"No .env files found.\");\n println!(\"Create one (for example .env) and try: f env setup\");\n return Ok(None);\n }\n\n let mut app = EnvSetupApp::new(project_root, env_files, defaults);\n\n enable_raw_mode().context(\"failed to enable raw mode\")?;\n let mut stdout = std::io::stdout();\n execute!(stdout, EnterAlternateScreen).context(\"failed to enter alternate screen\")?;\n let backend = CrosstermBackend::new(stdout);\n let mut terminal = Terminal::new(backend).context(\"failed to create terminal backend\")?;\n\n let app_result = run_app(&mut terminal, &mut app);\n\n disable_raw_mode().ok();\n let _ = terminal.show_cursor();\n drop(terminal);\n let mut stdout = std::io::stdout();\n execute!(stdout, LeaveAlternateScreen).ok();\n\n app_result\n}\n\n#[derive(Debug, Clone, Copy)]\nenum SetupStep {\n EnvFile,\n EnvTarget,\n CustomEnv,\n Keys,\n Confirm,\n}\n\nstruct EnvFileChoice {\n label: String,\n path: Option<PathBuf>,\n}\n\nstruct EnvTargetChoice {\n label: String,\n value: Option<String>,\n is_custom: bool,\n}\n\nstruct EnvKeyItem {\n key: String,\n selected: bool,\n suspect: bool,\n suspect_reason: Option<String>,\n value_len: usize,\n}\n\nstruct EnvSetupApp {\n project_root: PathBuf,\n step: SetupStep,\n env_files: Vec<EnvFileChoice>,\n selected_env_file: usize,\n env_targets: Vec<EnvTargetChoice>,\n selected_env_target: usize,\n custom_env: String,\n key_items: Vec<EnvKeyItem>,\n selected_key: usize,\n apply: bool,\n result: Option<EnvSetupResult>,\n}\n\nimpl EnvSetupApp {\n fn new(project_root: &Path, env_files: Vec<PathBuf>, defaults: EnvSetupDefaults) -> Self {\n let env_file_choices = build_env_file_choices(project_root, &env_files);\n let selected_env_file =\n pick_default_env_file(project_root, &env_file_choices, defaults.env_file.as_ref());\n\n let mut app = Self {\n project_root: project_root.to_path_buf(),\n step: SetupStep::EnvFile,\n env_files: env_file_choices,\n selected_env_file,\n env_targets: Vec::new(),\n selected_env_target: 0,\n custom_env: String::new(),\n key_items: Vec::new(),\n selected_key: 0,\n apply: true,\n result: None,\n };\n\n let preferred = defaults\n .environment\n .as_deref()\n .map(|s| s.to_string())\n .or_else(|| app.infer_env_target());\n app.refresh_env_targets(preferred.as_deref());\n\n app\n }\n\n fn infer_env_target(&self) -> Option<String> {\n let path = self.env_file_path()?;\n infer_env_target_from_file(&path)\n }\n\n fn refresh_env_targets(&mut self, preferred: Option<&str>) {\n let mut targets = vec![\n EnvTargetChoice {\n label: \"production (default)\".to_string(),\n value: Some(\"production\".to_string()),\n is_custom: false,\n },\n EnvTargetChoice {\n label: \"staging\".to_string(),\n value: Some(\"staging\".to_string()),\n is_custom: false,\n },\n EnvTargetChoice {\n label: \"dev\".to_string(),\n value: Some(\"dev\".to_string()),\n is_custom: false,\n },\n ];\n\n if let Some(env) = preferred {\n if !targets\n .iter()\n .any(|choice| choice.value.as_deref() == Some(env))\n {\n targets.push(EnvTargetChoice {\n label: env.to_string(),\n value: Some(env.to_string()),\n is_custom: false,\n });\n }\n }\n\n targets.push(EnvTargetChoice {\n label: \"custom...\".to_string(),\n value: None,\n is_custom: true,\n });\n\n self.env_targets = targets;\n self.selected_env_target = pick_default_env_target(&self.env_targets, preferred);\n }\n\n fn refresh_keys(&mut self) {\n self.key_items.clear();\n self.selected_key = 0;\n\n if let Some(path) = self.env_file_path() {\n if let Ok(items) = build_key_items(&path) {\n self.key_items = items;\n }\n }\n }\n\n fn env_file_path(&self) -> Option<PathBuf> {\n self.env_files\n .get(self.selected_env_file)\n .and_then(|choice| choice.path.clone())\n }\n\n fn env_file_path_ref(&self) -> Option<&Path> {\n self.env_files\n .get(self.selected_env_file)\n .and_then(|choice| choice.path.as_deref())\n }\n\n fn selected_env_target(&self) -> Option<String> {\n self.env_targets\n .get(self.selected_env_target)\n .and_then(|choice| choice.value.clone())\n }\n\n fn finalize(&mut self) {\n let selected_keys = self\n .key_items\n .iter()\n .filter(|item| item.selected)\n .map(|item| item.key.clone())\n .collect();\n\n let environment = self\n .selected_env_target()\n .unwrap_or_else(|| \"production\".to_string());\n\n self.result = Some(EnvSetupResult {\n env_file: self.env_file_path(),\n environment,\n selected_keys,\n apply: self.apply,\n });\n }\n}\n\nfn run_app<B: ratatui::backend::Backend>(\n terminal: &mut Terminal<B>,\n app: &mut EnvSetupApp,\n) -> Result<Option<EnvSetupResult>> {\n loop {\n terminal\n .draw(|f| draw_ui(f, app))\n .map_err(|err| anyhow::anyhow!(\"failed to draw env setup UI: {err}\"))?;\n\n if event::poll(std::time::Duration::from_millis(200))? {\n if let CEvent::Key(key) = event::read()? {\n if handle_key(app, key)? {\n return Ok(app.result.take());\n }\n }\n }\n }\n}\n\nfn handle_key(app: &mut EnvSetupApp, key: KeyEvent) -> Result<bool> {\n match key.code {\n KeyCode::Char('q') => return Ok(true),\n KeyCode::Esc => return Ok(step_back(app)),\n _ => {}\n }\n\n match app.step {\n SetupStep::EnvFile => match key.code {\n KeyCode::Up => {\n select_prev(&mut app.selected_env_file, app.env_files.len());\n let preferred = app.infer_env_target();\n app.refresh_env_targets(preferred.as_deref());\n }\n KeyCode::Down => {\n select_next(&mut app.selected_env_file, app.env_files.len());\n let preferred = app.infer_env_target();\n app.refresh_env_targets(preferred.as_deref());\n }\n KeyCode::Enter => {\n let preferred = app.infer_env_target();\n app.refresh_env_targets(preferred.as_deref());\n app.step = SetupStep::EnvTarget;\n }\n _ => {}\n },\n SetupStep::EnvTarget => match key.code {\n KeyCode::Up => select_prev(&mut app.selected_env_target, app.env_targets.len()),\n KeyCode::Down => select_next(&mut app.selected_env_target, app.env_targets.len()),\n KeyCode::Enter => {\n if app\n .env_targets\n .get(app.selected_env_target)\n .is_some_and(|choice| choice.is_custom)\n {\n app.custom_env.clear();\n app.step = SetupStep::CustomEnv;\n } else if app.env_file_path().is_some() {\n app.refresh_keys();\n if app.key_items.is_empty() {\n app.step = SetupStep::Confirm;\n } else {\n app.step = SetupStep::Keys;\n }\n } else {\n app.step = SetupStep::Confirm;\n }\n }\n _ => {}\n },\n SetupStep::CustomEnv => match key.code {\n KeyCode::Enter => {\n if !app.custom_env.trim().is_empty() {\n app.env_targets.push(EnvTargetChoice {\n label: app.custom_env.trim().to_string(),\n value: Some(app.custom_env.trim().to_string()),\n is_custom: false,\n });\n app.selected_env_target = app.env_targets.len().saturating_sub(2);\n if app.env_file_path().is_some() {\n app.refresh_keys();\n app.step = if app.key_items.is_empty() {\n SetupStep::Confirm\n } else {\n SetupStep::Keys\n };\n } else {\n app.step = SetupStep::Confirm;\n }\n }\n }\n KeyCode::Backspace => {\n app.custom_env.pop();\n }\n KeyCode::Char(ch) => {\n if !ch.is_control() {\n app.custom_env.push(ch);\n }\n }\n _ => {}\n },\n SetupStep::Keys => match key.code {\n KeyCode::Up => select_prev(&mut app.selected_key, app.key_items.len()),\n KeyCode::Down => select_next(&mut app.selected_key, app.key_items.len()),\n KeyCode::Char(' ') => {\n if let Some(item) = app.key_items.get_mut(app.selected_key) {\n item.selected = !item.selected;\n }\n }\n KeyCode::Enter => app.step = SetupStep::Confirm,\n _ => {}\n },\n SetupStep::Confirm => match key.code {\n KeyCode::Char(' ') => app.apply = !app.apply,\n KeyCode::Enter => {\n app.finalize();\n return Ok(true);\n }\n _ => {}\n },\n }\n\n Ok(false)\n}\n\nfn draw_ui(f: &mut ratatui::Frame<'_>, app: &EnvSetupApp) {\n let chunks = Layout::default()\n .direction(Direction::Vertical)\n .constraints(\n [\n Constraint::Length(3),\n Constraint::Min(1),\n Constraint::Length(3),\n ]\n .as_ref(),\n )\n .split(f.area());\n\n let title = match app.step {\n SetupStep::EnvFile => \"Env Setup: Select .env file\",\n SetupStep::EnvTarget => \"Select cloud environment\",\n SetupStep::CustomEnv => \"Enter custom environment\",\n SetupStep::Keys => \"Select keys to push\",\n SetupStep::Confirm => \"Confirm env setup\",\n };\n\n let header = Paragraph::new(Line::from(title))\n .block(Block::default().borders(Borders::ALL).title(\"flow\"))\n .alignment(ratatui::layout::Alignment::Center);\n f.render_widget(header, chunks[0]);\n\n match app.step {\n SetupStep::EnvFile => {\n let body = Layout::default()\n .direction(Direction::Horizontal)\n .constraints([Constraint::Percentage(55), Constraint::Percentage(45)].as_ref())\n .split(chunks[1]);\n let items = app\n .env_files\n .iter()\n .map(|choice| ListItem::new(Line::from(choice.label.clone())))\n .collect::<Vec<_>>();\n let list = List::new(items)\n .block(\n Block::default()\n .borders(Borders::ALL)\n .title(\"Secrets source\"),\n )\n .highlight_style(\n Style::default()\n .fg(Color::Black)\n .bg(Color::Cyan)\n .add_modifier(Modifier::BOLD),\n );\n let mut state = ratatui::widgets::ListState::default();\n state.select(Some(app.selected_env_file));\n f.render_stateful_widget(list, body[0], &mut state);\n\n let preview_lines = build_env_preview_lines(&app.project_root, app.env_file_path_ref());\n let preview = Paragraph::new(preview_lines)\n .block(Block::default().borders(Borders::ALL).title(\"Preview\"))\n .wrap(Wrap { trim: true });\n f.render_widget(preview, body[1]);\n }\n SetupStep::EnvTarget => {\n let items = app\n .env_targets\n .iter()\n .map(|choice| ListItem::new(Line::from(choice.label.clone())))\n .collect::<Vec<_>>();\n let list = List::new(items)\n .block(Block::default().borders(Borders::ALL).title(\"Environment\"))\n .highlight_style(\n Style::default()\n .fg(Color::Black)\n .bg(Color::Cyan)\n .add_modifier(Modifier::BOLD),\n );\n let mut state = ratatui::widgets::ListState::default();\n state.select(Some(app.selected_env_target));\n f.render_stateful_widget(list, chunks[1], &mut state);\n }\n SetupStep::CustomEnv => {\n let prompt = format!(\"> {}\", app.custom_env);\n let input = Paragraph::new(prompt)\n .block(\n Block::default()\n .borders(Borders::ALL)\n .title(\"Environment name\"),\n )\n .wrap(Wrap { trim: true });\n f.render_widget(input, chunks[1]);\n }\n SetupStep::Keys => {\n let body = Layout::default()\n .direction(Direction::Horizontal)\n .constraints([Constraint::Percentage(60), Constraint::Percentage(40)].as_ref())\n .split(chunks[1]);\n let selected_count = app.key_items.iter().filter(|item| item.selected).count();\n let items = app\n .key_items\n .iter()\n .map(|item| {\n let indicator = if item.selected { \"[x]\" } else { \"[ ]\" };\n let flag = if item.suspect { \" suspect\" } else { \"\" };\n let label = format!(\"{indicator} {}{flag}\", item.key);\n ListItem::new(Line::from(label))\n })\n .collect::<Vec<_>>();\n let list = List::new(items)\n .block(Block::default().borders(Borders::ALL).title(format!(\n \"Keys ({}/{})\",\n selected_count,\n app.key_items.len()\n )))\n .highlight_style(\n Style::default()\n .fg(Color::Black)\n .bg(Color::Cyan)\n .add_modifier(Modifier::BOLD),\n );\n let mut state = ratatui::widgets::ListState::default();\n state.select(Some(app.selected_key));\n f.render_stateful_widget(list, body[0], &mut state);\n\n let detail_lines = build_key_detail_lines(\n &app.project_root,\n app.env_file_path_ref(),\n app.key_items.get(app.selected_key),\n );\n let details = Paragraph::new(detail_lines)\n .block(Block::default().borders(Borders::ALL).title(\"Details\"))\n .wrap(Wrap { trim: true });\n f.render_widget(details, body[1]);\n }\n SetupStep::Confirm => {\n let env_file = app\n .env_file_path()\n .map(|p| relative_display(&app.project_root, &p))\n .unwrap_or_else(|| \"none\".to_string());\n let env_target = app\n .selected_env_target()\n .unwrap_or_else(|| \"production\".to_string());\n let selected_count = app.key_items.iter().filter(|item| item.selected).count();\n let apply = if app.apply { \"yes\" } else { \"no\" };\n let summary = vec![\n Line::from(vec![\n Span::styled(\"Env file: \", Style::default().add_modifier(Modifier::BOLD)),\n Span::raw(env_file),\n ]),\n Line::from(vec![\n Span::styled(\n \"Environment: \",\n Style::default().add_modifier(Modifier::BOLD),\n ),\n Span::raw(env_target),\n ]),\n Line::from(vec![\n Span::styled(\n \"Keys selected: \",\n Style::default().add_modifier(Modifier::BOLD),\n ),\n Span::raw(format!(\"{}\", selected_count)),\n ]),\n Line::from(vec![\n Span::styled(\"Apply now: \", Style::default().add_modifier(Modifier::BOLD)),\n Span::raw(apply),\n ]),\n ];\n\n let paragraph = Paragraph::new(summary)\n .block(Block::default().borders(Borders::ALL).title(\"Review\"))\n .wrap(Wrap { trim: true });\n f.render_widget(paragraph, chunks[1]);\n }\n }\n\n let help = match app.step {\n SetupStep::EnvFile => \"Up/Down to move, Enter to select, Esc to cancel, q to cancel\",\n SetupStep::EnvTarget => \"Up/Down to move, Enter to select, Esc to back, q to cancel\",\n SetupStep::CustomEnv => \"Type name, Enter to confirm, Esc to back, q to cancel\",\n SetupStep::Keys => {\n \"Up/Down to move, Space to toggle, Enter to continue, Esc to back, q to cancel\"\n }\n SetupStep::Confirm => \"Space to toggle apply, Enter to finish, Esc to back, q to cancel\",\n };\n let footer = Paragraph::new(help)\n .block(Block::default().borders(Borders::ALL))\n .alignment(ratatui::layout::Alignment::Center);\n f.render_widget(footer, chunks[2]);\n}\n\nfn build_env_preview_lines(project_root: &Path, env_file: Option<&Path>) -> Vec<Line<'static>> {\n let mut lines = Vec::new();\n let Some(path) = env_file else {\n lines.push(Line::from(\"No env file selected.\"));\n lines.push(Line::from(\"Secrets will not be set.\"));\n return lines;\n };\n\n lines.push(Line::from(vec![\n Span::styled(\"File: \", Style::default().add_modifier(Modifier::BOLD)),\n Span::raw(relative_display(project_root, path)),\n ]));\n lines.push(Line::from(\"Values are hidden.\"));\n\n let content = match fs::read_to_string(path) {\n Ok(content) => content,\n Err(_) => {\n lines.push(Line::from(\"Unable to read file.\"));\n return lines;\n }\n };\n\n let vars = parse_env_file(&content);\n if vars.is_empty() {\n lines.push(Line::from(\"No env vars found.\"));\n return lines;\n }\n\n let mut entries: Vec<_> = vars.into_iter().collect();\n entries.sort_by(|a, b| a.0.cmp(&b.0));\n\n let suspect_count = entries\n .iter()\n .filter(|(_, value)| suspect_reason(value).is_some())\n .count();\n let total = entries.len();\n\n lines.push(Line::from(format!(\n \"Keys: {} (suspect: {})\",\n total, suspect_count\n )));\n lines.push(Line::from(\"! = likely test/local value\"));\n\n let max_keys = 12usize;\n for (key, value) in entries.iter().take(max_keys) {\n let flag = if suspect_reason(value).is_some() {\n \" !\"\n } else {\n \"\"\n };\n lines.push(Line::from(format!(\" - {}{}\", key, flag)));\n }\n\n if total > max_keys {\n lines.push(Line::from(format!(\"... +{} more\", total - max_keys)));\n }\n\n lines\n}\n\nfn build_key_detail_lines(\n project_root: &Path,\n env_file: Option<&Path>,\n item: Option<&EnvKeyItem>,\n) -> Vec<Line<'static>> {\n let mut lines = Vec::new();\n let env_label = env_file\n .map(|path| relative_display(project_root, path))\n .unwrap_or_else(|| \"none\".to_string());\n lines.push(Line::from(format!(\"Env file: {}\", env_label)));\n\n let Some(item) = item else {\n lines.push(Line::from(\"No key selected.\"));\n return lines;\n };\n\n lines.push(Line::from(format!(\"Key: {}\", item.key)));\n lines.push(Line::from(format!(\n \"Selected: {}\",\n if item.selected { \"yes\" } else { \"no\" }\n )));\n lines.push(Line::from(format!(\n \"Status: {}\",\n if item.suspect { \"suspect\" } else { \"ok\" }\n )));\n if let Some(reason) = &item.suspect_reason {\n lines.push(Line::from(format!(\"Reason: {}\", reason)));\n }\n lines.push(Line::from(format!(\"Value length: {}\", item.value_len)));\n lines.push(Line::from(\"Values are hidden.\"));\n if item.suspect {\n lines.push(Line::from(\"Tip: suspect values default to unchecked.\"));\n }\n\n lines\n}\n\nfn select_prev(selected: &mut usize, len: usize) {\n if len == 0 {\n return;\n }\n if *selected == 0 {\n *selected = len.saturating_sub(1);\n } else {\n *selected -= 1;\n }\n}\n\nfn select_next(selected: &mut usize, len: usize) {\n if len == 0 {\n return;\n }\n if *selected + 1 >= len {\n *selected = 0;\n } else {\n *selected += 1;\n }\n}\n\nfn step_back(app: &mut EnvSetupApp) -> bool {\n match app.step {\n SetupStep::EnvFile => true,\n SetupStep::EnvTarget => {\n app.step = SetupStep::EnvFile;\n false\n }\n SetupStep::CustomEnv => {\n app.step = SetupStep::EnvTarget;\n false\n }\n SetupStep::Keys => {\n app.step = SetupStep::EnvTarget;\n false\n }\n SetupStep::Confirm => {\n if app.env_file_path().is_some() && !app.key_items.is_empty() {\n app.step = SetupStep::Keys;\n } else {\n app.step = SetupStep::EnvTarget;\n }\n false\n }\n }\n}\n\nfn relative_display(root: &Path, path: &Path) -> String {\n if let Ok(rel) = path.strip_prefix(root) {\n let rel = rel.to_string_lossy().to_string();\n if rel.is_empty() { \".\".to_string() } else { rel }\n } else {\n path.to_string_lossy().to_string()\n }\n}\n\nfn build_env_file_choices(project_root: &Path, env_files: &[PathBuf]) -> Vec<EnvFileChoice> {\n let mut choices = Vec::new();\n choices.push(EnvFileChoice {\n label: \"Skip (do not set secrets)\".to_string(),\n path: None,\n });\n\n for path in env_files {\n choices.push(EnvFileChoice {\n label: relative_display(project_root, path),\n path: Some(path.clone()),\n });\n }\n\n choices\n}\n\nfn pick_default_env_file(\n project_root: &Path,\n choices: &[EnvFileChoice],\n preferred: Option<&PathBuf>,\n) -> usize {\n if let Some(path) = preferred {\n if let Some((idx, _)) = choices\n .iter()\n .enumerate()\n .find(|(_, c)| c.path.as_ref() == Some(path))\n {\n return idx;\n }\n }\n\n let candidates = [\n \".env\",\n \".env.production\",\n \".env.staging\",\n \".env.dev\",\n \".env.local\",\n ];\n for candidate in candidates {\n let candidate_path = project_root.join(candidate);\n if let Some((idx, _)) = choices\n .iter()\n .enumerate()\n .find(|(_, c)| c.path.as_ref() == Some(&candidate_path))\n {\n return idx;\n }\n }\n\n if choices.len() > 1 { 1 } else { 0 }\n}\n\nfn pick_default_env_target(targets: &[EnvTargetChoice], preferred: Option<&str>) -> usize {\n if let Some(env) = preferred {\n if let Some((idx, _)) = targets\n .iter()\n .enumerate()\n .find(|(_, choice)| choice.value.as_deref() == Some(env))\n {\n return idx;\n }\n }\n 0\n}\n\nfn build_key_items(path: &Path) -> Result<Vec<EnvKeyItem>> {\n let content = fs::read_to_string(path)\n .with_context(|| format!(\"failed to read env file {}\", path.display()))?;\n let env = parse_env_file(&content);\n let mut keys: Vec<_> = env.into_iter().collect();\n keys.sort_by(|a, b| a.0.cmp(&b.0));\n\n Ok(keys\n .into_iter()\n .map(|(key, value)| {\n let reason = suspect_reason(&value);\n let suspect = reason.is_some();\n EnvKeyItem {\n key,\n selected: !suspect,\n suspect: suspect || value.trim().is_empty(),\n suspect_reason: reason.map(|reason| reason.to_string()),\n value_len: value.len(),\n }\n })\n .collect())\n}\n\nfn suspect_reason(value: &str) -> Option<&'static str> {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n return Some(\"empty\");\n }\n\n let lowered = trimmed.to_lowercase();\n if lowered.contains(\"sk_test\") || lowered.contains(\"pk_test\") {\n return Some(\"stripe_test\");\n }\n if lowered.contains(\"localhost\") || lowered.contains(\"127.0.0.1\") {\n return Some(\"localhost\");\n }\n if lowered.contains(\"example.com\") || lowered.contains(\"example\") {\n return Some(\"example\");\n }\n if lowered.contains(\"dummy\") {\n return Some(\"dummy\");\n }\n if lowered.contains(\"test\") {\n return Some(\"test\");\n }\n\n None\n}\n\nfn infer_env_target_from_file(path: &Path) -> Option<String> {\n let name = path.file_name()?.to_string_lossy().to_lowercase();\n if name.contains(\"staging\") {\n return Some(\"staging\".to_string());\n }\n if name.contains(\"dev\") || name.contains(\"development\") {\n return Some(\"dev\".to_string());\n }\n if name.contains(\"prod\") || name.contains(\"production\") {\n return Some(\"production\".to_string());\n }\n None\n}\n\nfn discover_env_files(root: &Path) -> Result<Vec<PathBuf>> {\n let walker = WalkBuilder::new(root)\n .hidden(false)\n .git_ignore(false)\n .git_global(false)\n .git_exclude(false)\n .max_depth(Some(10))\n .filter_entry(|entry| {\n if entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {\n let name = entry.file_name().to_string_lossy();\n !matches!(\n name.as_ref(),\n \"node_modules\"\n | \"target\"\n | \"dist\"\n | \"build\"\n | \".git\"\n | \".hg\"\n | \".svn\"\n | \"__pycache__\"\n | \".pytest_cache\"\n | \".mypy_cache\"\n | \"venv\"\n | \".venv\"\n | \"vendor\"\n | \"Pods\"\n | \".cargo\"\n | \".rustup\"\n )\n } else {\n true\n }\n })\n .build();\n\n let mut env_files = Vec::new();\n for entry in walker.flatten() {\n if entry.file_type().map(|ft| ft.is_file()).unwrap_or(false) {\n if let Some(name) = entry.path().file_name().and_then(|s| s.to_str()) {\n if name.starts_with(\".env\") && name != \".envrc\" {\n env_files.push(entry.path().to_path_buf());\n }\n }\n }\n }\n\n env_files.sort();\n env_files.dedup();\n Ok(env_files)\n}\n" }, { "path": "src/explain_commits.rs", "content": "//! Explain commits via AI — generate markdown summaries for git commits.\n//!\n//! Used by `f explain-commits N` and as a post-sync hook to auto-explain\n//! new commits in tracked repos.\n\nuse std::collections::HashMap;\nuse std::fs;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\nuse chrono::Utc;\nuse serde::{Deserialize, Serialize};\nuse sha2::{Digest, Sha256};\n\nuse crate::cli::ExplainCommitsCommand;\nuse crate::config;\nuse crate::projects;\n\nconst DEFAULT_OUTPUT_DIR: &str = \"docs/commits\";\nconst DEFAULT_BATCH_SIZE: usize = 10;\nconst MAX_DIFF_CHARS: usize = 8000;\nconst AI_TASK_SCRIPT: &str = \"~/code/org/gen/new/ai/scripts/ai-task.sh\";\nconst DEFAULT_PROVIDER: &str = \"nvidia\";\nconst DEFAULT_MODEL: &str = \"moonshotai/kimi-k2.5\";\n\n// -- Index tracking --\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct CommitIndex {\n version: u32,\n commits: HashMap<String, CommitEntry>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct CommitEntry {\n digest: String,\n file: String,\n at: String,\n #[serde(default)]\n sha: String,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ExplainedCommit {\n pub sha: String,\n pub short_sha: String,\n pub subject: String,\n pub author: String,\n pub date: String,\n pub summary: String,\n pub changes: String,\n pub files: Vec<String>,\n pub markdown_file: String,\n pub generated_at: String,\n}\n\nimpl Default for CommitIndex {\n fn default() -> Self {\n Self {\n version: 1,\n commits: HashMap::new(),\n }\n }\n}\n\nfn index_path(output_dir: &Path) -> PathBuf {\n output_dir.join(\".index.json\")\n}\n\nfn load_index(output_dir: &Path) -> CommitIndex {\n let path = index_path(output_dir);\n if path.exists() {\n fs::read_to_string(&path)\n .ok()\n .and_then(|s| serde_json::from_str(&s).ok())\n .unwrap_or_default()\n } else {\n CommitIndex::default()\n }\n}\n\nfn save_index(output_dir: &Path, index: &CommitIndex) -> Result<()> {\n let path = index_path(output_dir);\n let json = serde_json::to_string_pretty(index)?;\n fs::write(&path, json).context(\"failed to write commit index\")?;\n Ok(())\n}\n\nfn compute_digest(sha: &str, message: &str, diff: &str) -> String {\n let mut hasher = Sha256::new();\n hasher.update(sha.as_bytes());\n hasher.update(b\"\\n\");\n hasher.update(message.as_bytes());\n hasher.update(b\"\\n\");\n hasher.update(diff.as_bytes());\n format!(\"{:x}\", hasher.finalize())\n}\n\n// -- Git helpers --\n\nfn git_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .context(\"failed to run git\")?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"git {} failed: {}\", args.join(\" \"), stderr.trim());\n }\n\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nstruct CommitInfo {\n sha: String,\n short_sha: String,\n message: String,\n subject: String,\n author: String,\n date: String,\n diff: String,\n files: Vec<String>,\n}\n\nfn get_commit_info(repo_root: &Path, sha: &str) -> Result<CommitInfo> {\n let short_sha = &sha[..7.min(sha.len())];\n let message = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%B\", sha])?\n .trim()\n .to_string();\n let subject = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%s\", sha])?\n .trim()\n .to_string();\n let author = git_capture_in(repo_root, &[\"log\", \"-1\", \"--format=%an\", sha])?\n .trim()\n .to_string();\n let raw_date = git_capture_in(\n repo_root,\n &[\"log\", \"-1\", \"--date=format:%Y-%m-%d\", \"--format=%ad\", sha],\n )?\n .trim()\n .to_string();\n let date = if raw_date.len() == 10\n && raw_date.as_bytes().get(4) == Some(&b'-')\n && raw_date.as_bytes().get(7) == Some(&b'-')\n {\n raw_date\n } else {\n Utc::now().format(\"%Y-%m-%d\").to_string()\n };\n\n let diff_full =\n git_capture_in(repo_root, &[\"diff\", &format!(\"{}~1\", sha), sha]).unwrap_or_default();\n let diff = if diff_full.len() > MAX_DIFF_CHARS {\n format!(\n \"{}\\n\\n... (truncated, {} total chars)\",\n &diff_full[..MAX_DIFF_CHARS],\n diff_full.len()\n )\n } else {\n diff_full\n };\n\n let files_raw = git_capture_in(\n repo_root,\n &[\"diff\", \"--name-only\", &format!(\"{}~1\", sha), sha],\n )\n .unwrap_or_default();\n let files: Vec<String> = files_raw\n .lines()\n .map(|l| l.trim().to_string())\n .filter(|l| !l.is_empty())\n .collect();\n\n Ok(CommitInfo {\n sha: sha.to_string(),\n short_sha: short_sha.to_string(),\n message,\n subject,\n author,\n date,\n diff,\n files,\n })\n}\n\nfn get_commits_in_range(repo_root: &Path, from: &str, to: &str) -> Result<Vec<String>> {\n let range = format!(\"{}..{}\", from, to);\n let output = git_capture_in(repo_root, &[\"rev-list\", \"--reverse\", &range])?;\n Ok(output\n .lines()\n .map(|l| l.trim().to_string())\n .filter(|l| !l.is_empty())\n .collect())\n}\n\nfn get_last_n_commits(repo_root: &Path, n: usize) -> Result<Vec<String>> {\n let n_str = format!(\"{}\", n);\n let output = git_capture_in(repo_root, &[\"rev-list\", \"--reverse\", \"-n\", &n_str, \"HEAD\"])?;\n Ok(output\n .lines()\n .map(|l| l.trim().to_string())\n .filter(|l| !l.is_empty())\n .collect())\n}\n\n// -- AI explanation --\n\nfn call_ai_explain(info: &CommitInfo, provider: &str, model: &str) -> Result<String> {\n let script = shellexpand::tilde(AI_TASK_SCRIPT).to_string();\n\n let prompt = format!(\n \"Explain this git commit concisely. Give a 1-2 sentence summary, then explain what changed and why.\\n\\n\\\n Commit: {}\\nMessage: {}\\n\\nDiff:\\n{}\",\n info.short_sha, info.message, info.diff\n );\n\n let output = Command::new(&script)\n .args([\n \"--agent\",\n \"explain\",\n \"--provider\",\n provider,\n \"--model\",\n model,\n \"--prompt\",\n &prompt,\n \"--max-steps\",\n \"5\",\n ])\n .output();\n\n match output {\n Ok(out) if out.status.success() => {\n let text = String::from_utf8_lossy(&out.stdout).trim().to_string();\n if text.is_empty() {\n Ok(\"(AI returned empty response)\".to_string())\n } else {\n Ok(text)\n }\n }\n Ok(out) => {\n let stderr = String::from_utf8_lossy(&out.stderr);\n bail!(\"ai-task.sh failed: {}\", stderr.trim());\n }\n Err(e) => {\n bail!(\"failed to run ai-task.sh: {e}\");\n }\n }\n}\n\n// -- Markdown output --\n\nfn slugify(s: &str) -> String {\n s.chars()\n .map(|c| {\n if c.is_alphanumeric() || c == '-' {\n c.to_ascii_lowercase()\n } else if c == ' ' || c == '_' || c == '/' {\n '-'\n } else {\n '\\0'\n }\n })\n .filter(|c| *c != '\\0')\n .collect::<String>()\n .split('-')\n .filter(|s| !s.is_empty())\n .collect::<Vec<_>>()\n .join(\"-\")\n}\n\nfn write_commit_markdown(\n output_dir: &Path,\n info: &CommitInfo,\n ai_explanation: &str,\n generated_at: &str,\n) -> Result<String> {\n let slug = slugify(&info.subject);\n let slug = if slug.len() > 60 {\n slug[..60].trim_end_matches('-').to_string()\n } else {\n slug\n };\n\n let filename = format!(\"{}-{}-{}.md\", info.date, info.short_sha, slug);\n let filepath = output_dir.join(&filename);\n\n // Parse AI explanation into summary and details\n let (summary, details) = split_ai_response(ai_explanation);\n\n let files_section = info\n .files\n .iter()\n .map(|f| format!(\"- {}\", f))\n .collect::<Vec<_>>()\n .join(\"\\n\");\n\n let content = format!(\n \"# {subject}\\n\\n\\\n **Commit**: `{sha}` | **Date**: {date} | **Author**: {author}\\n\\n\\\n ## Summary\\n{summary}\\n\\n\\\n ## Changes\\n{details}\\n\\n\\\n ## Files\\n{files}\\n\",\n subject = info.subject,\n sha = info.short_sha,\n date = info.date,\n author = info.author,\n summary = &summary,\n details = &details,\n files = files_section,\n );\n\n fs::write(&filepath, &content)\n .with_context(|| format!(\"failed to write {}\", filepath.display()))?;\n\n let sidecar_file = filename.replacen(\".md\", \".json\", 1);\n let sidecar_path = output_dir.join(&sidecar_file);\n let sidecar = ExplainedCommit {\n sha: info.sha.clone(),\n short_sha: info.short_sha.clone(),\n subject: info.subject.clone(),\n author: info.author.clone(),\n date: info.date.clone(),\n summary,\n changes: details,\n files: info.files.clone(),\n markdown_file: filename.clone(),\n generated_at: generated_at.to_string(),\n };\n let sidecar_json = serde_json::to_string_pretty(&sidecar)?;\n fs::write(&sidecar_path, sidecar_json)\n .with_context(|| format!(\"failed to write {}\", sidecar_path.display()))?;\n\n Ok(filename)\n}\n\nfn split_ai_response(text: &str) -> (String, String) {\n // Try to split on first blank line — first paragraph is summary, rest is details\n let trimmed = text.trim();\n if let Some(pos) = trimmed.find(\"\\n\\n\") {\n let summary = trimmed[..pos].trim().to_string();\n let details = trimmed[pos..].trim().to_string();\n (summary, details)\n } else {\n (trimmed.to_string(), trimmed.to_string())\n }\n}\n\nfn resolve_output_dir_name(repo_root: &Path, output_dir_override: Option<&Path>) -> String {\n if let Some(path) = output_dir_override {\n return path.display().to_string();\n }\n let cfg = load_explain_config(repo_root);\n cfg.as_ref()\n .and_then(|c| c.output_dir.clone())\n .unwrap_or_else(|| DEFAULT_OUTPUT_DIR.to_string())\n}\n\nfn resolve_output_dir(repo_root: &Path, output_dir_override: Option<&Path>) -> PathBuf {\n if let Some(path) = output_dir_override {\n if path.is_absolute() {\n return path.to_path_buf();\n }\n return repo_root.join(path);\n }\n repo_root.join(resolve_output_dir_name(repo_root, None))\n}\n\nfn resolve_explain_target(_repo_root: &Path) -> (String, String) {\n // Kimi is enforced for commit explanations to keep output quality predictable.\n (DEFAULT_PROVIDER.to_string(), DEFAULT_MODEL.to_string())\n}\n\nfn short_sha_from_sha(sha: &str) -> String {\n sha[..7.min(sha.len())].to_string()\n}\n\nfn short_sha_from_filename(file: &str) -> String {\n // Filename convention: YYYY-MM-DD-<short_sha>-<slug>.md\n if file.len() > 11 {\n let rest = &file[11..];\n if let Some(short_sha) = rest.split('-').next() {\n return short_sha.trim().to_string();\n }\n }\n String::new()\n}\n\nfn extract_markdown_section(content: &str, heading: &str) -> String {\n let marker = format!(\"## {heading}\");\n let Some(start) = content.find(&marker) else {\n return String::new();\n };\n let section_start = start + marker.len();\n let mut tail = &content[section_start..];\n if let Some(stripped) = tail.strip_prefix('\\n') {\n tail = stripped;\n }\n if let Some(stripped) = tail.strip_prefix('\\r') {\n tail = stripped;\n }\n if let Some(next) = tail.find(\"\\n## \") {\n tail[..next].trim().to_string()\n } else {\n tail.trim().to_string()\n }\n}\n\nfn parse_markdown_metadata(content: &str) -> (String, String, String, String) {\n let subject = content\n .lines()\n .find_map(|line| line.strip_prefix(\"# \").map(str::trim))\n .unwrap_or_default()\n .to_string();\n let mut sha = String::new();\n let mut date = String::new();\n let mut author = String::new();\n if let Some(meta) = content.lines().find(|line| line.starts_with(\"**Commit**:\")) {\n for part in meta.split('|').map(str::trim) {\n if part.starts_with(\"**Commit**:\") {\n sha = part\n .split('`')\n .nth(1)\n .unwrap_or_default()\n .trim()\n .to_string();\n } else if part.starts_with(\"**Date**:\") {\n date = part.trim_start_matches(\"**Date**:\").trim().to_string();\n } else if part.starts_with(\"**Author**:\") {\n author = part.trim_start_matches(\"**Author**:\").trim().to_string();\n }\n }\n }\n (subject, sha, date, author)\n}\n\nfn read_explained_commit(\n output_dir: &Path,\n short_sha_key: &str,\n entry: &CommitEntry,\n) -> Result<Option<ExplainedCommit>> {\n let sidecar_file = entry.file.replacen(\".md\", \".json\", 1);\n let sidecar_path = output_dir.join(&sidecar_file);\n if sidecar_path.exists() {\n let json = fs::read_to_string(&sidecar_path)\n .with_context(|| format!(\"failed to read {}\", sidecar_path.display()))?;\n let mut commit: ExplainedCommit = serde_json::from_str(&json)\n .with_context(|| format!(\"failed to parse {}\", sidecar_path.display()))?;\n if commit.markdown_file.is_empty() {\n commit.markdown_file = entry.file.clone();\n }\n if commit.generated_at.is_empty() {\n commit.generated_at = entry.at.clone();\n }\n if commit.short_sha.is_empty() {\n commit.short_sha = short_sha_key.to_string();\n }\n return Ok(Some(commit));\n }\n\n let markdown_path = output_dir.join(&entry.file);\n if !markdown_path.exists() {\n return Ok(None);\n }\n let content = fs::read_to_string(&markdown_path)\n .with_context(|| format!(\"failed to read {}\", markdown_path.display()))?;\n let (subject, parsed_sha, parsed_date, parsed_author) = parse_markdown_metadata(&content);\n let summary = extract_markdown_section(&content, \"Summary\");\n let changes = extract_markdown_section(&content, \"Changes\");\n let files = extract_markdown_section(&content, \"Files\")\n .lines()\n .map(str::trim)\n .filter_map(|line| line.strip_prefix(\"- \").map(str::to_string))\n .collect::<Vec<_>>();\n\n let short_sha = if !short_sha_key.is_empty() {\n short_sha_key.to_string()\n } else if !entry.sha.is_empty() {\n short_sha_from_sha(&entry.sha)\n } else {\n short_sha_from_filename(&entry.file)\n };\n let fallback_sha = if !entry.sha.is_empty() {\n entry.sha.clone()\n } else if !parsed_sha.is_empty() {\n parsed_sha.clone()\n } else {\n short_sha.clone()\n };\n\n Ok(Some(ExplainedCommit {\n sha: fallback_sha,\n short_sha,\n subject,\n author: parsed_author,\n date: parsed_date,\n summary,\n changes,\n files,\n markdown_file: entry.file.clone(),\n generated_at: entry.at.clone(),\n }))\n}\n\n// -- Core functions --\n\nfn load_explain_config(repo_root: &Path) -> Option<config::ExplainCommitsConfig> {\n let flow_toml = repo_root.join(\"flow.toml\");\n if !flow_toml.exists() {\n return None;\n }\n let cfg = config::load_or_default(&flow_toml);\n cfg.explain_commits\n}\n\nfn maybe_register_project(repo_root: &Path) {\n let flow_toml = repo_root.join(\"flow.toml\");\n if !flow_toml.exists() {\n return;\n }\n let cfg = config::load_or_default(&flow_toml);\n if let Some(name) = cfg.project_name.as_deref() {\n let _ = projects::register_project(name, &flow_toml);\n }\n}\n\n/// Read explained commits for a project, newest first.\npub fn list_explained_commits(\n repo_root: &Path,\n limit: Option<usize>,\n) -> Result<Vec<ExplainedCommit>> {\n let output_dir = resolve_output_dir(repo_root, None);\n if !output_dir.exists() {\n return Ok(Vec::new());\n }\n\n let index = load_index(&output_dir);\n let mut indexed_entries = index.commits.into_iter().collect::<Vec<_>>();\n indexed_entries.sort_by(|(_, left), (_, right)| right.at.cmp(&left.at));\n\n let mut commits = Vec::new();\n for (short_sha_key, entry) in indexed_entries {\n if let Some(commit) = read_explained_commit(&output_dir, &short_sha_key, &entry)? {\n commits.push(commit);\n if let Some(max_items) = limit\n && commits.len() >= max_items\n {\n break;\n }\n }\n }\n\n Ok(commits)\n}\n\n/// Read one explained commit by SHA (full or prefix).\npub fn get_explained_commit(repo_root: &Path, sha: &str) -> Result<Option<ExplainedCommit>> {\n let trimmed = sha.trim();\n if trimmed.is_empty() {\n return Ok(None);\n }\n let commits = list_explained_commits(repo_root, None)?;\n let mut prefix_match: Option<ExplainedCommit> = None;\n for commit in commits {\n if commit.sha.eq_ignore_ascii_case(trimmed)\n || commit.short_sha.eq_ignore_ascii_case(trimmed)\n {\n return Ok(Some(commit));\n }\n if commit.sha.starts_with(trimmed) || commit.short_sha.starts_with(trimmed) {\n if prefix_match.is_none() {\n prefix_match = Some(commit);\n } else {\n // Ambiguous prefix.\n return Ok(None);\n }\n }\n }\n Ok(prefix_match)\n}\n\n/// Explain new commits since `head_before` (used by post-sync hook).\npub fn explain_new_commits_since(repo_root: &Path, head_before: &str) -> Result<()> {\n let head_after = git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"])?\n .trim()\n .to_string();\n\n if head_before == head_after {\n return Ok(());\n }\n\n let cfg = load_explain_config(repo_root);\n let output_dir_name = resolve_output_dir_name(repo_root, None);\n let batch_size = cfg\n .as_ref()\n .and_then(|c| c.batch_size)\n .unwrap_or(DEFAULT_BATCH_SIZE);\n\n let output_dir = resolve_output_dir(repo_root, None);\n fs::create_dir_all(&output_dir)?;\n let (provider, model) = resolve_explain_target(repo_root);\n\n let commits = get_commits_in_range(repo_root, head_before, &head_after)?;\n if commits.is_empty() {\n return Ok(());\n }\n\n let to_process = if commits.len() > batch_size {\n println!(\n \" {} new commits, processing last {} (batch limit)\",\n commits.len(),\n batch_size\n );\n &commits[commits.len() - batch_size..]\n } else {\n &commits\n };\n\n let mut index = load_index(&output_dir);\n let mut explained = 0;\n\n for sha in to_process {\n let info = match get_commit_info(repo_root, sha) {\n Ok(info) => info,\n Err(e) => {\n eprintln!(\" warn: skipping {}: {e}\", &sha[..7.min(sha.len())]);\n continue;\n }\n };\n\n let digest = compute_digest(&info.sha, &info.message, &info.diff);\n\n // Skip if already processed with same digest\n if let Some(entry) = index.commits.get(&info.short_sha)\n && entry.digest == digest\n {\n continue;\n }\n\n println!(\" explaining {} {}\", info.short_sha, info.subject);\n\n let explanation = match call_ai_explain(&info, &provider, &model) {\n Ok(text) => text,\n Err(e) => {\n eprintln!(\" warn: AI failed for {}: {e}\", info.short_sha);\n continue;\n }\n };\n\n let generated_at = Utc::now().to_rfc3339();\n let filename = write_commit_markdown(&output_dir, &info, &explanation, &generated_at)?;\n\n index.commits.insert(\n info.short_sha.clone(),\n CommitEntry {\n digest,\n file: filename,\n at: generated_at,\n sha: info.sha,\n },\n );\n explained += 1;\n }\n\n if explained > 0 {\n save_index(&output_dir, &index)?;\n println!(\" explained {explained} commit(s) → {output_dir_name}/\");\n }\n\n Ok(())\n}\n\n/// Explain last N commits (CLI entry point).\npub fn explain_last_n_commits(\n repo_root: &Path,\n n: usize,\n force: bool,\n output_dir_override: Option<&Path>,\n) -> Result<()> {\n let output_dir_name = resolve_output_dir_name(repo_root, output_dir_override);\n let output_dir = resolve_output_dir(repo_root, output_dir_override);\n fs::create_dir_all(&output_dir)?;\n let (provider, model) = resolve_explain_target(repo_root);\n println!(\"using provider={provider} model={model}\");\n\n let commits = get_last_n_commits(repo_root, n)?;\n if commits.is_empty() {\n println!(\"No commits found.\");\n return Ok(());\n }\n\n let mut index = load_index(&output_dir);\n let mut explained = 0;\n let mut skipped = 0;\n\n for sha in &commits {\n let info = match get_commit_info(repo_root, sha) {\n Ok(info) => info,\n Err(e) => {\n eprintln!(\"warn: skipping {}: {e}\", &sha[..7.min(sha.len())]);\n continue;\n }\n };\n\n let digest = compute_digest(&info.sha, &info.message, &info.diff);\n\n // Skip if already processed with same digest (unless --force)\n if !force {\n if let Some(entry) = index.commits.get(&info.short_sha)\n && entry.digest == digest\n {\n skipped += 1;\n continue;\n }\n }\n\n println!(\"explaining {} {}\", info.short_sha, info.subject);\n\n let explanation = match call_ai_explain(&info, &provider, &model) {\n Ok(text) => text,\n Err(e) => {\n eprintln!(\"warn: AI failed for {}: {e}\", info.short_sha);\n continue;\n }\n };\n\n let generated_at = Utc::now().to_rfc3339();\n let filename = write_commit_markdown(&output_dir, &info, &explanation, &generated_at)?;\n\n index.commits.insert(\n info.short_sha.clone(),\n CommitEntry {\n digest,\n file: filename,\n at: generated_at,\n sha: info.sha,\n },\n );\n explained += 1;\n }\n\n save_index(&output_dir, &index)?;\n\n if explained > 0 {\n println!(\"explained {explained} commit(s) → {output_dir_name}/\");\n }\n if skipped > 0 {\n println!(\"skipped {skipped} already-processed commit(s)\");\n }\n if explained == 0 && skipped == 0 {\n println!(\"no commits to explain\");\n }\n\n Ok(())\n}\n\n/// Called after sync — checks config and explains new commits. Non-fatal.\npub fn maybe_run_after_sync(repo_root: &Path, head_before: &str) -> Result<()> {\n maybe_register_project(repo_root);\n let cfg = load_explain_config(repo_root);\n let enabled = cfg.as_ref().and_then(|c| c.enabled).unwrap_or(false);\n if !enabled {\n return Ok(());\n }\n explain_new_commits_since(repo_root, head_before)\n}\n\n/// CLI entry point for `f explain-commits`.\npub fn run_cli(cmd: ExplainCommitsCommand) -> Result<()> {\n let repo_root = std::env::current_dir()?;\n\n // Verify we're in a git repo\n git_capture_in(&repo_root, &[\"rev-parse\", \"--git-dir\"])?;\n maybe_register_project(&repo_root);\n\n let n = cmd.count.unwrap_or(1);\n explain_last_n_commits(&repo_root, n, cmd.force, cmd.out_dir.as_deref())\n}\n" }, { "path": "src/ext.rs", "content": "use std::fs;\nuse std::io::{self, IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::ExtCommand;\nuse crate::code;\nuse crate::config;\nuse crate::setup::add_gitignore_entry;\n\npub fn run(cmd: ExtCommand) -> Result<()> {\n let source = normalize_path(&cmd.path)?;\n if !source.exists() {\n bail!(\"Path not found: {}\", source.display());\n }\n if !source.is_dir() {\n bail!(\"Path must be a directory: {}\", source.display());\n }\n\n let project_root = project_root_from_cwd();\n let ext_dir = project_root.join(\"ext\");\n fs::create_dir_all(&ext_dir)?;\n\n let name = source\n .file_name()\n .and_then(|n| n.to_str())\n .map(|s| s.to_string())\n .filter(|s| !s.trim().is_empty())\n .unwrap_or_else(|| \"external\".to_string());\n\n let dest = ext_dir.join(&name);\n if dest.exists() {\n bail!(\"Destination already exists: {}\", dest.display());\n }\n\n let source_workspace = prepare_source_workspace(&source, &project_root)?;\n copy_dir_all(&source_workspace, &dest)?;\n add_gitignore_entry(&project_root, \"ext/\")?;\n if let Err(err) = code::migrate_sessions_between_paths(&source, &dest, false, false, false) {\n eprintln!(\"WARN failed to migrate sessions: {err}\");\n }\n\n println!(\n \"Copied {} -> {}\",\n source_workspace.display(),\n dest.display()\n );\n Ok(())\n}\n\nfn normalize_path(path: &str) -> Result<PathBuf> {\n let expanded = config::expand_path(path);\n let canonical = expanded.canonicalize().unwrap_or(expanded);\n Ok(canonical)\n}\n\nfn project_root_from_cwd() -> PathBuf {\n let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\"));\n let mut current = cwd.clone();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return current;\n }\n if !current.pop() {\n return cwd;\n }\n }\n}\n\nfn copy_dir_all(from: &Path, to: &Path) -> Result<()> {\n fs::create_dir_all(to).with_context(|| format!(\"failed to create {}\", to.display()))?;\n for entry in fs::read_dir(from).with_context(|| format!(\"failed to read {}\", from.display()))? {\n let entry = entry?;\n let path = entry.path();\n let file_type = entry.file_type()?;\n let target = to.join(entry.file_name());\n\n if target.exists() {\n bail!(\"Refusing to overwrite {}\", target.display());\n }\n\n if file_type.is_dir() {\n copy_dir_all(&path, &target)?;\n } else if file_type.is_file() {\n fs::copy(&path, &target)\n .with_context(|| format!(\"failed to copy {}\", path.display()))?;\n } else if file_type.is_symlink() {\n let link_target = fs::read_link(&path)\n .with_context(|| format!(\"failed to read link {}\", path.display()))?;\n copy_symlink(&link_target, &target)?;\n }\n }\n Ok(())\n}\n\nfn copy_symlink(target: &Path, dest: &Path) -> Result<()> {\n #[cfg(unix)]\n {\n std::os::unix::fs::symlink(target, dest)\n .with_context(|| format!(\"failed to create symlink {}\", dest.display()))?;\n return Ok(());\n }\n #[cfg(not(unix))]\n {\n let metadata =\n fs::metadata(target).with_context(|| format!(\"failed to read {}\", target.display()))?;\n if metadata.is_dir() {\n copy_dir_all(target, dest)?;\n } else {\n fs::copy(target, dest)\n .with_context(|| format!(\"failed to copy {}\", target.display()))?;\n }\n Ok(())\n }\n}\n\nfn prepare_source_workspace(source: &Path, project_root: &Path) -> Result<PathBuf> {\n let repo_root = match jj_root(source) {\n Ok(root) => root,\n Err(_) => {\n bail!(\n \"Source is not a jj workspace. Run `jj git init --colocate` in {} and retry.\",\n source.display()\n );\n }\n };\n\n let workspace = workspace_name_for_project(project_root)?;\n if workspace.is_empty() {\n return Ok(source.to_path_buf());\n }\n\n let status = git_capture_in(&repo_root, &[\"status\", \"--porcelain\"]).unwrap_or_default();\n if !status.trim().is_empty() {\n println!(\"Source repo has uncommitted changes:\");\n for line in status.lines().take(20) {\n println!(\" {line}\");\n }\n let continue_anyway = prompt_yes_no(\n &format!(\"Continue and use jj workspace \\\"{}\\\"?\", workspace),\n false,\n )?;\n if !continue_anyway {\n bail!(\"Aborted; commit or stash changes before continuing.\");\n }\n }\n\n let workspaces = jj_workspace_list(&repo_root).unwrap_or_default();\n if let Some(existing_path) = workspaces.get(&workspace) {\n return Ok(PathBuf::from(existing_path));\n }\n\n let base = workspace_base(&repo_root)?;\n fs::create_dir_all(&base).with_context(|| format!(\"failed to create {}\", base.display()))?;\n let workspace_path = base.join(&workspace);\n jj_run_in(\n &repo_root,\n &[\n \"workspace\",\n \"add\",\n workspace_path\n .to_str()\n .ok_or_else(|| anyhow::anyhow!(\"invalid workspace path\"))?,\n \"--name\",\n &workspace,\n ],\n )?;\n\n println!(\n \"Created jj workspace {} at {}\",\n workspace,\n workspace_path.display()\n );\n Ok(workspace_path)\n}\n\nfn workspace_name_for_project(project_root: &Path) -> Result<String> {\n let home = std::env::var(\"HOME\").ok();\n let mut relative = None;\n if let Some(home) = home.as_deref() {\n if let Ok(stripped) = project_root.strip_prefix(home) {\n relative = Some(stripped.to_path_buf());\n }\n }\n let name = if let Some(rel) = relative {\n rel.to_string_lossy().trim_start_matches('/').to_string()\n } else {\n project_root\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(\"external\")\n .to_string()\n };\n\n let mut sanitized = String::new();\n for ch in name.chars() {\n if ch.is_ascii_alphanumeric() || ch == '/' || ch == '.' || ch == '-' || ch == '_' {\n sanitized.push(ch);\n } else {\n sanitized.push('-');\n }\n }\n Ok(sanitized.trim_matches('/').to_string())\n}\n\nfn workspace_base(repo_root: &Path) -> Result<PathBuf> {\n let home = std::env::var(\"HOME\").context(\"HOME not set\")?;\n let repo_name = repo_root\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(\"repo\");\n Ok(PathBuf::from(home)\n .join(\".jj\")\n .join(\"workspaces\")\n .join(repo_name))\n}\n\nfn jj_root(source: &Path) -> Result<PathBuf> {\n let root = jj_capture_in(source, &[\"root\"])?;\n Ok(PathBuf::from(root.trim()))\n}\n\nfn jj_workspace_list(repo_root: &Path) -> Result<std::collections::HashMap<String, String>> {\n let output = jj_capture_in(repo_root, &[\"workspace\", \"list\"])?;\n let mut map = std::collections::HashMap::new();\n for line in output.lines() {\n let line = line.trim().trim_start_matches('*').trim();\n let Some((name, path)) = line.split_once(':') else {\n continue;\n };\n let name = name.trim().to_string();\n let path = path.trim().to_string();\n if !name.is_empty() && !path.is_empty() {\n map.insert(name, path);\n }\n }\n Ok(map)\n}\n\nfn jj_run_in(repo_root: &Path, args: &[&str]) -> Result<()> {\n let output = Command::new(\"jj\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run jj {}\", args.join(\" \")))?;\n let stdout = String::from_utf8_lossy(&output.stdout);\n if !stdout.trim().is_empty() {\n print!(\"{}\", stdout);\n }\n let stderr = String::from_utf8_lossy(&output.stderr);\n for line in stderr.lines() {\n if line.contains(\"Refused to snapshot\") {\n continue;\n }\n eprintln!(\"{}\", line);\n }\n if !output.status.success() {\n bail!(\"jj {} failed\", args.join(\" \"));\n }\n Ok(())\n}\n\nfn jj_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"jj\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run jj {}\", args.join(\" \")))?;\n if !output.status.success() {\n bail!(\"jj {} failed\", args.join(\" \"));\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nfn git_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n if !output.status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nfn prompt_yes_no(message: &str, default_yes: bool) -> Result<bool> {\n let prompt = if default_yes { \"[Y/n]\" } else { \"[y/N]\" };\n print!(\"{message} {prompt}: \");\n io::stdout().flush()?;\n if !io::stdin().is_terminal() {\n bail!(\"Non-interactive session; cannot confirm action.\");\n }\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n if answer.is_empty() {\n return Ok(default_yes);\n }\n Ok(answer == \"y\" || answer == \"yes\")\n}\n" }, { "path": "src/features.rs", "content": "//! Feature registry: read/write `.ai/features/*.md` files with YAML frontmatter.\n//!\n//! Features are committed project knowledge describing what capabilities exist,\n//! which files implement them, and whether they have docs/tests.\n\nuse anyhow::{Context, Result};\nuse std::collections::HashMap;\nuse std::path::{Path, PathBuf};\n\n/// Parsed feature file from `.ai/features/<name>.md`.\n#[derive(Debug, Clone)]\npub struct FeatureEntry {\n pub name: String,\n pub description: String,\n pub status: String,\n pub files: Vec<String>,\n pub tests: Vec<String>,\n pub coverage: String,\n pub added_in: String,\n pub last_verified: String,\n pub created_at: String,\n pub updated_at: String,\n /// Markdown body after the frontmatter.\n pub content: String,\n}\n\n/// A feature whose tracked files overlap with the current diff.\n#[derive(Debug)]\npub struct StaleFeature {\n pub name: String,\n pub stale_files: Vec<String>,\n}\n\n/// Return the `.ai/features/` directory for a project.\nfn features_dir(project_root: &Path) -> PathBuf {\n project_root.join(\".ai\").join(\"features\")\n}\n\n/// List all feature names in `.ai/features/`.\npub fn list_features(project_root: &Path) -> Result<Vec<String>> {\n let dir = features_dir(project_root);\n if !dir.exists() {\n return Ok(Vec::new());\n }\n let mut names = Vec::new();\n for entry in std::fs::read_dir(&dir).context(\"reading .ai/features/\")? {\n let entry = entry?;\n let path = entry.path();\n if path.extension().map_or(false, |e| e == \"md\") {\n if let Some(stem) = path.file_stem().and_then(|s| s.to_str()) {\n names.push(stem.to_string());\n }\n }\n }\n names.sort();\n Ok(names)\n}\n\n/// Load a single feature file and parse its YAML frontmatter.\npub fn load_feature(path: &Path) -> Result<FeatureEntry> {\n let raw = std::fs::read_to_string(path)\n .with_context(|| format!(\"reading feature file {}\", path.display()))?;\n parse_feature_file(&raw, path)\n}\n\n/// Load all features from `.ai/features/`.\npub fn load_all_features(project_root: &Path) -> Result<Vec<FeatureEntry>> {\n let dir = features_dir(project_root);\n if !dir.exists() {\n return Ok(Vec::new());\n }\n let mut features = Vec::new();\n for entry in std::fs::read_dir(&dir)? {\n let entry = entry?;\n let path = entry.path();\n if path.extension().map_or(false, |e| e == \"md\") {\n match load_feature(&path) {\n Ok(f) => features.push(f),\n Err(e) => eprintln!(\"warning: skipping {}: {}\", path.display(), e),\n }\n }\n }\n Ok(features)\n}\n\n/// Scan `.ai/features/` and identify which are stale relative to the current diff.\npub fn scan_features(project_root: &Path, changed_files: &[String]) -> Vec<StaleFeature> {\n let features = match load_all_features(project_root) {\n Ok(f) => f,\n Err(_) => return Vec::new(),\n };\n\n let changed_set: std::collections::HashSet<&str> =\n changed_files.iter().map(|s| s.as_str()).collect();\n\n let mut stale = Vec::new();\n for feat in &features {\n let overlap: Vec<String> = feat\n .files\n .iter()\n .filter(|f| changed_set.contains(f.as_str()))\n .cloned()\n .collect();\n if !overlap.is_empty() {\n stale.push(StaleFeature {\n name: feat.name.clone(),\n stale_files: overlap,\n });\n }\n }\n stale\n}\n\n/// Write/update a feature file with YAML frontmatter + markdown body.\npub fn save_feature(project_root: &Path, entry: &FeatureEntry) -> Result<()> {\n let dir = features_dir(project_root);\n std::fs::create_dir_all(&dir).context(\"creating .ai/features/\")?;\n\n let path = dir.join(format!(\"{}.md\", entry.name));\n let content = render_feature_file(entry);\n std::fs::write(&path, content)\n .with_context(|| format!(\"writing feature file {}\", path.display()))?;\n Ok(())\n}\n\n/// Update the `last_verified` field of an existing feature.\npub fn update_feature_verified(project_root: &Path, name: &str, commit_sha: &str) -> Result<()> {\n let path = features_dir(project_root).join(format!(\"{}.md\", name));\n if !path.exists() {\n return Ok(());\n }\n let mut entry = load_feature(&path)?;\n entry.last_verified = commit_sha.to_string();\n entry.updated_at = chrono_now();\n save_feature(project_root, &entry)\n}\n\n/// Update the test files list for an existing feature.\npub fn update_feature_tests(project_root: &Path, name: &str, test_files: &[String]) -> Result<()> {\n let path = features_dir(project_root).join(format!(\"{}.md\", name));\n if !path.exists() {\n return Ok(());\n }\n let mut entry = load_feature(&path)?;\n // Merge new test files\n for tf in test_files {\n if !entry.tests.contains(tf) {\n entry.tests.push(tf.clone());\n }\n }\n if !test_files.is_empty() && entry.coverage == \"none\" {\n entry.coverage = \"partial\".to_string();\n }\n entry.updated_at = chrono_now();\n save_feature(project_root, &entry)\n}\n\n/// Apply quality results from the AI review: create new feature docs, update existing ones.\n/// Returns a list of action descriptions (e.g., \"created foo.md\").\npub(crate) fn apply_quality_results(\n project_root: &Path,\n quality: &crate::commit::QualityResult,\n commit_sha: &str,\n) -> Result<Vec<String>> {\n let mut actions = Vec::new();\n let now = chrono_now();\n\n // 1. Write new feature docs\n for new_feat in &quality.new_features {\n let entry = FeatureEntry {\n name: new_feat.name.clone(),\n description: new_feat.description.clone(),\n status: \"active\".to_string(),\n files: new_feat.files.clone(),\n tests: Vec::new(),\n coverage: \"none\".to_string(),\n added_in: commit_sha.to_string(),\n last_verified: commit_sha.to_string(),\n created_at: now.clone(),\n updated_at: now.clone(),\n content: new_feat.doc_content.clone(),\n };\n save_feature(project_root, &entry)?;\n actions.push(format!(\"created {}.md\", new_feat.name));\n }\n\n // 2. Update last_verified for touched features that are current\n for touched in &quality.features_touched {\n if touched.doc_current {\n update_feature_verified(project_root, &touched.name, commit_sha)?;\n }\n if touched.has_tests {\n update_feature_tests(project_root, &touched.name, &touched.test_files)?;\n }\n }\n\n Ok(actions)\n}\n\n/// Build context about existing features for the AI review prompt.\npub fn features_context_for_review(project_root: &Path, changed_files: &[String]) -> String {\n let features = match load_all_features(project_root) {\n Ok(f) => f,\n Err(_) => return String::new(),\n };\n\n if features.is_empty() {\n return String::new();\n }\n\n let stale = scan_features(project_root, changed_files);\n let stale_names: std::collections::HashSet<&str> =\n stale.iter().map(|s| s.name.as_str()).collect();\n\n let mut ctx = String::from(\"\\nExisting documented features in .ai/features/:\\n\");\n for feat in &features {\n let stale_marker = if stale_names.contains(feat.name.as_str()) {\n \" [STALE - files changed in this diff]\"\n } else {\n \"\"\n };\n ctx.push_str(&format!(\n \"- {} ({}): {}{}\\n\",\n feat.name, feat.status, feat.description, stale_marker\n ));\n }\n ctx\n}\n\n// ── Internal helpers ────────────────────────────────────────────────\n\nfn chrono_now() -> String {\n // Simple ISO 8601 without chrono dependency\n let now = std::time::SystemTime::now()\n .duration_since(std::time::UNIX_EPOCH)\n .unwrap_or_default()\n .as_secs();\n // Format as basic ISO-ish timestamp\n format!(\"{}Z\", now)\n}\n\nfn parse_feature_file(raw: &str, path: &Path) -> Result<FeatureEntry> {\n // Split frontmatter from content\n let (frontmatter, body) = if raw.starts_with(\"---\\n\") || raw.starts_with(\"---\\r\\n\") {\n let after_open = if raw.starts_with(\"---\\r\\n\") { 5 } else { 4 };\n if let Some(end) = raw[after_open..].find(\"\\n---\") {\n let fm_end = after_open + end;\n let body_start = fm_end + 4; // skip \\n---\n let body_start = if raw[body_start..].starts_with('\\n') {\n body_start + 1\n } else if raw[body_start..].starts_with(\"\\r\\n\") {\n body_start + 2\n } else {\n body_start\n };\n (\n &raw[after_open..fm_end],\n raw[body_start..].trim().to_string(),\n )\n } else {\n (\"\", raw.to_string())\n }\n } else {\n (\"\", raw.to_string())\n };\n\n let fm = parse_yaml_frontmatter(frontmatter);\n let name = fm\n .get(\"name\")\n .cloned()\n .or_else(|| {\n path.file_stem()\n .and_then(|s| s.to_str())\n .map(|s| s.to_string())\n })\n .unwrap_or_default();\n\n Ok(FeatureEntry {\n name,\n description: fm.get(\"description\").cloned().unwrap_or_default(),\n status: fm\n .get(\"status\")\n .cloned()\n .unwrap_or_else(|| \"active\".to_string()),\n files: parse_yaml_list(fm.get(\"files\").map(|s| s.as_str()).unwrap_or(\"\")),\n tests: parse_yaml_list(fm.get(\"tests\").map(|s| s.as_str()).unwrap_or(\"\")),\n coverage: fm\n .get(\"coverage\")\n .cloned()\n .unwrap_or_else(|| \"none\".to_string()),\n added_in: fm.get(\"added_in\").cloned().unwrap_or_default(),\n last_verified: fm.get(\"last_verified\").cloned().unwrap_or_default(),\n created_at: fm.get(\"created_at\").cloned().unwrap_or_default(),\n updated_at: fm.get(\"updated_at\").cloned().unwrap_or_default(),\n content: body,\n })\n}\n\n/// Minimal YAML frontmatter parser for key: value pairs.\nfn parse_yaml_frontmatter(fm: &str) -> HashMap<String, String> {\n let mut map = HashMap::new();\n let mut current_key = String::new();\n let mut in_list = false;\n let mut list_items = Vec::new();\n\n for line in fm.lines() {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n continue;\n }\n\n // Check if this is a list item\n if trimmed.starts_with(\"- \") && in_list {\n let value = trimmed[2..].trim().to_string();\n list_items.push(value);\n continue;\n }\n\n // If we were building a list, save it\n if in_list && !list_items.is_empty() {\n map.insert(current_key.clone(), list_items.join(\"\\n\"));\n list_items.clear();\n in_list = false;\n }\n\n // Parse key: value\n if let Some(colon_pos) = trimmed.find(':') {\n let key = trimmed[..colon_pos].trim().to_string();\n let value = trimmed[colon_pos + 1..].trim().to_string();\n if value.is_empty() {\n // This might be the start of a list\n current_key = key;\n in_list = true;\n } else {\n map.insert(key, value);\n }\n }\n }\n\n // Save any trailing list\n if in_list && !list_items.is_empty() {\n map.insert(current_key, list_items.join(\"\\n\"));\n }\n\n map\n}\n\n/// Parse a YAML list stored as newline-separated values.\nfn parse_yaml_list(raw: &str) -> Vec<String> {\n if raw.is_empty() {\n return Vec::new();\n }\n raw.lines()\n .map(|l| l.trim().to_string())\n .filter(|l| !l.is_empty())\n .collect()\n}\n\nfn render_feature_file(entry: &FeatureEntry) -> String {\n let mut out = String::from(\"---\\n\");\n out.push_str(&format!(\"name: {}\\n\", entry.name));\n out.push_str(&format!(\"description: {}\\n\", entry.description));\n out.push_str(&format!(\"status: {}\\n\", entry.status));\n\n if !entry.files.is_empty() {\n out.push_str(\"files:\\n\");\n for f in &entry.files {\n out.push_str(&format!(\" - {}\\n\", f));\n }\n } else {\n out.push_str(\"files:\\n\");\n }\n\n if !entry.tests.is_empty() {\n out.push_str(\"tests:\\n\");\n for t in &entry.tests {\n out.push_str(&format!(\" - {}\\n\", t));\n }\n } else {\n out.push_str(\"tests:\\n\");\n }\n\n out.push_str(&format!(\"coverage: {}\\n\", entry.coverage));\n out.push_str(&format!(\"added_in: {}\\n\", entry.added_in));\n out.push_str(&format!(\"last_verified: {}\\n\", entry.last_verified));\n out.push_str(&format!(\"created_at: {}\\n\", entry.created_at));\n out.push_str(&format!(\"updated_at: {}\\n\", entry.updated_at));\n out.push_str(\"---\\n\\n\");\n out.push_str(&entry.content);\n if !entry.content.ends_with('\\n') {\n out.push('\\n');\n }\n out\n}\n" }, { "path": "src/fish_install.rs", "content": "use std::env;\nuse std::fs;\nuse std::io::{self, IsTerminal, Write};\nuse std::path::PathBuf;\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::FishInstallOpts;\nuse crate::fish_trace;\n\npub fn run(opts: FishInstallOpts) -> Result<()> {\n let bin_dir = opts.bin_dir.unwrap_or_else(default_bin_dir);\n let fish_bin = bin_dir.join(\"fish\");\n\n // Check if already installed\n if fish_bin.exists() && !opts.force {\n if is_traced_fish(&fish_bin)? {\n println!(\"Traced fish is already installed at {}\", fish_bin.display());\n println!(\"Use --force to reinstall.\");\n return Ok(());\n }\n if !opts.yes && !confirm_overwrite(&fish_bin)? {\n bail!(\"Aborted.\");\n }\n }\n\n // Find fish source\n let source = match opts.source {\n Some(path) => {\n if !path.join(\"Cargo.toml\").exists() {\n bail!(\n \"No Cargo.toml found at {}. Is this the fish-shell repo?\",\n path.display()\n );\n }\n path\n }\n None => {\n let Some(path) = fish_trace::fish_source_path() else {\n bail!(\n \"Could not find fish-shell source. Please specify --source or set FISH_SOURCE_PATH.\\n\\\n Clone from: https://github.com/fish-shell/fish-shell\"\n );\n };\n path\n }\n };\n\n println!(\"Building traced fish from {}\", source.display());\n\n // Confirm before building\n if !opts.yes && io::stdin().is_terminal() {\n println!();\n println!(\"This will:\");\n println!(\" 1. Build fish shell with release optimizations\");\n println!(\" 2. Install to {}\", fish_bin.display());\n println!(\" 3. Enable always-on I/O tracing (near-zero overhead)\");\n println!();\n if !confirm(\"Proceed?\")? {\n bail!(\"Aborted.\");\n }\n }\n\n // Build release\n println!(\"Running: cargo build --release --locked\");\n let status = Command::new(\"cargo\")\n .args([\"build\", \"--release\", \"--locked\"])\n .current_dir(&source)\n .status()\n .context(\"failed to run cargo build\")?;\n\n if !status.success() {\n bail!(\"cargo build failed\");\n }\n\n // Install\n let built_bin = source.join(\"target/release/fish\");\n if !built_bin.exists() {\n bail!(\"Built binary not found at {}\", built_bin.display());\n }\n\n fs::create_dir_all(&bin_dir)\n .with_context(|| format!(\"failed to create {}\", bin_dir.display()))?;\n\n fs::copy(&built_bin, &fish_bin)\n .with_context(|| format!(\"failed to copy to {}\", fish_bin.display()))?;\n\n #[cfg(unix)]\n {\n use std::os::unix::fs::PermissionsExt;\n let mut perms = fs::metadata(&fish_bin)?.permissions();\n perms.set_mode(0o755);\n fs::set_permissions(&fish_bin, perms)?;\n }\n\n println!();\n println!(\"Installed traced fish to {}\", fish_bin.display());\n println!();\n println!(\"To use it:\");\n println!(\" exec {}\", fish_bin.display());\n println!();\n println!(\"Or add {} to your PATH.\", bin_dir.display());\n println!();\n println!(\"I/O tracing is enabled by default. View traces with:\");\n println!(\" f fish-last # last command + output\");\n println!(\" f fish-last-full # full details\");\n println!(\" f last-cmd # (same as fish-last when traced fish is active)\");\n\n if !path_in_env(&bin_dir) {\n println!();\n println!(\"Note: {} is not in your PATH.\", bin_dir.display());\n println!(\"Add it with: fish_add_path {}\", bin_dir.display());\n }\n\n Ok(())\n}\n\nfn default_bin_dir() -> PathBuf {\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".local\")\n .join(\"bin\")\n}\n\nfn is_traced_fish(path: &PathBuf) -> Result<bool> {\n // Check if the fish binary has our tracing markers\n let output = Command::new(path)\n .args([\"-c\", \"echo $fish_io_trace\"])\n .output();\n\n // If it runs without error, it might be our fork\n // A more reliable check would be to look for specific version strings\n match output {\n Ok(out) => {\n // Our traced fish defaults to \"metadata\" mode\n let stdout = String::from_utf8_lossy(&out.stdout);\n // Check if fish_io_trace variable exists (it's set by default in our fork)\n Ok(stdout.trim() == \"metadata\" || stdout.contains(\"metadata\"))\n }\n Err(_) => Ok(false),\n }\n}\n\nfn confirm_overwrite(path: &PathBuf) -> Result<bool> {\n if !io::stdin().is_terminal() {\n return Ok(false);\n }\n print!(\"{} already exists. Overwrite? [y/N]: \", path.display());\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n Ok(answer == \"y\" || answer == \"yes\")\n}\n\nfn confirm(msg: &str) -> Result<bool> {\n if !io::stdin().is_terminal() {\n return Ok(true);\n }\n print!(\"{} [y/N]: \", msg);\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n Ok(answer == \"y\" || answer == \"yes\")\n}\n\nfn path_in_env(bin_dir: &PathBuf) -> bool {\n let Ok(path) = env::var(\"PATH\") else {\n return false;\n };\n env::split_paths(&path).any(|entry| entry == *bin_dir)\n}\n" }, { "path": "src/fish_trace.rs", "content": "use std::env;\nuse std::fs;\nuse std::path::{Path, PathBuf};\nuse std::time::{Duration, UNIX_EPOCH};\n\nuse anyhow::{Context, Result};\n\n/// Fish shell trace record from io-trace metadata\n#[derive(Debug, Clone)]\npub struct FishTraceRecord {\n pub version: u32,\n pub timestamp_secs: u64,\n pub job_id: u64,\n pub cwd: String,\n pub cmd: String,\n pub status: i32,\n pub pipestatus: Vec<i32>,\n pub stdout_len: usize,\n pub stderr_len: usize,\n pub stdout_truncated: bool,\n pub stderr_truncated: bool,\n}\n\nimpl FishTraceRecord {\n pub fn timestamp_ms(&self) -> u64 {\n self.timestamp_secs * 1000\n }\n\n pub fn formatted_time(&self) -> String {\n let system_time = UNIX_EPOCH + Duration::from_secs(self.timestamp_secs);\n let dt: chrono::DateTime<chrono::Local> = system_time.into();\n dt.format(\"%H:%M:%S\").to_string()\n }\n\n pub fn success(&self) -> bool {\n self.status == 0\n }\n}\n\n/// Get the fish io-trace directory\npub fn io_trace_dir() -> PathBuf {\n if let Ok(path) = env::var(\"FISH_IO_TRACE_DIR\") {\n return PathBuf::from(path);\n }\n let data_home = env::var(\"XDG_DATA_HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|_| {\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".local\")\n .join(\"share\")\n });\n data_home.join(\"fish\").join(\"io-trace\")\n}\n\n/// Load the last fish trace record\npub fn load_last_record() -> Result<Option<FishTraceRecord>> {\n let dir = io_trace_dir();\n let meta_path = dir.join(\"last.meta\");\n if !meta_path.exists() {\n return Ok(None);\n }\n parse_meta_file(&meta_path)\n}\n\n/// Load stdout from last fish trace\npub fn load_last_stdout() -> Result<Option<String>> {\n let dir = io_trace_dir();\n let path = dir.join(\"last.stdout\");\n if !path.exists() {\n return Ok(None);\n }\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n Ok(Some(content))\n}\n\n/// Load stderr from last fish trace\npub fn load_last_stderr() -> Result<Option<String>> {\n let dir = io_trace_dir();\n let path = dir.join(\"last.stderr\");\n if !path.exists() {\n return Ok(None);\n }\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n Ok(Some(content))\n}\n\nfn parse_meta_file(path: &Path) -> Result<Option<FishTraceRecord>> {\n let content =\n fs::read_to_string(path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n\n let mut record = FishTraceRecord {\n version: 1,\n timestamp_secs: 0,\n job_id: 0,\n cwd: String::new(),\n cmd: String::new(),\n status: 0,\n pipestatus: vec![],\n stdout_len: 0,\n stderr_len: 0,\n stdout_truncated: false,\n stderr_truncated: false,\n };\n\n for line in content.lines() {\n let line = line.trim();\n if line.is_empty() {\n continue;\n }\n let Some((key, value)) = line.split_once('=') else {\n continue;\n };\n match key {\n \"version\" => record.version = value.parse().unwrap_or(1),\n \"timestamp_secs\" => record.timestamp_secs = value.parse().unwrap_or(0),\n \"job_id\" => record.job_id = value.parse().unwrap_or(0),\n \"cwd\" => record.cwd = value.to_string(),\n \"cmd\" => {\n // Remove surrounding quotes if present\n let v = value.trim();\n if v.starts_with('\"') && v.ends_with('\"') && v.len() > 1 {\n record.cmd = v[1..v.len() - 1].to_string();\n } else {\n record.cmd = v.to_string();\n }\n }\n \"status\" => record.status = value.parse().unwrap_or(0),\n \"pipestatus\" => {\n record.pipestatus = value\n .split(',')\n .filter_map(|s| s.trim().parse().ok())\n .collect();\n }\n \"stdout_len\" => record.stdout_len = value.parse().unwrap_or(0),\n \"stderr_len\" => record.stderr_len = value.parse().unwrap_or(0),\n \"stdout_truncated\" => record.stdout_truncated = value != \"0\",\n \"stderr_truncated\" => record.stderr_truncated = value != \"0\",\n _ => {}\n }\n }\n\n if record.timestamp_secs == 0 {\n return Ok(None);\n }\n\n Ok(Some(record))\n}\n\n/// Print the last fish shell command and its output (like `trail last`)\npub fn print_last_fish_cmd() -> Result<()> {\n let Some(record) = load_last_record()? else {\n println!(\"No fish trace found at {}\", io_trace_dir().display());\n return Ok(());\n };\n\n println!(\"{}\", record.cmd);\n\n let stdout = load_last_stdout()?.unwrap_or_default();\n let stderr = load_last_stderr()?.unwrap_or_default();\n\n if !stdout.is_empty() {\n print!(\"{stdout}\");\n if !stdout.ends_with('\\n') {\n println!();\n }\n }\n\n if !stderr.is_empty() {\n eprint!(\"{stderr}\");\n if !stderr.ends_with('\\n') {\n eprintln!();\n }\n }\n\n if stdout.is_empty() && stderr.is_empty() && !record.success() {\n println!(\"(exit status: {})\", record.status);\n }\n\n Ok(())\n}\n\n/// Print full details of the last fish shell command\npub fn print_last_fish_cmd_full() -> Result<()> {\n let Some(record) = load_last_record()? else {\n println!(\"No fish trace found at {}\", io_trace_dir().display());\n return Ok(());\n };\n\n println!(\"cmd: {}\", record.cmd);\n println!(\"cwd: {}\", record.cwd);\n println!(\"job_id: {}\", record.job_id);\n println!(\"timestamp: {}\", record.formatted_time());\n println!(\n \"status: {} (code: {})\",\n if record.success() {\n \"success\"\n } else {\n \"failure\"\n },\n record.status\n );\n if !record.pipestatus.is_empty() {\n let ps: Vec<String> = record.pipestatus.iter().map(|s| s.to_string()).collect();\n println!(\"pipestatus: {}\", ps.join(\",\"));\n }\n println!(\n \"stdout: {} bytes{}\",\n record.stdout_len,\n if record.stdout_truncated {\n \" (truncated)\"\n } else {\n \"\"\n }\n );\n println!(\n \"stderr: {} bytes{}\",\n record.stderr_len,\n if record.stderr_truncated {\n \" (truncated)\"\n } else {\n \"\"\n }\n );\n\n let stdout = load_last_stdout()?.unwrap_or_default();\n let stderr = load_last_stderr()?.unwrap_or_default();\n\n if !stdout.is_empty() || !stderr.is_empty() {\n println!(\"--- output ---\");\n }\n if !stdout.is_empty() {\n print!(\"{stdout}\");\n if !stdout.ends_with('\\n') {\n println!();\n }\n }\n if !stderr.is_empty() {\n eprintln!(\"--- stderr ---\");\n eprint!(\"{stderr}\");\n }\n\n Ok(())\n}\n\n/// Check if traced fish shell is installed\npub fn is_traced_fish_installed() -> bool {\n let bin_path = traced_fish_bin_path();\n bin_path.exists()\n}\n\n/// Get the path to the traced fish binary\npub fn traced_fish_bin_path() -> PathBuf {\n if let Ok(path) = env::var(\"FISH_TRACED_BIN\") {\n return PathBuf::from(path);\n }\n dirs::home_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".local\")\n .join(\"bin\")\n .join(\"fish\")\n}\n\n/// Get the path to fish-shell source repo (for building)\npub fn fish_source_path() -> Option<PathBuf> {\n // Check env var first\n if let Ok(path) = env::var(\"FISH_SOURCE_PATH\") {\n let p = PathBuf::from(path);\n if p.exists() {\n return Some(p);\n }\n }\n\n // Check common locations\n let home = dirs::home_dir()?;\n let candidates = [\n home.join(\"repos/fish-shell/fish-shell\"),\n home.join(\"code/fish-shell\"),\n home.join(\".local/src/fish-shell\"),\n ];\n\n for candidate in candidates {\n if candidate.join(\"Cargo.toml\").exists() {\n return Some(candidate);\n }\n }\n\n None\n}\n" }, { "path": "src/fix.rs", "content": "use std::fs;\nuse std::io::{self, IsTerminal, Read, Write};\nuse std::path::PathBuf;\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::FixOpts;\nuse crate::opentui_prompt;\n\npub fn run(opts: FixOpts) -> Result<()> {\n let message = resolve_fix_message(&opts.message)?;\n\n let repo_root = git_top_level()?;\n if try_run_commit_repair(&repo_root, &message)? {\n return Ok(());\n }\n\n let unroll = !opts.no_unroll;\n let mut stashed = false;\n\n if unroll {\n ensure_clean_or_stash(&repo_root, opts.stash, &mut stashed)?;\n ensure_has_parent_commit(&repo_root)?;\n let head = git_output(&repo_root, &[\"rev-parse\", \"HEAD\"])?;\n let head_short = head.trim().chars().take(7).collect::<String>();\n println!(\"Unrolling last commit ({head_short})...\");\n git_status(&repo_root, &[\"reset\", \"--soft\", \"HEAD~1\"])?;\n }\n\n if !opts.no_agent {\n run_fix_agent(&repo_root, &opts.agent, &message)?;\n } else {\n println!(\"Skipped fix agent (use without --no-agent to run Hive).\");\n }\n\n if stashed {\n println!(\"Restoring stashed changes...\");\n let _ = git_status(&repo_root, &[\"stash\", \"pop\"]);\n }\n\n Ok(())\n}\n\nfn resolve_fix_message(parts: &[String]) -> Result<String> {\n let joined = parts.join(\" \").trim().to_string();\n if joined.is_empty() {\n bail!(\"provide a fix message, e.g. `f fix last commit had spotify api leaked`\");\n }\n\n let Some(path) = detect_fix_input_file(parts) else {\n return Ok(joined);\n };\n\n let content = fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read fix input file {}\", path.display()))?;\n let trimmed = content.trim();\n if trimmed.is_empty() {\n bail!(\"fix input file is empty: {}\", path.display());\n }\n\n println!(\"Loaded fix context from {}\", path.display());\n Ok(format!(\n \"Use this report as the source of truth for what to fix.\\n\\nReport file: {}\\n\\n{}\",\n path.display(),\n trimmed\n ))\n}\n\nfn detect_fix_input_file(parts: &[String]) -> Option<PathBuf> {\n if parts.len() != 1 {\n return None;\n }\n let raw = parts[0].trim();\n if raw.is_empty() {\n return None;\n }\n let candidate = raw.strip_prefix('@').unwrap_or(raw);\n let path = PathBuf::from(candidate);\n if !path.is_file() {\n return None;\n }\n Some(path.canonicalize().unwrap_or(path))\n}\n\nfn try_run_commit_repair(repo_root: &std::path::Path, message: &str) -> Result<bool> {\n if !matches_recommit_request(message) {\n return Ok(false);\n }\n\n let status = git_output(repo_root, &[\"status\", \"--porcelain\"])?;\n if !status.trim().is_empty() {\n let lines = vec![\n \"Working tree has uncommitted changes that will be included in the new commit.\"\n .to_string(),\n ];\n if !confirm_with_tui(\"Re-commit\", &lines, \"Continue with re-commit? [Y/n]: \")? {\n bail!(\"Aborted.\");\n }\n }\n\n let plan_lines = vec![\n \"Plan:\".to_string(),\n \" 1) git reset --soft HEAD~1 (undo last commit, keep changes staged)\".to_string(),\n \" 2) f commit (recreate commit with updated hygiene)\".to_string(),\n ];\n if !confirm_with_tui(\"Re-commit\", &plan_lines, \"Proceed? [Y/n]: \")? {\n bail!(\"Aborted.\");\n }\n\n git_status(repo_root, &[\"reset\", \"--soft\", \"HEAD~1\"])?;\n let status = Command::new(\"f\")\n .arg(\"commit\")\n .current_dir(repo_root)\n .status()\n .context(\"failed to run f commit\")?;\n if !status.success() {\n bail!(\"f commit failed with status {}\", status);\n }\n\n Ok(true)\n}\n\nfn confirm_with_tui(title: &str, lines: &[String], prompt: &str) -> Result<bool> {\n if let Some(answer) = opentui_prompt::confirm(title, lines, true) {\n return Ok(answer);\n }\n\n if !lines.is_empty() {\n for line in lines {\n println!(\"{}\", line);\n }\n }\n\n confirm_default_yes(prompt)\n}\n\nfn matches_recommit_request(message: &str) -> bool {\n let lowered = message.to_ascii_lowercase();\n let undo = lowered.contains(\"undo last commit\")\n || lowered.contains(\"undo the last commit\")\n || lowered.contains(\"reset last commit\")\n || lowered.contains(\"reset the last commit\")\n || lowered.contains(\"recommit\");\n let rerun = lowered.contains(\"run f commit\")\n || lowered.contains(\"rerun f commit\")\n || lowered.contains(\"run f commit again\")\n || lowered.contains(\"re-run f commit\")\n || lowered.contains(\"recommit and run f commit\");\n undo && rerun\n}\n\nfn confirm_default_yes(prompt: &str) -> Result<bool> {\n print!(\"{}\", prompt);\n io::stdout().flush()?;\n\n if std::io::stdin().is_terminal() {\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n return Ok(true);\n }\n return Ok(matches!(trimmed.to_ascii_lowercase().as_str(), \"y\" | \"yes\"));\n }\n\n let mut input = String::new();\n io::stdin().read_to_string(&mut input)?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n return Ok(true);\n }\n Ok(matches!(trimmed.to_ascii_lowercase().as_str(), \"y\" | \"yes\"))\n}\n\nfn run_fix_agent(repo_root: &std::path::Path, agent: &str, message: &str) -> Result<()> {\n if which::which(\"hive\").is_err() {\n bail!(\"hive not found in PATH. Install it or add it to PATH to run fix agent.\");\n }\n\n let task = format!(\n \"Fix this repo. Task: {message}\\n\\n\\\nIf the issue involves leaked secrets, remove them from tracked files, \\\nupdate .gitignore if needed, and ensure the repo is safe to recommit.\"\n );\n\n let status = Command::new(\"hive\")\n .args([\"agent\", agent, &task])\n .current_dir(repo_root)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run hive agent\")?;\n\n if !status.success() {\n bail!(\"hive agent failed\");\n }\n\n Ok(())\n}\n\nfn git_top_level() -> Result<std::path::PathBuf> {\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"--show-toplevel\"])\n .output()\n .context(\"failed to run git\")?;\n if !output.status.success() {\n bail!(\"not a git repository (or git not available)\");\n }\n let root = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if root.is_empty() {\n bail!(\"failed to resolve git repository root\");\n }\n Ok(std::path::PathBuf::from(root))\n}\n\nfn ensure_clean_or_stash(\n repo_root: &std::path::Path,\n allow_stash: bool,\n stashed: &mut bool,\n) -> Result<()> {\n let status = git_output(repo_root, &[\"status\", \"--porcelain\"])?;\n if status.trim().is_empty() {\n return Ok(());\n }\n\n if !allow_stash {\n bail!(\"working tree has uncommitted changes; commit/stash them or rerun with --stash\");\n }\n\n println!(\"Stashing local changes...\");\n git_status(\n repo_root,\n &[\"stash\", \"push\", \"-u\", \"-m\", \"f fix auto-stash\"],\n )?;\n *stashed = true;\n Ok(())\n}\n\nfn ensure_has_parent_commit(repo_root: &std::path::Path) -> Result<()> {\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"HEAD~1\"])\n .current_dir(repo_root)\n .output()\n .context(\"failed to check git history\")?;\n if !output.status.success() {\n bail!(\"cannot unroll: repository has no parent commit\");\n }\n Ok(())\n}\n\nfn git_output(repo_root: &std::path::Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"git\")\n .args(args)\n .current_dir(repo_root)\n .output()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"git {} failed: {}\", args.join(\" \"), stderr.trim());\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nfn git_status(repo_root: &std::path::Path, args: &[&str]) -> Result<()> {\n let status = Command::new(\"git\")\n .args(args)\n .current_dir(repo_root)\n .status()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n if !status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n Ok(())\n}\n" }, { "path": "src/fixup.rs", "content": "//! Fix common TOML syntax errors in flow.toml files.\n//!\n//! Common issues that AI tools create:\n//! - `\\$` escape sequences (invalid in TOML basic strings)\n//! - `\\n` literal in basic strings instead of actual newlines\n//! - Unclosed multi-line strings\n\nuse std::fs;\n\nuse anyhow::{Context, Result};\nuse regex::Regex;\n\nuse crate::cli::FixupOpts;\n\n/// Result of a fixup operation.\n#[derive(Debug)]\npub struct FixupResult {\n pub fixes_applied: Vec<FixupAction>,\n pub had_errors: bool,\n}\n\n#[derive(Debug)]\npub struct FixupAction {\n pub line: usize,\n pub description: String,\n pub before: String,\n pub after: String,\n}\n\npub fn run(opts: FixupOpts) -> Result<()> {\n let config_path = if opts.config.is_absolute() {\n opts.config.clone()\n } else {\n std::env::current_dir()?.join(&opts.config)\n };\n\n if !config_path.exists() {\n anyhow::bail!(\"flow.toml not found at {}\", config_path.display());\n }\n\n let content = fs::read_to_string(&config_path)\n .with_context(|| format!(\"failed to read {}\", config_path.display()))?;\n\n let result = fix_toml_content(&content);\n\n if result.fixes_applied.is_empty() {\n println!(\"✓ No issues found in {}\", config_path.display());\n return Ok(());\n }\n\n println!(\n \"Found {} issue(s) in {}:\\n\",\n result.fixes_applied.len(),\n config_path.display()\n );\n\n for fix in &result.fixes_applied {\n println!(\" Line {}: {}\", fix.line, fix.description);\n println!(\" - {}\", truncate_for_display(&fix.before, 60));\n println!(\" + {}\", truncate_for_display(&fix.after, 60));\n println!();\n }\n\n if opts.dry_run {\n println!(\"Dry run - no changes written.\");\n return Ok(());\n }\n\n // Apply fixes\n let fixed_content = apply_fixes(&content, &result.fixes_applied);\n\n // Validate the fixed content parses\n if let Err(e) = toml::from_str::<toml::Value>(&fixed_content) {\n println!(\"⚠ Warning: Fixed content still has TOML errors: {}\", e);\n println!(\"Writing anyway - manual review recommended.\");\n }\n\n fs::write(&config_path, &fixed_content)\n .with_context(|| format!(\"failed to write {}\", config_path.display()))?;\n\n println!(\n \"✓ Fixed {} issue(s) in {}\",\n result.fixes_applied.len(),\n config_path.display()\n );\n\n Ok(())\n}\n\n/// Fix common TOML issues in the content.\npub fn fix_toml_content(content: &str) -> FixupResult {\n let mut fixes = Vec::new();\n let lines: Vec<&str> = content.lines().collect();\n\n // Track if we're inside a multi-line basic string (\"\"\")\n let mut in_multiline_basic = false;\n let mut _multiline_start_line = 0;\n\n for (line_idx, line) in lines.iter().enumerate() {\n let line_num = line_idx + 1;\n\n // Count triple quotes to track multi-line string state\n let triple_quote_count = line.matches(r#\"\"\"\"\"#).count();\n\n if !in_multiline_basic {\n // Check for start of multi-line basic string\n if triple_quote_count == 1 {\n in_multiline_basic = true;\n _multiline_start_line = line_num;\n } else if triple_quote_count == 2 {\n // Single-line multi-line string (opens and closes on same line)\n // Check for issues in this line\n if let Some(fix) = check_invalid_escapes(line, line_num) {\n fixes.push(fix);\n }\n }\n } else {\n // Inside multi-line basic string\n if triple_quote_count >= 1 {\n // End of multi-line string\n in_multiline_basic = false;\n }\n\n // Check for invalid escape sequences inside multi-line basic strings\n if let Some(fix) = check_invalid_escapes(line, line_num) {\n fixes.push(fix);\n }\n }\n }\n\n FixupResult {\n fixes_applied: fixes,\n had_errors: false,\n }\n}\n\n/// Apply fixes to TOML content and return the updated string.\npub fn apply_fixes_to_content(content: &str, fixes: &[FixupAction]) -> String {\n apply_fixes(content, fixes)\n}\n\n/// Check a line for invalid escape sequences in TOML basic strings.\nfn check_invalid_escapes(line: &str, line_num: usize) -> Option<FixupAction> {\n // Invalid escapes in TOML basic strings: \\$ \\: \\@ \\! etc.\n // Valid escapes: \\\\ \\n \\t \\r \\\" \\b \\f \\uXXXX \\UXXXXXXXX and \\ followed by newline\n // We need to find backslash followed by characters that are NOT valid escape chars\n let invalid_escape_re = Regex::new(r#\"\\\\([^\\\\nrtbf\"uU\\s])\"#).unwrap();\n\n if let Some(capture) = invalid_escape_re.find(line) {\n let escaped_char = &line[capture.start() + 1..capture.end()];\n let fixed_line = invalid_escape_re\n .replace_all(line, |caps: ®ex::Captures| {\n // Just remove the backslash, keep the character\n caps[1].to_string()\n })\n .to_string();\n\n return Some(FixupAction {\n line: line_num,\n description: format!(\"Invalid escape sequence '\\\\{}'\", escaped_char),\n before: line.to_string(),\n after: fixed_line,\n });\n }\n\n None\n}\n\n/// Apply fixes to content, returning the fixed string.\nfn apply_fixes(content: &str, fixes: &[FixupAction]) -> String {\n let lines: Vec<&str> = content.lines().collect();\n let mut result_lines: Vec<String> = lines.iter().map(|s| s.to_string()).collect();\n\n for fix in fixes {\n if fix.line > 0 && fix.line <= result_lines.len() {\n result_lines[fix.line - 1] = fix.after.clone();\n }\n }\n\n // Preserve original line endings\n let has_trailing_newline = content.ends_with('\\n');\n let mut result = result_lines.join(\"\\n\");\n if has_trailing_newline {\n result.push('\\n');\n }\n\n result\n}\n\nfn truncate_for_display(s: &str, max_len: usize) -> String {\n if s.len() <= max_len {\n s.to_string()\n } else {\n // Find valid UTF-8 char boundary\n let mut end = max_len.min(s.len());\n while end > 0 && !s.is_char_boundary(end) {\n end -= 1;\n }\n format!(\"{}...\", &s[..end])\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn fixes_escaped_dollar() {\n let content = r##\"\n[[tasks]]\nname = \"test\"\ncommand = \"\"\"\necho \"Price: \\$8\"\n\"\"\"\n\"##;\n let result = fix_toml_content(content);\n assert_eq!(result.fixes_applied.len(), 1);\n assert!(result.fixes_applied[0].description.contains(r\"\\$\"));\n }\n\n #[test]\n fn preserves_valid_escapes() {\n let content = r##\"\n[[tasks]]\nname = \"test\"\ncommand = \"\"\"\necho \"Line1\"\necho \"Tab here\"\n\"\"\"\n\"##;\n let result = fix_toml_content(content);\n assert!(result.fixes_applied.is_empty());\n }\n\n #[test]\n fn no_fixes_needed() {\n let content = r#\"\n[[tasks]]\nname = \"test\"\ncommand = \"echo hello\"\n\"#;\n let result = fix_toml_content(content);\n assert!(result.fixes_applied.is_empty());\n }\n}\n" }, { "path": "src/flox.rs", "content": "use std::{\n collections::BTreeMap,\n fs,\n path::{Path, PathBuf},\n process::{Command, Stdio},\n};\n\nuse anyhow::{Context, Result, bail};\nuse serde::Serialize;\n\nuse crate::config::FloxInstallSpec;\n\nconst MANIFEST_VERSION: u8 = 1;\nconst ENV_VERSION: u8 = 1;\n\n/// Paths needed to invoke `flox activate` for a generated manifest.\n#[derive(Clone, Debug)]\npub struct FloxEnv {\n pub project_root: PathBuf,\n pub manifest_path: PathBuf,\n pub lockfile_path: PathBuf,\n}\n\n#[derive(Serialize)]\nstruct ManifestFile {\n version: u8,\n install: BTreeMap<String, FloxInstallSpec>,\n}\n\n#[derive(Serialize)]\nstruct EnvJson {\n version: u8,\n manifest: String,\n lockfile: String,\n}\n\n/// Ensure a flox manifest exists for the given packages and return the paths to use.\npub fn ensure_env(project_root: &Path, packages: &[(String, FloxInstallSpec)]) -> Result<FloxEnv> {\n ensure_env_at(project_root, packages)\n}\n\npub fn ensure_env_at(root: &Path, packages: &[(String, FloxInstallSpec)]) -> Result<FloxEnv> {\n if packages.is_empty() {\n bail!(\"flox environment requested without any packages\");\n }\n\n let flox_bin = which::which(\"flox\")\n .context(\"flox is required to use [deps]; install flox and ensure it is on PATH\")?;\n\n let env_dir = root.join(\".flox\").join(\"env\");\n let manifest_path = env_dir.join(\"manifest.toml\");\n let lockfile_path = env_dir.join(\"manifest.lock\");\n fs::create_dir_all(&env_dir)\n .with_context(|| format!(\"failed to create flox env directory {}\", env_dir.display()))?;\n\n let manifest_toml = render_manifest(packages)?;\n let manifest_changed = write_if_changed(&manifest_path, &manifest_toml)?;\n\n // Produce a lockfile so flox activations don't need to mutate state.\n if manifest_changed || !lockfile_path.exists() {\n let output = Command::new(&flox_bin)\n .arg(\"lock-manifest\")\n .arg(&manifest_path)\n .output()\n .with_context(|| \"failed to run 'flox lock-manifest'\")?;\n\n if output.status.success() {\n write_if_changed(\n &lockfile_path,\n String::from_utf8_lossy(&output.stdout).as_ref(),\n )?;\n } else {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"flox lock-manifest failed: {}\", stderr.trim());\n }\n }\n\n write_env_json(root, &manifest_path, &lockfile_path)?;\n\n Ok(FloxEnv {\n project_root: root.to_path_buf(),\n manifest_path,\n lockfile_path,\n })\n}\n\n/// Run a shell command inside the prepared flox environment.\npub fn run_in_env(env: &FloxEnv, workdir: &Path, command: &str) -> Result<()> {\n write_env_json(&env.project_root, &env.manifest_path, &env.lockfile_path)?;\n\n let flox_bin = which::which(\"flox\").context(\"flox is required to run tasks with flox deps\")?;\n let status = Command::new(&flox_bin)\n .arg(\"activate\")\n .arg(\"-d\")\n .arg(&env.project_root)\n .arg(\"--\")\n .arg(\"/bin/sh\")\n .arg(\"-c\")\n .arg(command)\n .current_dir(workdir)\n .stdout(Stdio::piped())\n .stderr(Stdio::piped())\n .status()\n .with_context(|| \"failed to spawn flox activate for task\")?;\n\n if status.success() {\n return Ok(());\n }\n\n tracing::debug!(\n status = ?status.code(),\n \"flox activate failed; running task with host PATH\"\n );\n run_on_host(workdir, command)\n}\n\nfn write_env_json(project_root: &Path, manifest_path: &Path, lockfile_path: &Path) -> Result<()> {\n let flox_root = project_root.join(\".flox\");\n let top_level = flox_root.join(\"env.json\");\n let nested = flox_root.join(\"env\").join(\"env.json\");\n\n let nested_json = EnvJson {\n version: ENV_VERSION,\n manifest: manifest_path.to_string_lossy().to_string(),\n lockfile: lockfile_path.to_string_lossy().to_string(),\n };\n // top-level env.json with relative paths for flox CLI expectations\n let top_level_json = EnvJson {\n version: ENV_VERSION,\n manifest: \"env/manifest.toml\".to_string(),\n lockfile: \"env/manifest.lock\".to_string(),\n };\n\n if let Some(parent) = top_level.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n if let Some(parent) = nested.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n\n let top_level_contents = serde_json::to_string_pretty(&top_level_json)\n .context(\"failed to render top-level env.json\")?;\n let nested_contents =\n serde_json::to_string_pretty(&nested_json).context(\"failed to render nested env.json\")?;\n\n write_if_changed(&top_level, &top_level_contents)?;\n write_if_changed(&nested, &nested_contents)?;\n Ok(())\n}\n\nfn run_on_host(workdir: &Path, command: &str) -> Result<()> {\n let host_status = Command::new(\"/bin/sh\")\n .arg(\"-c\")\n .arg(command)\n .current_dir(workdir)\n .status()\n .with_context(|| \"failed to spawn command without managed env\")?;\n if host_status.success() {\n Ok(())\n } else {\n bail!(\n \"command exited with status {}\",\n host_status.code().unwrap_or(-1)\n );\n }\n}\n\nfn render_manifest(packages: &[(String, FloxInstallSpec)]) -> Result<String> {\n let mut install = BTreeMap::new();\n for (name, spec) in packages {\n install.insert(name.clone(), spec.clone());\n }\n\n let manifest = ManifestFile {\n version: MANIFEST_VERSION,\n install,\n };\n\n toml::to_string_pretty(&manifest).context(\"failed to render flox manifest\")\n}\n\nfn write_if_changed(path: &Path, contents: &str) -> Result<bool> {\n let needs_write = fs::read_to_string(path).map_or(true, |existing| existing != contents);\n if needs_write {\n fs::write(path, contents).with_context(|| format!(\"failed to write {}\", path.display()))?;\n }\n Ok(needs_write)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn manifest_renders_with_full_descriptor() {\n let deps = vec![(\n \"ripgrep\".to_string(),\n FloxInstallSpec {\n pkg_path: \"ripgrep\".into(),\n pkg_group: Some(\"tools\".into()),\n version: Some(\"14\".into()),\n systems: Some(vec![\"x86_64-darwin\".into()]),\n priority: Some(10),\n },\n )];\n\n let rendered = render_manifest(&deps).expect(\"render manifest\");\n assert!(rendered.contains(\"version = 1\"));\n assert!(rendered.contains(\"[install.ripgrep]\"));\n assert!(rendered.contains(r#\"pkg-path = \"ripgrep\"\"#));\n assert!(rendered.contains(r#\"pkg-group = \"tools\"\"#));\n assert!(rendered.contains(r#\"version = \"14\"\"#));\n assert!(rendered.contains(r#\"priority = 10\"#));\n }\n}\n" }, { "path": "src/gh_release.rs", "content": "//! GitHub release management.\n//!\n//! Provides functionality to:\n//! - Create GitHub releases with version tags\n//! - Upload release assets (binaries, tarballs)\n//! - List and manage existing releases\n\nuse std::fs;\nuse std::io::{self, Write};\nuse std::path::Path;\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::{GhReleaseAction, GhReleaseCommand, GhReleaseCreateOpts};\n\n/// Run the release command.\npub fn run(cmd: GhReleaseCommand) -> Result<()> {\n // Check if gh CLI is available\n if Command::new(\"gh\").arg(\"--version\").output().is_err() {\n bail!(\"GitHub CLI (gh) is not installed. Install from: https://cli.github.com\");\n }\n\n // Check if authenticated\n let auth_status = Command::new(\"gh\")\n .args([\"auth\", \"status\"])\n .output()\n .context(\"failed to check gh auth status\")?;\n\n if !auth_status.status.success() {\n println!(\"Not authenticated with GitHub.\");\n println!(\"Run: gh auth login\");\n bail!(\"GitHub authentication required\");\n }\n\n // Check if in a git repo\n if !Path::new(\".git\").exists() {\n bail!(\"Not in a git repository. Run this command from a git repo root.\");\n }\n\n match cmd.action {\n Some(GhReleaseAction::Create(opts)) => create_release(opts),\n Some(GhReleaseAction::List { limit }) => list_releases(limit),\n Some(GhReleaseAction::Delete { tag, yes }) => delete_release(&tag, yes),\n Some(GhReleaseAction::Download { tag, output }) => {\n download_release(tag.as_deref(), &output)\n }\n None => list_releases(10), // Default action\n }\n}\n\n/// Create a new GitHub release.\nfn create_release(opts: GhReleaseCreateOpts) -> Result<()> {\n // Determine the tag\n let tag = match opts.tag {\n Some(t) => t,\n None => detect_version()?,\n };\n\n // Ensure tag has 'v' prefix for consistency\n let tag = if tag.starts_with('v') {\n tag\n } else {\n format!(\"v{}\", tag)\n };\n\n println!(\"Creating release {}...\", tag);\n\n // Check if tag already exists\n let tag_exists = Command::new(\"gh\")\n .args([\"release\", \"view\", &tag])\n .output()\n .map(|o| o.status.success())\n .unwrap_or(false);\n\n if tag_exists {\n bail!(\n \"Release {} already exists. Use a different version or delete the existing release.\",\n tag\n );\n }\n\n // Validate assets exist\n for asset in &opts.asset {\n if !Path::new(asset).exists() {\n bail!(\"Asset file not found: {}\", asset);\n }\n }\n\n // Confirmation\n if !opts.yes {\n println!();\n println!(\"Release details:\");\n println!(\" Tag: {}\", tag);\n if let Some(ref title) = opts.title {\n println!(\" Title: {}\", title);\n }\n if opts.draft {\n println!(\" Type: Draft\");\n }\n if opts.prerelease {\n println!(\" Type: Pre-release\");\n }\n if !opts.asset.is_empty() {\n println!(\" Assets: {}\", opts.asset.join(\", \"));\n }\n println!();\n\n print!(\"Create release? [Y/n]: \");\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let input = input.trim().to_lowercase();\n if input == \"n\" || input == \"no\" {\n println!(\"Aborted.\");\n return Ok(());\n }\n }\n\n // Build the gh release create command\n let mut args = vec![\"release\", \"create\", &tag];\n\n let title_str;\n if let Some(ref title) = opts.title {\n args.push(\"--title\");\n title_str = title.clone();\n args.push(&title_str);\n }\n\n let notes_str;\n if let Some(ref notes) = opts.notes {\n args.push(\"--notes\");\n notes_str = notes.clone();\n args.push(¬es_str);\n } else if let Some(ref notes_file) = opts.notes_file {\n args.push(\"--notes-file\");\n args.push(notes_file);\n } else if opts.generate_notes {\n args.push(\"--generate-notes\");\n }\n\n if opts.draft {\n args.push(\"--draft\");\n }\n\n if opts.prerelease {\n args.push(\"--prerelease\");\n }\n\n let target_str;\n if let Some(ref target) = opts.target {\n args.push(\"--target\");\n target_str = target.clone();\n args.push(&target_str);\n }\n\n // Add assets\n for asset in &opts.asset {\n args.push(asset);\n }\n\n println!(\"Running: gh {}\", args.join(\" \"));\n\n let status = Command::new(\"gh\")\n .args(&args)\n .status()\n .context(\"failed to create release\")?;\n\n if !status.success() {\n bail!(\"Failed to create release\");\n }\n\n println!();\n println!(\"Release {} created successfully!\", tag);\n\n // Show the release URL\n let url_output = Command::new(\"gh\")\n .args([\"release\", \"view\", &tag, \"--json\", \"url\", \"-q\", \".url\"])\n .output();\n\n if let Ok(output) = url_output {\n if output.status.success() {\n let url = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if !url.is_empty() {\n println!(\"View at: {}\", url);\n }\n }\n }\n\n Ok(())\n}\n\n/// List recent releases.\nfn list_releases(limit: usize) -> Result<()> {\n let output = Command::new(\"gh\")\n .args([\"release\", \"list\", \"--limit\", &limit.to_string()])\n .output()\n .context(\"failed to list releases\")?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n if stderr.contains(\"no releases found\") {\n println!(\"No releases found.\");\n return Ok(());\n }\n bail!(\"Failed to list releases: {}\", stderr);\n }\n\n let stdout = String::from_utf8_lossy(&output.stdout);\n if stdout.trim().is_empty() {\n println!(\"No releases found.\");\n } else {\n println!(\"{}\", stdout);\n }\n\n Ok(())\n}\n\n/// Delete a release.\nfn delete_release(tag: &str, yes: bool) -> Result<()> {\n // Check if release exists\n let exists = Command::new(\"gh\")\n .args([\"release\", \"view\", tag])\n .output()\n .map(|o| o.status.success())\n .unwrap_or(false);\n\n if !exists {\n bail!(\"Release {} not found\", tag);\n }\n\n if !yes {\n print!(\"Delete release {}? [y/N]: \", tag);\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let input = input.trim().to_lowercase();\n if input != \"y\" && input != \"yes\" {\n println!(\"Aborted.\");\n return Ok(());\n }\n }\n\n let status = Command::new(\"gh\")\n .args([\"release\", \"delete\", tag, \"--yes\"])\n .status()\n .context(\"failed to delete release\")?;\n\n if !status.success() {\n bail!(\"Failed to delete release\");\n }\n\n println!(\"Release {} deleted.\", tag);\n\n // Optionally delete the tag too\n print!(\"Also delete the git tag {}? [y/N]: \", tag);\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let input = input.trim().to_lowercase();\n if input == \"y\" || input == \"yes\" {\n Command::new(\"git\").args([\"tag\", \"-d\", tag]).status().ok();\n Command::new(\"git\")\n .args([\"push\", \"origin\", &format!(\":refs/tags/{}\", tag)])\n .status()\n .ok();\n println!(\"Tag {} deleted.\", tag);\n }\n\n Ok(())\n}\n\n/// Download release assets.\nfn download_release(tag: Option<&str>, output: &str) -> Result<()> {\n let mut args = vec![\"release\", \"download\"];\n\n if let Some(t) = tag {\n args.push(t);\n }\n\n args.push(\"--dir\");\n args.push(output);\n\n // Create output directory if needed\n if output != \".\" {\n fs::create_dir_all(output).context(\"failed to create output directory\")?;\n }\n\n println!(\"Downloading release assets to {}...\", output);\n\n let status = Command::new(\"gh\")\n .args(&args)\n .status()\n .context(\"failed to download release\")?;\n\n if !status.success() {\n bail!(\"Failed to download release assets\");\n }\n\n println!(\"Download complete.\");\n Ok(())\n}\n\n/// Detect version from Cargo.toml or package.json.\nfn detect_version() -> Result<String> {\n // Try Cargo.toml first\n if Path::new(\"Cargo.toml\").exists() {\n let content = fs::read_to_string(\"Cargo.toml\")?;\n for line in content.lines() {\n if line.starts_with(\"version\") {\n if let Some(version) = line.split('=').nth(1) {\n let version = version.trim().trim_matches('\"').trim_matches('\\'');\n return Ok(version.to_string());\n }\n }\n }\n }\n\n // Try package.json\n if Path::new(\"package.json\").exists() {\n let content = fs::read_to_string(\"package.json\")?;\n if let Ok(json) = serde_json::from_str::<serde_json::Value>(&content) {\n if let Some(version) = json.get(\"version\").and_then(|v| v.as_str()) {\n return Ok(version.to_string());\n }\n }\n }\n\n // Try pyproject.toml\n if Path::new(\"pyproject.toml\").exists() {\n let content = fs::read_to_string(\"pyproject.toml\")?;\n for line in content.lines() {\n if line.starts_with(\"version\") {\n if let Some(version) = line.split('=').nth(1) {\n let version = version.trim().trim_matches('\"').trim_matches('\\'');\n return Ok(version.to_string());\n }\n }\n }\n }\n\n // Try to get from git tags\n let output = Command::new(\"git\")\n .args([\"describe\", \"--tags\", \"--abbrev=0\"])\n .output();\n\n if let Ok(output) = output {\n if output.status.success() {\n let tag = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if !tag.is_empty() {\n // Increment patch version\n let version = tag.strip_prefix('v').unwrap_or(&tag);\n let parts: Vec<&str> = version.split('.').collect();\n if parts.len() >= 3 {\n if let Ok(patch) = parts[2].parse::<u32>() {\n return Ok(format!(\"{}.{}.{}\", parts[0], parts[1], patch + 1));\n }\n }\n return Ok(version.to_string());\n }\n }\n }\n\n bail!(\n \"Could not detect version. Please specify with: f release create <tag>\\n\\\n Or add version to Cargo.toml, package.json, or pyproject.toml\"\n )\n}\n" }, { "path": "src/git_guard.rs", "content": "use std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::GitRepairOpts;\n\n/// Returns true when the repo has a `.jj` directory (jj colocated mode).\nfn is_jj_colocated(repo_root: &Path) -> bool {\n repo_root.join(\".jj\").is_dir()\n}\n\nfn git_capture_in(repo_root: &Path, args: &[&str]) -> Option<String> {\n let out = Command::new(\"git\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .ok()?;\n if !out.status.success() {\n return None;\n }\n Some(String::from_utf8_lossy(&out.stdout).trim().to_string())\n}\n\nfn has_working_tree_changes(repo_root: &Path) -> bool {\n match git_capture_in(repo_root, &[\"status\", \"--porcelain\"]) {\n Some(s) => !s.trim().is_empty(),\n None => false,\n }\n}\n\nfn short_sha(sha: &str) -> &str {\n if sha.len() <= 7 { sha } else { &sha[..7] }\n}\n\nfn attach_detached_head_to_keep_branch(repo_root: &Path) -> Result<bool> {\n if !is_jj_colocated(repo_root) {\n return Ok(false);\n }\n let Some(head) = git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"]) else {\n return Ok(false);\n };\n if head.trim().is_empty() {\n return Ok(false);\n }\n let branch = format!(\"jj/keep/{}\", head.trim());\n\n // If it already exists, just check it out.\n if git_ref_exists(repo_root, &branch) {\n let status = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"checkout\", &branch])\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .status();\n return Ok(matches!(status, Ok(s) if s.success()));\n }\n\n // Create and check out (at HEAD) without touching the working tree.\n let status = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"checkout\", \"-b\", &branch, head.trim()])\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .status();\n Ok(matches!(status, Ok(s) if s.success()))\n}\n\n/// In a jj-colocated repo, detached HEAD is common. For git-based workflows,\n/// we need to ensure HEAD is attached to a local branch.\n///\n/// Strategy:\n/// - If main/master exists AND points at the current HEAD commit, attach to it\n/// (no working tree changes).\n/// - Otherwise, attach HEAD to a synthetic `jj/keep/<sha>` branch at the current commit.\nfn jj_auto_checkout(repo_root: &Path) -> Result<bool> {\n if !is_jj_colocated(repo_root) {\n return Ok(false);\n }\n\n let Some(head) = git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"]) else {\n return Ok(false);\n };\n for target in [\"main\", \"master\"] {\n if !git_ref_exists(repo_root, target) {\n continue;\n }\n let Some(target_sha) = git_capture_in(repo_root, &[\"rev-parse\", target]) else {\n continue;\n };\n if target_sha == head {\n let status = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"checkout\", target])\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .status();\n if matches!(status, Ok(s) if s.success()) {\n return Ok(true);\n }\n }\n }\n\n attach_detached_head_to_keep_branch(repo_root)\n}\n\nfn resolve_land_target_branch(repo_root: &Path, requested: &str) -> Result<String> {\n if git_ref_exists(repo_root, requested) {\n return Ok(requested.to_string());\n }\n if requested == \"main\" && git_ref_exists(repo_root, \"master\") {\n return Ok(\"master\".to_string());\n }\n bail!(\n \"Target branch '{}' not found (and fallback branch unavailable).\",\n requested\n );\n}\n\nfn ensure_clean_working_tree_for_land(repo_root: &Path) -> Result<()> {\n let status = git_capture_in(repo_root, &[\"status\", \"--porcelain\"]).unwrap_or_default();\n if !status.trim().is_empty() {\n bail!(\"Cannot land onto main with uncommitted changes. Commit or stash first.\");\n }\n Ok(())\n}\n\nfn land_head_to_branch(repo_root: &Path, requested_target: &str) -> Result<()> {\n ensure_clean_working_tree_for_land(repo_root)?;\n\n let current = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|| \"HEAD\".to_string());\n if current.trim() == \"HEAD\" {\n bail!(\"HEAD is detached. Run `f git-repair` first.\");\n }\n let current = current.trim().to_string();\n let target = resolve_land_target_branch(repo_root, requested_target)?;\n if current == target {\n println!(\"Already on {}\", target);\n return Ok(());\n }\n\n let head_sha = git_capture_in(repo_root, &[\"rev-parse\", \"HEAD\"])\n .ok_or_else(|| anyhow::anyhow!(\"failed to resolve HEAD commit\"))?;\n\n git_run_in(repo_root, &[\"checkout\", &target])?;\n match git_run_in(repo_root, &[\"cherry-pick\", head_sha.trim()]) {\n Ok(_) => {\n println!(\n \"✓ Landed commit {} from {} onto {}\",\n short_sha(head_sha.trim()),\n current,\n target\n );\n Ok(())\n }\n Err(err) => {\n let conflicts = git_unmerged_files(repo_root);\n let _ = git_run_in(repo_root, &[\"cherry-pick\", \"--abort\"]);\n let _ = git_run_in(repo_root, &[\"checkout\", ¤t]);\n\n eprintln!(\n \"Landing failed: commit {} conflicts with {}. Flow aborted cherry-pick and returned to {}.\",\n short_sha(head_sha.trim()),\n target,\n current\n );\n if !conflicts.is_empty() {\n eprintln!(\"Conflicting files:\");\n for file in conflicts {\n eprintln!(\" - {}\", file);\n }\n }\n eprintln!(\n \"No data was lost. You can rebase {} onto {} and retry.\",\n current, target\n );\n Err(err).context(\"failed to land commit onto target branch\")\n }\n }\n}\n\n#[derive(Debug, Clone)]\nstruct GitState {\n rebase: bool,\n merge: bool,\n cherry_pick: bool,\n revert: bool,\n bisect: bool,\n detached: bool,\n unmerged_files: Vec<String>,\n}\n\npub fn ensure_clean_for_commit(repo_root: &Path) -> Result<()> {\n ensure_clean_state(repo_root, \"commit\")\n}\n\npub fn ensure_clean_for_push(repo_root: &Path) -> Result<()> {\n ensure_clean_state(repo_root, \"push\")\n}\n\nfn ensure_clean_state(repo_root: &Path, action: &str) -> Result<()> {\n let state = detect_git_state(repo_root)?;\n let mut issues = Vec::new();\n\n if state.rebase {\n issues.push(\"rebase in progress\".to_string());\n }\n if state.merge {\n issues.push(\"merge in progress\".to_string());\n }\n if state.cherry_pick {\n issues.push(\"cherry-pick in progress\".to_string());\n }\n if state.revert {\n issues.push(\"revert in progress\".to_string());\n }\n if state.bisect {\n issues.push(\"bisect in progress\".to_string());\n }\n if !state.unmerged_files.is_empty() {\n issues.push(format!(\n \"unmerged files: {}\",\n state.unmerged_files.join(\", \")\n ));\n }\n if state.detached {\n // In jj-colocated repos, detached HEAD is normal — auto-fix it.\n if !jj_auto_checkout(repo_root)? {\n issues.push(\"detached HEAD\".to_string());\n }\n }\n\n if !issues.is_empty() {\n let mut msg = format!(\"Git state not clean for {}:\", action);\n for issue in issues {\n msg.push_str(&format!(\"\\n - {}\", issue));\n }\n msg.push_str(\"\\n\\nRun `f git-repair` or resolve manually before continuing.\");\n bail!(msg);\n }\n\n Ok(())\n}\n\npub fn run_git_repair(opts: GitRepairOpts) -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to read current directory\")?;\n let repo_root = find_repo_root(&cwd)?;\n let branch = opts.branch.as_deref().unwrap_or(\"main\");\n let state = detect_git_state(&repo_root)?;\n\n if opts.dry_run {\n print_state(&state, branch, opts.land_main);\n return Ok(());\n }\n\n let mut did_work = false;\n if state.rebase {\n let _ = git_run_in(&repo_root, &[\"rebase\", \"--abort\"]);\n did_work = true;\n }\n if state.merge {\n let _ = git_run_in(&repo_root, &[\"merge\", \"--abort\"]);\n did_work = true;\n }\n if state.cherry_pick {\n let _ = git_run_in(&repo_root, &[\"cherry-pick\", \"--abort\"]);\n did_work = true;\n }\n if state.revert {\n let _ = git_run_in(&repo_root, &[\"revert\", \"--abort\"]);\n did_work = true;\n }\n if state.bisect {\n let _ = git_run_in(&repo_root, &[\"bisect\", \"reset\"]);\n did_work = true;\n }\n\n if state.detached {\n // In jj-colocated repos, prefer attaching HEAD to a safe local branch.\n // If there are working copy changes, do NOT try to checkout main/master (it can overwrite).\n if is_jj_colocated(&repo_root) && has_working_tree_changes(&repo_root) {\n if attach_detached_head_to_keep_branch(&repo_root)? {\n did_work = true;\n } else {\n bail!(\n \"Detached HEAD in jj-colocated repo with local changes, but failed to attach to a keep branch.\"\n );\n }\n } else if jj_auto_checkout(&repo_root)? {\n did_work = true;\n } else {\n let target = if git_ref_exists(&repo_root, branch) {\n branch.to_string()\n } else if git_ref_exists(&repo_root, \"master\") {\n \"master\".to_string()\n } else {\n bail!(\n \"Detached HEAD and branch '{}' not found. Checkout a branch manually.\",\n branch\n );\n };\n git_run_in(&repo_root, &[\"checkout\", &target])?;\n did_work = true;\n }\n }\n\n if opts.land_main {\n land_head_to_branch(&repo_root, branch)?;\n did_work = true;\n }\n\n if did_work {\n println!(\"✓ Git repair complete\");\n } else {\n println!(\"No repair needed\");\n }\n\n Ok(())\n}\n\nfn detect_git_state(repo_root: &Path) -> Result<GitState> {\n let git_dir = git_dir(repo_root)?;\n let rebase = git_dir.join(\"rebase-merge\").exists() || git_dir.join(\"rebase-apply\").exists();\n let merge = git_dir.join(\"MERGE_HEAD\").exists();\n let cherry_pick = git_dir.join(\"CHERRY_PICK_HEAD\").exists();\n let revert = git_dir.join(\"REVERT_HEAD\").exists();\n let bisect = git_dir.join(\"BISECT_LOG\").exists();\n let detached = is_detached_head(repo_root)?;\n let unmerged_files = git_unmerged_files(repo_root);\n\n Ok(GitState {\n rebase,\n merge,\n cherry_pick,\n revert,\n bisect,\n detached,\n unmerged_files,\n })\n}\n\nfn git_dir(repo_root: &Path) -> Result<PathBuf> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"rev-parse\", \"--git-dir\"])\n .output()\n .context(\"failed to locate git directory\")?;\n if !output.status.success() {\n bail!(\"Not a git repository\");\n }\n let raw = String::from_utf8_lossy(&output.stdout).trim().to_string();\n let dir = PathBuf::from(raw);\n if dir.is_absolute() {\n Ok(dir)\n } else {\n Ok(repo_root.join(dir))\n }\n}\n\nfn is_detached_head(repo_root: &Path) -> Result<bool> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"symbolic-ref\", \"--quiet\", \"--short\", \"HEAD\"])\n .output()\n .context(\"failed to check HEAD\")?;\n Ok(!output.status.success())\n}\n\nfn git_unmerged_files(repo_root: &Path) -> Vec<String> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"diff\", \"--name-only\", \"--diff-filter=U\"])\n .output();\n match output {\n Ok(out) => String::from_utf8_lossy(&out.stdout)\n .lines()\n .filter(|l| !l.trim().is_empty())\n .map(|l| l.trim().to_string())\n .collect(),\n Err(_) => Vec::new(),\n }\n}\n\nfn git_run_in(repo_root: &Path, args: &[&str]) -> Result<()> {\n let status = Command::new(\"git\")\n .current_dir(repo_root)\n .args(args)\n .status()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n if !status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n Ok(())\n}\n\nfn git_ref_exists(repo_root: &Path, name: &str) -> bool {\n Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"show-ref\", \"--verify\", &format!(\"refs/heads/{}\", name)])\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .status()\n .map(|s| s.success())\n .unwrap_or(false)\n}\n\nfn print_state(state: &GitState, branch: &str, land_main: bool) {\n println!(\"Git repair dry-run:\");\n println!(\" rebase: {}\", state.rebase);\n println!(\" merge: {}\", state.merge);\n println!(\" cherry-pick: {}\", state.cherry_pick);\n println!(\" revert: {}\", state.revert);\n println!(\" bisect: {}\", state.bisect);\n println!(\" detached: {}\", state.detached);\n if !state.unmerged_files.is_empty() {\n println!(\" unmerged files: {}\", state.unmerged_files.join(\", \"));\n }\n println!(\" target branch: {}\", branch);\n println!(\" land main: {}\", land_main);\n}\n\nfn find_repo_root(start: &Path) -> Result<PathBuf> {\n let output = Command::new(\"git\")\n .current_dir(start)\n .args([\"rev-parse\", \"--show-toplevel\"])\n .output()\n .context(\"failed to find git repository\")?;\n\n if !output.status.success() {\n bail!(\"Not in a git repository\");\n }\n\n let path = String::from_utf8_lossy(&output.stdout).trim().to_string();\n Ok(PathBuf::from(path))\n}\n" }, { "path": "src/gitignore_policy.rs", "content": "use std::collections::{BTreeMap, BTreeSet, HashSet};\nuse std::env;\nuse std::ffi::OsStr;\nuse std::fs;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\nuse serde::Deserialize;\n\nuse crate::cli::{GitignoreAction, GitignoreCommand, GitignorePolicyInitOpts, GitignoreScanOpts};\nuse crate::config;\n\nconst POLICY_OVERRIDE_ENV: &str = \"FLOW_ALLOW_GITIGNORE_POLICY\";\nconst POLICY_FILE_NAME: &str = \"gitignore-policy.toml\";\nconst DEFAULT_REPOS_ROOT: &str = \"~/repos\";\nconst DEFAULT_BLOCKED_PATTERNS: &[&str] = &[\".ai/todos/*.bike\", \".beads/\", \".rise/\"];\nconst DEFAULT_ALLOWED_OWNERS: &[&str] = &[\"nikivdev\"];\n\n#[derive(Debug, Clone)]\npub struct GitignorePolicy {\n pub blocked_patterns: Vec<String>,\n pub allowed_owners: Vec<String>,\n pub repos_roots: Vec<PathBuf>,\n}\n\n#[derive(Debug, Deserialize, Default)]\nstruct GitignorePolicyFile {\n blocked_patterns: Option<Vec<String>>,\n allowed_owners: Option<Vec<String>>,\n repos_roots: Option<Vec<String>>,\n}\n\n#[derive(Debug, Clone)]\nstruct Violation {\n file: PathBuf,\n line: usize,\n entry: String,\n blocked_pattern: String,\n}\n\nimpl Default for GitignorePolicy {\n fn default() -> Self {\n Self {\n blocked_patterns: DEFAULT_BLOCKED_PATTERNS\n .iter()\n .map(|s| s.to_string())\n .collect(),\n allowed_owners: DEFAULT_ALLOWED_OWNERS\n .iter()\n .map(|s| s.to_ascii_lowercase())\n .collect(),\n repos_roots: vec![expand_home(DEFAULT_REPOS_ROOT)],\n }\n }\n}\n\npub fn run(cmd: GitignoreCommand) -> Result<()> {\n match cmd\n .action\n .unwrap_or(GitignoreAction::Audit(GitignoreScanOpts {\n root: None,\n all: false,\n })) {\n GitignoreAction::Audit(opts) => run_scan(opts, false),\n GitignoreAction::Fix(opts) => run_scan(opts, true),\n GitignoreAction::PolicyInit(opts) => init_policy_file(opts),\n GitignoreAction::SetupGlobal { print_only } => setup_global_gitignore(print_only),\n GitignoreAction::PolicyPath => {\n println!(\"{}\", policy_path().display());\n Ok(())\n }\n }\n}\n\npub fn enforce_staged_policy(repo_root: &Path) -> Result<()> {\n if policy_override_enabled() {\n return Ok(());\n }\n\n let policy = load_policy();\n if !is_external_repo(repo_root, &policy) {\n return Ok(());\n }\n\n let violations = staged_gitignore_violations(repo_root, &policy)?;\n if violations.is_empty() {\n return Ok(());\n }\n\n eprintln!(\"Refusing to commit personal tooling ignore entries in an external repo:\");\n for v in &violations {\n eprintln!(\n \" - {}:{} adds '{}' (blocked by policy '{}')\",\n v.file.display(),\n v.line,\n v.entry,\n v.blocked_pattern\n );\n }\n eprintln!();\n eprintln!(\"Use global gitignore for personal tooling, then retry.\");\n eprintln!(\"To clean existing repos: f gitignore fix\");\n eprintln!(\"Override once with {}=1\", POLICY_OVERRIDE_ENV);\n\n bail!(\"blocked personal tooling .gitignore entries\")\n}\n\npub fn load_policy() -> GitignorePolicy {\n let mut policy = GitignorePolicy::default();\n let path = policy_path();\n\n if !path.exists() {\n return policy;\n }\n\n let content = match fs::read_to_string(&path) {\n Ok(content) => content,\n Err(err) => {\n eprintln!(\n \"warn: failed to read {}: {} (using defaults)\",\n path.display(),\n err\n );\n return policy;\n }\n };\n\n let parsed: GitignorePolicyFile = match toml::from_str(&content) {\n Ok(parsed) => parsed,\n Err(err) => {\n eprintln!(\n \"warn: failed to parse {}: {} (using defaults)\",\n path.display(),\n err\n );\n return policy;\n }\n };\n\n if let Some(patterns) = parsed.blocked_patterns {\n let cleaned = clean_patterns(patterns.into_iter());\n if !cleaned.is_empty() {\n policy.blocked_patterns = cleaned;\n }\n }\n\n if let Some(owners) = parsed.allowed_owners {\n let cleaned: Vec<String> = owners\n .into_iter()\n .map(|s| s.trim().to_ascii_lowercase())\n .filter(|s| !s.is_empty())\n .collect();\n if !cleaned.is_empty() {\n policy.allowed_owners = cleaned;\n }\n }\n\n if let Some(roots) = parsed.repos_roots {\n let cleaned: Vec<PathBuf> = roots\n .into_iter()\n .map(|s| expand_home(s.trim()))\n .filter(|p| !p.as_os_str().is_empty())\n .collect();\n if !cleaned.is_empty() {\n policy.repos_roots = cleaned;\n }\n }\n\n policy\n}\n\npub fn policy_path() -> PathBuf {\n config::global_config_dir().join(POLICY_FILE_NAME)\n}\n\npub fn is_external_repo(repo_root: &Path, policy: &GitignorePolicy) -> bool {\n let Some(owner) = repo_origin_owner(repo_root) else {\n return true;\n };\n\n !policy\n .allowed_owners\n .iter()\n .any(|o| o.eq_ignore_ascii_case(owner.as_str()))\n}\n\nfn run_scan(opts: GitignoreScanOpts, apply_fix: bool) -> Result<()> {\n let policy = load_policy();\n let roots = scan_roots(&opts, &policy);\n\n let mut repo_roots: Vec<PathBuf> = Vec::new();\n for root in roots {\n repo_roots.extend(discover_repo_roots(&root));\n }\n repo_roots.sort();\n repo_roots.dedup();\n\n if repo_roots.is_empty() {\n println!(\"No repositories found.\");\n return Ok(());\n }\n\n let mut findings_by_repo: BTreeMap<PathBuf, Vec<Violation>> = BTreeMap::new();\n let mut touched_files: BTreeSet<PathBuf> = BTreeSet::new();\n\n for repo_root in repo_roots {\n if !opts.all && !is_external_repo(&repo_root, &policy) {\n continue;\n }\n\n if apply_fix {\n let changed = fix_repo_gitignores(&repo_root, &policy)?;\n touched_files.extend(changed);\n }\n\n let repo_findings = inspect_repo_gitignores(&repo_root, &policy)?;\n if !repo_findings.is_empty() {\n findings_by_repo.insert(repo_root, repo_findings);\n }\n }\n\n if apply_fix {\n if touched_files.is_empty() {\n println!(\"No policy entries needed removal.\");\n } else {\n println!(\n \"Removed policy entries from {} .gitignore file(s).\",\n touched_files.len()\n );\n for path in touched_files {\n println!(\" - {}\", path.display());\n }\n }\n }\n\n if findings_by_repo.is_empty() {\n println!(\"No blocked personal-tooling patterns found.\");\n return Ok(());\n }\n\n println!(\"Blocked personal-tooling patterns found:\");\n for (repo, findings) in &findings_by_repo {\n println!(\"\\n{}\", repo.display());\n for v in findings {\n println!(\n \" - {}:{} '{}' (blocked by '{}')\",\n v.file.display(),\n v.line,\n v.entry,\n v.blocked_pattern\n );\n }\n }\n\n if apply_fix {\n bail!(\"Some blocked entries remain; review output above\")\n } else {\n bail!(\"Found blocked personal-tooling entries\")\n }\n}\n\nfn init_policy_file(opts: GitignorePolicyInitOpts) -> Result<()> {\n let path = policy_path();\n let parent = path\n .parent()\n .ok_or_else(|| anyhow::anyhow!(\"invalid policy path {}\", path.display()))?;\n fs::create_dir_all(parent).with_context(|| format!(\"failed to create {}\", parent.display()))?;\n\n if path.exists() && !opts.force {\n bail!(\n \"{} already exists (use --force to overwrite)\",\n path.display()\n );\n }\n\n fs::write(&path, default_policy_template())\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n println!(\"Wrote {}\", path.display());\n Ok(())\n}\n\nfn setup_global_gitignore(print_only: bool) -> Result<()> {\n let policy = load_policy();\n let target = resolve_global_excludes_path()?;\n\n if print_only {\n println!(\"Global excludes file: {}\", target.display());\n println!(\"Patterns:\");\n for pattern in &policy.blocked_patterns {\n println!(\" - {}\", pattern);\n }\n return Ok(());\n }\n\n if let Some(parent) = target.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n\n let existing = fs::read_to_string(&target).unwrap_or_default();\n let mut lines: Vec<String> = existing.lines().map(|s| s.to_string()).collect();\n let mut appended = 0usize;\n\n for pattern in &policy.blocked_patterns {\n let wanted = pattern.trim();\n let Some(target_norm) = normalize_entry(wanted) else {\n continue;\n };\n let present = lines.iter().any(|line| {\n normalize_entry(line)\n .map(|norm| norm == target_norm)\n .unwrap_or(false)\n });\n if present {\n continue;\n }\n lines.push(wanted.to_string());\n appended += 1;\n }\n\n let mut rendered = lines.join(\"\\n\");\n if !rendered.is_empty() {\n rendered.push('\\n');\n }\n fs::write(&target, rendered)\n .with_context(|| format!(\"failed to write {}\", target.display()))?;\n\n ensure_global_excludes_config(&target)?;\n\n if appended == 0 {\n println!(\"Global excludes already up to date: {}\", target.display());\n } else {\n println!(\n \"Added {} pattern(s) to global excludes: {}\",\n appended,\n target.display()\n );\n }\n\n Ok(())\n}\n\nfn resolve_global_excludes_path() -> Result<PathBuf> {\n if let Some(configured) = git_capture_global_config(\"core.excludesFile\")? {\n return Ok(expand_home(configured.trim()));\n }\n\n Ok(home_dir_or_default().join(\".config/git/ignore\"))\n}\n\nfn ensure_global_excludes_config(path: &Path) -> Result<()> {\n let current = git_capture_global_config(\"core.excludesFile\")?;\n if let Some(current) = current {\n let current_path = expand_home(current.trim());\n if current_path == path {\n return Ok(());\n }\n }\n\n let value = path.to_string_lossy().to_string();\n let status = Command::new(\"git\")\n .args([\"config\", \"--global\", \"core.excludesFile\", &value])\n .status()\n .context(\"failed to run git config --global core.excludesFile\")?;\n if !status.success() {\n bail!(\"git config --global core.excludesFile failed\")\n }\n Ok(())\n}\n\nfn git_capture_global_config(key: &str) -> Result<Option<String>> {\n let output = Command::new(\"git\")\n .args([\"config\", \"--global\", \"--get\", key])\n .output()\n .with_context(|| format!(\"failed to read global git config key {}\", key))?;\n\n if !output.status.success() {\n return Ok(None);\n }\n\n let value = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if value.is_empty() {\n Ok(None)\n } else {\n Ok(Some(value))\n }\n}\n\nfn staged_gitignore_violations(\n repo_root: &Path,\n policy: &GitignorePolicy,\n) -> Result<Vec<Violation>> {\n let staged_files = staged_gitignore_files(repo_root)?;\n if staged_files.is_empty() {\n return Ok(Vec::new());\n }\n\n let blocked = blocked_lookup(policy);\n let mut violations = Vec::new();\n\n for file in staged_files {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"diff\", \"--cached\", \"-U0\", \"--\", &file])\n .output()\n .with_context(|| format!(\"failed to inspect staged diff for {}\", file))?;\n\n if !output.status.success() {\n continue;\n }\n\n let diff = String::from_utf8_lossy(&output.stdout);\n let mut line_no: usize = 0;\n\n for line in diff.lines() {\n if line.starts_with(\"@@\") {\n line_no = parse_hunk_new_line(line).unwrap_or(0);\n continue;\n }\n\n if let Some(rest) = line.strip_prefix('+') {\n if line.starts_with(\"+++\") {\n continue;\n }\n if let Some(normalized) = normalize_entry(rest) {\n if let Some((_, blocked_pattern)) =\n blocked.iter().find(|(norm, _)| norm == &normalized)\n {\n violations.push(Violation {\n file: PathBuf::from(&file),\n line: if line_no == 0 { 1 } else { line_no },\n entry: rest.trim().to_string(),\n blocked_pattern: blocked_pattern.clone(),\n });\n }\n }\n line_no = line_no.saturating_add(1);\n continue;\n }\n\n if line.starts_with(' ') {\n line_no = line_no.saturating_add(1);\n }\n }\n }\n\n Ok(violations)\n}\n\nfn staged_gitignore_files(repo_root: &Path) -> Result<Vec<String>> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"diff\", \"--cached\", \"--name-only\", \"--diff-filter=ACMR\"])\n .output()\n .context(\"failed to list staged files\")?;\n\n if !output.status.success() {\n bail!(\"git diff --cached --name-only failed\")\n }\n\n Ok(String::from_utf8_lossy(&output.stdout)\n .lines()\n .map(str::trim)\n .filter(|s| s.ends_with(\".gitignore\"))\n .map(|s| s.to_string())\n .collect())\n}\n\nfn inspect_repo_gitignores(repo_root: &Path, policy: &GitignorePolicy) -> Result<Vec<Violation>> {\n let blocked = blocked_lookup(policy);\n let files = list_gitignore_files(repo_root);\n let mut out = Vec::new();\n\n for file in files {\n let content = fs::read_to_string(&file)\n .with_context(|| format!(\"failed to read {}\", file.display()))?;\n for (idx, line) in content.lines().enumerate() {\n let Some(normalized) = normalize_entry(line) else {\n continue;\n };\n if let Some((_, blocked_pattern)) = blocked.iter().find(|(norm, _)| norm == &normalized)\n {\n out.push(Violation {\n file: file.clone(),\n line: idx + 1,\n entry: line.trim().to_string(),\n blocked_pattern: blocked_pattern.clone(),\n });\n }\n }\n }\n\n Ok(out)\n}\n\nfn fix_repo_gitignores(repo_root: &Path, policy: &GitignorePolicy) -> Result<Vec<PathBuf>> {\n let blocked: HashSet<String> = blocked_lookup(policy).into_iter().map(|(n, _)| n).collect();\n let files = list_gitignore_files(repo_root);\n let mut changed = Vec::new();\n\n for file in files {\n let content = fs::read_to_string(&file)\n .with_context(|| format!(\"failed to read {}\", file.display()))?;\n let had_trailing_newline = content.ends_with('\\n');\n\n let mut kept = Vec::new();\n let mut removed_any = false;\n for line in content.lines() {\n let remove = normalize_entry(line)\n .map(|normalized| blocked.contains(&normalized))\n .unwrap_or(false);\n if remove {\n removed_any = true;\n continue;\n }\n kept.push(line.to_string());\n }\n\n if !removed_any {\n continue;\n }\n\n let mut new_content = kept.join(\"\\n\");\n if had_trailing_newline && !new_content.is_empty() {\n new_content.push('\\n');\n }\n\n fs::write(&file, new_content)\n .with_context(|| format!(\"failed to write {}\", file.display()))?;\n changed.push(file);\n }\n\n Ok(changed)\n}\n\nfn list_gitignore_files(repo_root: &Path) -> Vec<PathBuf> {\n let mut files = Vec::new();\n collect_gitignore_files(repo_root, 0, 64, &mut files);\n files.sort();\n files\n}\n\nfn discover_repo_roots(root: &Path) -> Vec<PathBuf> {\n let mut repos: BTreeSet<PathBuf> = BTreeSet::new();\n collect_repo_roots(root, 0, 4, &mut repos);\n repos.into_iter().collect()\n}\n\nfn collect_gitignore_files(dir: &Path, depth: usize, max_depth: usize, out: &mut Vec<PathBuf>) {\n if depth > max_depth {\n return;\n }\n\n let Ok(entries) = fs::read_dir(dir) else {\n return;\n };\n\n for entry in entries.flatten() {\n let path = entry.path();\n let Ok(ft) = entry.file_type() else {\n continue;\n };\n\n if ft.is_file() {\n if path.file_name() == Some(OsStr::new(\".gitignore\")) {\n out.push(path);\n }\n continue;\n }\n\n if !ft.is_dir() {\n continue;\n }\n\n let name = path.file_name().and_then(OsStr::to_str).unwrap_or_default();\n if name == \".git\" || name == \"node_modules\" || name == \"target\" {\n continue;\n }\n\n collect_gitignore_files(&path, depth + 1, max_depth, out);\n }\n}\n\nfn collect_repo_roots(dir: &Path, depth: usize, max_depth: usize, out: &mut BTreeSet<PathBuf>) {\n if depth > max_depth {\n return;\n }\n\n let Ok(entries) = fs::read_dir(dir) else {\n return;\n };\n\n for entry in entries.flatten() {\n let path = entry.path();\n let Ok(ft) = entry.file_type() else {\n continue;\n };\n\n if !ft.is_dir() {\n continue;\n }\n\n let name = path.file_name().and_then(OsStr::to_str).unwrap_or_default();\n if name == \".git\" {\n if let Some(parent) = path.parent() {\n out.insert(parent.to_path_buf());\n }\n continue;\n }\n\n if name == \"node_modules\" || name == \"target\" {\n continue;\n }\n\n collect_repo_roots(&path, depth + 1, max_depth, out);\n }\n}\n\nfn scan_roots(opts: &GitignoreScanOpts, policy: &GitignorePolicy) -> Vec<PathBuf> {\n if let Some(root) = opts.root.as_deref() {\n return vec![expand_home(root)];\n }\n\n if !policy.repos_roots.is_empty() {\n return policy.repos_roots.clone();\n }\n\n vec![expand_home(DEFAULT_REPOS_ROOT)]\n}\n\nfn blocked_lookup(policy: &GitignorePolicy) -> Vec<(String, String)> {\n policy\n .blocked_patterns\n .iter()\n .filter_map(|p| normalize_entry(p).map(|norm| (norm, p.trim().to_string())))\n .collect()\n}\n\nfn clean_patterns<I>(patterns: I) -> Vec<String>\nwhere\n I: Iterator<Item = String>,\n{\n patterns\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n .collect()\n}\n\nfn normalize_entry(line: &str) -> Option<String> {\n let trimmed = line.trim();\n if trimmed.is_empty() || trimmed.starts_with('#') {\n return None;\n }\n\n let content = if let Some((head, _)) = trimmed.split_once(\" #\") {\n head.trim()\n } else {\n trimmed\n };\n\n let normalized = content.trim_start_matches('/').trim();\n if normalized.is_empty() {\n return None;\n }\n\n Some(normalized.to_string())\n}\n\nfn parse_hunk_new_line(hunk: &str) -> Option<usize> {\n let plus = hunk.find('+')?;\n let after_plus = &hunk[plus + 1..];\n let digits: String = after_plus\n .chars()\n .take_while(|c| c.is_ascii_digit())\n .collect();\n digits.parse::<usize>().ok()\n}\n\nfn repo_origin_owner(repo_root: &Path) -> Option<String> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"remote\", \"get-url\", \"origin\"])\n .output()\n .ok()?;\n\n if !output.status.success() {\n return None;\n }\n\n let url = String::from_utf8_lossy(&output.stdout);\n parse_github_owner(url.trim())\n}\n\nfn parse_github_owner(url: &str) -> Option<String> {\n let trimmed = url.trim().trim_end_matches('/');\n\n if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n let repo = rest.trim_end_matches(\".git\");\n return repo.split('/').next().map(|s| s.to_string());\n }\n\n if let Some(rest) = trimmed.strip_prefix(\"https://github.com/\") {\n let repo = rest.trim_end_matches(\".git\");\n return repo.split('/').next().map(|s| s.to_string());\n }\n\n None\n}\n\nfn policy_override_enabled() -> bool {\n env::var(POLICY_OVERRIDE_ENV)\n .ok()\n .map(|v| {\n let v = v.trim().to_ascii_lowercase();\n v == \"1\" || v == \"true\" || v == \"yes\"\n })\n .unwrap_or(false)\n}\n\nfn expand_home(input: &str) -> PathBuf {\n let trimmed = input.trim();\n if trimmed == \"~\" {\n return home_dir_or_default();\n }\n if let Some(rest) = trimmed.strip_prefix(\"~/\") {\n return home_dir_or_default().join(rest);\n }\n PathBuf::from(trimmed)\n}\n\nfn home_dir_or_default() -> PathBuf {\n dirs::home_dir().unwrap_or_else(|| PathBuf::from(\".\"))\n}\n\nfn default_policy_template() -> String {\n format!(\n \"# Flow gitignore policy\\n#\\n# These patterns are local developer tooling noise and should stay out of\\n# external/public repositories.\\n\\nblocked_patterns = [\\n \\\"{}\\\",\\n \\\"{}\\\",\\n \\\"{}\\\",\\n]\\n\\n# Repositories owned by these GitHub users are treated as internal and exempt.\\nallowed_owners = [\\n \\\"{}\\\",\\n]\\n\\n# Roots scanned by `f gitignore audit` and `f gitignore fix` when --root is omitted.\\nrepos_roots = [\\n \\\"{}\\\",\\n]\\n\",\n DEFAULT_BLOCKED_PATTERNS[0],\n DEFAULT_BLOCKED_PATTERNS[1],\n DEFAULT_BLOCKED_PATTERNS[2],\n DEFAULT_ALLOWED_OWNERS[0],\n DEFAULT_REPOS_ROOT,\n )\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn normalize_entry_ignores_comments_and_slashes() {\n assert_eq!(normalize_entry(\"/.beads/\"), Some(\".beads/\".to_string()));\n assert_eq!(\n normalize_entry(\".rise/ # local\"),\n Some(\".rise/\".to_string())\n );\n assert_eq!(normalize_entry(\"# note\"), None);\n }\n\n #[test]\n fn parse_github_owner_from_remote_url() {\n assert_eq!(\n parse_github_owner(\"https://github.com/pqrs-org/Karabiner-Elements.git\"),\n Some(\"pqrs-org\".to_string())\n );\n assert_eq!(\n parse_github_owner(\"git@github.com:nikivdev/Karabiner-Elements.git\"),\n Some(\"nikivdev\".to_string())\n );\n }\n}\n" }, { "path": "src/hash.rs", "content": "use std::env;\nuse std::io::IsTerminal;\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::HashOpts;\nuse crate::env as flow_env;\n\nconst LINK_PREFIX: &str = \"unstash./\";\n\npub fn run(opts: HashOpts) -> Result<()> {\n if opts.args.is_empty() {\n bail!(\"Usage: f hash <paths or unhash args>\");\n }\n\n let unhash_bin = which::which(\"unhash\")\n .context(\"unhash not found on PATH. Run `f deploy-unhash` in the unhash repo.\")?;\n\n let mut cmd = Command::new(unhash_bin);\n cmd.args(&opts.args);\n\n if env::var(\"UNHASH_KEY\").is_err() {\n if let Ok(Some(value)) = flow_env::get_personal_env_var(\"UNHASH_KEY\") {\n cmd.env(\"UNHASH_KEY\", value);\n }\n }\n\n let output = cmd.output().context(\"failed to run unhash\")?;\n if !output.status.success() {\n let stdout = String::from_utf8_lossy(&output.stdout);\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"unhash failed: {}\\n{}{}\", output.status, stdout, stderr);\n }\n\n let stdout = String::from_utf8_lossy(&output.stdout);\n let mut lines = stdout.lines().filter(|line| !line.trim().is_empty());\n let hash = lines\n .next()\n .ok_or_else(|| anyhow::anyhow!(\"unhash output missing hash\"))?\n .trim()\n .to_string();\n\n let link = format!(\"{LINK_PREFIX}{hash}\");\n copy_to_clipboard(&link)?;\n\n println!(\"{hash}\");\n println!(\"{link}\");\n\n if let Some(path_line) = lines.next() {\n println!(\"{}\", path_line.trim());\n }\n\n Ok(())\n}\n\nfn copy_to_clipboard(text: &str) -> Result<()> {\n if std::env::var(\"FLOW_NO_CLIPBOARD\").is_ok() || !std::io::stdin().is_terminal() {\n return Ok(());\n }\n #[cfg(target_os = \"macos\")]\n {\n let mut child = Command::new(\"pbcopy\")\n .stdin(std::process::Stdio::piped())\n .spawn()\n .context(\"failed to spawn pbcopy\")?;\n\n if let Some(stdin) = child.stdin.as_mut() {\n use std::io::Write;\n stdin.write_all(text.as_bytes())?;\n }\n\n child.wait()?;\n }\n\n #[cfg(target_os = \"linux\")]\n {\n let result = Command::new(\"xclip\")\n .arg(\"-selection\")\n .arg(\"clipboard\")\n .stdin(std::process::Stdio::piped())\n .spawn();\n\n let mut child = match result {\n Ok(c) => c,\n Err(_) => Command::new(\"xsel\")\n .arg(\"--clipboard\")\n .arg(\"--input\")\n .stdin(std::process::Stdio::piped())\n .spawn()\n .context(\"failed to spawn xclip or xsel\")?,\n };\n\n if let Some(stdin) = child.stdin.as_mut() {\n use std::io::Write;\n stdin.write_all(text.as_bytes())?;\n }\n\n child.wait()?;\n }\n\n #[cfg(not(any(target_os = \"macos\", target_os = \"linux\")))]\n {\n bail!(\"clipboard not supported on this platform\");\n }\n\n Ok(())\n}\n" }, { "path": "src/health.rs", "content": "use std::collections::HashMap;\nuse std::env;\nuse std::fs;\nuse std::path::PathBuf;\nuse std::process::Command;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result, bail};\nuse base64::{Engine as _, engine::general_purpose::STANDARD as BASE64_STD};\n\nuse crate::cli::HealthOpts;\nuse crate::config;\nuse crate::doctor;\nuse crate::env as flow_env;\nuse crate::http_client;\nuse crate::setup::add_gitignore_entry;\n\npub fn run(_opts: HealthOpts) -> Result<()> {\n println!(\"Running flow health checks...\\n\");\n\n ensure_run_layout()?;\n ensure_fish_shell()?;\n ensure_fish_flow_init()?;\n ensure_gitignore()?;\n\n doctor::run(crate::cli::DoctorOpts {})?;\n ensure_ai_server()?;\n ensure_unhash()?;\n ensure_rise_health()?;\n ensure_linsa_base_health()?;\n ensure_zerg_ai_health()?;\n\n println!(\"\\n✅ flow health checks passed.\");\n Ok(())\n}\n\nfn ensure_run_layout() -> Result<()> {\n let run_root = config::expand_path(\"~/run\");\n let run_internal = run_root.join(\"i\");\n\n if !run_root.exists() {\n fs::create_dir_all(&run_root)\n .with_context(|| format!(\"failed to create {}\", run_root.display()))?;\n println!(\"✅ created run root: {}\", run_root.display());\n } else {\n println!(\"✅ run root ready: {}\", run_root.display());\n }\n\n if !run_internal.exists() {\n fs::create_dir_all(&run_internal)\n .with_context(|| format!(\"failed to create {}\", run_internal.display()))?;\n println!(\"✅ created internal run root: {}\", run_internal.display());\n } else {\n println!(\"✅ internal run root ready: {}\", run_internal.display());\n }\n\n if run_root.join(\"flow.toml\").exists() {\n println!(\"✅ run public repo detected\");\n } else {\n println!(\"ℹ️ run public repo not detected at {}\", run_root.display());\n }\n\n if run_internal.join(\"flow.toml\").exists() {\n println!(\"✅ run internal repo detected\");\n } else {\n println!(\n \"ℹ️ run internal repo not detected at {}\",\n run_internal.display()\n );\n }\n\n println!(\n \"ℹ️ run shortcuts: f r <task>, f ri <task>, f rp <project> <task>, f rip <project> <task>\"\n );\n\n Ok(())\n}\n\nfn ensure_fish_shell() -> Result<()> {\n let shell = env::var(\"SHELL\").unwrap_or_default();\n if !shell.contains(\"fish\") {\n let fish = which::which(\"fish\")\n .context(\"fish is required; install it and ensure it is on PATH\")?;\n bail!(\"fish shell required. Run:\\n chsh -s {}\", fish.display());\n }\n Ok(())\n}\n\nfn ensure_fish_flow_init() -> Result<()> {\n let config_path = fish_config_path()?;\n let content = fs::read_to_string(&config_path).unwrap_or_default();\n if content.contains(\"# flow:start\") {\n return Ok(());\n }\n\n println!(\n \"⚠ flow fish integration missing in {}. Run: f shell-init fish\",\n config_path.display()\n );\n Ok(())\n}\n\nfn ensure_gitignore() -> Result<()> {\n let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\"));\n let Some(flow_path) = find_flow_toml_upwards(&cwd) else {\n return Ok(());\n };\n let root = flow_path.parent().unwrap_or(&cwd);\n\n if !root.join(\".git\").exists() {\n return Ok(());\n }\n\n add_gitignore_entry(root, \".ai/todos/*.bike\")?;\n add_gitignore_entry(root, \".ai/review-log.jsonl\")?;\n Ok(())\n}\n\nfn ensure_ai_server() -> Result<()> {\n let keys = config::global_env_keys();\n let mut resolved: HashMap<String, String> = HashMap::new();\n let mut missing = Vec::new();\n\n for key in &keys {\n if let Ok(value) = env::var(key) {\n if !value.trim().is_empty() {\n resolved.insert(key.clone(), value);\n continue;\n }\n }\n missing.push(key.clone());\n }\n\n if !missing.is_empty() {\n if let Ok(vars) = flow_env::fetch_personal_env_vars(&missing) {\n for (key, value) in vars {\n if !value.trim().is_empty() {\n resolved.insert(key, value);\n }\n }\n }\n }\n\n let url = resolved.get(\"AI_SERVER_URL\").cloned().unwrap_or_default();\n let model = resolved.get(\"AI_SERVER_MODEL\").cloned().unwrap_or_default();\n let token = resolved.get(\"AI_SERVER_TOKEN\").cloned().unwrap_or_default();\n\n if url.trim().is_empty() {\n println!(\"⚠️ AI server env not configured (AI_SERVER_URL).\");\n println!(\" Set it once: f env set --personal AI_SERVER_URL=http://127.0.0.1:7331\");\n return Ok(());\n }\n\n let base = base_ai_url(&url);\n let client = http_client::blocking_with_timeout(Duration::from_millis(800))\n .context(\"failed to create http client\")?;\n\n let health_url = format!(\"{}/health\", base);\n let mut ok = client\n .get(&health_url)\n .send()\n .map(|resp| resp.status().is_success())\n .unwrap_or(false);\n\n if !ok {\n let models_url = format!(\"{}/v1/models\", base);\n ok = client\n .get(&models_url)\n .send()\n .map(|resp| resp.status().is_success())\n .unwrap_or(false);\n }\n\n if ok {\n println!(\"✅ AI server reachable at {}\", base);\n } else {\n println!(\"⚠️ AI server not reachable at {}\", base);\n println!(\" Start it with your ai server repo (e.g. f daemon start ai-server).\");\n }\n\n if model.trim().is_empty() {\n println!(\n \"⚠️ AI_SERVER_MODEL not set. Example: f env set --personal AI_SERVER_MODEL=zai-glm-4.7\"\n );\n }\n\n if token.trim().is_empty() {\n println!(\"ℹ️ AI_SERVER_TOKEN not set (ok if server is open).\");\n }\n\n Ok(())\n}\n\nfn ensure_unhash() -> Result<()> {\n match which::which(\"unhash\") {\n Ok(path) => {\n println!(\"✅ unhash binary found at {}\", path.display());\n }\n Err(_) => {\n println!(\"⚠️ unhash not found on PATH.\");\n println!(\" Install with: cd ~/code/unhash && f deploy\");\n return Ok(());\n }\n }\n\n let key = env::var(\"UNHASH_KEY\").ok().filter(|v| !v.trim().is_empty());\n let key = match key {\n Some(value) => Some(value),\n None => flow_env::get_personal_env_var(\"UNHASH_KEY\").ok().flatten(),\n };\n\n match key {\n Some(value) => {\n if is_valid_unhash_key(&value) {\n println!(\"✅ UNHASH_KEY configured (env or flow env)\");\n } else {\n println!(\"⚠️ UNHASH_KEY is invalid (expected 32-byte base64 or hex).\");\n println!(\" Fix with: unhash keygen | f env set UNHASH_KEY=...\");\n }\n }\n None => {\n println!(\"⚠️ UNHASH_KEY not set.\");\n println!(\" Run: unhash health --setup\");\n }\n }\n\n Ok(())\n}\n\nfn ensure_rise_health() -> Result<()> {\n let rise_bin = match which::which(\"rise\") {\n Ok(path) => path,\n Err(_) => {\n println!(\"ℹ️ rise not installed; skipping.\");\n return Ok(());\n }\n };\n\n let rise_root = config::expand_path(\"~/code/rise\");\n if !rise_root.exists() {\n println!(\n \"ℹ️ rise repo not found at {}; skipping.\",\n rise_root.display()\n );\n return Ok(());\n }\n\n let supports_health = Command::new(&rise_bin)\n .arg(\"help\")\n .output()\n .ok()\n .and_then(|output| {\n let mut combined = String::from_utf8_lossy(&output.stdout).to_string();\n combined.push_str(&String::from_utf8_lossy(&output.stderr));\n Some(combined.contains(\"rise health\"))\n })\n .unwrap_or(false);\n\n if !supports_health {\n println!(\"ℹ️ rise health not available; skipping.\");\n return Ok(());\n }\n\n let status = Command::new(&rise_bin)\n .arg(\"health\")\n .current_dir(&rise_root)\n .status();\n\n match status {\n Ok(status) if status.success() => {\n println!(\"✅ rise health ok\");\n }\n Ok(status) => {\n println!(\n \"⚠️ rise health failed (exit {}).\",\n status.code().unwrap_or(-1)\n );\n }\n Err(err) => {\n println!(\"⚠️ failed to run rise health: {}\", err);\n }\n }\n\n Ok(())\n}\n\nfn ensure_linsa_base_health() -> Result<()> {\n let base_root = config::expand_path(\"~/code/org/linsa/base\");\n if !base_root.exists() {\n println!(\"ℹ️ ~/code/org/linsa/base not installed; skipping.\");\n return Ok(());\n }\n\n if base_root.join(\"flow.toml\").exists() {\n println!(\"✅ linsa/base found at {}\", base_root.display());\n } else {\n println!(\n \"⚠️ linsa/base found but flow.toml missing: {}\",\n base_root.display()\n );\n }\n\n Ok(())\n}\n\nfn ensure_zerg_ai_health() -> Result<()> {\n let zerg_root = config::expand_path(\"~/code/zerg/ai\");\n if !zerg_root.exists() {\n println!(\"ℹ️ ~/code/zerg/ai not installed; skipping.\");\n return Ok(());\n }\n\n let url = env::var(\"ZERG_AI_URL\")\n .ok()\n .filter(|v| !v.trim().is_empty())\n .or_else(|| {\n env::var(\"AI_SERVER_URL\")\n .ok()\n .filter(|v| !v.trim().is_empty())\n })\n .unwrap_or_else(|| \"http://127.0.0.1:7331\".to_string());\n\n let base = base_ai_url(&url);\n let client = http_client::blocking_with_timeout(Duration::from_millis(800))\n .context(\"failed to create http client\")?;\n\n let health_url = format!(\"{}/health\", base);\n let ok = client\n .get(&health_url)\n .send()\n .map(|resp| resp.status().is_success())\n .unwrap_or(false);\n\n if ok {\n println!(\"✅ zerg/ai reachable at {}\", base);\n } else {\n println!(\"⚠️ zerg/ai not reachable at {}\", base);\n }\n\n Ok(())\n}\n\nfn is_valid_unhash_key(raw: &str) -> bool {\n if let Ok(bytes) = BASE64_STD.decode(raw.trim()) {\n if bytes.len() == 32 {\n return true;\n }\n }\n if let Some(bytes) = decode_hex(raw.trim()) {\n if bytes.len() == 32 {\n return true;\n }\n }\n false\n}\n\nfn decode_hex(input: &str) -> Option<Vec<u8>> {\n let bytes = input.as_bytes();\n if bytes.len() % 2 != 0 {\n return None;\n }\n let mut out = Vec::with_capacity(bytes.len() / 2);\n let mut i = 0;\n while i < bytes.len() {\n let hi = hex_value(bytes[i])?;\n let lo = hex_value(bytes[i + 1])?;\n out.push((hi << 4) | lo);\n i += 2;\n }\n Some(out)\n}\n\nfn hex_value(byte: u8) -> Option<u8> {\n match byte {\n b'0'..=b'9' => Some(byte - b'0'),\n b'a'..=b'f' => Some(byte - b'a' + 10),\n b'A'..=b'F' => Some(byte - b'A' + 10),\n _ => None,\n }\n}\n\nfn base_ai_url(url: &str) -> String {\n let trimmed = url.trim_end_matches('/');\n if let Some(idx) = trimmed.find(\"/v1/\") {\n return trimmed[..idx].to_string();\n }\n trimmed.to_string()\n}\n\nfn find_flow_toml_upwards(start: &PathBuf) -> Option<PathBuf> {\n let mut current = start.as_path();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n current = current.parent()?;\n }\n}\n\nfn fish_config_path() -> Result<PathBuf> {\n let home = dirs::home_dir().context(\"failed to resolve home directory\")?;\n Ok(home.join(\"config\").join(\"fish\").join(\"config.fish\"))\n}\n" }, { "path": "src/help_full.json", "content": "{\"version\":\"0.1.3\",\"entries\":[{\"command\":\"f search\",\"short\":null,\"long\":null,\"description\":\"Fuzzy search global commands/tasks without a project flow.toml.\",\"entry_type\":\"subcommand\"},{\"command\":\"f global\",\"short\":null,\"long\":null,\"description\":\"Run tasks from the global flow config.\",\"entry_type\":\"subcommand\"},{\"command\":\"f global\",\"short\":\"-l\",\"long\":\"--list\",\"description\":\"List global tasks\",\"entry_type\":\"flag\"},{\"command\":\"f global list\",\"short\":null,\"long\":null,\"description\":\"List global tasks\",\"entry_type\":\"subcommand\"},{\"command\":\"f global run\",\"short\":null,\"long\":null,\"description\":\"Run a global task by name\",\"entry_type\":\"subcommand\"},{\"command\":\"f global match\",\"short\":null,\"long\":null,\"description\":\"Match a query against global tasks (LM Studio)\",\"entry_type\":\"subcommand\"},{\"command\":\"f global match\",\"short\":null,\"long\":\"--model\",\"description\":\"LM Studio model to use (defaults to qwen3-8b)\",\"entry_type\":\"flag\"},{\"command\":\"f global match\",\"short\":null,\"long\":\"--port\",\"description\":\"LM Studio API port (defaults to 1234)\",\"entry_type\":\"flag\"},{\"command\":\"f global match\",\"short\":\"-n\",\"long\":\"--dry-run\",\"description\":\"Only show the match without running the task\",\"entry_type\":\"flag\"},{\"command\":\"f hub\",\"short\":null,\"long\":null,\"description\":\"Ensure the background hub daemon is running (spawns it if missing).\",\"entry_type\":\"subcommand\"},{\"command\":\"f hub\",\"short\":null,\"long\":\"--host\",\"description\":\"Hostname or IP address of the hub daemon\",\"entry_type\":\"flag\"},{\"command\":\"f hub\",\"short\":null,\"long\":\"--port\",\"description\":\"TCP port for the daemon's HTTP interface\",\"entry_type\":\"flag\"},{\"command\":\"f hub\",\"short\":null,\"long\":\"--config\",\"description\":\"Optional path to the lin hub config (defaults to lin's built-in lookup)\",\"entry_type\":\"flag\"},{\"command\":\"f hub\",\"short\":null,\"long\":\"--no-ui\",\"description\":\"Skip launching the hub TUI after ensuring the daemon is running\",\"entry_type\":\"flag\"},{\"command\":\"f hub\",\"short\":null,\"long\":\"--docs-hub\",\"description\":\"Also start the docs hub (Next.js dev server)\",\"entry_type\":\"flag\"},{\"command\":\"f hub start\",\"short\":null,\"long\":null,\"description\":\"Start or ensure the hub daemon is running\",\"entry_type\":\"subcommand\"},{\"command\":\"f hub stop\",\"short\":null,\"long\":null,\"description\":\"Stop the hub daemon if it was started by flow\",\"entry_type\":\"subcommand\"},{\"command\":\"f init\",\"short\":null,\"long\":null,\"description\":\"Scaffold a new flow.toml in the current directory.\",\"entry_type\":\"subcommand\"},{\"command\":\"f init\",\"short\":null,\"long\":\"--path\",\"description\":\"Where to write the scaffolded flow.toml (defaults to ./flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f shell-init\",\"short\":null,\"long\":null,\"description\":\"Output shell integration script.\",\"entry_type\":\"subcommand\"},{\"command\":\"f shell\",\"short\":null,\"long\":null,\"description\":\"Manage shell integration.\",\"entry_type\":\"subcommand\"},{\"command\":\"f shell reset\",\"short\":null,\"long\":null,\"description\":\"Refresh the current shell session\",\"entry_type\":\"subcommand\"},{\"command\":\"f shell fix-terminal\",\"short\":null,\"long\":null,\"description\":\"Disable fish terminal query to avoid PDA warning\",\"entry_type\":\"subcommand\"},{\"command\":\"f new\",\"short\":null,\"long\":null,\"description\":\"Create a new project from a template.\",\"entry_type\":\"subcommand\"},{\"command\":\"f new\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show what would change without writing\",\"entry_type\":\"flag\"},{\"command\":\"f home\",\"short\":null,\"long\":null,\"description\":\"Home setup and config repo management.\",\"entry_type\":\"subcommand\"},{\"command\":\"f home\",\"short\":null,\"long\":\"--internal\",\"description\":\"Optional internal config repo URL (cloned into ~/config/i)\",\"entry_type\":\"flag\"},{\"command\":\"f home setup\",\"short\":null,\"long\":null,\"description\":\"Guide home setup and validate GitHub access\",\"entry_type\":\"subcommand\"},{\"command\":\"f archive\",\"short\":null,\"long\":null,\"description\":\"Archive the current project to ~/archive/code.\",\"entry_type\":\"subcommand\"},{\"command\":\"f doctor\",\"short\":null,\"long\":null,\"description\":\"Verify required tools and shell integrations.\",\"entry_type\":\"subcommand\"},{\"command\":\"f health\",\"short\":null,\"long\":null,\"description\":\"Ensure your system matches Flow's expectations.\",\"entry_type\":\"subcommand\"},{\"command\":\"f invariants\",\"short\":null,\"long\":null,\"description\":\"Check project invariants from flow.toml against working tree or staged changes.\",\"entry_type\":\"subcommand\"},{\"command\":\"f invariants\",\"short\":null,\"long\":\"--staged\",\"description\":\"Only check staged changes (default: check all changes vs HEAD)\",\"entry_type\":\"flag\"},{\"command\":\"f tasks\",\"short\":null,\"long\":null,\"description\":\"Fuzzy search task history or list available tasks.\",\"entry_type\":\"subcommand\"},{\"command\":\"f tasks list\",\"short\":null,\"long\":null,\"description\":\"List tasks from the current project flow.toml\",\"entry_type\":\"subcommand\"},{\"command\":\"f tasks list\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f tasks list\",\"short\":null,\"long\":\"--dupes\",\"description\":\"Show only duplicate task names and their scopes\",\"entry_type\":\"flag\"},{\"command\":\"f tasks dupes\",\"short\":null,\"long\":null,\"description\":\"Show duplicate task names discovered across nested flow.toml files\",\"entry_type\":\"subcommand\"},{\"command\":\"f tasks dupes\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f tasks init-ai\",\"short\":null,\"long\":null,\"description\":\"Initialize AI task directory with a MoonBit starter task\",\"entry_type\":\"subcommand\"},{\"command\":\"f tasks init-ai\",\"short\":null,\"long\":\"--root\",\"description\":\"Root directory where .ai/tasks should be created\",\"entry_type\":\"flag\"},{\"command\":\"f tasks init-ai\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite starter file if it already exists\",\"entry_type\":\"flag\"},{\"command\":\"f tasks build-ai\",\"short\":null,\"long\":null,\"description\":\"Prebuild and cache a specific AI task binary\",\"entry_type\":\"subcommand\"},{\"command\":\"f tasks build-ai\",\"short\":null,\"long\":\"--root\",\"description\":\"Root directory used for .ai/tasks discovery\",\"entry_type\":\"flag\"},{\"command\":\"f tasks build-ai\",\"short\":null,\"long\":\"--force\",\"description\":\"Force rebuild even if a cached artifact exists\",\"entry_type\":\"flag\"},{\"command\":\"f tasks run-ai\",\"short\":null,\"long\":null,\"description\":\"Run a specific AI task with optional cache/daemon execution\",\"entry_type\":\"subcommand\"},{\"command\":\"f tasks run-ai\",\"short\":null,\"long\":\"--root\",\"description\":\"Root directory used for .ai/tasks discovery\",\"entry_type\":\"flag\"},{\"command\":\"f tasks run-ai\",\"short\":null,\"long\":\"--daemon\",\"description\":\"Run through the AI task daemon\",\"entry_type\":\"flag\"},{\"command\":\"f tasks run-ai\",\"short\":null,\"long\":\"--no-cache\",\"description\":\"Disable binary cache and use direct moon run\",\"entry_type\":\"flag\"},{\"command\":\"f tasks daemon\",\"short\":null,\"long\":null,\"description\":\"Manage the AI task daemon\",\"entry_type\":\"subcommand\"},{\"command\":\"f tasks daemon start\",\"short\":null,\"long\":null,\"description\":\"Start task daemon in the background\",\"entry_type\":\"subcommand\"},{\"command\":\"f tasks daemon stop\",\"short\":null,\"long\":null,\"description\":\"Stop task daemon\",\"entry_type\":\"subcommand\"},{\"command\":\"f tasks daemon status\",\"short\":null,\"long\":null,\"description\":\"Show task daemon status\",\"entry_type\":\"subcommand\"},{\"command\":\"f fast\",\"short\":null,\"long\":null,\"description\":\"Run an AI task via the low-latency fast client path.\",\"entry_type\":\"subcommand\"},{\"command\":\"f fast\",\"short\":null,\"long\":\"--root\",\"description\":\"Root directory used for .ai/tasks discovery\",\"entry_type\":\"flag\"},{\"command\":\"f fast\",\"short\":null,\"long\":\"--no-cache\",\"description\":\"Disable binary cache and use direct moon run\",\"entry_type\":\"flag\"},{\"command\":\"f up\",\"short\":null,\"long\":null,\"description\":\"Bring a project up using lifecycle conventions.\",\"entry_type\":\"subcommand\"},{\"command\":\"f up\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f down\",\"short\":null,\"long\":null,\"description\":\"Bring a project down using lifecycle conventions.\",\"entry_type\":\"subcommand\"},{\"command\":\"f down\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f ai-test-new\",\"short\":null,\"long\":null,\"description\":\"Create a local AI scratch test file under .ai/test.\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai-test-new\",\"short\":null,\"long\":\"--dir\",\"description\":\"Base scratch test directory, relative to project root\",\"entry_type\":\"flag\"},{\"command\":\"f ai-test-new\",\"short\":null,\"long\":\"--spec\",\"description\":\"Use `.spec.ts` instead of `.test.ts`\",\"entry_type\":\"flag\"},{\"command\":\"f ai-test-new\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite existing file if present\",\"entry_type\":\"flag\"},{\"command\":\"f last-cmd\",\"short\":null,\"long\":null,\"description\":\"Show the last task input and its output/error.\",\"entry_type\":\"subcommand\"},{\"command\":\"f last-cmd-full\",\"short\":null,\"long\":null,\"description\":\"Show the last task run (command, status, and output) recorded by flow.\",\"entry_type\":\"subcommand\"},{\"command\":\"f fish-last\",\"short\":null,\"long\":null,\"description\":\"Show the last fish shell command and output (from fish io-trace).\",\"entry_type\":\"subcommand\"},{\"command\":\"f fish-last-full\",\"short\":null,\"long\":null,\"description\":\"Show full details of the last fish shell command.\",\"entry_type\":\"subcommand\"},{\"command\":\"f fish-install\",\"short\":null,\"long\":null,\"description\":\"Install traced fish shell (fish fork with always-on I/O tracing).\",\"entry_type\":\"subcommand\"},{\"command\":\"f fish-install\",\"short\":null,\"long\":\"--source\",\"description\":\"Path to fish-shell source repo (auto-detected if not set)\",\"entry_type\":\"flag\"},{\"command\":\"f fish-install\",\"short\":null,\"long\":\"--bin-dir\",\"description\":\"Install directory for the fish binary (defaults to ~/.local/bin)\",\"entry_type\":\"flag\"},{\"command\":\"f fish-install\",\"short\":null,\"long\":\"--force\",\"description\":\"Force reinstall even if already installed\",\"entry_type\":\"flag\"},{\"command\":\"f fish-install\",\"short\":\"-y\",\"long\":\"--yes\",\"description\":\"Skip confirmation prompt\",\"entry_type\":\"flag\"},{\"command\":\"f rerun\",\"short\":null,\"long\":null,\"description\":\"Re-run the last task executed in this project.\",\"entry_type\":\"subcommand\"},{\"command\":\"f rerun\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f ps\",\"short\":null,\"long\":null,\"description\":\"List running flow processes for the current project.\",\"entry_type\":\"subcommand\"},{\"command\":\"f ps\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f ps\",\"short\":null,\"long\":\"--all\",\"description\":\"Show all running flow processes across all projects\",\"entry_type\":\"flag\"},{\"command\":\"f kill\",\"short\":null,\"long\":null,\"description\":\"Stop running flow processes.\",\"entry_type\":\"subcommand\"},{\"command\":\"f kill\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f kill\",\"short\":null,\"long\":\"--pid\",\"description\":\"Kill by PID directly\",\"entry_type\":\"flag\"},{\"command\":\"f kill\",\"short\":null,\"long\":\"--all\",\"description\":\"Kill all processes for this project\",\"entry_type\":\"flag\"},{\"command\":\"f kill\",\"short\":\"-f\",\"long\":\"--force\",\"description\":\"Force kill (SIGKILL) without graceful shutdown\",\"entry_type\":\"flag\"},{\"command\":\"f kill\",\"short\":null,\"long\":\"--timeout\",\"description\":\"Timeout in seconds before sending SIGKILL (default: 5)\",\"entry_type\":\"flag\"},{\"command\":\"f logs\",\"short\":null,\"long\":null,\"description\":\"View logs from running or recent tasks.\",\"entry_type\":\"subcommand\"},{\"command\":\"f logs\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f logs\",\"short\":\"-f\",\"long\":\"--follow\",\"description\":\"Follow the log in real-time (like tail -f)\",\"entry_type\":\"flag\"},{\"command\":\"f logs\",\"short\":\"-n\",\"long\":\"--lines\",\"description\":\"Number of lines to show from the end\",\"entry_type\":\"flag\"},{\"command\":\"f logs\",\"short\":null,\"long\":\"--all\",\"description\":\"Show logs for all projects\",\"entry_type\":\"flag\"},{\"command\":\"f logs\",\"short\":\"-l\",\"long\":\"--list\",\"description\":\"List available log files instead of showing content\",\"entry_type\":\"flag\"},{\"command\":\"f logs\",\"short\":\"-p\",\"long\":\"--project\",\"description\":\"Look up logs by registered project name instead of config path\",\"entry_type\":\"flag\"},{\"command\":\"f logs\",\"short\":\"-q\",\"long\":\"--quiet\",\"description\":\"Suppress headers, output only log content\",\"entry_type\":\"flag\"},{\"command\":\"f logs\",\"short\":null,\"long\":\"--task-id\",\"description\":\"Hub task ID to fetch logs for (from delegated tasks)\",\"entry_type\":\"flag\"},{\"command\":\"f trace\",\"short\":null,\"long\":null,\"description\":\"Quick traces for AI + task runs from jazz2 state.\",\"entry_type\":\"subcommand\"},{\"command\":\"f trace\",\"short\":\"-n\",\"long\":\"--limit\",\"description\":\"Max rows per source (default: 40)\",\"entry_type\":\"flag\"},{\"command\":\"f trace\",\"short\":\"-f\",\"long\":\"--follow\",\"description\":\"Follow and stream new entries\",\"entry_type\":\"flag\"},{\"command\":\"f trace\",\"short\":null,\"long\":\"--project\",\"description\":\"Filter by project path substring\",\"entry_type\":\"flag\"},{\"command\":\"f trace\",\"short\":null,\"long\":\"--source\",\"description\":\"Which source to show: all, tasks, ai\",\"entry_type\":\"flag\"},{\"command\":\"f trace session\",\"short\":null,\"long\":null,\"description\":\"Show full history of the last active AI session for a project path\",\"entry_type\":\"subcommand\"},{\"command\":\"f analytics\",\"short\":null,\"long\":null,\"description\":\"Manage anonymous usage analytics preferences and local queue.\",\"entry_type\":\"subcommand\"},{\"command\":\"f analytics status\",\"short\":null,\"long\":null,\"description\":\"Show analytics status and queue metadata\",\"entry_type\":\"subcommand\"},{\"command\":\"f analytics enable\",\"short\":null,\"long\":null,\"description\":\"Enable anonymous usage analytics\",\"entry_type\":\"subcommand\"},{\"command\":\"f analytics disable\",\"short\":null,\"long\":null,\"description\":\"Disable anonymous usage analytics\",\"entry_type\":\"subcommand\"},{\"command\":\"f analytics export\",\"short\":null,\"long\":null,\"description\":\"Print queued analytics events\",\"entry_type\":\"subcommand\"},{\"command\":\"f analytics purge\",\"short\":null,\"long\":null,\"description\":\"Delete all queued analytics events\",\"entry_type\":\"subcommand\"},{\"command\":\"f projects\",\"short\":null,\"long\":null,\"description\":\"List registered projects.\",\"entry_type\":\"subcommand\"},{\"command\":\"f sessions\",\"short\":null,\"long\":null,\"description\":\"Fuzzy search AI sessions across all projects and copy context.\",\"entry_type\":\"subcommand\"},{\"command\":\"f sessions\",\"short\":\"-p\",\"long\":\"--provider\",\"description\":\"Filter by provider (claude, codex, cursor, or all)\",\"entry_type\":\"flag\"},{\"command\":\"f sessions\",\"short\":\"-c\",\"long\":\"--count\",\"description\":\"Number of exchanges to copy (default: all since checkpoint)\",\"entry_type\":\"flag\"},{\"command\":\"f sessions\",\"short\":\"-l\",\"long\":\"--list\",\"description\":\"Show sessions but don't copy to clipboard\",\"entry_type\":\"flag\"},{\"command\":\"f sessions\",\"short\":\"-f\",\"long\":\"--full\",\"description\":\"Get full session context, ignoring checkpoints\",\"entry_type\":\"flag\"},{\"command\":\"f sessions\",\"short\":null,\"long\":\"--summarize\",\"description\":\"Generate summaries for stale sessions (uses Gemini)\",\"entry_type\":\"flag\"},{\"command\":\"f sessions\",\"short\":null,\"long\":\"--handoff\",\"description\":\"Condense the selected session into a handoff summary (uses Gemini)\",\"entry_type\":\"flag\"},{\"command\":\"f active\",\"short\":null,\"long\":null,\"description\":\"Show or set the active project.\",\"entry_type\":\"subcommand\"},{\"command\":\"f active\",\"short\":\"-c\",\"long\":\"--clear\",\"description\":\"Clear the active project\",\"entry_type\":\"flag\"},{\"command\":\"f server\",\"short\":null,\"long\":null,\"description\":\"Start the flow HTTP server for log ingestion and queries.\",\"entry_type\":\"subcommand\"},{\"command\":\"f server\",\"short\":null,\"long\":\"--host\",\"description\":\"Host to bind the server to\",\"entry_type\":\"flag\"},{\"command\":\"f server\",\"short\":null,\"long\":\"--port\",\"description\":\"Port for the HTTP server\",\"entry_type\":\"flag\"},{\"command\":\"f server foreground\",\"short\":null,\"long\":null,\"description\":\"Start the server in the foreground\",\"entry_type\":\"subcommand\"},{\"command\":\"f server stop\",\"short\":null,\"long\":null,\"description\":\"Stop the background server\",\"entry_type\":\"subcommand\"},{\"command\":\"f web\",\"short\":null,\"long\":null,\"description\":\"Open the Flow web UI for this project.\",\"entry_type\":\"subcommand\"},{\"command\":\"f web\",\"short\":null,\"long\":\"--port\",\"description\":\"Port to serve the web UI on\",\"entry_type\":\"flag\"},{\"command\":\"f web\",\"short\":null,\"long\":\"--host\",\"description\":\"Host to bind the web UI server to\",\"entry_type\":\"flag\"},{\"command\":\"f match\",\"short\":null,\"long\":null,\"description\":\"Match a natural language query to a task using LM Studio.\",\"entry_type\":\"subcommand\"},{\"command\":\"f match\",\"short\":null,\"long\":\"--model\",\"description\":\"LM Studio model to use (defaults to qwen3-8b)\",\"entry_type\":\"flag\"},{\"command\":\"f match\",\"short\":null,\"long\":\"--port\",\"description\":\"LM Studio API port (defaults to 1234)\",\"entry_type\":\"flag\"},{\"command\":\"f match\",\"short\":\"-n\",\"long\":\"--dry-run\",\"description\":\"Only show the match without running the task\",\"entry_type\":\"flag\"},{\"command\":\"f ask\",\"short\":null,\"long\":null,\"description\":\"Ask the AI server to suggest a task or Flow command.\",\"entry_type\":\"subcommand\"},{\"command\":\"f ask\",\"short\":null,\"long\":\"--model\",\"description\":\"AI server model to use (defaults to AI_SERVER_MODEL)\",\"entry_type\":\"flag\"},{\"command\":\"f ask\",\"short\":null,\"long\":\"--url\",\"description\":\"AI server URL (defaults to AI_SERVER_URL or http://127.0.0.1:7331)\",\"entry_type\":\"flag\"},{\"command\":\"f branches\",\"short\":null,\"long\":null,\"description\":\"List and search git branches quickly.\",\"entry_type\":\"subcommand\"},{\"command\":\"f branches list\",\"short\":null,\"long\":null,\"description\":\"List recent branches\",\"entry_type\":\"subcommand\"},{\"command\":\"f branches list\",\"short\":null,\"long\":\"--remote\",\"description\":\"Include remote branches\",\"entry_type\":\"flag\"},{\"command\":\"f branches list\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of branches to show\",\"entry_type\":\"flag\"},{\"command\":\"f branches find\",\"short\":null,\"long\":null,\"description\":\"Find branches by substring or token query\",\"entry_type\":\"subcommand\"},{\"command\":\"f branches find\",\"short\":null,\"long\":\"--remote\",\"description\":\"Include remote branches\",\"entry_type\":\"flag\"},{\"command\":\"f branches find\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of matches to show\",\"entry_type\":\"flag\"},{\"command\":\"f branches find\",\"short\":null,\"long\":\"--switch\",\"description\":\"Switch to the top match automatically\",\"entry_type\":\"flag\"},{\"command\":\"f branches ai\",\"short\":null,\"long\":null,\"description\":\"Use AI to map a natural language query to the best branch\",\"entry_type\":\"subcommand\"},{\"command\":\"f branches ai\",\"short\":null,\"long\":\"--remote\",\"description\":\"Include remote branches\",\"entry_type\":\"flag\"},{\"command\":\"f branches ai\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum candidate branches to send to AI\",\"entry_type\":\"flag\"},{\"command\":\"f branches ai\",\"short\":null,\"long\":\"--model\",\"description\":\"AI server model to use (defaults to AI_SERVER_MODEL)\",\"entry_type\":\"flag\"},{\"command\":\"f branches ai\",\"short\":null,\"long\":\"--url\",\"description\":\"AI server URL (defaults to AI_SERVER_URL or http://127.0.0.1:7331)\",\"entry_type\":\"flag\"},{\"command\":\"f branches ai\",\"short\":null,\"long\":\"--switch\",\"description\":\"Switch to the selected branch automatically\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":null,\"description\":\"AI-powered commit with code review and optional GitEdit sync.\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit\",\"short\":\"-n\",\"long\":\"--no-push\",\"description\":\"Skip pushing after commit\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--queue\",\"description\":\"Queue the commit for review before pushing\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--no-queue\",\"description\":\"Bypass commit queue and allow pushing immediately\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--force\",\"description\":\"Force commit without queue (bypass stacked review)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--approved\",\"description\":\"Commit and push immediately (bypass commit queue)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--review\",\"description\":\"Open the queued commit in Rise for review after commit\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--sync\",\"description\":\"Run synchronously (don't delegate to hub)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--context\",\"description\":\"Include AI session context in code review (default: off)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--hashed\",\"description\":\"Include an unhash.sh bundle/link in the commit message (opt-in)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--dry\",\"description\":\"Dry run: show context that would be passed to review without committing\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--quick\",\"description\":\"Commit immediately and run Codex review asynchronously in the background\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--slow\",\"description\":\"Run blocking review before committing (legacy commitWithCheck behavior)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--codex\",\"description\":\"Use Codex instead of Claude for code review (default: Claude)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--review-model\",\"description\":\"Choose a specific review model (claude-opus, codex-high, codex-mini)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":\"-m\",\"long\":\"--message\",\"description\":\"Custom message to include in commit (appended after author line)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--fast\",\"description\":\"Fast commit with optional message (defaults to \\\".\\\")\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--path\",\"description\":\"Stage and commit only these paths (repeatable)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":\"-t\",\"long\":\"--tokens\",\"description\":\"Max tokens for AI session context (default: 1000)\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--skip-quality\",\"description\":\"Skip all quality gates for this commit\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--skip-docs\",\"description\":\"Skip documentation requirements only\",\"entry_type\":\"flag\"},{\"command\":\"f commit\",\"short\":null,\"long\":\"--skip-tests\",\"description\":\"Skip test requirements only\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue\",\"short\":null,\"long\":null,\"description\":\"Manage the commit review queue.\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue list\",\"short\":null,\"long\":null,\"description\":\"List queued commits\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue show\",\"short\":null,\"long\":null,\"description\":\"Show details for a queued commit\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue open\",\"short\":null,\"long\":null,\"description\":\"Open the queued commit diff in Rise app (multi-file diff UI)\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue diff\",\"short\":null,\"long\":null,\"description\":\"Print the full diff for a queued commit to stdout\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue review\",\"short\":null,\"long\":null,\"description\":\"Re-run AI review for queued commits and refresh queue/todo metadata\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue review\",\"short\":null,\"long\":\"--all\",\"description\":\"Review all queued commits across branches\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue approve\",\"short\":null,\"long\":null,\"description\":\"Approve a queued commit and push it\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue approve\",\"short\":null,\"long\":\"--all\",\"description\":\"Approve all queued commits on the current branch (push once)\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue approve\",\"short\":null,\"long\":\"--queue-if-missing\",\"description\":\"If hash is not queued but exists in git history, queue it first\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue approve\",\"short\":null,\"long\":\"--mark-reviewed\",\"description\":\"Mark an auto-queued commit as manually reviewed\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue approve\",\"short\":\"-f\",\"long\":\"--force\",\"description\":\"Push even if the commit is not at HEAD\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue approve\",\"short\":null,\"long\":\"--allow-issues\",\"description\":\"Allow pushing even if the queued commit has review issues recorded\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue approve\",\"short\":null,\"long\":\"--allow-unreviewed\",\"description\":\"Allow pushing even if the review timed out or is missing\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue approve-all\",\"short\":null,\"long\":null,\"description\":\"Approve all queued commits on the current branch (push once)\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue approve-all\",\"short\":\"-f\",\"long\":\"--force\",\"description\":\"Push even if the branch is behind its remote\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue approve-all\",\"short\":null,\"long\":\"--allow-issues\",\"description\":\"Allow pushing even if some queued commits have review issues recorded\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue approve-all\",\"short\":null,\"long\":\"--allow-unreviewed\",\"description\":\"Allow pushing even if some queued commits have review timed out / missing\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue drop\",\"short\":null,\"long\":null,\"description\":\"Remove a commit from the queue without pushing\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue pr-create\",\"short\":null,\"long\":null,\"description\":\"Create or update a GitHub PR for a queued commit (pushes a bookmark/branch as the PR head)\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue pr-create\",\"short\":null,\"long\":\"--base\",\"description\":\"Base branch for the PR (default: main)\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue pr-create\",\"short\":null,\"long\":\"--draft\",\"description\":\"Create as a draft PR\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue pr-create\",\"short\":null,\"long\":\"--open\",\"description\":\"Open PR in browser after creating/finding it\",\"entry_type\":\"flag\"},{\"command\":\"f commit-queue pr-open\",\"short\":null,\"long\":null,\"description\":\"Open the PR for a queued commit in the browser (creates it if missing)\",\"entry_type\":\"subcommand\"},{\"command\":\"f commit-queue pr-open\",\"short\":null,\"long\":\"--base\",\"description\":\"Base branch for the PR if it needs to be created (default: main)\",\"entry_type\":\"flag\"},{\"command\":\"f reviews-todo\",\"short\":null,\"long\":null,\"description\":\"Manage deferred deep-review todos for queued commits.\",\"entry_type\":\"subcommand\"},{\"command\":\"f reviews-todo list\",\"short\":null,\"long\":null,\"description\":\"List pending review todos with priority indicators\",\"entry_type\":\"subcommand\"},{\"command\":\"f reviews-todo show\",\"short\":null,\"long\":null,\"description\":\"Show details for a review todo\",\"entry_type\":\"subcommand\"},{\"command\":\"f reviews-todo done\",\"short\":null,\"long\":null,\"description\":\"Mark a review todo as resolved\",\"entry_type\":\"subcommand\"},{\"command\":\"f reviews-todo fix\",\"short\":null,\"long\":null,\"description\":\"Auto-fix a review todo via Codex\",\"entry_type\":\"subcommand\"},{\"command\":\"f reviews-todo fix\",\"short\":null,\"long\":\"--all\",\"description\":\"Fix all open review todos\",\"entry_type\":\"flag\"},{\"command\":\"f reviews-todo codex\",\"short\":null,\"long\":null,\"description\":\"Run Codex deep review for queued commits\",\"entry_type\":\"subcommand\"},{\"command\":\"f reviews-todo codex\",\"short\":null,\"long\":\"--all\",\"description\":\"Review all queued commits across branches\",\"entry_type\":\"flag\"},{\"command\":\"f reviews-todo approve-all\",\"short\":null,\"long\":null,\"description\":\"Approve all queued commits once deep review todos are resolved\",\"entry_type\":\"subcommand\"},{\"command\":\"f reviews-todo approve-all\",\"short\":\"-f\",\"long\":\"--force\",\"description\":\"Push even if the branch is behind its remote\",\"entry_type\":\"flag\"},{\"command\":\"f reviews-todo approve-all\",\"short\":null,\"long\":\"--allow-issues\",\"description\":\"Allow pushing even if some queued commits have review issues recorded\",\"entry_type\":\"flag\"},{\"command\":\"f reviews-todo approve-all\",\"short\":null,\"long\":\"--allow-unreviewed\",\"description\":\"Allow pushing even if some queued commits have review timed out / missing\",\"entry_type\":\"flag\"},{\"command\":\"f pr\",\"short\":null,\"long\":null,\"description\":\"Create a GitHub PR from current changes or a queued commit.\",\"entry_type\":\"subcommand\"},{\"command\":\"f pr\",\"short\":null,\"long\":\"--base\",\"description\":\"Base branch for the PR (default: main)\",\"entry_type\":\"flag\"},{\"command\":\"f pr\",\"short\":null,\"long\":\"--draft\",\"description\":\"Create as a draft PR\",\"entry_type\":\"flag\"},{\"command\":\"f pr\",\"short\":null,\"long\":\"--no-open\",\"description\":\"Do not open the PR in browser after creating/finding it\",\"entry_type\":\"flag\"},{\"command\":\"f pr\",\"short\":null,\"long\":\"--no-commit\",\"description\":\"Skip creating a new commit; use an existing queued commit\",\"entry_type\":\"flag\"},{\"command\":\"f pr\",\"short\":null,\"long\":\"--hash\",\"description\":\"Specific queued commit hash to use (short or full)\",\"entry_type\":\"flag\"},{\"command\":\"f pr\",\"short\":null,\"long\":\"--path\",\"description\":\"Stage and commit only these paths before creating PR (repeatable)\",\"entry_type\":\"flag\"},{\"command\":\"f gitignore\",\"short\":null,\"long\":null,\"description\":\"Manage personal tooling ignore policy across repos.\",\"entry_type\":\"subcommand\"},{\"command\":\"f gitignore audit\",\"short\":null,\"long\":null,\"description\":\"Audit .gitignore files for blocked personal-tooling patterns\",\"entry_type\":\"subcommand\"},{\"command\":\"f gitignore audit\",\"short\":null,\"long\":\"--root\",\"description\":\"Root directory to scan for repositories (defaults to policy repos_roots, then ~/repos)\",\"entry_type\":\"flag\"},{\"command\":\"f gitignore audit\",\"short\":null,\"long\":\"--all\",\"description\":\"Include repos owned by allowed owners\",\"entry_type\":\"flag\"},{\"command\":\"f gitignore fix\",\"short\":null,\"long\":null,\"description\":\"Remove blocked personal-tooling patterns from .gitignore files\",\"entry_type\":\"subcommand\"},{\"command\":\"f gitignore fix\",\"short\":null,\"long\":\"--root\",\"description\":\"Root directory to scan for repositories (defaults to policy repos_roots, then ~/repos)\",\"entry_type\":\"flag\"},{\"command\":\"f gitignore fix\",\"short\":null,\"long\":\"--all\",\"description\":\"Include repos owned by allowed owners\",\"entry_type\":\"flag\"},{\"command\":\"f gitignore policy-init\",\"short\":null,\"long\":null,\"description\":\"Create ~/.config/flow/gitignore-policy.toml with defaults\",\"entry_type\":\"subcommand\"},{\"command\":\"f gitignore policy-init\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite an existing policy file\",\"entry_type\":\"flag\"},{\"command\":\"f gitignore setup-global\",\"short\":null,\"long\":null,\"description\":\"Configure a global git excludes file with blocked personal-tooling patterns\",\"entry_type\":\"subcommand\"},{\"command\":\"f gitignore setup-global\",\"short\":null,\"long\":\"--print-only\",\"description\":\"Print target path/entries without writing changes\",\"entry_type\":\"flag\"},{\"command\":\"f gitignore policy-path\",\"short\":null,\"long\":null,\"description\":\"Print the active policy file path\",\"entry_type\":\"subcommand\"},{\"command\":\"f review\",\"short\":null,\"long\":null,\"description\":\"Open queued commits for review in Rise.\",\"entry_type\":\"subcommand\"},{\"command\":\"f review latest\",\"short\":null,\"long\":null,\"description\":\"Open the latest queued commit in Rise\",\"entry_type\":\"subcommand\"},{\"command\":\"f review copy\",\"short\":null,\"long\":null,\"description\":\"Copy a ready-to-send review prompt for a queued commit to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f undo\",\"short\":null,\"long\":null,\"description\":\"Undo the last undoable action (commit, push).\",\"entry_type\":\"subcommand\"},{\"command\":\"f undo\",\"short\":\"-n\",\"long\":\"--dry-run\",\"description\":\"Dry run - show what would be undone without doing it\",\"entry_type\":\"flag\"},{\"command\":\"f undo\",\"short\":\"-f\",\"long\":\"--force\",\"description\":\"Force undo even if it requires force push\",\"entry_type\":\"flag\"},{\"command\":\"f undo show\",\"short\":null,\"long\":null,\"description\":\"Show the last undoable action\",\"entry_type\":\"subcommand\"},{\"command\":\"f undo list\",\"short\":null,\"long\":null,\"description\":\"List recent undoable actions\",\"entry_type\":\"subcommand\"},{\"command\":\"f undo list\",\"short\":\"-l\",\"long\":\"--limit\",\"description\":\"Maximum number of actions to show\",\"entry_type\":\"flag\"},{\"command\":\"f fix\",\"short\":null,\"long\":null,\"description\":\"Fix issues in the repo with help from Hive.\",\"entry_type\":\"subcommand\"},{\"command\":\"f fix\",\"short\":null,\"long\":\"--no-unroll\",\"description\":\"Skip unrolling the last commit\",\"entry_type\":\"flag\"},{\"command\":\"f fix\",\"short\":null,\"long\":\"--stash\",\"description\":\"Stash local changes before unrolling, then restore after\",\"entry_type\":\"flag\"},{\"command\":\"f fix\",\"short\":null,\"long\":\"--agent\",\"description\":\"Hive agent name to run (default: shell)\",\"entry_type\":\"flag\"},{\"command\":\"f fix\",\"short\":null,\"long\":\"--no-agent\",\"description\":\"Skip running Hive agent (only unroll)\",\"entry_type\":\"flag\"},{\"command\":\"f fixup\",\"short\":null,\"long\":null,\"description\":\"Fix common TOML syntax errors in flow.toml.\",\"entry_type\":\"subcommand\"},{\"command\":\"f fixup\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the flow.toml to fix (defaults to ./flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f fixup\",\"short\":\"-n\",\"long\":\"--dry-run\",\"description\":\"Only show what would be fixed without making changes\",\"entry_type\":\"flag\"},{\"command\":\"f changes\",\"short\":null,\"long\":null,\"description\":\"Share or apply git diffs without remotes.\",\"entry_type\":\"subcommand\"},{\"command\":\"f changes current-diff\",\"short\":null,\"long\":null,\"description\":\"Print the current git diff for sharing.\",\"entry_type\":\"subcommand\"},{\"command\":\"f changes accept\",\"short\":null,\"long\":null,\"description\":\"Apply a diff to the current repo.\",\"entry_type\":\"subcommand\"},{\"command\":\"f changes accept\",\"short\":\"-f\",\"long\":\"--file\",\"description\":\"Read diff from a file path\",\"entry_type\":\"flag\"},{\"command\":\"f diff\",\"short\":null,\"long\":null,\"description\":\"Create or unpack a shareable diff bundle.\",\"entry_type\":\"subcommand\"},{\"command\":\"f diff\",\"short\":null,\"long\":\"--env\",\"description\":\"Include specific env vars from local personal env store. Examples: --env CEREBRAS_API_KEY --env CEREBRAS_MODEL --env CEREBRAS_API_KEY,CEREBRAS_MODEL --env='[\\\\\\\"CEREBRAS_API_KEY\\\\\\\",\\\\\\\"CEREBRAS_MODEL\\\\\\\"]'\",\"entry_type\":\"flag\"},{\"command\":\"f hash\",\"short\":null,\"long\":null,\"description\":\"Hash files or sessions with unhash and copy a share link.\",\"entry_type\":\"subcommand\"},{\"command\":\"f daemon\",\"short\":null,\"long\":null,\"description\":\"Manage background daemons (start, stop, status).\",\"entry_type\":\"subcommand\"},{\"command\":\"f daemon start\",\"short\":null,\"long\":null,\"description\":\"Start a daemon by name\",\"entry_type\":\"subcommand\"},{\"command\":\"f daemon stop\",\"short\":null,\"long\":null,\"description\":\"Stop a running daemon\",\"entry_type\":\"subcommand\"},{\"command\":\"f daemon restart\",\"short\":null,\"long\":null,\"description\":\"Restart a daemon (stop then start)\",\"entry_type\":\"subcommand\"},{\"command\":\"f daemon status\",\"short\":null,\"long\":null,\"description\":\"Show status of all configured daemons\",\"entry_type\":\"subcommand\"},{\"command\":\"f daemon list\",\"short\":null,\"long\":null,\"description\":\"List available daemons\",\"entry_type\":\"subcommand\"},{\"command\":\"f supervisor\",\"short\":null,\"long\":null,\"description\":\"Run the Flow supervisor (daemon manager).\",\"entry_type\":\"subcommand\"},{\"command\":\"f supervisor\",\"short\":null,\"long\":\"--socket\",\"description\":\"Socket path for supervisor IPC (defaults to ~/.config/flow/supervisor.sock)\",\"entry_type\":\"flag\"},{\"command\":\"f supervisor start\",\"short\":null,\"long\":null,\"description\":\"Start the supervisor in the background\",\"entry_type\":\"subcommand\"},{\"command\":\"f supervisor start\",\"short\":null,\"long\":\"--boot\",\"description\":\"Start boot daemons in addition to autostart daemons\",\"entry_type\":\"flag\"},{\"command\":\"f supervisor run\",\"short\":null,\"long\":null,\"description\":\"Run the supervisor in the foreground (blocking)\",\"entry_type\":\"subcommand\"},{\"command\":\"f supervisor run\",\"short\":null,\"long\":\"--boot\",\"description\":\"Start boot daemons in addition to autostart daemons\",\"entry_type\":\"flag\"},{\"command\":\"f supervisor install\",\"short\":null,\"long\":null,\"description\":\"Install a macOS LaunchAgent to keep the supervisor running\",\"entry_type\":\"subcommand\"},{\"command\":\"f supervisor install\",\"short\":null,\"long\":\"--boot\",\"description\":\"Start boot daemons in addition to autostart daemons\",\"entry_type\":\"flag\"},{\"command\":\"f supervisor uninstall\",\"short\":null,\"long\":null,\"description\":\"Remove the macOS LaunchAgent for the supervisor\",\"entry_type\":\"subcommand\"},{\"command\":\"f supervisor stop\",\"short\":null,\"long\":null,\"description\":\"Stop the supervisor if running\",\"entry_type\":\"subcommand\"},{\"command\":\"f supervisor status\",\"short\":null,\"long\":null,\"description\":\"Show supervisor status\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai\",\"short\":null,\"long\":null,\"description\":\"Manage AI coding sessions (Claude Code).\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai list\",\"short\":null,\"long\":null,\"description\":\"List all AI sessions for this project (Claude + Codex + Cursor)\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor\",\"short\":null,\"long\":null,\"description\":\"Cursor: inspect and read agent transcripts for this project\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor list\",\"short\":null,\"long\":null,\"description\":\"List sessions for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor latest-id\",\"short\":null,\"long\":null,\"description\":\"Print the most recent session ID for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor latest-id\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor sessions\",\"short\":null,\"long\":null,\"description\":\"List provider sessions with IDs\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor sessions\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor sessions\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor continue\",\"short\":null,\"long\":null,\"description\":\"Continue the most recent session for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor continue\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to continue from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor new\",\"short\":null,\"long\":null,\"description\":\"Start a new session (ignores existing sessions)\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor resume\",\"short\":null,\"long\":null,\"description\":\"Resume a session\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor resume\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resume from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor connect\",\"short\":null,\"long\":null,\"description\":\"Connect to an existing Codex session selected by natural-language query\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor connect\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to search instead of the configured Codex home-session path\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor connect\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor connect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON for the selected session instead of resuming it\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor open\",\"short\":null,\"long\":null,\"description\":\"Open a Codex session with fast repo-scoped recovery and reference unrolling\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor open\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to open from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor open\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor resolve\",\"short\":null,\"long\":null,\"description\":\"Resolve how `f codex open` would interpret a query\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor resolve\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resolve from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor resolve\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor resolve\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor doctor\",\"short\":null,\"long\":null,\"description\":\"Print effective Codex control-plane settings for this path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor doctor\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor doctor\",\"short\":null,\"long\":\"--assert-runtime\",\"description\":\"Exit non-zero unless wrapper transport and runtime skills are active\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor doctor\",\"short\":null,\"long\":\"--assert-schedule\",\"description\":\"Exit non-zero unless the scheduled scorecard refresher is installed and loaded\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor doctor\",\"short\":null,\"long\":\"--assert-learning\",\"description\":\"Exit non-zero unless Flow has grounded learning data for this target\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor doctor\",\"short\":null,\"long\":\"--assert-autonomous\",\"description\":\"Exit non-zero unless runtime, schedule, and grounded learning are all active\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor doctor\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor eval\",\"short\":null,\"long\":null,\"description\":\"Evaluate how well Flow-guided Codex usage is working for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor eval\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor eval\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent logged events/outcomes to inspect\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor eval\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor enable-global\",\"short\":null,\"long\":null,\"description\":\"Enable the global Codex wrapper/runtime path so Flow features are actually used\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor enable-global\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show the resulting global config and actions without writing anything\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor enable-global\",\"short\":null,\"long\":\"--install-launchd\",\"description\":\"Also install the macOS launchd scorecard refresher\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor enable-global\",\"short\":null,\"long\":\"--start-daemon\",\"description\":\"Start codexd immediately after enabling the global config\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor enable-global\",\"short\":null,\"long\":\"--sync-skills\",\"description\":\"Sync any discovered external skill sources after enabling the config\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor enable-global\",\"short\":null,\"long\":\"--full\",\"description\":\"Shortcut for --install-launchd --start-daemon --sync-skills\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor enable-global\",\"short\":null,\"long\":\"--minutes\",\"description\":\"Launchd cadence in minutes (used with --install-launchd/--full)\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor enable-global\",\"short\":null,\"long\":\"--limit\",\"description\":\"Max logged events to scan per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor enable-global\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Max repos to rebuild per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor enable-global\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Recent-history window for launchd cron selection\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor daemon\",\"short\":null,\"long\":null,\"description\":\"Manage the Flow codexd query daemon\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor daemon start\",\"short\":null,\"long\":null,\"description\":\"Start codexd under Flow supervision\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor daemon stop\",\"short\":null,\"long\":null,\"description\":\"Stop codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor daemon restart\",\"short\":null,\"long\":null,\"description\":\"Restart codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor daemon status\",\"short\":null,\"long\":null,\"description\":\"Show codexd status\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor memory\",\"short\":null,\"long\":null,\"description\":\"Inspect or sync the Jazz2-backed Codex memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor memory status\",\"short\":null,\"long\":null,\"description\":\"Show memory mirror status and counts\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor memory status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor memory sync\",\"short\":null,\"long\":null,\"description\":\"Sync recent Codex skill-eval logs into the Jazz2-backed memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor memory sync\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events and outcomes to ingest\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor memory sync\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor memory query\",\"short\":null,\"long\":null,\"description\":\"Query compact repo/code memory facts for a path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor memory query\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to query\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor memory query\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of fact hits to include\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor memory query\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor memory recent\",\"short\":null,\"long\":null,\"description\":\"Show recent memory rows, optionally scoped to a repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor memory recent\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor memory recent\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of rows to print\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor memory recent\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor telemetry\",\"short\":null,\"long\":null,\"description\":\"Export redacted Codex workflow telemetry to configured Maple endpoints\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor telemetry status\",\"short\":null,\"long\":null,\"description\":\"Show Codex telemetry export config and current forwarder state\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor telemetry status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor telemetry flush\",\"short\":null,\"long\":null,\"description\":\"Flush recently logged Codex telemetry to configured Maple endpoints once\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor telemetry flush\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of unseen events/outcomes to export in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor telemetry flush\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor trace\",\"short\":null,\"long\":null,\"description\":\"Inspect Flow-managed Codex traces for the current or a specific session\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor trace status\",\"short\":null,\"long\":null,\"description\":\"Show Maple trace read status and configured credentials\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor trace status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor trace current-session\",\"short\":null,\"long\":null,\"description\":\"Inspect the trace associated with the active Flow-managed Codex session\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor trace current-session\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor trace current-session\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor trace inspect\",\"short\":null,\"long\":null,\"description\":\"Inspect a specific trace id\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor trace inspect\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor trace inspect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval\",\"short\":null,\"long\":null,\"description\":\"Build and inspect local Codex skill scorecards from Flow history\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor skill-eval run\",\"short\":null,\"long\":null,\"description\":\"Rebuild the local scorecard for this repo/path from recent Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor skill-eval run\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval run\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events to use when rebuilding\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval run\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval show\",\"short\":null,\"long\":null,\"description\":\"Show the current scorecard for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor skill-eval show\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval show\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval events\",\"short\":null,\"long\":null,\"description\":\"Show recent logged skill-eval events\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor skill-eval events\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval events\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of events to print\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval events\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval cron\",\"short\":null,\"long\":null,\"description\":\"Refresh scorecards for the most recent repos seen in Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor skill-eval cron\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of logged events to scan for target repos\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval cron\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Maximum number of repo targets to rebuild in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval cron\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Only consider repos seen within this many recent hours\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-eval cron\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-source\",\"short\":null,\"long\":null,\"description\":\"Discover and sync external Codex skill sources\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor skill-source list\",\"short\":null,\"long\":null,\"description\":\"List discovered external skills available for Codex runtime injection\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor skill-source list\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-source list\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-source sync\",\"short\":null,\"long\":null,\"description\":\"Copy discovered external skills into ~/.codex/skills for persistent use\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor skill-source sync\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-source sync\",\"short\":null,\"long\":\"--skill\",\"description\":\"Restrict sync to the named discovered skills\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor skill-source sync\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite an existing ~/.codex/skills/<name> directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor runtime\",\"short\":null,\"long\":null,\"description\":\"Inspect or manage Flow-managed Codex runtime helpers\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor runtime show\",\"short\":null,\"long\":null,\"description\":\"Show recent Flow-managed Codex runtime skill activations\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor runtime clear\",\"short\":null,\"long\":null,\"description\":\"Remove Flow-managed runtime skill state and stale symlinks\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor runtime write-plan\",\"short\":null,\"long\":null,\"description\":\"Write a markdown plan to ~/plan and print the final path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor runtime write-plan\",\"short\":null,\"long\":\"--title\",\"description\":\"Human-readable title used to derive the filename\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor runtime write-plan\",\"short\":null,\"long\":\"--stem\",\"description\":\"Explicit filename stem to use instead of deriving from the title\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor runtime write-plan\",\"short\":null,\"long\":\"--dir\",\"description\":\"Destination directory (defaults to ~/plan)\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor runtime write-plan\",\"short\":null,\"long\":\"--source-session\",\"description\":\"Codex session id to append as a footer (defaults to $CODEX_THREAD_ID)\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor find\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and resume the best match\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor find\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor find\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor findAndCopy\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and copy the best match to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor findAndCopy\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor findAndCopy\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor copy\",\"short\":null,\"long\":null,\"description\":\"Copy session history to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor context\",\"short\":null,\"long\":null,\"description\":\"Copy last prompt and response to clipboard (for context passing). Usage: f ai claude context [session] [path] [count]\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor show\",\"short\":null,\"long\":null,\"description\":\"Print a cleaned session excerpt to stdout\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor show\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to project directory (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor show\",\"short\":null,\"long\":\"--count\",\"description\":\"Number of exchanges to include (default: 12)\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor show\",\"short\":null,\"long\":\"--full\",\"description\":\"Print the full cleaned transcript instead of just the trailing exchanges\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor recover\",\"short\":null,\"long\":null,\"description\":\"Recover recent Codex session context for a repo or subpath\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai cursor recover\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to recover context for (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor recover\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor recover\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of candidate sessions to return\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor recover\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai cursor recover\",\"short\":null,\"long\":\"--summary-only\",\"description\":\"Emit only the compact recovery summary for prompt injection\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude\",\"short\":null,\"long\":null,\"description\":\"Claude Code: continue last session or start new one\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude list\",\"short\":null,\"long\":null,\"description\":\"List sessions for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude latest-id\",\"short\":null,\"long\":null,\"description\":\"Print the most recent session ID for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude latest-id\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude sessions\",\"short\":null,\"long\":null,\"description\":\"List provider sessions with IDs\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude sessions\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude sessions\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude continue\",\"short\":null,\"long\":null,\"description\":\"Continue the most recent session for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude continue\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to continue from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude new\",\"short\":null,\"long\":null,\"description\":\"Start a new session (ignores existing sessions)\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude resume\",\"short\":null,\"long\":null,\"description\":\"Resume a session\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude resume\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resume from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude connect\",\"short\":null,\"long\":null,\"description\":\"Connect to an existing Codex session selected by natural-language query\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude connect\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to search instead of the configured Codex home-session path\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude connect\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude connect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON for the selected session instead of resuming it\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude open\",\"short\":null,\"long\":null,\"description\":\"Open a Codex session with fast repo-scoped recovery and reference unrolling\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude open\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to open from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude open\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude resolve\",\"short\":null,\"long\":null,\"description\":\"Resolve how `f codex open` would interpret a query\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude resolve\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resolve from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude resolve\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude resolve\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude doctor\",\"short\":null,\"long\":null,\"description\":\"Print effective Codex control-plane settings for this path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude doctor\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude doctor\",\"short\":null,\"long\":\"--assert-runtime\",\"description\":\"Exit non-zero unless wrapper transport and runtime skills are active\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude doctor\",\"short\":null,\"long\":\"--assert-schedule\",\"description\":\"Exit non-zero unless the scheduled scorecard refresher is installed and loaded\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude doctor\",\"short\":null,\"long\":\"--assert-learning\",\"description\":\"Exit non-zero unless Flow has grounded learning data for this target\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude doctor\",\"short\":null,\"long\":\"--assert-autonomous\",\"description\":\"Exit non-zero unless runtime, schedule, and grounded learning are all active\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude doctor\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude eval\",\"short\":null,\"long\":null,\"description\":\"Evaluate how well Flow-guided Codex usage is working for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude eval\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude eval\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent logged events/outcomes to inspect\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude eval\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude enable-global\",\"short\":null,\"long\":null,\"description\":\"Enable the global Codex wrapper/runtime path so Flow features are actually used\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude enable-global\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show the resulting global config and actions without writing anything\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude enable-global\",\"short\":null,\"long\":\"--install-launchd\",\"description\":\"Also install the macOS launchd scorecard refresher\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude enable-global\",\"short\":null,\"long\":\"--start-daemon\",\"description\":\"Start codexd immediately after enabling the global config\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude enable-global\",\"short\":null,\"long\":\"--sync-skills\",\"description\":\"Sync any discovered external skill sources after enabling the config\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude enable-global\",\"short\":null,\"long\":\"--full\",\"description\":\"Shortcut for --install-launchd --start-daemon --sync-skills\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude enable-global\",\"short\":null,\"long\":\"--minutes\",\"description\":\"Launchd cadence in minutes (used with --install-launchd/--full)\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude enable-global\",\"short\":null,\"long\":\"--limit\",\"description\":\"Max logged events to scan per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude enable-global\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Max repos to rebuild per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude enable-global\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Recent-history window for launchd cron selection\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude daemon\",\"short\":null,\"long\":null,\"description\":\"Manage the Flow codexd query daemon\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude daemon start\",\"short\":null,\"long\":null,\"description\":\"Start codexd under Flow supervision\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude daemon stop\",\"short\":null,\"long\":null,\"description\":\"Stop codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude daemon restart\",\"short\":null,\"long\":null,\"description\":\"Restart codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude daemon status\",\"short\":null,\"long\":null,\"description\":\"Show codexd status\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude memory\",\"short\":null,\"long\":null,\"description\":\"Inspect or sync the Jazz2-backed Codex memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude memory status\",\"short\":null,\"long\":null,\"description\":\"Show memory mirror status and counts\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude memory status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude memory sync\",\"short\":null,\"long\":null,\"description\":\"Sync recent Codex skill-eval logs into the Jazz2-backed memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude memory sync\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events and outcomes to ingest\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude memory sync\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude memory query\",\"short\":null,\"long\":null,\"description\":\"Query compact repo/code memory facts for a path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude memory query\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to query\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude memory query\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of fact hits to include\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude memory query\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude memory recent\",\"short\":null,\"long\":null,\"description\":\"Show recent memory rows, optionally scoped to a repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude memory recent\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude memory recent\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of rows to print\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude memory recent\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude telemetry\",\"short\":null,\"long\":null,\"description\":\"Export redacted Codex workflow telemetry to configured Maple endpoints\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude telemetry status\",\"short\":null,\"long\":null,\"description\":\"Show Codex telemetry export config and current forwarder state\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude telemetry status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude telemetry flush\",\"short\":null,\"long\":null,\"description\":\"Flush recently logged Codex telemetry to configured Maple endpoints once\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude telemetry flush\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of unseen events/outcomes to export in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude telemetry flush\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude trace\",\"short\":null,\"long\":null,\"description\":\"Inspect Flow-managed Codex traces for the current or a specific session\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude trace status\",\"short\":null,\"long\":null,\"description\":\"Show Maple trace read status and configured credentials\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude trace status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude trace current-session\",\"short\":null,\"long\":null,\"description\":\"Inspect the trace associated with the active Flow-managed Codex session\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude trace current-session\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude trace current-session\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude trace inspect\",\"short\":null,\"long\":null,\"description\":\"Inspect a specific trace id\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude trace inspect\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude trace inspect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval\",\"short\":null,\"long\":null,\"description\":\"Build and inspect local Codex skill scorecards from Flow history\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude skill-eval run\",\"short\":null,\"long\":null,\"description\":\"Rebuild the local scorecard for this repo/path from recent Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude skill-eval run\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval run\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events to use when rebuilding\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval run\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval show\",\"short\":null,\"long\":null,\"description\":\"Show the current scorecard for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude skill-eval show\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval show\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval events\",\"short\":null,\"long\":null,\"description\":\"Show recent logged skill-eval events\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude skill-eval events\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval events\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of events to print\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval events\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval cron\",\"short\":null,\"long\":null,\"description\":\"Refresh scorecards for the most recent repos seen in Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude skill-eval cron\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of logged events to scan for target repos\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval cron\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Maximum number of repo targets to rebuild in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval cron\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Only consider repos seen within this many recent hours\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-eval cron\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-source\",\"short\":null,\"long\":null,\"description\":\"Discover and sync external Codex skill sources\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude skill-source list\",\"short\":null,\"long\":null,\"description\":\"List discovered external skills available for Codex runtime injection\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude skill-source list\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-source list\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-source sync\",\"short\":null,\"long\":null,\"description\":\"Copy discovered external skills into ~/.codex/skills for persistent use\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude skill-source sync\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-source sync\",\"short\":null,\"long\":\"--skill\",\"description\":\"Restrict sync to the named discovered skills\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude skill-source sync\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite an existing ~/.codex/skills/<name> directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude runtime\",\"short\":null,\"long\":null,\"description\":\"Inspect or manage Flow-managed Codex runtime helpers\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude runtime show\",\"short\":null,\"long\":null,\"description\":\"Show recent Flow-managed Codex runtime skill activations\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude runtime clear\",\"short\":null,\"long\":null,\"description\":\"Remove Flow-managed runtime skill state and stale symlinks\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude runtime write-plan\",\"short\":null,\"long\":null,\"description\":\"Write a markdown plan to ~/plan and print the final path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude runtime write-plan\",\"short\":null,\"long\":\"--title\",\"description\":\"Human-readable title used to derive the filename\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude runtime write-plan\",\"short\":null,\"long\":\"--stem\",\"description\":\"Explicit filename stem to use instead of deriving from the title\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude runtime write-plan\",\"short\":null,\"long\":\"--dir\",\"description\":\"Destination directory (defaults to ~/plan)\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude runtime write-plan\",\"short\":null,\"long\":\"--source-session\",\"description\":\"Codex session id to append as a footer (defaults to $CODEX_THREAD_ID)\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude find\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and resume the best match\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude find\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude find\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude findAndCopy\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and copy the best match to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude findAndCopy\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude findAndCopy\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude copy\",\"short\":null,\"long\":null,\"description\":\"Copy session history to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude context\",\"short\":null,\"long\":null,\"description\":\"Copy last prompt and response to clipboard (for context passing). Usage: f ai claude context [session] [path] [count]\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude show\",\"short\":null,\"long\":null,\"description\":\"Print a cleaned session excerpt to stdout\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude show\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to project directory (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude show\",\"short\":null,\"long\":\"--count\",\"description\":\"Number of exchanges to include (default: 12)\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude show\",\"short\":null,\"long\":\"--full\",\"description\":\"Print the full cleaned transcript instead of just the trailing exchanges\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude recover\",\"short\":null,\"long\":null,\"description\":\"Recover recent Codex session context for a repo or subpath\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai claude recover\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to recover context for (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude recover\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude recover\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of candidate sessions to return\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude recover\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai claude recover\",\"short\":null,\"long\":\"--summary-only\",\"description\":\"Emit only the compact recovery summary for prompt injection\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex\",\"short\":null,\"long\":null,\"description\":\"Codex: continue last session or start new one\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex list\",\"short\":null,\"long\":null,\"description\":\"List sessions for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex latest-id\",\"short\":null,\"long\":null,\"description\":\"Print the most recent session ID for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex latest-id\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex sessions\",\"short\":null,\"long\":null,\"description\":\"List provider sessions with IDs\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex sessions\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex sessions\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex continue\",\"short\":null,\"long\":null,\"description\":\"Continue the most recent session for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex continue\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to continue from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex new\",\"short\":null,\"long\":null,\"description\":\"Start a new session (ignores existing sessions)\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex resume\",\"short\":null,\"long\":null,\"description\":\"Resume a session\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex resume\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resume from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex connect\",\"short\":null,\"long\":null,\"description\":\"Connect to an existing Codex session selected by natural-language query\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex connect\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to search instead of the configured Codex home-session path\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex connect\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex connect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON for the selected session instead of resuming it\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex open\",\"short\":null,\"long\":null,\"description\":\"Open a Codex session with fast repo-scoped recovery and reference unrolling\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex open\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to open from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex open\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex resolve\",\"short\":null,\"long\":null,\"description\":\"Resolve how `f codex open` would interpret a query\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex resolve\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resolve from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex resolve\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex resolve\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex doctor\",\"short\":null,\"long\":null,\"description\":\"Print effective Codex control-plane settings for this path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex doctor\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex doctor\",\"short\":null,\"long\":\"--assert-runtime\",\"description\":\"Exit non-zero unless wrapper transport and runtime skills are active\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex doctor\",\"short\":null,\"long\":\"--assert-schedule\",\"description\":\"Exit non-zero unless the scheduled scorecard refresher is installed and loaded\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex doctor\",\"short\":null,\"long\":\"--assert-learning\",\"description\":\"Exit non-zero unless Flow has grounded learning data for this target\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex doctor\",\"short\":null,\"long\":\"--assert-autonomous\",\"description\":\"Exit non-zero unless runtime, schedule, and grounded learning are all active\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex doctor\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex eval\",\"short\":null,\"long\":null,\"description\":\"Evaluate how well Flow-guided Codex usage is working for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex eval\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex eval\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent logged events/outcomes to inspect\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex eval\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex enable-global\",\"short\":null,\"long\":null,\"description\":\"Enable the global Codex wrapper/runtime path so Flow features are actually used\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex enable-global\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show the resulting global config and actions without writing anything\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex enable-global\",\"short\":null,\"long\":\"--install-launchd\",\"description\":\"Also install the macOS launchd scorecard refresher\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex enable-global\",\"short\":null,\"long\":\"--start-daemon\",\"description\":\"Start codexd immediately after enabling the global config\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex enable-global\",\"short\":null,\"long\":\"--sync-skills\",\"description\":\"Sync any discovered external skill sources after enabling the config\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex enable-global\",\"short\":null,\"long\":\"--full\",\"description\":\"Shortcut for --install-launchd --start-daemon --sync-skills\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex enable-global\",\"short\":null,\"long\":\"--minutes\",\"description\":\"Launchd cadence in minutes (used with --install-launchd/--full)\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex enable-global\",\"short\":null,\"long\":\"--limit\",\"description\":\"Max logged events to scan per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex enable-global\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Max repos to rebuild per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex enable-global\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Recent-history window for launchd cron selection\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex daemon\",\"short\":null,\"long\":null,\"description\":\"Manage the Flow codexd query daemon\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex daemon start\",\"short\":null,\"long\":null,\"description\":\"Start codexd under Flow supervision\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex daemon stop\",\"short\":null,\"long\":null,\"description\":\"Stop codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex daemon restart\",\"short\":null,\"long\":null,\"description\":\"Restart codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex daemon status\",\"short\":null,\"long\":null,\"description\":\"Show codexd status\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex memory\",\"short\":null,\"long\":null,\"description\":\"Inspect or sync the Jazz2-backed Codex memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex memory status\",\"short\":null,\"long\":null,\"description\":\"Show memory mirror status and counts\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex memory status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex memory sync\",\"short\":null,\"long\":null,\"description\":\"Sync recent Codex skill-eval logs into the Jazz2-backed memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex memory sync\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events and outcomes to ingest\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex memory sync\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex memory query\",\"short\":null,\"long\":null,\"description\":\"Query compact repo/code memory facts for a path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex memory query\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to query\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex memory query\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of fact hits to include\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex memory query\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex memory recent\",\"short\":null,\"long\":null,\"description\":\"Show recent memory rows, optionally scoped to a repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex memory recent\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex memory recent\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of rows to print\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex memory recent\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex telemetry\",\"short\":null,\"long\":null,\"description\":\"Export redacted Codex workflow telemetry to configured Maple endpoints\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex telemetry status\",\"short\":null,\"long\":null,\"description\":\"Show Codex telemetry export config and current forwarder state\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex telemetry status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex telemetry flush\",\"short\":null,\"long\":null,\"description\":\"Flush recently logged Codex telemetry to configured Maple endpoints once\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex telemetry flush\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of unseen events/outcomes to export in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex telemetry flush\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex trace\",\"short\":null,\"long\":null,\"description\":\"Inspect Flow-managed Codex traces for the current or a specific session\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex trace status\",\"short\":null,\"long\":null,\"description\":\"Show Maple trace read status and configured credentials\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex trace status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex trace current-session\",\"short\":null,\"long\":null,\"description\":\"Inspect the trace associated with the active Flow-managed Codex session\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex trace current-session\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex trace current-session\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex trace inspect\",\"short\":null,\"long\":null,\"description\":\"Inspect a specific trace id\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex trace inspect\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex trace inspect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval\",\"short\":null,\"long\":null,\"description\":\"Build and inspect local Codex skill scorecards from Flow history\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex skill-eval run\",\"short\":null,\"long\":null,\"description\":\"Rebuild the local scorecard for this repo/path from recent Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex skill-eval run\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval run\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events to use when rebuilding\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval run\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval show\",\"short\":null,\"long\":null,\"description\":\"Show the current scorecard for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex skill-eval show\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval show\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval events\",\"short\":null,\"long\":null,\"description\":\"Show recent logged skill-eval events\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex skill-eval events\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval events\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of events to print\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval events\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval cron\",\"short\":null,\"long\":null,\"description\":\"Refresh scorecards for the most recent repos seen in Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex skill-eval cron\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of logged events to scan for target repos\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval cron\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Maximum number of repo targets to rebuild in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval cron\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Only consider repos seen within this many recent hours\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-eval cron\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-source\",\"short\":null,\"long\":null,\"description\":\"Discover and sync external Codex skill sources\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex skill-source list\",\"short\":null,\"long\":null,\"description\":\"List discovered external skills available for Codex runtime injection\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex skill-source list\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-source list\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-source sync\",\"short\":null,\"long\":null,\"description\":\"Copy discovered external skills into ~/.codex/skills for persistent use\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex skill-source sync\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-source sync\",\"short\":null,\"long\":\"--skill\",\"description\":\"Restrict sync to the named discovered skills\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex skill-source sync\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite an existing ~/.codex/skills/<name> directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex runtime\",\"short\":null,\"long\":null,\"description\":\"Inspect or manage Flow-managed Codex runtime helpers\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex runtime show\",\"short\":null,\"long\":null,\"description\":\"Show recent Flow-managed Codex runtime skill activations\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex runtime clear\",\"short\":null,\"long\":null,\"description\":\"Remove Flow-managed runtime skill state and stale symlinks\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex runtime write-plan\",\"short\":null,\"long\":null,\"description\":\"Write a markdown plan to ~/plan and print the final path\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex runtime write-plan\",\"short\":null,\"long\":\"--title\",\"description\":\"Human-readable title used to derive the filename\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex runtime write-plan\",\"short\":null,\"long\":\"--stem\",\"description\":\"Explicit filename stem to use instead of deriving from the title\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex runtime write-plan\",\"short\":null,\"long\":\"--dir\",\"description\":\"Destination directory (defaults to ~/plan)\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex runtime write-plan\",\"short\":null,\"long\":\"--source-session\",\"description\":\"Codex session id to append as a footer (defaults to $CODEX_THREAD_ID)\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex find\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and resume the best match\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex find\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex find\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex findAndCopy\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and copy the best match to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex findAndCopy\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex findAndCopy\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex copy\",\"short\":null,\"long\":null,\"description\":\"Copy session history to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex context\",\"short\":null,\"long\":null,\"description\":\"Copy last prompt and response to clipboard (for context passing). Usage: f ai claude context [session] [path] [count]\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex show\",\"short\":null,\"long\":null,\"description\":\"Print a cleaned session excerpt to stdout\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex show\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to project directory (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex show\",\"short\":null,\"long\":\"--count\",\"description\":\"Number of exchanges to include (default: 12)\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex show\",\"short\":null,\"long\":\"--full\",\"description\":\"Print the full cleaned transcript instead of just the trailing exchanges\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex recover\",\"short\":null,\"long\":null,\"description\":\"Recover recent Codex session context for a repo or subpath\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai codex recover\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to recover context for (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex recover\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex recover\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of candidate sessions to return\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex recover\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f ai codex recover\",\"short\":null,\"long\":\"--summary-only\",\"description\":\"Emit only the compact recovery summary for prompt injection\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":null,\"description\":\"Run a prompt through Everruns and bridge client-side tool calls to seqd\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--session-id\",\"description\":\"Reuse an existing Everruns session ID\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--agent-id\",\"description\":\"Agent ID to use when creating a new session\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--harness-id\",\"description\":\"Harness ID to use when creating a new session\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--model-id\",\"description\":\"Model ID override when creating a new session\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--base-url\",\"description\":\"Everruns API base URL (default: http://127.0.0.1:9300/api)\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--api-key\",\"description\":\"Everruns API key (Bearer token). Prefer env var when possible\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--poll-ms\",\"description\":\"Poll interval for /events while waiting for completion\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--wait-timeout-secs\",\"description\":\"Max seconds to wait for output/tool cycles before timing out\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--seq-socket\",\"description\":\"Path to seqd Unix socket (default: $SEQ_SOCKET_PATH, then /tmp/seqd.sock)\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--seq-timeout-ms\",\"description\":\"Read/write timeout for seqd RPC calls in milliseconds\",\"entry_type\":\"flag\"},{\"command\":\"f ai everruns\",\"short\":null,\"long\":\"--no-seq-tools\",\"description\":\"Do not inject seq client-side tool definitions when creating a new session\",\"entry_type\":\"flag\"},{\"command\":\"f ai resume\",\"short\":null,\"long\":null,\"description\":\"Resume an AI session by name or ID\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai resume\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resume from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f ai save\",\"short\":null,\"long\":null,\"description\":\"Save/bookmark the current or most recent session with a name\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai save\",\"short\":null,\"long\":\"--id\",\"description\":\"Session ID to save (defaults to most recent)\",\"entry_type\":\"flag\"},{\"command\":\"f ai notes\",\"short\":null,\"long\":null,\"description\":\"Open or create notes for a session\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai remove\",\"short\":null,\"long\":null,\"description\":\"Remove a saved session from tracking (doesn't delete the actual session)\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai init\",\"short\":null,\"long\":null,\"description\":\"Initialize .ai folder structure in current project\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai import\",\"short\":null,\"long\":null,\"description\":\"Import all existing sessions for this project\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai copy\",\"short\":null,\"long\":null,\"description\":\"Copy session history to clipboard (fuzzy search to select)\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai copy-claude\",\"short\":null,\"long\":null,\"description\":\"Copy last Claude session to clipboard. Optionally search for a session containing text\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai copy-codex\",\"short\":null,\"long\":null,\"description\":\"Copy last Codex session to clipboard. Optionally search for a session containing text\",\"entry_type\":\"subcommand\"},{\"command\":\"f ai context\",\"short\":null,\"long\":null,\"description\":\"Copy last prompt and response from a session to clipboard (for context passing). Usage: f ai context [session] [path] [count]\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex\",\"short\":null,\"long\":null,\"description\":\"Start or continue Codex session.\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex list\",\"short\":null,\"long\":null,\"description\":\"List sessions for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex latest-id\",\"short\":null,\"long\":null,\"description\":\"Print the most recent session ID for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex latest-id\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex sessions\",\"short\":null,\"long\":null,\"description\":\"List provider sessions with IDs\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex sessions\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex sessions\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex continue\",\"short\":null,\"long\":null,\"description\":\"Continue the most recent session for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex continue\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to continue from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex new\",\"short\":null,\"long\":null,\"description\":\"Start a new session (ignores existing sessions)\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex resume\",\"short\":null,\"long\":null,\"description\":\"Resume a session\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex resume\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resume from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex connect\",\"short\":null,\"long\":null,\"description\":\"Connect to an existing Codex session selected by natural-language query\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex connect\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to search instead of the configured Codex home-session path\",\"entry_type\":\"flag\"},{\"command\":\"f codex connect\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f codex connect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON for the selected session instead of resuming it\",\"entry_type\":\"flag\"},{\"command\":\"f codex open\",\"short\":null,\"long\":null,\"description\":\"Open a Codex session with fast repo-scoped recovery and reference unrolling\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex open\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to open from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex open\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f codex resolve\",\"short\":null,\"long\":null,\"description\":\"Resolve how `f codex open` would interpret a query\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex resolve\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resolve from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex resolve\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f codex resolve\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex doctor\",\"short\":null,\"long\":null,\"description\":\"Print effective Codex control-plane settings for this path\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex doctor\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex doctor\",\"short\":null,\"long\":\"--assert-runtime\",\"description\":\"Exit non-zero unless wrapper transport and runtime skills are active\",\"entry_type\":\"flag\"},{\"command\":\"f codex doctor\",\"short\":null,\"long\":\"--assert-schedule\",\"description\":\"Exit non-zero unless the scheduled scorecard refresher is installed and loaded\",\"entry_type\":\"flag\"},{\"command\":\"f codex doctor\",\"short\":null,\"long\":\"--assert-learning\",\"description\":\"Exit non-zero unless Flow has grounded learning data for this target\",\"entry_type\":\"flag\"},{\"command\":\"f codex doctor\",\"short\":null,\"long\":\"--assert-autonomous\",\"description\":\"Exit non-zero unless runtime, schedule, and grounded learning are all active\",\"entry_type\":\"flag\"},{\"command\":\"f codex doctor\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex eval\",\"short\":null,\"long\":null,\"description\":\"Evaluate how well Flow-guided Codex usage is working for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex eval\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex eval\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent logged events/outcomes to inspect\",\"entry_type\":\"flag\"},{\"command\":\"f codex eval\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex enable-global\",\"short\":null,\"long\":null,\"description\":\"Enable the global Codex wrapper/runtime path so Flow features are actually used\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex enable-global\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show the resulting global config and actions without writing anything\",\"entry_type\":\"flag\"},{\"command\":\"f codex enable-global\",\"short\":null,\"long\":\"--install-launchd\",\"description\":\"Also install the macOS launchd scorecard refresher\",\"entry_type\":\"flag\"},{\"command\":\"f codex enable-global\",\"short\":null,\"long\":\"--start-daemon\",\"description\":\"Start codexd immediately after enabling the global config\",\"entry_type\":\"flag\"},{\"command\":\"f codex enable-global\",\"short\":null,\"long\":\"--sync-skills\",\"description\":\"Sync any discovered external skill sources after enabling the config\",\"entry_type\":\"flag\"},{\"command\":\"f codex enable-global\",\"short\":null,\"long\":\"--full\",\"description\":\"Shortcut for --install-launchd --start-daemon --sync-skills\",\"entry_type\":\"flag\"},{\"command\":\"f codex enable-global\",\"short\":null,\"long\":\"--minutes\",\"description\":\"Launchd cadence in minutes (used with --install-launchd/--full)\",\"entry_type\":\"flag\"},{\"command\":\"f codex enable-global\",\"short\":null,\"long\":\"--limit\",\"description\":\"Max logged events to scan per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f codex enable-global\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Max repos to rebuild per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f codex enable-global\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Recent-history window for launchd cron selection\",\"entry_type\":\"flag\"},{\"command\":\"f codex daemon\",\"short\":null,\"long\":null,\"description\":\"Manage the Flow codexd query daemon\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex daemon start\",\"short\":null,\"long\":null,\"description\":\"Start codexd under Flow supervision\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex daemon stop\",\"short\":null,\"long\":null,\"description\":\"Stop codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex daemon restart\",\"short\":null,\"long\":null,\"description\":\"Restart codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex daemon status\",\"short\":null,\"long\":null,\"description\":\"Show codexd status\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex memory\",\"short\":null,\"long\":null,\"description\":\"Inspect or sync the Jazz2-backed Codex memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex memory status\",\"short\":null,\"long\":null,\"description\":\"Show memory mirror status and counts\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex memory status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex memory sync\",\"short\":null,\"long\":null,\"description\":\"Sync recent Codex skill-eval logs into the Jazz2-backed memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex memory sync\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events and outcomes to ingest\",\"entry_type\":\"flag\"},{\"command\":\"f codex memory sync\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex memory query\",\"short\":null,\"long\":null,\"description\":\"Query compact repo/code memory facts for a path\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex memory query\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to query\",\"entry_type\":\"flag\"},{\"command\":\"f codex memory query\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of fact hits to include\",\"entry_type\":\"flag\"},{\"command\":\"f codex memory query\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex memory recent\",\"short\":null,\"long\":null,\"description\":\"Show recent memory rows, optionally scoped to a repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex memory recent\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex memory recent\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of rows to print\",\"entry_type\":\"flag\"},{\"command\":\"f codex memory recent\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex telemetry\",\"short\":null,\"long\":null,\"description\":\"Export redacted Codex workflow telemetry to configured Maple endpoints\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex telemetry status\",\"short\":null,\"long\":null,\"description\":\"Show Codex telemetry export config and current forwarder state\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex telemetry status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex telemetry flush\",\"short\":null,\"long\":null,\"description\":\"Flush recently logged Codex telemetry to configured Maple endpoints once\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex telemetry flush\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of unseen events/outcomes to export in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f codex telemetry flush\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex trace\",\"short\":null,\"long\":null,\"description\":\"Inspect Flow-managed Codex traces for the current or a specific session\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex trace status\",\"short\":null,\"long\":null,\"description\":\"Show Maple trace read status and configured credentials\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex trace status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex trace current-session\",\"short\":null,\"long\":null,\"description\":\"Inspect the trace associated with the active Flow-managed Codex session\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex trace current-session\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f codex trace current-session\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex trace inspect\",\"short\":null,\"long\":null,\"description\":\"Inspect a specific trace id\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex trace inspect\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f codex trace inspect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval\",\"short\":null,\"long\":null,\"description\":\"Build and inspect local Codex skill scorecards from Flow history\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex skill-eval run\",\"short\":null,\"long\":null,\"description\":\"Rebuild the local scorecard for this repo/path from recent Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex skill-eval run\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval run\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events to use when rebuilding\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval run\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval show\",\"short\":null,\"long\":null,\"description\":\"Show the current scorecard for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex skill-eval show\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval show\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval events\",\"short\":null,\"long\":null,\"description\":\"Show recent logged skill-eval events\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex skill-eval events\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval events\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of events to print\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval events\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval cron\",\"short\":null,\"long\":null,\"description\":\"Refresh scorecards for the most recent repos seen in Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex skill-eval cron\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of logged events to scan for target repos\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval cron\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Maximum number of repo targets to rebuild in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval cron\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Only consider repos seen within this many recent hours\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-eval cron\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-source\",\"short\":null,\"long\":null,\"description\":\"Discover and sync external Codex skill sources\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex skill-source list\",\"short\":null,\"long\":null,\"description\":\"List discovered external skills available for Codex runtime injection\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex skill-source list\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-source list\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-source sync\",\"short\":null,\"long\":null,\"description\":\"Copy discovered external skills into ~/.codex/skills for persistent use\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex skill-source sync\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-source sync\",\"short\":null,\"long\":\"--skill\",\"description\":\"Restrict sync to the named discovered skills\",\"entry_type\":\"flag\"},{\"command\":\"f codex skill-source sync\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite an existing ~/.codex/skills/<name> directory\",\"entry_type\":\"flag\"},{\"command\":\"f codex runtime\",\"short\":null,\"long\":null,\"description\":\"Inspect or manage Flow-managed Codex runtime helpers\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex runtime show\",\"short\":null,\"long\":null,\"description\":\"Show recent Flow-managed Codex runtime skill activations\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex runtime clear\",\"short\":null,\"long\":null,\"description\":\"Remove Flow-managed runtime skill state and stale symlinks\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex runtime write-plan\",\"short\":null,\"long\":null,\"description\":\"Write a markdown plan to ~/plan and print the final path\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex runtime write-plan\",\"short\":null,\"long\":\"--title\",\"description\":\"Human-readable title used to derive the filename\",\"entry_type\":\"flag\"},{\"command\":\"f codex runtime write-plan\",\"short\":null,\"long\":\"--stem\",\"description\":\"Explicit filename stem to use instead of deriving from the title\",\"entry_type\":\"flag\"},{\"command\":\"f codex runtime write-plan\",\"short\":null,\"long\":\"--dir\",\"description\":\"Destination directory (defaults to ~/plan)\",\"entry_type\":\"flag\"},{\"command\":\"f codex runtime write-plan\",\"short\":null,\"long\":\"--source-session\",\"description\":\"Codex session id to append as a footer (defaults to $CODEX_THREAD_ID)\",\"entry_type\":\"flag\"},{\"command\":\"f codex find\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and resume the best match\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex find\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f codex find\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f codex findAndCopy\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and copy the best match to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex findAndCopy\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f codex findAndCopy\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f codex copy\",\"short\":null,\"long\":null,\"description\":\"Copy session history to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex context\",\"short\":null,\"long\":null,\"description\":\"Copy last prompt and response to clipboard (for context passing). Usage: f ai claude context [session] [path] [count]\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex show\",\"short\":null,\"long\":null,\"description\":\"Print a cleaned session excerpt to stdout\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex show\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to project directory (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f codex show\",\"short\":null,\"long\":\"--count\",\"description\":\"Number of exchanges to include (default: 12)\",\"entry_type\":\"flag\"},{\"command\":\"f codex show\",\"short\":null,\"long\":\"--full\",\"description\":\"Print the full cleaned transcript instead of just the trailing exchanges\",\"entry_type\":\"flag\"},{\"command\":\"f codex recover\",\"short\":null,\"long\":null,\"description\":\"Recover recent Codex session context for a repo or subpath\",\"entry_type\":\"subcommand\"},{\"command\":\"f codex recover\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to recover context for (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f codex recover\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f codex recover\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of candidate sessions to return\",\"entry_type\":\"flag\"},{\"command\":\"f codex recover\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f codex recover\",\"short\":null,\"long\":\"--summary-only\",\"description\":\"Emit only the compact recovery summary for prompt injection\",\"entry_type\":\"flag\"},{\"command\":\"f cursor\",\"short\":null,\"long\":null,\"description\":\"Read Cursor agent transcripts for this project.\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor list\",\"short\":null,\"long\":null,\"description\":\"List sessions for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor latest-id\",\"short\":null,\"long\":null,\"description\":\"Print the most recent session ID for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor latest-id\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor sessions\",\"short\":null,\"long\":null,\"description\":\"List provider sessions with IDs\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor sessions\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor sessions\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor continue\",\"short\":null,\"long\":null,\"description\":\"Continue the most recent session for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor continue\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to continue from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor new\",\"short\":null,\"long\":null,\"description\":\"Start a new session (ignores existing sessions)\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor resume\",\"short\":null,\"long\":null,\"description\":\"Resume a session\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor resume\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resume from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor connect\",\"short\":null,\"long\":null,\"description\":\"Connect to an existing Codex session selected by natural-language query\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor connect\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to search instead of the configured Codex home-session path\",\"entry_type\":\"flag\"},{\"command\":\"f cursor connect\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f cursor connect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON for the selected session instead of resuming it\",\"entry_type\":\"flag\"},{\"command\":\"f cursor open\",\"short\":null,\"long\":null,\"description\":\"Open a Codex session with fast repo-scoped recovery and reference unrolling\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor open\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to open from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor open\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f cursor resolve\",\"short\":null,\"long\":null,\"description\":\"Resolve how `f codex open` would interpret a query\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor resolve\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resolve from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor resolve\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f cursor resolve\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor doctor\",\"short\":null,\"long\":null,\"description\":\"Print effective Codex control-plane settings for this path\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor doctor\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor doctor\",\"short\":null,\"long\":\"--assert-runtime\",\"description\":\"Exit non-zero unless wrapper transport and runtime skills are active\",\"entry_type\":\"flag\"},{\"command\":\"f cursor doctor\",\"short\":null,\"long\":\"--assert-schedule\",\"description\":\"Exit non-zero unless the scheduled scorecard refresher is installed and loaded\",\"entry_type\":\"flag\"},{\"command\":\"f cursor doctor\",\"short\":null,\"long\":\"--assert-learning\",\"description\":\"Exit non-zero unless Flow has grounded learning data for this target\",\"entry_type\":\"flag\"},{\"command\":\"f cursor doctor\",\"short\":null,\"long\":\"--assert-autonomous\",\"description\":\"Exit non-zero unless runtime, schedule, and grounded learning are all active\",\"entry_type\":\"flag\"},{\"command\":\"f cursor doctor\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor eval\",\"short\":null,\"long\":null,\"description\":\"Evaluate how well Flow-guided Codex usage is working for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor eval\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor eval\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent logged events/outcomes to inspect\",\"entry_type\":\"flag\"},{\"command\":\"f cursor eval\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor enable-global\",\"short\":null,\"long\":null,\"description\":\"Enable the global Codex wrapper/runtime path so Flow features are actually used\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor enable-global\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show the resulting global config and actions without writing anything\",\"entry_type\":\"flag\"},{\"command\":\"f cursor enable-global\",\"short\":null,\"long\":\"--install-launchd\",\"description\":\"Also install the macOS launchd scorecard refresher\",\"entry_type\":\"flag\"},{\"command\":\"f cursor enable-global\",\"short\":null,\"long\":\"--start-daemon\",\"description\":\"Start codexd immediately after enabling the global config\",\"entry_type\":\"flag\"},{\"command\":\"f cursor enable-global\",\"short\":null,\"long\":\"--sync-skills\",\"description\":\"Sync any discovered external skill sources after enabling the config\",\"entry_type\":\"flag\"},{\"command\":\"f cursor enable-global\",\"short\":null,\"long\":\"--full\",\"description\":\"Shortcut for --install-launchd --start-daemon --sync-skills\",\"entry_type\":\"flag\"},{\"command\":\"f cursor enable-global\",\"short\":null,\"long\":\"--minutes\",\"description\":\"Launchd cadence in minutes (used with --install-launchd/--full)\",\"entry_type\":\"flag\"},{\"command\":\"f cursor enable-global\",\"short\":null,\"long\":\"--limit\",\"description\":\"Max logged events to scan per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f cursor enable-global\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Max repos to rebuild per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f cursor enable-global\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Recent-history window for launchd cron selection\",\"entry_type\":\"flag\"},{\"command\":\"f cursor daemon\",\"short\":null,\"long\":null,\"description\":\"Manage the Flow codexd query daemon\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor daemon start\",\"short\":null,\"long\":null,\"description\":\"Start codexd under Flow supervision\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor daemon stop\",\"short\":null,\"long\":null,\"description\":\"Stop codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor daemon restart\",\"short\":null,\"long\":null,\"description\":\"Restart codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor daemon status\",\"short\":null,\"long\":null,\"description\":\"Show codexd status\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor memory\",\"short\":null,\"long\":null,\"description\":\"Inspect or sync the Jazz2-backed Codex memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor memory status\",\"short\":null,\"long\":null,\"description\":\"Show memory mirror status and counts\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor memory status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor memory sync\",\"short\":null,\"long\":null,\"description\":\"Sync recent Codex skill-eval logs into the Jazz2-backed memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor memory sync\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events and outcomes to ingest\",\"entry_type\":\"flag\"},{\"command\":\"f cursor memory sync\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor memory query\",\"short\":null,\"long\":null,\"description\":\"Query compact repo/code memory facts for a path\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor memory query\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to query\",\"entry_type\":\"flag\"},{\"command\":\"f cursor memory query\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of fact hits to include\",\"entry_type\":\"flag\"},{\"command\":\"f cursor memory query\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor memory recent\",\"short\":null,\"long\":null,\"description\":\"Show recent memory rows, optionally scoped to a repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor memory recent\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor memory recent\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of rows to print\",\"entry_type\":\"flag\"},{\"command\":\"f cursor memory recent\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor telemetry\",\"short\":null,\"long\":null,\"description\":\"Export redacted Codex workflow telemetry to configured Maple endpoints\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor telemetry status\",\"short\":null,\"long\":null,\"description\":\"Show Codex telemetry export config and current forwarder state\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor telemetry status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor telemetry flush\",\"short\":null,\"long\":null,\"description\":\"Flush recently logged Codex telemetry to configured Maple endpoints once\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor telemetry flush\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of unseen events/outcomes to export in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f cursor telemetry flush\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor trace\",\"short\":null,\"long\":null,\"description\":\"Inspect Flow-managed Codex traces for the current or a specific session\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor trace status\",\"short\":null,\"long\":null,\"description\":\"Show Maple trace read status and configured credentials\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor trace status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor trace current-session\",\"short\":null,\"long\":null,\"description\":\"Inspect the trace associated with the active Flow-managed Codex session\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor trace current-session\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f cursor trace current-session\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor trace inspect\",\"short\":null,\"long\":null,\"description\":\"Inspect a specific trace id\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor trace inspect\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f cursor trace inspect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval\",\"short\":null,\"long\":null,\"description\":\"Build and inspect local Codex skill scorecards from Flow history\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor skill-eval run\",\"short\":null,\"long\":null,\"description\":\"Rebuild the local scorecard for this repo/path from recent Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor skill-eval run\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval run\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events to use when rebuilding\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval run\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval show\",\"short\":null,\"long\":null,\"description\":\"Show the current scorecard for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor skill-eval show\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval show\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval events\",\"short\":null,\"long\":null,\"description\":\"Show recent logged skill-eval events\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor skill-eval events\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval events\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of events to print\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval events\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval cron\",\"short\":null,\"long\":null,\"description\":\"Refresh scorecards for the most recent repos seen in Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor skill-eval cron\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of logged events to scan for target repos\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval cron\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Maximum number of repo targets to rebuild in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval cron\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Only consider repos seen within this many recent hours\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-eval cron\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-source\",\"short\":null,\"long\":null,\"description\":\"Discover and sync external Codex skill sources\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor skill-source list\",\"short\":null,\"long\":null,\"description\":\"List discovered external skills available for Codex runtime injection\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor skill-source list\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-source list\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-source sync\",\"short\":null,\"long\":null,\"description\":\"Copy discovered external skills into ~/.codex/skills for persistent use\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor skill-source sync\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-source sync\",\"short\":null,\"long\":\"--skill\",\"description\":\"Restrict sync to the named discovered skills\",\"entry_type\":\"flag\"},{\"command\":\"f cursor skill-source sync\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite an existing ~/.codex/skills/<name> directory\",\"entry_type\":\"flag\"},{\"command\":\"f cursor runtime\",\"short\":null,\"long\":null,\"description\":\"Inspect or manage Flow-managed Codex runtime helpers\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor runtime show\",\"short\":null,\"long\":null,\"description\":\"Show recent Flow-managed Codex runtime skill activations\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor runtime clear\",\"short\":null,\"long\":null,\"description\":\"Remove Flow-managed runtime skill state and stale symlinks\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor runtime write-plan\",\"short\":null,\"long\":null,\"description\":\"Write a markdown plan to ~/plan and print the final path\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor runtime write-plan\",\"short\":null,\"long\":\"--title\",\"description\":\"Human-readable title used to derive the filename\",\"entry_type\":\"flag\"},{\"command\":\"f cursor runtime write-plan\",\"short\":null,\"long\":\"--stem\",\"description\":\"Explicit filename stem to use instead of deriving from the title\",\"entry_type\":\"flag\"},{\"command\":\"f cursor runtime write-plan\",\"short\":null,\"long\":\"--dir\",\"description\":\"Destination directory (defaults to ~/plan)\",\"entry_type\":\"flag\"},{\"command\":\"f cursor runtime write-plan\",\"short\":null,\"long\":\"--source-session\",\"description\":\"Codex session id to append as a footer (defaults to $CODEX_THREAD_ID)\",\"entry_type\":\"flag\"},{\"command\":\"f cursor find\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and resume the best match\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor find\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f cursor find\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f cursor findAndCopy\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and copy the best match to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor findAndCopy\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f cursor findAndCopy\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f cursor copy\",\"short\":null,\"long\":null,\"description\":\"Copy session history to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor context\",\"short\":null,\"long\":null,\"description\":\"Copy last prompt and response to clipboard (for context passing). Usage: f ai claude context [session] [path] [count]\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor show\",\"short\":null,\"long\":null,\"description\":\"Print a cleaned session excerpt to stdout\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor show\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to project directory (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f cursor show\",\"short\":null,\"long\":\"--count\",\"description\":\"Number of exchanges to include (default: 12)\",\"entry_type\":\"flag\"},{\"command\":\"f cursor show\",\"short\":null,\"long\":\"--full\",\"description\":\"Print the full cleaned transcript instead of just the trailing exchanges\",\"entry_type\":\"flag\"},{\"command\":\"f cursor recover\",\"short\":null,\"long\":null,\"description\":\"Recover recent Codex session context for a repo or subpath\",\"entry_type\":\"subcommand\"},{\"command\":\"f cursor recover\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to recover context for (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f cursor recover\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f cursor recover\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of candidate sessions to return\",\"entry_type\":\"flag\"},{\"command\":\"f cursor recover\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f cursor recover\",\"short\":null,\"long\":\"--summary-only\",\"description\":\"Emit only the compact recovery summary for prompt injection\",\"entry_type\":\"flag\"},{\"command\":\"f claude\",\"short\":null,\"long\":null,\"description\":\"Start or continue Claude session.\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude list\",\"short\":null,\"long\":null,\"description\":\"List sessions for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude latest-id\",\"short\":null,\"long\":null,\"description\":\"Print the most recent session ID for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude latest-id\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude sessions\",\"short\":null,\"long\":null,\"description\":\"List provider sessions with IDs\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude sessions\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude sessions\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude continue\",\"short\":null,\"long\":null,\"description\":\"Continue the most recent session for this provider\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude continue\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to continue from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude new\",\"short\":null,\"long\":null,\"description\":\"Start a new session (ignores existing sessions)\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude resume\",\"short\":null,\"long\":null,\"description\":\"Resume a session\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude resume\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resume from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude connect\",\"short\":null,\"long\":null,\"description\":\"Connect to an existing Codex session selected by natural-language query\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude connect\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to search instead of the configured Codex home-session path\",\"entry_type\":\"flag\"},{\"command\":\"f claude connect\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f claude connect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON for the selected session instead of resuming it\",\"entry_type\":\"flag\"},{\"command\":\"f claude open\",\"short\":null,\"long\":null,\"description\":\"Open a Codex session with fast repo-scoped recovery and reference unrolling\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude open\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to open from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude open\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f claude resolve\",\"short\":null,\"long\":null,\"description\":\"Resolve how `f codex open` would interpret a query\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude resolve\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to resolve from instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude resolve\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict session lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f claude resolve\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude doctor\",\"short\":null,\"long\":null,\"description\":\"Print effective Codex control-plane settings for this path\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude doctor\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude doctor\",\"short\":null,\"long\":\"--assert-runtime\",\"description\":\"Exit non-zero unless wrapper transport and runtime skills are active\",\"entry_type\":\"flag\"},{\"command\":\"f claude doctor\",\"short\":null,\"long\":\"--assert-schedule\",\"description\":\"Exit non-zero unless the scheduled scorecard refresher is installed and loaded\",\"entry_type\":\"flag\"},{\"command\":\"f claude doctor\",\"short\":null,\"long\":\"--assert-learning\",\"description\":\"Exit non-zero unless Flow has grounded learning data for this target\",\"entry_type\":\"flag\"},{\"command\":\"f claude doctor\",\"short\":null,\"long\":\"--assert-autonomous\",\"description\":\"Exit non-zero unless runtime, schedule, and grounded learning are all active\",\"entry_type\":\"flag\"},{\"command\":\"f claude doctor\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude eval\",\"short\":null,\"long\":null,\"description\":\"Evaluate how well Flow-guided Codex usage is working for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude eval\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude eval\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent logged events/outcomes to inspect\",\"entry_type\":\"flag\"},{\"command\":\"f claude eval\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude enable-global\",\"short\":null,\"long\":null,\"description\":\"Enable the global Codex wrapper/runtime path so Flow features are actually used\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude enable-global\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show the resulting global config and actions without writing anything\",\"entry_type\":\"flag\"},{\"command\":\"f claude enable-global\",\"short\":null,\"long\":\"--install-launchd\",\"description\":\"Also install the macOS launchd scorecard refresher\",\"entry_type\":\"flag\"},{\"command\":\"f claude enable-global\",\"short\":null,\"long\":\"--start-daemon\",\"description\":\"Start codexd immediately after enabling the global config\",\"entry_type\":\"flag\"},{\"command\":\"f claude enable-global\",\"short\":null,\"long\":\"--sync-skills\",\"description\":\"Sync any discovered external skill sources after enabling the config\",\"entry_type\":\"flag\"},{\"command\":\"f claude enable-global\",\"short\":null,\"long\":\"--full\",\"description\":\"Shortcut for --install-launchd --start-daemon --sync-skills\",\"entry_type\":\"flag\"},{\"command\":\"f claude enable-global\",\"short\":null,\"long\":\"--minutes\",\"description\":\"Launchd cadence in minutes (used with --install-launchd/--full)\",\"entry_type\":\"flag\"},{\"command\":\"f claude enable-global\",\"short\":null,\"long\":\"--limit\",\"description\":\"Max logged events to scan per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f claude enable-global\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Max repos to rebuild per launchd run\",\"entry_type\":\"flag\"},{\"command\":\"f claude enable-global\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Recent-history window for launchd cron selection\",\"entry_type\":\"flag\"},{\"command\":\"f claude daemon\",\"short\":null,\"long\":null,\"description\":\"Manage the Flow codexd query daemon\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude daemon start\",\"short\":null,\"long\":null,\"description\":\"Start codexd under Flow supervision\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude daemon stop\",\"short\":null,\"long\":null,\"description\":\"Stop codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude daemon restart\",\"short\":null,\"long\":null,\"description\":\"Restart codexd\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude daemon status\",\"short\":null,\"long\":null,\"description\":\"Show codexd status\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude memory\",\"short\":null,\"long\":null,\"description\":\"Inspect or sync the Jazz2-backed Codex memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude memory status\",\"short\":null,\"long\":null,\"description\":\"Show memory mirror status and counts\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude memory status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude memory sync\",\"short\":null,\"long\":null,\"description\":\"Sync recent Codex skill-eval logs into the Jazz2-backed memory mirror\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude memory sync\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events and outcomes to ingest\",\"entry_type\":\"flag\"},{\"command\":\"f claude memory sync\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude memory query\",\"short\":null,\"long\":null,\"description\":\"Query compact repo/code memory facts for a path\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude memory query\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path or repo root to query\",\"entry_type\":\"flag\"},{\"command\":\"f claude memory query\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of fact hits to include\",\"entry_type\":\"flag\"},{\"command\":\"f claude memory query\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude memory recent\",\"short\":null,\"long\":null,\"description\":\"Show recent memory rows, optionally scoped to a repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude memory recent\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude memory recent\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of rows to print\",\"entry_type\":\"flag\"},{\"command\":\"f claude memory recent\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude telemetry\",\"short\":null,\"long\":null,\"description\":\"Export redacted Codex workflow telemetry to configured Maple endpoints\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude telemetry status\",\"short\":null,\"long\":null,\"description\":\"Show Codex telemetry export config and current forwarder state\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude telemetry status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude telemetry flush\",\"short\":null,\"long\":null,\"description\":\"Flush recently logged Codex telemetry to configured Maple endpoints once\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude telemetry flush\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of unseen events/outcomes to export in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f claude telemetry flush\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude trace\",\"short\":null,\"long\":null,\"description\":\"Inspect Flow-managed Codex traces for the current or a specific session\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude trace status\",\"short\":null,\"long\":null,\"description\":\"Show Maple trace read status and configured credentials\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude trace status\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude trace current-session\",\"short\":null,\"long\":null,\"description\":\"Inspect the trace associated with the active Flow-managed Codex session\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude trace current-session\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f claude trace current-session\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude trace inspect\",\"short\":null,\"long\":null,\"description\":\"Inspect a specific trace id\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude trace inspect\",\"short\":null,\"long\":\"--flush\",\"description\":\"Flush recent Flow Codex telemetry before inspecting the trace\",\"entry_type\":\"flag\"},{\"command\":\"f claude trace inspect\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval\",\"short\":null,\"long\":null,\"description\":\"Build and inspect local Codex skill scorecards from Flow history\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude skill-eval run\",\"short\":null,\"long\":null,\"description\":\"Rebuild the local scorecard for this repo/path from recent Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude skill-eval run\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval run\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of recent events to use when rebuilding\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval run\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval show\",\"short\":null,\"long\":null,\"description\":\"Show the current scorecard for this repo/path\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude skill-eval show\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval show\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval events\",\"short\":null,\"long\":null,\"description\":\"Show recent logged skill-eval events\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude skill-eval events\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval events\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of events to print\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval events\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval cron\",\"short\":null,\"long\":null,\"description\":\"Refresh scorecards for the most recent repos seen in Flow Codex history\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude skill-eval cron\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of logged events to scan for target repos\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval cron\",\"short\":null,\"long\":\"--max-targets\",\"description\":\"Maximum number of repo targets to rebuild in one pass\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval cron\",\"short\":null,\"long\":\"--within-hours\",\"description\":\"Only consider repos seen within this many recent hours\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-eval cron\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-source\",\"short\":null,\"long\":null,\"description\":\"Discover and sync external Codex skill sources\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude skill-source list\",\"short\":null,\"long\":null,\"description\":\"List discovered external skills available for Codex runtime injection\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude skill-source list\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-source list\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-source sync\",\"short\":null,\"long\":null,\"description\":\"Copy discovered external skills into ~/.codex/skills for persistent use\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude skill-source sync\",\"short\":null,\"long\":\"--path\",\"description\":\"Project path to inspect instead of the current directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-source sync\",\"short\":null,\"long\":\"--skill\",\"description\":\"Restrict sync to the named discovered skills\",\"entry_type\":\"flag\"},{\"command\":\"f claude skill-source sync\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite an existing ~/.codex/skills/<name> directory\",\"entry_type\":\"flag\"},{\"command\":\"f claude runtime\",\"short\":null,\"long\":null,\"description\":\"Inspect or manage Flow-managed Codex runtime helpers\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude runtime show\",\"short\":null,\"long\":null,\"description\":\"Show recent Flow-managed Codex runtime skill activations\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude runtime clear\",\"short\":null,\"long\":null,\"description\":\"Remove Flow-managed runtime skill state and stale symlinks\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude runtime write-plan\",\"short\":null,\"long\":null,\"description\":\"Write a markdown plan to ~/plan and print the final path\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude runtime write-plan\",\"short\":null,\"long\":\"--title\",\"description\":\"Human-readable title used to derive the filename\",\"entry_type\":\"flag\"},{\"command\":\"f claude runtime write-plan\",\"short\":null,\"long\":\"--stem\",\"description\":\"Explicit filename stem to use instead of deriving from the title\",\"entry_type\":\"flag\"},{\"command\":\"f claude runtime write-plan\",\"short\":null,\"long\":\"--dir\",\"description\":\"Destination directory (defaults to ~/plan)\",\"entry_type\":\"flag\"},{\"command\":\"f claude runtime write-plan\",\"short\":null,\"long\":\"--source-session\",\"description\":\"Codex session id to append as a footer (defaults to $CODEX_THREAD_ID)\",\"entry_type\":\"flag\"},{\"command\":\"f claude find\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and resume the best match\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude find\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f claude find\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f claude findAndCopy\",\"short\":null,\"long\":null,\"description\":\"Search Codex sessions by prompt text and copy the best match to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude findAndCopy\",\"short\":null,\"long\":\"--path\",\"description\":\"Limit search to sessions from this path or repo subtree (default: all Codex sessions)\",\"entry_type\":\"flag\"},{\"command\":\"f claude findAndCopy\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict --path lookup to an exact cwd instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f claude copy\",\"short\":null,\"long\":null,\"description\":\"Copy session history to clipboard\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude context\",\"short\":null,\"long\":null,\"description\":\"Copy last prompt and response to clipboard (for context passing). Usage: f ai claude context [session] [path] [count]\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude show\",\"short\":null,\"long\":null,\"description\":\"Print a cleaned session excerpt to stdout\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude show\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to project directory (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f claude show\",\"short\":null,\"long\":\"--count\",\"description\":\"Number of exchanges to include (default: 12)\",\"entry_type\":\"flag\"},{\"command\":\"f claude show\",\"short\":null,\"long\":\"--full\",\"description\":\"Print the full cleaned transcript instead of just the trailing exchanges\",\"entry_type\":\"flag\"},{\"command\":\"f claude recover\",\"short\":null,\"long\":null,\"description\":\"Recover recent Codex session context for a repo or subpath\",\"entry_type\":\"subcommand\"},{\"command\":\"f claude recover\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to recover context for (default: current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f claude recover\",\"short\":null,\"long\":\"--exact-cwd\",\"description\":\"Restrict lookup to an exact cwd match instead of a repo-tree prefix\",\"entry_type\":\"flag\"},{\"command\":\"f claude recover\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of candidate sessions to return\",\"entry_type\":\"flag\"},{\"command\":\"f claude recover\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f claude recover\",\"short\":null,\"long\":\"--summary-only\",\"description\":\"Emit only the compact recovery summary for prompt injection\",\"entry_type\":\"flag\"},{\"command\":\"f env\",\"short\":null,\"long\":null,\"description\":\"Manage project env vars and cloud sync.\",\"entry_type\":\"subcommand\"},{\"command\":\"f env sync\",\"short\":null,\"long\":null,\"description\":\"Sync project settings and set up autonomous agent workflow\",\"entry_type\":\"subcommand\"},{\"command\":\"f env unlock\",\"short\":null,\"long\":null,\"description\":\"Unlock env read access (Touch ID on macOS)\",\"entry_type\":\"subcommand\"},{\"command\":\"f env new\",\"short\":null,\"long\":null,\"description\":\"Create a new env token from available templates\",\"entry_type\":\"subcommand\"},{\"command\":\"f env login\",\"short\":null,\"long\":null,\"description\":\"Authenticate with cloud to fetch env vars\",\"entry_type\":\"subcommand\"},{\"command\":\"f env pull\",\"short\":null,\"long\":null,\"description\":\"Fetch env vars from cloud and write to .env\",\"entry_type\":\"subcommand\"},{\"command\":\"f env pull\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment to fetch (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f env push\",\"short\":null,\"long\":null,\"description\":\"Push local .env to cloud\",\"entry_type\":\"subcommand\"},{\"command\":\"f env push\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment to push to (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f env guide\",\"short\":null,\"long\":null,\"description\":\"Guided prompt to set required env vars from flow.toml\",\"entry_type\":\"subcommand\"},{\"command\":\"f env guide\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment to set in (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f env apply\",\"short\":null,\"long\":null,\"description\":\"Apply env vars from cloud to the configured Cloudflare worker\",\"entry_type\":\"subcommand\"},{\"command\":\"f env bootstrap\",\"short\":null,\"long\":null,\"description\":\"Bootstrap Cloudflare secrets from flow.toml (interactive)\",\"entry_type\":\"subcommand\"},{\"command\":\"f env setup\",\"short\":null,\"long\":null,\"description\":\"Interactive env setup (uses flow.toml when configured)\",\"entry_type\":\"subcommand\"},{\"command\":\"f env setup\",\"short\":\"-f\",\"long\":\"--env-file\",\"description\":\"Optional .env file path to preselect\",\"entry_type\":\"flag\"},{\"command\":\"f env setup\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Optional environment to preselect\",\"entry_type\":\"flag\"},{\"command\":\"f env list\",\"short\":null,\"long\":null,\"description\":\"List env vars for this project\",\"entry_type\":\"subcommand\"},{\"command\":\"f env list\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment to list (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f env set\",\"short\":null,\"long\":null,\"description\":\"Set a personal env var (default backend)\",\"entry_type\":\"subcommand\"},{\"command\":\"f env set\",\"short\":null,\"long\":\"--personal\",\"description\":\"Compatibility flag (ignored; set always targets personal env)\",\"entry_type\":\"flag\"},{\"command\":\"f env delete\",\"short\":null,\"long\":null,\"description\":\"Delete personal env var(s)\",\"entry_type\":\"subcommand\"},{\"command\":\"f env project\",\"short\":null,\"long\":null,\"description\":\"Manage project-scoped env vars\",\"entry_type\":\"subcommand\"},{\"command\":\"f env project set\",\"short\":null,\"long\":null,\"description\":\"Set a project-scoped env var\",\"entry_type\":\"subcommand\"},{\"command\":\"f env project set\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f env project delete\",\"short\":null,\"long\":null,\"description\":\"Delete project-scoped env var(s)\",\"entry_type\":\"subcommand\"},{\"command\":\"f env project delete\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f env project list\",\"short\":null,\"long\":null,\"description\":\"List project env vars\",\"entry_type\":\"subcommand\"},{\"command\":\"f env project list\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f env status\",\"short\":null,\"long\":null,\"description\":\"Show current auth status\",\"entry_type\":\"subcommand\"},{\"command\":\"f env get\",\"short\":null,\"long\":null,\"description\":\"Get specific env var(s) and print to stdout\",\"entry_type\":\"subcommand\"},{\"command\":\"f env get\",\"short\":null,\"long\":\"--personal\",\"description\":\"Fetch from personal env vars instead of project\",\"entry_type\":\"flag\"},{\"command\":\"f env get\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment to fetch from (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f env get\",\"short\":\"-f\",\"long\":\"--format\",\"description\":\"Output format: env (KEY=VALUE), json, or value (just the value, single key only)\",\"entry_type\":\"flag\"},{\"command\":\"f env run\",\"short\":null,\"long\":null,\"description\":\"Run a command with env vars injected from cloud\",\"entry_type\":\"subcommand\"},{\"command\":\"f env run\",\"short\":null,\"long\":\"--personal\",\"description\":\"Fetch from personal env vars instead of project\",\"entry_type\":\"flag\"},{\"command\":\"f env run\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment to fetch from (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f env run\",\"short\":\"-k\",\"long\":\"--keys\",\"description\":\"Specific keys to inject (if empty, injects all)\",\"entry_type\":\"flag\"},{\"command\":\"f env keys\",\"short\":null,\"long\":null,\"description\":\"Show configured env keys from flow.toml\",\"entry_type\":\"subcommand\"},{\"command\":\"f env token\",\"short\":null,\"long\":null,\"description\":\"Manage service tokens for host deployments\",\"entry_type\":\"subcommand\"},{\"command\":\"f env token create\",\"short\":null,\"long\":null,\"description\":\"Create a new service token for a project\",\"entry_type\":\"subcommand\"},{\"command\":\"f env token create\",\"short\":\"-n\",\"long\":\"--name\",\"description\":\"Token name (e.g., \\\"pulse-production\\\")\",\"entry_type\":\"flag\"},{\"command\":\"f env token create\",\"short\":\"-p\",\"long\":\"--permissions\",\"description\":\"Permissions: read, write, or admin\",\"entry_type\":\"flag\"},{\"command\":\"f env token list\",\"short\":null,\"long\":null,\"description\":\"List service tokens\",\"entry_type\":\"subcommand\"},{\"command\":\"f env token revoke\",\"short\":null,\"long\":null,\"description\":\"Revoke a service token\",\"entry_type\":\"subcommand\"},{\"command\":\"f otp\",\"short\":null,\"long\":null,\"description\":\"Fetch one-time passwords from 1Password Connect.\",\"entry_type\":\"subcommand\"},{\"command\":\"f otp get\",\"short\":null,\"long\":null,\"description\":\"Get a TOTP code from 1Password Connect\",\"entry_type\":\"subcommand\"},{\"command\":\"f otp get\",\"short\":null,\"long\":\"--field\",\"description\":\"Optional field label to select when multiple TOTP fields exist\",\"entry_type\":\"flag\"},{\"command\":\"f auth\",\"short\":null,\"long\":null,\"description\":\"Authenticate Flow AI via myflow.\",\"entry_type\":\"subcommand\"},{\"command\":\"f auth\",\"short\":null,\"long\":\"--api-url\",\"description\":\"Override API base URL for myflow (defaults to https://myflow.sh)\",\"entry_type\":\"flag\"},{\"command\":\"f services\",\"short\":null,\"long\":null,\"description\":\"Onboard third-party services (Stripe, etc.) with guided env setup.\",\"entry_type\":\"subcommand\"},{\"command\":\"f services stripe\",\"short\":null,\"long\":null,\"description\":\"Set up Stripe env vars with guided prompts\",\"entry_type\":\"subcommand\"},{\"command\":\"f services stripe\",\"short\":\"-p\",\"long\":\"--path\",\"description\":\"Path to the project root (defaults to current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f services stripe\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment to store vars in (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f services stripe\",\"short\":null,\"long\":\"--mode\",\"description\":\"Stripe mode (test or live)\",\"entry_type\":\"flag\"},{\"command\":\"f services stripe\",\"short\":null,\"long\":\"--force\",\"description\":\"Prompt even if keys are already set\",\"entry_type\":\"flag\"},{\"command\":\"f services stripe\",\"short\":null,\"long\":\"--apply\",\"description\":\"Apply env vars to Cloudflare after setting them\",\"entry_type\":\"flag\"},{\"command\":\"f services stripe\",\"short\":null,\"long\":\"--no-apply\",\"description\":\"Skip applying env vars to Cloudflare\",\"entry_type\":\"flag\"},{\"command\":\"f services list\",\"short\":null,\"long\":null,\"description\":\"List available service setup flows\",\"entry_type\":\"subcommand\"},{\"command\":\"f macos\",\"short\":null,\"long\":null,\"description\":\"Manage macOS launch agents and daemons.\",\"entry_type\":\"subcommand\"},{\"command\":\"f macos list\",\"short\":null,\"long\":null,\"description\":\"List all launchd services\",\"entry_type\":\"subcommand\"},{\"command\":\"f macos list\",\"short\":null,\"long\":\"--user\",\"description\":\"Only show user agents\",\"entry_type\":\"flag\"},{\"command\":\"f macos list\",\"short\":null,\"long\":\"--system\",\"description\":\"Only show system agents/daemons\",\"entry_type\":\"flag\"},{\"command\":\"f macos list\",\"short\":null,\"long\":\"--json\",\"description\":\"Output as JSON\",\"entry_type\":\"flag\"},{\"command\":\"f macos status\",\"short\":null,\"long\":null,\"description\":\"Show running non-Apple services\",\"entry_type\":\"subcommand\"},{\"command\":\"f macos audit\",\"short\":null,\"long\":null,\"description\":\"Audit services with recommendations\",\"entry_type\":\"subcommand\"},{\"command\":\"f macos audit\",\"short\":null,\"long\":\"--json\",\"description\":\"Output as JSON\",\"entry_type\":\"flag\"},{\"command\":\"f macos info\",\"short\":null,\"long\":null,\"description\":\"Show detailed info about a service\",\"entry_type\":\"subcommand\"},{\"command\":\"f macos disable\",\"short\":null,\"long\":null,\"description\":\"Disable a service\",\"entry_type\":\"subcommand\"},{\"command\":\"f macos disable\",\"short\":\"-y\",\"long\":\"--yes\",\"description\":\"Skip confirmation prompt\",\"entry_type\":\"flag\"},{\"command\":\"f macos enable\",\"short\":null,\"long\":null,\"description\":\"Enable a service\",\"entry_type\":\"subcommand\"},{\"command\":\"f macos clean\",\"short\":null,\"long\":null,\"description\":\"Disable known bloatware services\",\"entry_type\":\"subcommand\"},{\"command\":\"f macos clean\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Only show what would be done\",\"entry_type\":\"flag\"},{\"command\":\"f macos clean\",\"short\":\"-y\",\"long\":\"--yes\",\"description\":\"Skip confirmation prompt\",\"entry_type\":\"flag\"},{\"command\":\"f ssh\",\"short\":null,\"long\":null,\"description\":\"Manage SSH keys via the cloud backend.\",\"entry_type\":\"subcommand\"},{\"command\":\"f ssh setup\",\"short\":null,\"long\":null,\"description\":\"Generate a new SSH keypair and store it in cloud personal env vars\",\"entry_type\":\"subcommand\"},{\"command\":\"f ssh setup\",\"short\":null,\"long\":\"--name\",\"description\":\"Optional key name (default: \\\"default\\\")\",\"entry_type\":\"flag\"},{\"command\":\"f ssh setup\",\"short\":null,\"long\":\"--no-unlock\",\"description\":\"Skip automatically unlocking the key after setup\",\"entry_type\":\"flag\"},{\"command\":\"f ssh unlock\",\"short\":null,\"long\":null,\"description\":\"Unlock the SSH key from cloud and load it into the Flow SSH agent\",\"entry_type\":\"subcommand\"},{\"command\":\"f ssh unlock\",\"short\":null,\"long\":\"--name\",\"description\":\"Optional key name (default: \\\"default\\\")\",\"entry_type\":\"flag\"},{\"command\":\"f ssh unlock\",\"short\":null,\"long\":\"--ttl-hours\",\"description\":\"TTL for ssh-agent in hours (default: 24)\",\"entry_type\":\"flag\"},{\"command\":\"f ssh status\",\"short\":null,\"long\":null,\"description\":\"Show whether the Flow SSH agent and key are available\",\"entry_type\":\"subcommand\"},{\"command\":\"f ssh status\",\"short\":null,\"long\":\"--name\",\"description\":\"Optional key name (default: \\\"default\\\")\",\"entry_type\":\"flag\"},{\"command\":\"f todo\",\"short\":null,\"long\":null,\"description\":\"Manage project todos.\",\"entry_type\":\"subcommand\"},{\"command\":\"f todo bike\",\"short\":null,\"long\":null,\"description\":\"Open the project Bike file\",\"entry_type\":\"subcommand\"},{\"command\":\"f todo add\",\"short\":null,\"long\":null,\"description\":\"Add a new todo\",\"entry_type\":\"subcommand\"},{\"command\":\"f todo add\",\"short\":\"-n\",\"long\":\"--note\",\"description\":\"Optional note to store with the todo\",\"entry_type\":\"flag\"},{\"command\":\"f todo add\",\"short\":null,\"long\":\"--session\",\"description\":\"Attach a specific AI session reference (provider:session_id)\",\"entry_type\":\"flag\"},{\"command\":\"f todo add\",\"short\":null,\"long\":\"--no-session\",\"description\":\"Skip attaching the most recent AI session\",\"entry_type\":\"flag\"},{\"command\":\"f todo add\",\"short\":\"-s\",\"long\":\"--status\",\"description\":\"Initial status (pending, in-progress, completed, blocked)\",\"entry_type\":\"flag\"},{\"command\":\"f todo list\",\"short\":null,\"long\":null,\"description\":\"List todos (active by default)\",\"entry_type\":\"subcommand\"},{\"command\":\"f todo list\",\"short\":null,\"long\":\"--all\",\"description\":\"Include completed todos\",\"entry_type\":\"flag\"},{\"command\":\"f todo done\",\"short\":null,\"long\":null,\"description\":\"Mark a todo as completed\",\"entry_type\":\"subcommand\"},{\"command\":\"f todo edit\",\"short\":null,\"long\":null,\"description\":\"Edit a todo\",\"entry_type\":\"subcommand\"},{\"command\":\"f todo edit\",\"short\":\"-t\",\"long\":\"--title\",\"description\":\"Update the title\",\"entry_type\":\"flag\"},{\"command\":\"f todo edit\",\"short\":\"-s\",\"long\":\"--status\",\"description\":\"Update the status\",\"entry_type\":\"flag\"},{\"command\":\"f todo edit\",\"short\":\"-n\",\"long\":\"--note\",\"description\":\"Update the note (empty clears)\",\"entry_type\":\"flag\"},{\"command\":\"f todo remove\",\"short\":null,\"long\":null,\"description\":\"Remove a todo\",\"entry_type\":\"subcommand\"},{\"command\":\"f ext\",\"short\":null,\"long\":null,\"description\":\"Copy an external dependency into ext/ and ignore it.\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills\",\"short\":null,\"long\":null,\"description\":\"Manage Codex skills (.ai/skills/).\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills list\",\"short\":null,\"long\":null,\"description\":\"List all skills for this project\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills new\",\"short\":null,\"long\":null,\"description\":\"Create a new skill\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills new\",\"short\":\"-d\",\"long\":\"--description\",\"description\":\"Short description of what the skill does\",\"entry_type\":\"flag\"},{\"command\":\"f skills show\",\"short\":null,\"long\":null,\"description\":\"Show skill details\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills edit\",\"short\":null,\"long\":null,\"description\":\"Edit a skill in your editor\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills remove\",\"short\":null,\"long\":null,\"description\":\"Remove a skill\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills install\",\"short\":null,\"long\":null,\"description\":\"Install a curated skill from the registry\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills publish\",\"short\":null,\"long\":null,\"description\":\"Publish a local skill to the shared registry\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills search\",\"short\":null,\"long\":null,\"description\":\"Search for skills in the remote registry\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills sync\",\"short\":null,\"long\":null,\"description\":\"Sync flow.toml tasks as skills\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills reload\",\"short\":null,\"long\":null,\"description\":\"Force Codex app-server to rescan skills from disk for this cwd\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills fetch\",\"short\":null,\"long\":null,\"description\":\"Fetch dependency skills via seq scraper integration\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills fetch\",\"short\":null,\"long\":\"--seq-repo\",\"description\":\"Path to seq repo (default: ~/code/seq)\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch\",\"short\":null,\"long\":\"--script-path\",\"description\":\"Path to seq teach script (overrides --seq-repo)\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch\",\"short\":null,\"long\":\"--scraper-base-url\",\"description\":\"Scraper daemon/API base URL\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch\",\"short\":null,\"long\":\"--scraper-api-key\",\"description\":\"Scraper API token\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch\",\"short\":null,\"long\":\"--out-dir\",\"description\":\"Output directory for generated skills (relative to repo root)\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch\",\"short\":null,\"long\":\"--cache-ttl-hours\",\"description\":\"Cache TTL in hours for scraper responses\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch\",\"short\":null,\"long\":\"--allow-direct-fallback\",\"description\":\"Allow direct fetch fallback when scraper queue/api is unavailable\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch\",\"short\":null,\"long\":\"--no-mem-events\",\"description\":\"Disable seq.mem JSON event emission\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch\",\"short\":null,\"long\":\"--mem-events-path\",\"description\":\"Override seq.mem JSONEachRow path\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch dep\",\"short\":null,\"long\":null,\"description\":\"Generate skills for one or more dependencies\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills fetch dep\",\"short\":null,\"long\":\"--ecosystem\",\"description\":\"Force ecosystem for all deps\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch dep\",\"short\":null,\"long\":\"--force\",\"description\":\"Bypass cache and scrape fresh\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch auto\",\"short\":null,\"long\":null,\"description\":\"Auto-discover dependencies from manifests and generate skills\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills fetch auto\",\"short\":null,\"long\":\"--top\",\"description\":\"Max dependencies per ecosystem\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch auto\",\"short\":null,\"long\":\"--ecosystems\",\"description\":\"Comma-separated ecosystem list (npm,pypi,cargo,swift)\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch auto\",\"short\":null,\"long\":\"--force\",\"description\":\"Bypass cache and scrape fresh\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch url\",\"short\":null,\"long\":null,\"description\":\"Generate skills from one or more URLs\",\"entry_type\":\"subcommand\"},{\"command\":\"f skills fetch url\",\"short\":null,\"long\":\"--name\",\"description\":\"Skill name override\",\"entry_type\":\"flag\"},{\"command\":\"f skills fetch url\",\"short\":null,\"long\":\"--force\",\"description\":\"Bypass cache and scrape fresh\",\"entry_type\":\"flag\"},{\"command\":\"f url\",\"short\":null,\"long\":null,\"description\":\"Inspect a URL into a thin, AI-friendly summary.\",\"entry_type\":\"subcommand\"},{\"command\":\"f url inspect\",\"short\":null,\"long\":null,\"description\":\"Inspect a URL and return a compact normalized summary\",\"entry_type\":\"subcommand\"},{\"command\":\"f url inspect\",\"short\":null,\"long\":\"--json\",\"description\":\"Print machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f url inspect\",\"short\":null,\"long\":\"--full\",\"description\":\"Include the full markdown/content body when available\",\"entry_type\":\"flag\"},{\"command\":\"f url inspect\",\"short\":null,\"long\":\"--provider\",\"description\":\"Provider to use. `auto` tries Cloudflare first, then scraper, then direct fetch\",\"entry_type\":\"flag\"},{\"command\":\"f url inspect\",\"short\":null,\"long\":\"--timeout-s\",\"description\":\"Request timeout in seconds\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":null,\"description\":\"Crawl a site and return a compact multi-page summary\",\"entry_type\":\"subcommand\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--json\",\"description\":\"Print machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--full\",\"description\":\"Include full markdown for returned records\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--limit\",\"description\":\"Maximum number of pages to crawl\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--depth\",\"description\":\"Maximum crawl depth from the starting URL\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--records\",\"description\":\"Maximum number of completed records to return in the final summary\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--source\",\"description\":\"Crawl source: all discovered URLs, only sitemaps, or only links\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--render\",\"description\":\"Render pages in a browser before extraction. Disabled by default for faster static crawls\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--include-external-links\",\"description\":\"Include external links during crawl\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--include-subdomains\",\"description\":\"Include subdomains during crawl\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--include-pattern\",\"description\":\"Only include URLs matching these wildcard patterns\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--exclude-pattern\",\"description\":\"Exclude URLs matching these wildcard patterns\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--max-age-s\",\"description\":\"Max crawl cache age in seconds\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--wait-timeout-s\",\"description\":\"Max time to wait for crawl completion in seconds\",\"entry_type\":\"flag\"},{\"command\":\"f url crawl\",\"short\":null,\"long\":\"--poll-interval-s\",\"description\":\"Poll interval while waiting for completion, in seconds\",\"entry_type\":\"flag\"},{\"command\":\"f deps\",\"short\":null,\"long\":null,\"description\":\"Install or update project dependencies.\",\"entry_type\":\"subcommand\"},{\"command\":\"f deps\",\"short\":null,\"long\":\"--manager\",\"description\":\"Force a package manager instead of auto-detect\",\"entry_type\":\"flag\"},{\"command\":\"f deps install\",\"short\":null,\"long\":null,\"description\":\"Install dependencies\",\"entry_type\":\"subcommand\"},{\"command\":\"f deps update\",\"short\":null,\"long\":null,\"description\":\"Smart dependency updates based on inferred ecosystem\",\"entry_type\":\"subcommand\"},{\"command\":\"f deps update\",\"short\":null,\"long\":\"--latest\",\"description\":\"Upgrade to latest versions when supported by ecosystem tooling\",\"entry_type\":\"flag\"},{\"command\":\"f deps update\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Print planned commands without executing them\",\"entry_type\":\"flag\"},{\"command\":\"f deps update\",\"short\":\"-y\",\"long\":\"--yes\",\"description\":\"Skip confirmation prompt\",\"entry_type\":\"flag\"},{\"command\":\"f deps update\",\"short\":null,\"long\":\"--no-tui\",\"description\":\"Disable OpenTUI confirmation and use plain prompt\",\"entry_type\":\"flag\"},{\"command\":\"f deps update\",\"short\":null,\"long\":\"--ecosystem\",\"description\":\"Force a specific ecosystem instead of auto-detect\",\"entry_type\":\"flag\"},{\"command\":\"f deps update\",\"short\":null,\"long\":\"--manager\",\"description\":\"Force JS package manager (only used for js ecosystem)\",\"entry_type\":\"flag\"},{\"command\":\"f deps pick\",\"short\":null,\"long\":null,\"description\":\"Fuzzy-pick a dependency or linked repo and fetch it to ~/repos\",\"entry_type\":\"subcommand\"},{\"command\":\"f deps repo\",\"short\":null,\"long\":null,\"description\":\"Add an external repo dependency and link it under .ai/repos\",\"entry_type\":\"subcommand\"},{\"command\":\"f deps repo\",\"short\":null,\"long\":\"--root\",\"description\":\"Root directory for clones (default: ~/repos)\",\"entry_type\":\"flag\"},{\"command\":\"f deps repo\",\"short\":null,\"long\":\"--private\",\"description\":\"Create a private fork in your GitHub account and set origin\",\"entry_type\":\"flag\"},{\"command\":\"f db\",\"short\":null,\"long\":null,\"description\":\"Manage databases (Jazz, Postgres).\",\"entry_type\":\"subcommand\"},{\"command\":\"f db jazz\",\"short\":null,\"long\":null,\"description\":\"Jazz2 app credentials and env wiring\",\"entry_type\":\"subcommand\"},{\"command\":\"f db jazz new\",\"short\":null,\"long\":null,\"description\":\"Create a new Jazz2 app credential set and store env vars\",\"entry_type\":\"subcommand\"},{\"command\":\"f db jazz new\",\"short\":null,\"long\":\"--kind\",\"description\":\"What the app credentials will be used for\",\"entry_type\":\"flag\"},{\"command\":\"f db jazz new\",\"short\":null,\"long\":\"--name\",\"description\":\"Optional name for the app\",\"entry_type\":\"flag\"},{\"command\":\"f db jazz new\",\"short\":null,\"long\":\"--peer\",\"description\":\"Optional sync server URL (ws/wss urls are normalized to http/https)\",\"entry_type\":\"flag\"},{\"command\":\"f db jazz new\",\"short\":null,\"long\":\"--api-key\",\"description\":\"Optional Jazz API key (for hosted cloud routing)\",\"entry_type\":\"flag\"},{\"command\":\"f db jazz new\",\"short\":\"-e\",\"long\":\"--environment\",\"description\":\"Environment to store in (dev, staging, production)\",\"entry_type\":\"flag\"},{\"command\":\"f db postgres\",\"short\":null,\"long\":null,\"description\":\"Postgres workflows (migrations/generation)\",\"entry_type\":\"subcommand\"},{\"command\":\"f db postgres generate\",\"short\":null,\"long\":null,\"description\":\"Generate Drizzle migrations for the configured Postgres project\",\"entry_type\":\"subcommand\"},{\"command\":\"f db postgres generate\",\"short\":null,\"long\":\"--project\",\"description\":\"Override the Postgres project directory (defaults to ~/org/la/la/server)\",\"entry_type\":\"flag\"},{\"command\":\"f db postgres migrate\",\"short\":null,\"long\":null,\"description\":\"Apply Drizzle migrations for the configured Postgres project\",\"entry_type\":\"subcommand\"},{\"command\":\"f db postgres migrate\",\"short\":null,\"long\":\"--project\",\"description\":\"Override the Postgres project directory (defaults to ~/org/la/la/server)\",\"entry_type\":\"flag\"},{\"command\":\"f db postgres migrate\",\"short\":null,\"long\":\"--database-url\",\"description\":\"Explicit DATABASE_URL (falls back to env/.env/Planetscale env vars)\",\"entry_type\":\"flag\"},{\"command\":\"f db postgres migrate\",\"short\":null,\"long\":\"--generate\",\"description\":\"Generate migrations before applying them\",\"entry_type\":\"flag\"},{\"command\":\"f tools\",\"short\":null,\"long\":null,\"description\":\"Manage AI tools (.ai/tools/*.ts).\",\"entry_type\":\"subcommand\"},{\"command\":\"f tools list\",\"short\":null,\"long\":null,\"description\":\"List all tools for this project\",\"entry_type\":\"subcommand\"},{\"command\":\"f tools run\",\"short\":null,\"long\":null,\"description\":\"Run a tool\",\"entry_type\":\"subcommand\"},{\"command\":\"f tools new\",\"short\":null,\"long\":null,\"description\":\"Create a new tool\",\"entry_type\":\"subcommand\"},{\"command\":\"f tools new\",\"short\":\"-d\",\"long\":\"--description\",\"description\":\"Short description of what the tool does\",\"entry_type\":\"flag\"},{\"command\":\"f tools new\",\"short\":null,\"long\":\"--ai\",\"description\":\"Use AI (localcode) to generate the tool implementation\",\"entry_type\":\"flag\"},{\"command\":\"f tools edit\",\"short\":null,\"long\":null,\"description\":\"Edit a tool in your editor\",\"entry_type\":\"subcommand\"},{\"command\":\"f tools remove\",\"short\":null,\"long\":null,\"description\":\"Remove a tool\",\"entry_type\":\"subcommand\"},{\"command\":\"f notify\",\"short\":null,\"long\":null,\"description\":\"Send a proposal notification to Lin for approval.\",\"entry_type\":\"subcommand\"},{\"command\":\"f notify\",\"short\":\"-t\",\"long\":\"--title\",\"description\":\"Title of the proposal (shown in widget header)\",\"entry_type\":\"flag\"},{\"command\":\"f notify\",\"short\":\"-c\",\"long\":\"--context\",\"description\":\"Optional context or description\",\"entry_type\":\"flag\"},{\"command\":\"f notify\",\"short\":\"-e\",\"long\":\"--expires\",\"description\":\"Expiration time in seconds (default: 300 = 5 minutes)\",\"entry_type\":\"flag\"},{\"command\":\"f commits\",\"short\":null,\"long\":null,\"description\":\"Browse and analyze git commits with AI session metadata.\",\"entry_type\":\"subcommand\"},{\"command\":\"f commits\",\"short\":\"-n\",\"long\":\"--limit\",\"description\":\"Number of commits to show (default: 100)\",\"entry_type\":\"flag\"},{\"command\":\"f commits\",\"short\":null,\"long\":\"--all\",\"description\":\"Show commits across all branches\",\"entry_type\":\"flag\"},{\"command\":\"f commits top\",\"short\":null,\"long\":null,\"description\":\"List notable commits\",\"entry_type\":\"subcommand\"},{\"command\":\"f commits mark\",\"short\":null,\"long\":null,\"description\":\"Mark a commit as notable\",\"entry_type\":\"subcommand\"},{\"command\":\"f commits unmark\",\"short\":null,\"long\":null,\"description\":\"Remove a commit from notable list\",\"entry_type\":\"subcommand\"},{\"command\":\"f seq-rpc\",\"short\":null,\"long\":null,\"description\":\"Call seqd RPC v1 via native Rust client.\",\"entry_type\":\"subcommand\"},{\"command\":\"f seq-rpc\",\"short\":null,\"long\":\"--socket\",\"description\":\"Path to seqd Unix socket (default: $SEQ_SOCKET_PATH, then /tmp/seqd.sock)\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc\",\"short\":null,\"long\":\"--timeout-ms\",\"description\":\"Read/write timeout in milliseconds\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc\",\"short\":null,\"long\":\"--pretty\",\"description\":\"Pretty-print JSON response\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc ping\",\"short\":null,\"long\":null,\"description\":\"Health check\",\"entry_type\":\"subcommand\"},{\"command\":\"f seq-rpc ping\",\"short\":null,\"long\":\"--request-id\",\"description\":\"Caller-owned id for request correlation\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc ping\",\"short\":null,\"long\":\"--run-id\",\"description\":\"Caller run id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc ping\",\"short\":null,\"long\":\"--tool-call-id\",\"description\":\"Caller tool call id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc app-state\",\"short\":null,\"long\":null,\"description\":\"Current/previous foreground app snapshot\",\"entry_type\":\"subcommand\"},{\"command\":\"f seq-rpc app-state\",\"short\":null,\"long\":\"--request-id\",\"description\":\"Caller-owned id for request correlation\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc app-state\",\"short\":null,\"long\":\"--run-id\",\"description\":\"Caller run id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc app-state\",\"short\":null,\"long\":\"--tool-call-id\",\"description\":\"Caller tool call id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc perf\",\"short\":null,\"long\":null,\"description\":\"Daemon perf/rusage snapshot\",\"entry_type\":\"subcommand\"},{\"command\":\"f seq-rpc perf\",\"short\":null,\"long\":\"--request-id\",\"description\":\"Caller-owned id for request correlation\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc perf\",\"short\":null,\"long\":\"--run-id\",\"description\":\"Caller run id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc perf\",\"short\":null,\"long\":\"--tool-call-id\",\"description\":\"Caller tool call id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc open-app\",\"short\":null,\"long\":null,\"description\":\"Open application by name\",\"entry_type\":\"subcommand\"},{\"command\":\"f seq-rpc open-app\",\"short\":null,\"long\":\"--request-id\",\"description\":\"Caller-owned id for request correlation\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc open-app\",\"short\":null,\"long\":\"--run-id\",\"description\":\"Caller run id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc open-app\",\"short\":null,\"long\":\"--tool-call-id\",\"description\":\"Caller tool call id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc open-app-toggle\",\"short\":null,\"long\":null,\"description\":\"Toggle application by name\",\"entry_type\":\"subcommand\"},{\"command\":\"f seq-rpc open-app-toggle\",\"short\":null,\"long\":\"--request-id\",\"description\":\"Caller-owned id for request correlation\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc open-app-toggle\",\"short\":null,\"long\":\"--run-id\",\"description\":\"Caller run id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc open-app-toggle\",\"short\":null,\"long\":\"--tool-call-id\",\"description\":\"Caller tool call id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc screenshot\",\"short\":null,\"long\":null,\"description\":\"Save screenshot to path\",\"entry_type\":\"subcommand\"},{\"command\":\"f seq-rpc screenshot\",\"short\":null,\"long\":\"--request-id\",\"description\":\"Caller-owned id for request correlation\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc screenshot\",\"short\":null,\"long\":\"--run-id\",\"description\":\"Caller run id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc screenshot\",\"short\":null,\"long\":\"--tool-call-id\",\"description\":\"Caller tool call id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc rpc\",\"short\":null,\"long\":null,\"description\":\"Raw operation and optional JSON args\",\"entry_type\":\"subcommand\"},{\"command\":\"f seq-rpc rpc\",\"short\":null,\"long\":\"--args-json\",\"description\":\"Optional JSON args payload\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc rpc\",\"short\":null,\"long\":\"--request-id\",\"description\":\"Caller-owned id for request correlation\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc rpc\",\"short\":null,\"long\":\"--run-id\",\"description\":\"Caller run id\",\"entry_type\":\"flag\"},{\"command\":\"f seq-rpc rpc\",\"short\":null,\"long\":\"--tool-call-id\",\"description\":\"Caller tool call id\",\"entry_type\":\"flag\"},{\"command\":\"f explain-commits\",\"short\":null,\"long\":null,\"description\":\"Generate AI explanations for recent commits.\",\"entry_type\":\"subcommand\"},{\"command\":\"f explain-commits\",\"short\":null,\"long\":\"--force\",\"description\":\"Re-explain even if already processed\",\"entry_type\":\"flag\"},{\"command\":\"f explain-commits\",\"short\":null,\"long\":\"--out-dir\",\"description\":\"Output directory (relative to repo root unless absolute)\",\"entry_type\":\"flag\"},{\"command\":\"f setup\",\"short\":null,\"long\":null,\"description\":\"Bootstrap project and run setup task or aliases.\",\"entry_type\":\"subcommand\"},{\"command\":\"f setup\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f agents\",\"short\":null,\"long\":null,\"description\":\"Invoke gen AI agents.\",\"entry_type\":\"subcommand\"},{\"command\":\"f agents list\",\"short\":null,\"long\":null,\"description\":\"List available agents\",\"entry_type\":\"subcommand\"},{\"command\":\"f agents run\",\"short\":null,\"long\":null,\"description\":\"Run an agent with a prompt\",\"entry_type\":\"subcommand\"},{\"command\":\"f agents global\",\"short\":null,\"long\":null,\"description\":\"Run a global agent (prompt optional)\",\"entry_type\":\"subcommand\"},{\"command\":\"f agents copy\",\"short\":null,\"long\":null,\"description\":\"Copy agent instructions to clipboard (fuzzy select)\",\"entry_type\":\"subcommand\"},{\"command\":\"f agents rules\",\"short\":null,\"long\":null,\"description\":\"Switch agents.md profile (fuzzy select if not provided)\",\"entry_type\":\"subcommand\"},{\"command\":\"f hive\",\"short\":null,\"long\":null,\"description\":\"Manage and run hive agents.\",\"entry_type\":\"subcommand\"},{\"command\":\"f hive list\",\"short\":null,\"long\":null,\"description\":\"List available hive agents\",\"entry_type\":\"subcommand\"},{\"command\":\"f hive run\",\"short\":null,\"long\":null,\"description\":\"Run a hive agent with a prompt\",\"entry_type\":\"subcommand\"},{\"command\":\"f hive new\",\"short\":null,\"long\":null,\"description\":\"Create a new agent spec\",\"entry_type\":\"subcommand\"},{\"command\":\"f hive new\",\"short\":\"-g\",\"long\":\"--global\",\"description\":\"Create as global agent (default: project-local)\",\"entry_type\":\"flag\"},{\"command\":\"f hive edit\",\"short\":null,\"long\":null,\"description\":\"Edit an agent spec file\",\"entry_type\":\"subcommand\"},{\"command\":\"f hive show\",\"short\":null,\"long\":null,\"description\":\"Show an agent's spec\",\"entry_type\":\"subcommand\"},{\"command\":\"f sync\",\"short\":null,\"long\":null,\"description\":\"Sync git repo: pull + upstream merge (push optional).\",\"entry_type\":\"subcommand\"},{\"command\":\"f sync\",\"short\":\"-r\",\"long\":\"--rebase\",\"description\":\"Use rebase instead of merge when pulling\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":null,\"long\":\"--push\",\"description\":\"Push to configured git remote after sync (default: false)\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":null,\"long\":\"--no-push\",\"description\":\"Skip pushing to configured git remote (legacy; default is already no push)\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":\"-s\",\"long\":\"--stash\",\"description\":\"Auto-stash uncommitted changes (default: true)\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":null,\"long\":\"--stash-commits\",\"description\":\"Stash local JJ commits to a bookmark before syncing (JJ-only)\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":null,\"long\":\"--allow-queue\",\"description\":\"Allow sync/rebase even when commit queue is non-empty\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":null,\"long\":\"--create-repo\",\"description\":\"Create origin repo on GitHub if it doesn't exist\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":\"-f\",\"long\":\"--fix\",\"description\":\"Auto-fix conflicts and errors using Claude (default: true)\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":null,\"long\":\"--no-fix\",\"description\":\"Disable auto-fix (same as --fix=false)\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":null,\"long\":\"--max-fix-attempts\",\"description\":\"Maximum fix attempts before giving up\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":null,\"long\":\"--allow-review-issues\",\"description\":\"Allow push even if P1/P2 review todos are open\",\"entry_type\":\"flag\"},{\"command\":\"f sync\",\"short\":null,\"long\":\"--compact\",\"description\":\"Reduce sync output noise (show remote update counts without commit line listings)\",\"entry_type\":\"flag\"},{\"command\":\"f checkout\",\"short\":null,\"long\":null,\"description\":\"Checkout a GitHub PR safely.\",\"entry_type\":\"subcommand\"},{\"command\":\"f checkout\",\"short\":null,\"long\":\"--remote\",\"description\":\"Preferred remote to use when checking out a PR branch\",\"entry_type\":\"flag\"},{\"command\":\"f checkout\",\"short\":null,\"long\":\"--stash\",\"description\":\"Auto-stash uncommitted changes before checkout (default: true)\",\"entry_type\":\"flag\"},{\"command\":\"f checkout\",\"short\":null,\"long\":\"--no-stash\",\"description\":\"Disable auto-stash (same as --stash=false)\",\"entry_type\":\"flag\"},{\"command\":\"f switch\",\"short\":null,\"long\":null,\"description\":\"Switch to a branch and align upstream tracking.\",\"entry_type\":\"subcommand\"},{\"command\":\"f switch\",\"short\":null,\"long\":\"--remote\",\"description\":\"Preferred remote to track from (default: upstream, then origin)\",\"entry_type\":\"flag\"},{\"command\":\"f switch\",\"short\":null,\"long\":\"--preserve\",\"description\":\"Auto-preserve a safety snapshot branch/bookmark before switching (default: true)\",\"entry_type\":\"flag\"},{\"command\":\"f switch\",\"short\":null,\"long\":\"--no-preserve\",\"description\":\"Disable safety snapshot preservation (same as --preserve=false)\",\"entry_type\":\"flag\"},{\"command\":\"f switch\",\"short\":null,\"long\":\"--stash\",\"description\":\"Auto-stash uncommitted changes before switching (default: true)\",\"entry_type\":\"flag\"},{\"command\":\"f switch\",\"short\":null,\"long\":\"--no-stash\",\"description\":\"Disable auto-stash (same as --stash=false)\",\"entry_type\":\"flag\"},{\"command\":\"f switch\",\"short\":null,\"long\":\"--sync\",\"description\":\"Run sync after switching (uses --no-push)\",\"entry_type\":\"flag\"},{\"command\":\"f push\",\"short\":null,\"long\":null,\"description\":\"Push current branch to a configured private mirror remote.\",\"entry_type\":\"subcommand\"},{\"command\":\"f push\",\"short\":null,\"long\":\"--remote\",\"description\":\"Git remote name to push to (default: origin)\",\"entry_type\":\"flag\"},{\"command\":\"f push\",\"short\":null,\"long\":\"--owner\",\"description\":\"Owner/org for the mirror repo (overrides FLOW_PUSH_OWNER / personal env store)\",\"entry_type\":\"flag\"},{\"command\":\"f push\",\"short\":null,\"long\":\"--repo\",\"description\":\"Override repo name (defaults to upstream/origin repo name or folder name)\",\"entry_type\":\"flag\"},{\"command\":\"f push\",\"short\":null,\"long\":\"--create-repo\",\"description\":\"Create the target repo if it does not exist (requires `gh` auth)\",\"entry_type\":\"flag\"},{\"command\":\"f push\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite an existing remote URL when it points elsewhere\",\"entry_type\":\"flag\"},{\"command\":\"f push\",\"short\":null,\"long\":\"--no-ssh\",\"description\":\"Do not attempt to unlock Flow-managed SSH key before pushing\",\"entry_type\":\"flag\"},{\"command\":\"f push\",\"short\":null,\"long\":\"--ttl-hours\",\"description\":\"TTL (hours) for Flow SSH key unlock (default: 24)\",\"entry_type\":\"flag\"},{\"command\":\"f push\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Print what would be done without changing remotes or pushing\",\"entry_type\":\"flag\"},{\"command\":\"f status\",\"short\":null,\"long\":null,\"description\":\"Show JJ workflow status optimized for stacked home-branch work.\",\"entry_type\":\"subcommand\"},{\"command\":\"f status\",\"short\":null,\"long\":\"--raw\",\"description\":\"Show raw `jj status` output without Flow's workflow summary\",\"entry_type\":\"flag\"},{\"command\":\"f jj\",\"short\":null,\"long\":null,\"description\":\"Jujutsu (jj) workflow helpers.\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj init\",\"short\":null,\"long\":null,\"description\":\"Initialize jj in the repo (colocated with git when possible)\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj init\",\"short\":null,\"long\":\"--path\",\"description\":\"Optional path to initialize (defaults to current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f jj status\",\"short\":null,\"long\":null,\"description\":\"Show jj status\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj status\",\"short\":null,\"long\":\"--raw\",\"description\":\"Show raw `jj status` output without Flow's workflow summary\",\"entry_type\":\"flag\"},{\"command\":\"f jj fetch\",\"short\":null,\"long\":null,\"description\":\"Fetch from git remotes\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj rebase\",\"short\":null,\"long\":null,\"description\":\"Rebase current change onto a destination\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj rebase\",\"short\":null,\"long\":\"--dest\",\"description\":\"Destination to rebase onto (default: jj.default_branch or main/master)\",\"entry_type\":\"flag\"},{\"command\":\"f jj push\",\"short\":null,\"long\":null,\"description\":\"Push bookmarks to git\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj push\",\"short\":null,\"long\":\"--bookmark\",\"description\":\"Bookmark to push\",\"entry_type\":\"flag\"},{\"command\":\"f jj push\",\"short\":null,\"long\":\"--all\",\"description\":\"Push all bookmarks\",\"entry_type\":\"flag\"},{\"command\":\"f jj sync\",\"short\":null,\"long\":null,\"description\":\"Fetch, rebase, then push a bookmark\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj sync\",\"short\":null,\"long\":\"--bookmark\",\"description\":\"Bookmark to push after rebase (optional)\",\"entry_type\":\"flag\"},{\"command\":\"f jj sync\",\"short\":null,\"long\":\"--dest\",\"description\":\"Destination to rebase onto (default: jj.default_branch or main/master)\",\"entry_type\":\"flag\"},{\"command\":\"f jj sync\",\"short\":null,\"long\":\"--remote\",\"description\":\"Remote to sync with (default: git.remote, then jj.remote, then origin)\",\"entry_type\":\"flag\"},{\"command\":\"f jj sync\",\"short\":null,\"long\":\"--no-push\",\"description\":\"Skip pushing after rebase\",\"entry_type\":\"flag\"},{\"command\":\"f jj workspace\",\"short\":null,\"long\":null,\"description\":\"Manage workspaces\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj workspace list\",\"short\":null,\"long\":null,\"description\":\"List workspaces\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj workspace add\",\"short\":null,\"long\":null,\"description\":\"Add a workspace\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj workspace add\",\"short\":null,\"long\":\"--path\",\"description\":\"Optional path for workspace directory\",\"entry_type\":\"flag\"},{\"command\":\"f jj workspace add\",\"short\":null,\"long\":\"--rev\",\"description\":\"Optional base revision for the new workspace working copy\",\"entry_type\":\"flag\"},{\"command\":\"f jj workspace lane\",\"short\":null,\"long\":null,\"description\":\"Create an isolated parallel workspace lane anchored on trunk\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj workspace lane\",\"short\":null,\"long\":\"--path\",\"description\":\"Optional path for workspace directory\",\"entry_type\":\"flag\"},{\"command\":\"f jj workspace lane\",\"short\":null,\"long\":\"--base\",\"description\":\"Base revision (default: <default_branch>@<remote> if tracked, else <default_branch>)\",\"entry_type\":\"flag\"},{\"command\":\"f jj workspace lane\",\"short\":null,\"long\":\"--remote\",\"description\":\"Remote used for default base resolution\",\"entry_type\":\"flag\"},{\"command\":\"f jj workspace lane\",\"short\":null,\"long\":\"--no-fetch\",\"description\":\"Skip fetch before creating the lane\",\"entry_type\":\"flag\"},{\"command\":\"f jj workspace review\",\"short\":null,\"long\":null,\"description\":\"Create or reuse a stable JJ workspace for a review branch without touching the current checkout\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj workspace review\",\"short\":null,\"long\":\"--path\",\"description\":\"Optional path for workspace directory\",\"entry_type\":\"flag\"},{\"command\":\"f jj workspace review\",\"short\":null,\"long\":\"--base\",\"description\":\"Optional base revision. Defaults to the branch commit when found, else trunk\",\"entry_type\":\"flag\"},{\"command\":\"f jj workspace review\",\"short\":null,\"long\":\"--remote\",\"description\":\"Remote used for branch lookup and default base resolution\",\"entry_type\":\"flag\"},{\"command\":\"f jj workspace review\",\"short\":null,\"long\":\"--no-fetch\",\"description\":\"Skip fetch before resolving the review branch\",\"entry_type\":\"flag\"},{\"command\":\"f jj bookmark\",\"short\":null,\"long\":null,\"description\":\"Manage bookmarks\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj bookmark list\",\"short\":null,\"long\":null,\"description\":\"List bookmarks\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj bookmark track\",\"short\":null,\"long\":null,\"description\":\"Track a bookmark from a remote\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj bookmark track\",\"short\":null,\"long\":\"--remote\",\"description\":\"Remote name (default: git.remote, then jj.remote, then origin)\",\"entry_type\":\"flag\"},{\"command\":\"f jj bookmark create\",\"short\":null,\"long\":null,\"description\":\"Create a bookmark at a revision\",\"entry_type\":\"subcommand\"},{\"command\":\"f jj bookmark create\",\"short\":null,\"long\":\"--rev\",\"description\":\"Revision to attach to (default: @)\",\"entry_type\":\"flag\"},{\"command\":\"f jj bookmark create\",\"short\":null,\"long\":\"--track\",\"description\":\"Whether to track the remote bookmark (default: jj.auto_track)\",\"entry_type\":\"flag\"},{\"command\":\"f jj bookmark create\",\"short\":null,\"long\":\"--remote\",\"description\":\"Remote to track (default: git.remote, then jj.remote, then origin)\",\"entry_type\":\"flag\"},{\"command\":\"f git-repair\",\"short\":null,\"long\":null,\"description\":\"Repair git state (abort rebase/merge, leave detached HEAD).\",\"entry_type\":\"subcommand\"},{\"command\":\"f git-repair\",\"short\":null,\"long\":\"--branch\",\"description\":\"Branch to checkout if HEAD is detached (default: main)\",\"entry_type\":\"flag\"},{\"command\":\"f git-repair\",\"short\":\"-n\",\"long\":\"--dry-run\",\"description\":\"Dry run - show what would be repaired\",\"entry_type\":\"flag\"},{\"command\":\"f git-repair\",\"short\":null,\"long\":\"--land-main\",\"description\":\"After repair, switch to target branch and cherry-pick current HEAD onto it. If conflicts occur, flow auto-aborts and returns to the source branch\",\"entry_type\":\"flag\"},{\"command\":\"f info\",\"short\":null,\"long\":null,\"description\":\"Show project information.\",\"entry_type\":\"subcommand\"},{\"command\":\"f upstream\",\"short\":null,\"long\":null,\"description\":\"Manage upstream fork workflow.\",\"entry_type\":\"subcommand\"},{\"command\":\"f upstream status\",\"short\":null,\"long\":null,\"description\":\"Show current upstream configuration\",\"entry_type\":\"subcommand\"},{\"command\":\"f upstream setup\",\"short\":null,\"long\":null,\"description\":\"Set up upstream remote and local tracking branch\",\"entry_type\":\"subcommand\"},{\"command\":\"f upstream setup\",\"short\":\"-u\",\"long\":\"--upstream-url\",\"description\":\"URL of the upstream repository\",\"entry_type\":\"flag\"},{\"command\":\"f upstream setup\",\"short\":\"-u\",\"long\":\"--upstream-branch\",\"description\":\"Branch name on upstream (default: main)\",\"entry_type\":\"flag\"},{\"command\":\"f upstream pull\",\"short\":null,\"long\":null,\"description\":\"Pull changes from upstream into local 'upstream' branch\",\"entry_type\":\"subcommand\"},{\"command\":\"f upstream pull\",\"short\":\"-b\",\"long\":\"--branch\",\"description\":\"Also merge into this branch after pulling\",\"entry_type\":\"flag\"},{\"command\":\"f upstream check\",\"short\":null,\"long\":null,\"description\":\"Checkout local 'upstream' branch synced to upstream\",\"entry_type\":\"subcommand\"},{\"command\":\"f upstream sync\",\"short\":null,\"long\":null,\"description\":\"Full sync: pull upstream, merge to dev/main, push to origin\",\"entry_type\":\"subcommand\"},{\"command\":\"f upstream sync\",\"short\":null,\"long\":\"--no-push\",\"description\":\"Skip pushing to origin\",\"entry_type\":\"flag\"},{\"command\":\"f upstream sync\",\"short\":null,\"long\":\"--create-repo\",\"description\":\"Create origin repo on GitHub if it doesn't exist\",\"entry_type\":\"flag\"},{\"command\":\"f upstream open\",\"short\":null,\"long\":null,\"description\":\"Open upstream repository URL in browser\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy\",\"short\":null,\"long\":null,\"description\":\"Deploy project to host or cloud platform.\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy host\",\"short\":null,\"long\":null,\"description\":\"Deploy to Linux host via SSH\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy host\",\"short\":null,\"long\":\"--remote-build\",\"description\":\"Build remotely instead of syncing local build artifacts\",\"entry_type\":\"flag\"},{\"command\":\"f deploy host\",\"short\":null,\"long\":\"--setup\",\"description\":\"Run setup script even if already deployed\",\"entry_type\":\"flag\"},{\"command\":\"f deploy cloudflare\",\"short\":null,\"long\":null,\"description\":\"Deploy to Cloudflare Workers\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy cloudflare\",\"short\":null,\"long\":\"--secrets\",\"description\":\"Also set secrets from env_file\",\"entry_type\":\"flag\"},{\"command\":\"f deploy cloudflare\",\"short\":null,\"long\":\"--dev\",\"description\":\"Run in dev mode instead of deploying\",\"entry_type\":\"flag\"},{\"command\":\"f deploy web\",\"short\":null,\"long\":null,\"description\":\"Deploy the web site (Cloudflare)\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy setup\",\"short\":null,\"long\":null,\"description\":\"Interactive deploy setup (Cloudflare Workers for now)\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy railway\",\"short\":null,\"long\":null,\"description\":\"Deploy to Railway\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy config\",\"short\":null,\"long\":null,\"description\":\"Configure deployment defaults (Linux host)\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy release\",\"short\":null,\"long\":null,\"description\":\"Run the project's release task\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy release\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f deploy status\",\"short\":null,\"long\":null,\"description\":\"Show deployment status\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy logs\",\"short\":null,\"long\":null,\"description\":\"View deployment logs\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy logs\",\"short\":\"-f\",\"long\":\"--follow\",\"description\":\"Follow logs in real-time\",\"entry_type\":\"flag\"},{\"command\":\"f deploy logs\",\"short\":null,\"long\":\"--since-deploy\",\"description\":\"Show logs since the last successful deploy (default)\",\"entry_type\":\"flag\"},{\"command\":\"f deploy logs\",\"short\":null,\"long\":\"--all\",\"description\":\"Show full log history (ignores --since-deploy)\",\"entry_type\":\"flag\"},{\"command\":\"f deploy logs\",\"short\":\"-n\",\"long\":\"--lines\",\"description\":\"Number of lines to show\",\"entry_type\":\"flag\"},{\"command\":\"f deploy restart\",\"short\":null,\"long\":null,\"description\":\"Restart the deployed service\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy stop\",\"short\":null,\"long\":null,\"description\":\"Stop the deployed service\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy shell\",\"short\":null,\"long\":null,\"description\":\"SSH into the host (for host deployments)\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy set-host\",\"short\":null,\"long\":null,\"description\":\"Configure host for deployment\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy show-host\",\"short\":null,\"long\":null,\"description\":\"Show current host configuration\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy health\",\"short\":null,\"long\":null,\"description\":\"Check if deployment is healthy (HTTP health check)\",\"entry_type\":\"subcommand\"},{\"command\":\"f deploy health\",\"short\":null,\"long\":\"--url\",\"description\":\"Custom URL to check (defaults to domain from config)\",\"entry_type\":\"flag\"},{\"command\":\"f deploy health\",\"short\":null,\"long\":\"--status\",\"description\":\"Expected HTTP status code\",\"entry_type\":\"flag\"},{\"command\":\"f prod\",\"short\":null,\"long\":null,\"description\":\"Deploy to production using flow.toml deploy config.\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod host\",\"short\":null,\"long\":null,\"description\":\"Deploy to Linux host via SSH\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod host\",\"short\":null,\"long\":\"--remote-build\",\"description\":\"Build remotely instead of syncing local build artifacts\",\"entry_type\":\"flag\"},{\"command\":\"f prod host\",\"short\":null,\"long\":\"--setup\",\"description\":\"Run setup script even if already deployed\",\"entry_type\":\"flag\"},{\"command\":\"f prod cloudflare\",\"short\":null,\"long\":null,\"description\":\"Deploy to Cloudflare Workers\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod cloudflare\",\"short\":null,\"long\":\"--secrets\",\"description\":\"Also set secrets from env_file\",\"entry_type\":\"flag\"},{\"command\":\"f prod cloudflare\",\"short\":null,\"long\":\"--dev\",\"description\":\"Run in dev mode instead of deploying\",\"entry_type\":\"flag\"},{\"command\":\"f prod web\",\"short\":null,\"long\":null,\"description\":\"Deploy the web site (Cloudflare)\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod setup\",\"short\":null,\"long\":null,\"description\":\"Interactive deploy setup (Cloudflare Workers for now)\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod railway\",\"short\":null,\"long\":null,\"description\":\"Deploy to Railway\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod config\",\"short\":null,\"long\":null,\"description\":\"Configure deployment defaults (Linux host)\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod release\",\"short\":null,\"long\":null,\"description\":\"Run the project's release task\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod release\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f prod status\",\"short\":null,\"long\":null,\"description\":\"Show deployment status\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod logs\",\"short\":null,\"long\":null,\"description\":\"View deployment logs\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod logs\",\"short\":\"-f\",\"long\":\"--follow\",\"description\":\"Follow logs in real-time\",\"entry_type\":\"flag\"},{\"command\":\"f prod logs\",\"short\":null,\"long\":\"--since-deploy\",\"description\":\"Show logs since the last successful deploy (default)\",\"entry_type\":\"flag\"},{\"command\":\"f prod logs\",\"short\":null,\"long\":\"--all\",\"description\":\"Show full log history (ignores --since-deploy)\",\"entry_type\":\"flag\"},{\"command\":\"f prod logs\",\"short\":\"-n\",\"long\":\"--lines\",\"description\":\"Number of lines to show\",\"entry_type\":\"flag\"},{\"command\":\"f prod restart\",\"short\":null,\"long\":null,\"description\":\"Restart the deployed service\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod stop\",\"short\":null,\"long\":null,\"description\":\"Stop the deployed service\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod shell\",\"short\":null,\"long\":null,\"description\":\"SSH into the host (for host deployments)\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod set-host\",\"short\":null,\"long\":null,\"description\":\"Configure host for deployment\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod show-host\",\"short\":null,\"long\":null,\"description\":\"Show current host configuration\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod health\",\"short\":null,\"long\":null,\"description\":\"Check if deployment is healthy (HTTP health check)\",\"entry_type\":\"subcommand\"},{\"command\":\"f prod health\",\"short\":null,\"long\":\"--url\",\"description\":\"Custom URL to check (defaults to domain from config)\",\"entry_type\":\"flag\"},{\"command\":\"f prod health\",\"short\":null,\"long\":\"--status\",\"description\":\"Expected HTTP status code\",\"entry_type\":\"flag\"},{\"command\":\"f publish\",\"short\":null,\"long\":null,\"description\":\"Publish project to gitedit.dev or GitHub.\",\"entry_type\":\"subcommand\"},{\"command\":\"f publish gitedit\",\"short\":null,\"long\":null,\"description\":\"Publish to gitedit.dev\",\"entry_type\":\"subcommand\"},{\"command\":\"f publish gitedit\",\"short\":\"-n\",\"long\":\"--name\",\"description\":\"Repository name (defaults to current folder name)\",\"entry_type\":\"flag\"},{\"command\":\"f publish gitedit\",\"short\":null,\"long\":\"--owner\",\"description\":\"Repository owner/org (GitHub) or owner (gitedit.dev)\",\"entry_type\":\"flag\"},{\"command\":\"f publish gitedit\",\"short\":null,\"long\":\"--set-origin\",\"description\":\"Update existing origin remote to match the target repo (GitHub)\",\"entry_type\":\"flag\"},{\"command\":\"f publish gitedit\",\"short\":null,\"long\":\"--public\",\"description\":\"Make the repository public\",\"entry_type\":\"flag\"},{\"command\":\"f publish gitedit\",\"short\":null,\"long\":\"--private\",\"description\":\"Make the repository private\",\"entry_type\":\"flag\"},{\"command\":\"f publish gitedit\",\"short\":\"-d\",\"long\":\"--description\",\"description\":\"Description for the repository\",\"entry_type\":\"flag\"},{\"command\":\"f publish gitedit\",\"short\":\"-y\",\"long\":\"--yes\",\"description\":\"Skip confirmation prompts\",\"entry_type\":\"flag\"},{\"command\":\"f publish github\",\"short\":null,\"long\":null,\"description\":\"Publish to GitHub\",\"entry_type\":\"subcommand\"},{\"command\":\"f publish github\",\"short\":\"-n\",\"long\":\"--name\",\"description\":\"Repository name (defaults to current folder name)\",\"entry_type\":\"flag\"},{\"command\":\"f publish github\",\"short\":null,\"long\":\"--owner\",\"description\":\"Repository owner/org (GitHub) or owner (gitedit.dev)\",\"entry_type\":\"flag\"},{\"command\":\"f publish github\",\"short\":null,\"long\":\"--set-origin\",\"description\":\"Update existing origin remote to match the target repo (GitHub)\",\"entry_type\":\"flag\"},{\"command\":\"f publish github\",\"short\":null,\"long\":\"--public\",\"description\":\"Make the repository public\",\"entry_type\":\"flag\"},{\"command\":\"f publish github\",\"short\":null,\"long\":\"--private\",\"description\":\"Make the repository private\",\"entry_type\":\"flag\"},{\"command\":\"f publish github\",\"short\":\"-d\",\"long\":\"--description\",\"description\":\"Description for the repository\",\"entry_type\":\"flag\"},{\"command\":\"f publish github\",\"short\":\"-y\",\"long\":\"--yes\",\"description\":\"Skip confirmation prompts\",\"entry_type\":\"flag\"},{\"command\":\"f clone\",\"short\":null,\"long\":null,\"description\":\"Clone a repository into the current directory (git clone style).\",\"entry_type\":\"subcommand\"},{\"command\":\"f repos\",\"short\":null,\"long\":null,\"description\":\"Clone repositories into a structured local directory.\",\"entry_type\":\"subcommand\"},{\"command\":\"f repos clone\",\"short\":null,\"long\":null,\"description\":\"Clone a repository into ~/repos/<owner>/<repo>\",\"entry_type\":\"subcommand\"},{\"command\":\"f repos clone\",\"short\":null,\"long\":\"--root\",\"description\":\"Root directory for clones (default: ~/repos)\",\"entry_type\":\"flag\"},{\"command\":\"f repos clone\",\"short\":null,\"long\":\"--full\",\"description\":\"Perform a full clone (skip shallow clone + background history fetch)\",\"entry_type\":\"flag\"},{\"command\":\"f repos clone\",\"short\":null,\"long\":\"--no-upstream\",\"description\":\"Skip automatic upstream setup for forks\",\"entry_type\":\"flag\"},{\"command\":\"f repos clone\",\"short\":\"-u\",\"long\":\"--upstream-url\",\"description\":\"Upstream URL override (defaults to fork parent via gh)\",\"entry_type\":\"flag\"},{\"command\":\"f repos create\",\"short\":null,\"long\":null,\"description\":\"Create a GitHub repository from the current folder and push it\",\"entry_type\":\"subcommand\"},{\"command\":\"f repos create\",\"short\":\"-n\",\"long\":\"--name\",\"description\":\"Repository name (defaults to current folder name)\",\"entry_type\":\"flag\"},{\"command\":\"f repos create\",\"short\":null,\"long\":\"--owner\",\"description\":\"Repository owner/org (GitHub) or owner (gitedit.dev)\",\"entry_type\":\"flag\"},{\"command\":\"f repos create\",\"short\":null,\"long\":\"--set-origin\",\"description\":\"Update existing origin remote to match the target repo (GitHub)\",\"entry_type\":\"flag\"},{\"command\":\"f repos create\",\"short\":null,\"long\":\"--public\",\"description\":\"Make the repository public\",\"entry_type\":\"flag\"},{\"command\":\"f repos create\",\"short\":null,\"long\":\"--private\",\"description\":\"Make the repository private\",\"entry_type\":\"flag\"},{\"command\":\"f repos create\",\"short\":\"-d\",\"long\":\"--description\",\"description\":\"Description for the repository\",\"entry_type\":\"flag\"},{\"command\":\"f repos create\",\"short\":\"-y\",\"long\":\"--yes\",\"description\":\"Skip confirmation prompts\",\"entry_type\":\"flag\"},{\"command\":\"f repos capsule\",\"short\":null,\"long\":null,\"description\":\"Build or inspect a compact repo capsule for path-based Codex context\",\"entry_type\":\"subcommand\"},{\"command\":\"f repos capsule\",\"short\":null,\"long\":\"--path\",\"description\":\"Repo or project path to inspect (defaults to the current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f repos capsule\",\"short\":null,\"long\":\"--refresh\",\"description\":\"Force a fresh capsule rebuild before printing\",\"entry_type\":\"flag\"},{\"command\":\"f repos capsule\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f repos alias\",\"short\":null,\"long\":null,\"description\":\"Manage repo aliases used by Codex repo-reference resolution\",\"entry_type\":\"subcommand\"},{\"command\":\"f repos alias list\",\"short\":null,\"long\":null,\"description\":\"List registered repo aliases\",\"entry_type\":\"subcommand\"},{\"command\":\"f repos alias list\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f repos alias set\",\"short\":null,\"long\":null,\"description\":\"Register or update an alias for a repo path\",\"entry_type\":\"subcommand\"},{\"command\":\"f repos alias set\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f repos alias remove\",\"short\":null,\"long\":null,\"description\":\"Remove a registered alias\",\"entry_type\":\"subcommand\"},{\"command\":\"f repos alias import-shelf\",\"short\":null,\"long\":null,\"description\":\"Import aliases from Shelf config\",\"entry_type\":\"subcommand\"},{\"command\":\"f repos alias import-shelf\",\"short\":null,\"long\":\"--config\",\"description\":\"Override the Shelf config path (default: ~/.agents/shelf/config.json)\",\"entry_type\":\"flag\"},{\"command\":\"f repos alias import-shelf\",\"short\":null,\"long\":\"--json\",\"description\":\"Emit machine-readable JSON\",\"entry_type\":\"flag\"},{\"command\":\"f code\",\"short\":null,\"long\":null,\"description\":\"Browse git repos under ~/code.\",\"entry_type\":\"subcommand\"},{\"command\":\"f code\",\"short\":null,\"long\":\"--root\",\"description\":\"Root directory to scan (default: ~/code)\",\"entry_type\":\"flag\"},{\"command\":\"f code list\",\"short\":null,\"long\":null,\"description\":\"List git repos under ~/code\",\"entry_type\":\"subcommand\"},{\"command\":\"f code new\",\"short\":null,\"long\":null,\"description\":\"Create a new project from a template in ~/new/<name>\",\"entry_type\":\"subcommand\"},{\"command\":\"f code new\",\"short\":null,\"long\":\"--ignored\",\"description\":\"Add the new path to .gitignore in the containing repo\",\"entry_type\":\"flag\"},{\"command\":\"f code new\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show what would change without writing\",\"entry_type\":\"flag\"},{\"command\":\"f code migrate\",\"short\":null,\"long\":null,\"description\":\"Move a folder into ~/code/<relative-path> and migrate AI sessions\",\"entry_type\":\"subcommand\"},{\"command\":\"f code migrate\",\"short\":\"-c\",\"long\":\"--copy\",\"description\":\"Copy instead of move (keeps original)\",\"entry_type\":\"flag\"},{\"command\":\"f code migrate\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show what would change without writing\",\"entry_type\":\"flag\"},{\"command\":\"f code migrate\",\"short\":null,\"long\":\"--skip-claude\",\"description\":\"Skip migrating Claude sessions\",\"entry_type\":\"flag\"},{\"command\":\"f code migrate\",\"short\":null,\"long\":\"--skip-codex\",\"description\":\"Skip migrating Codex sessions\",\"entry_type\":\"flag\"},{\"command\":\"f code move-sessions\",\"short\":null,\"long\":null,\"description\":\"Move AI sessions when a project path changes\",\"entry_type\":\"subcommand\"},{\"command\":\"f code move-sessions\",\"short\":null,\"long\":\"--from\",\"description\":\"Old project path\",\"entry_type\":\"flag\"},{\"command\":\"f code move-sessions\",\"short\":null,\"long\":\"--to\",\"description\":\"New project path\",\"entry_type\":\"flag\"},{\"command\":\"f code move-sessions\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show what would change without writing\",\"entry_type\":\"flag\"},{\"command\":\"f code move-sessions\",\"short\":null,\"long\":\"--skip-claude\",\"description\":\"Skip migrating Claude sessions\",\"entry_type\":\"flag\"},{\"command\":\"f code move-sessions\",\"short\":null,\"long\":\"--skip-codex\",\"description\":\"Skip migrating Codex sessions\",\"entry_type\":\"flag\"},{\"command\":\"f migrate\",\"short\":null,\"long\":null,\"description\":\"Move or copy a folder to a new location, preserving symlinks and AI sessions.\",\"entry_type\":\"subcommand\"},{\"command\":\"f migrate\",\"short\":\"-c\",\"long\":\"--copy\",\"description\":\"Copy instead of move (keeps original)\",\"entry_type\":\"flag\"},{\"command\":\"f migrate\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show what would change without writing\",\"entry_type\":\"flag\"},{\"command\":\"f migrate\",\"short\":null,\"long\":\"--skip-claude\",\"description\":\"Skip migrating Claude sessions\",\"entry_type\":\"flag\"},{\"command\":\"f migrate\",\"short\":null,\"long\":\"--skip-codex\",\"description\":\"Skip migrating Codex sessions\",\"entry_type\":\"flag\"},{\"command\":\"f migrate code\",\"short\":null,\"long\":null,\"description\":\"Move or copy current folder to ~/code/<relative-path>\",\"entry_type\":\"subcommand\"},{\"command\":\"f migrate code\",\"short\":\"-c\",\"long\":\"--copy\",\"description\":\"Copy instead of move (keeps original)\",\"entry_type\":\"flag\"},{\"command\":\"f migrate code\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Show what would change without writing\",\"entry_type\":\"flag\"},{\"command\":\"f migrate code\",\"short\":null,\"long\":\"--skip-claude\",\"description\":\"Skip migrating Claude sessions\",\"entry_type\":\"flag\"},{\"command\":\"f migrate code\",\"short\":null,\"long\":\"--skip-codex\",\"description\":\"Skip migrating Codex sessions\",\"entry_type\":\"flag\"},{\"command\":\"f parallel\",\"short\":null,\"long\":null,\"description\":\"Run tasks in parallel with pretty status display.\",\"entry_type\":\"subcommand\"},{\"command\":\"f parallel\",\"short\":\"-j\",\"long\":\"--jobs\",\"description\":\"Maximum number of concurrent jobs (default: number of CPU cores)\",\"entry_type\":\"flag\"},{\"command\":\"f parallel\",\"short\":\"-f\",\"long\":\"--fail-fast\",\"description\":\"Stop all tasks on first failure\",\"entry_type\":\"flag\"},{\"command\":\"f docs\",\"short\":null,\"long\":null,\"description\":\"Manage auto-generated documentation in .ai/docs/.\",\"entry_type\":\"subcommand\"},{\"command\":\"f docs new\",\"short\":null,\"long\":null,\"description\":\"Create a docs/ folder with starter markdown files\",\"entry_type\":\"subcommand\"},{\"command\":\"f docs new\",\"short\":null,\"long\":\"--path\",\"description\":\"Path to create docs in (defaults to current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f docs new\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite if docs/ already exists\",\"entry_type\":\"flag\"},{\"command\":\"f docs hub\",\"short\":null,\"long\":null,\"description\":\"Run the docs hub that aggregates docs from ~/code and ~/org\",\"entry_type\":\"subcommand\"},{\"command\":\"f docs hub\",\"short\":null,\"long\":\"--host\",\"description\":\"Host to bind the docs hub to\",\"entry_type\":\"flag\"},{\"command\":\"f docs hub\",\"short\":null,\"long\":\"--port\",\"description\":\"Port for the docs hub\",\"entry_type\":\"flag\"},{\"command\":\"f docs hub\",\"short\":null,\"long\":\"--hub-root\",\"description\":\"Docs hub root (defaults to ~/.config/flow/docs-hub)\",\"entry_type\":\"flag\"},{\"command\":\"f docs hub\",\"short\":null,\"long\":\"--template-root\",\"description\":\"Template root (defaults to ~/new/docs)\",\"entry_type\":\"flag\"},{\"command\":\"f docs hub\",\"short\":null,\"long\":\"--code-root\",\"description\":\"Code root to scan for docs (defaults to ~/code)\",\"entry_type\":\"flag\"},{\"command\":\"f docs hub\",\"short\":null,\"long\":\"--org-root\",\"description\":\"Org root to scan for docs (defaults to ~/org)\",\"entry_type\":\"flag\"},{\"command\":\"f docs hub\",\"short\":null,\"long\":\"--no-ai\",\"description\":\"Skip scanning for .ai/docs\",\"entry_type\":\"flag\"},{\"command\":\"f docs hub\",\"short\":null,\"long\":\"--no-open\",\"description\":\"Skip opening the browser\",\"entry_type\":\"flag\"},{\"command\":\"f docs hub\",\"short\":null,\"long\":\"--sync-only\",\"description\":\"Sync content and exit without running the dev server\",\"entry_type\":\"flag\"},{\"command\":\"f docs deploy\",\"short\":null,\"long\":null,\"description\":\"Deploy the docs hub to Cloudflare Pages\",\"entry_type\":\"subcommand\"},{\"command\":\"f docs deploy\",\"short\":null,\"long\":\"--project\",\"description\":\"Cloudflare Pages project name (defaults to flow.toml name)\",\"entry_type\":\"flag\"},{\"command\":\"f docs deploy\",\"short\":null,\"long\":\"--domain\",\"description\":\"Custom domain to attach (optional)\",\"entry_type\":\"flag\"},{\"command\":\"f docs deploy\",\"short\":\"-y\",\"long\":\"--yes\",\"description\":\"Skip confirmation prompts\",\"entry_type\":\"flag\"},{\"command\":\"f docs sync\",\"short\":null,\"long\":null,\"description\":\"Sync documentation with recent commits\",\"entry_type\":\"subcommand\"},{\"command\":\"f docs sync\",\"short\":\"-n\",\"long\":\"--commits\",\"description\":\"Number of commits to analyze (default: 10)\",\"entry_type\":\"flag\"},{\"command\":\"f docs sync\",\"short\":null,\"long\":\"--dry\",\"description\":\"Dry run: show what would be updated without changing files\",\"entry_type\":\"flag\"},{\"command\":\"f docs list\",\"short\":null,\"long\":null,\"description\":\"List documentation files\",\"entry_type\":\"subcommand\"},{\"command\":\"f docs status\",\"short\":null,\"long\":null,\"description\":\"Show documentation status (what needs updating)\",\"entry_type\":\"subcommand\"},{\"command\":\"f docs edit\",\"short\":null,\"long\":null,\"description\":\"Open a doc file in editor\",\"entry_type\":\"subcommand\"},{\"command\":\"f upgrade\",\"short\":null,\"long\":null,\"description\":\"Upgrade flow to the latest version.\",\"entry_type\":\"subcommand\"},{\"command\":\"f upgrade\",\"short\":null,\"long\":\"--canary\",\"description\":\"Upgrade to the latest canary build (GitHub release tag: \\\"canary\\\")\",\"entry_type\":\"flag\"},{\"command\":\"f upgrade\",\"short\":null,\"long\":\"--stable\",\"description\":\"Upgrade to the latest stable release (GitHub \\\"latest\\\" release)\",\"entry_type\":\"flag\"},{\"command\":\"f upgrade\",\"short\":\"-n\",\"long\":\"--dry-run\",\"description\":\"Print what would happen without making changes\",\"entry_type\":\"flag\"},{\"command\":\"f upgrade\",\"short\":\"-f\",\"long\":\"--force\",\"description\":\"Force upgrade even if already on the latest version\",\"entry_type\":\"flag\"},{\"command\":\"f upgrade\",\"short\":\"-o\",\"long\":\"--output\",\"description\":\"Download to a specific path instead of replacing the current executable\",\"entry_type\":\"flag\"},{\"command\":\"f latest\",\"short\":null,\"long\":null,\"description\":\"Pull ~/code/flow and rebuild the local flow binary.\",\"entry_type\":\"subcommand\"},{\"command\":\"f release\",\"short\":null,\"long\":null,\"description\":\"Release a project (registry, GitHub, or task).\",\"entry_type\":\"subcommand\"},{\"command\":\"f release\",\"short\":null,\"long\":\"--config\",\"description\":\"Path to the project flow config (flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f release task\",\"short\":null,\"long\":null,\"description\":\"Run the configured release task\",\"entry_type\":\"subcommand\"},{\"command\":\"f release registry\",\"short\":null,\"long\":null,\"description\":\"Publish a release to a Flow registry\",\"entry_type\":\"subcommand\"},{\"command\":\"f release registry\",\"short\":\"-v\",\"long\":\"--version\",\"description\":\"Version to publish (auto-detected if omitted)\",\"entry_type\":\"flag\"},{\"command\":\"f release registry\",\"short\":null,\"long\":\"--registry\",\"description\":\"Registry base URL (overrides flow.toml)\",\"entry_type\":\"flag\"},{\"command\":\"f release registry\",\"short\":null,\"long\":\"--package\",\"description\":\"Override package name for the registry\",\"entry_type\":\"flag\"},{\"command\":\"f release registry\",\"short\":null,\"long\":\"--bin\",\"description\":\"Override the binary name(s) to upload\",\"entry_type\":\"flag\"},{\"command\":\"f release registry\",\"short\":null,\"long\":\"--no-build\",\"description\":\"Skip building binaries before publishing\",\"entry_type\":\"flag\"},{\"command\":\"f release registry\",\"short\":null,\"long\":\"--latest\",\"description\":\"Mark this version as latest in the registry\",\"entry_type\":\"flag\"},{\"command\":\"f release registry\",\"short\":null,\"long\":\"--no-latest\",\"description\":\"Skip updating the latest pointer\",\"entry_type\":\"flag\"},{\"command\":\"f release registry\",\"short\":\"-n\",\"long\":\"--dry-run\",\"description\":\"Dry run: show what would be published without publishing\",\"entry_type\":\"flag\"},{\"command\":\"f release github\",\"short\":null,\"long\":null,\"description\":\"Manage GitHub releases\",\"entry_type\":\"subcommand\"},{\"command\":\"f release github create\",\"short\":null,\"long\":null,\"description\":\"Create a new GitHub release\",\"entry_type\":\"subcommand\"},{\"command\":\"f release github create\",\"short\":\"-t\",\"long\":\"--title\",\"description\":\"Release title (defaults to tag name)\",\"entry_type\":\"flag\"},{\"command\":\"f release github create\",\"short\":\"-n\",\"long\":\"--notes\",\"description\":\"Release notes (reads from stdin or file if not provided)\",\"entry_type\":\"flag\"},{\"command\":\"f release github create\",\"short\":null,\"long\":\"--notes-file\",\"description\":\"Read release notes from a file\",\"entry_type\":\"flag\"},{\"command\":\"f release github create\",\"short\":null,\"long\":\"--generate-notes\",\"description\":\"Generate release notes automatically from commits\",\"entry_type\":\"flag\"},{\"command\":\"f release github create\",\"short\":null,\"long\":\"--draft\",\"description\":\"Create as draft release\",\"entry_type\":\"flag\"},{\"command\":\"f release github create\",\"short\":null,\"long\":\"--prerelease\",\"description\":\"Mark as prerelease\",\"entry_type\":\"flag\"},{\"command\":\"f release github create\",\"short\":\"-a\",\"long\":\"--asset\",\"description\":\"Asset files to upload (can be specified multiple times)\",\"entry_type\":\"flag\"},{\"command\":\"f release github create\",\"short\":null,\"long\":\"--target\",\"description\":\"Target commit/branch for the release tag\",\"entry_type\":\"flag\"},{\"command\":\"f release github create\",\"short\":\"-y\",\"long\":\"--yes\",\"description\":\"Skip confirmation prompts\",\"entry_type\":\"flag\"},{\"command\":\"f release github list\",\"short\":null,\"long\":null,\"description\":\"List recent releases\",\"entry_type\":\"subcommand\"},{\"command\":\"f release github list\",\"short\":\"-l\",\"long\":\"--limit\",\"description\":\"Number of releases to show\",\"entry_type\":\"flag\"},{\"command\":\"f release github delete\",\"short\":null,\"long\":null,\"description\":\"Delete a release\",\"entry_type\":\"subcommand\"},{\"command\":\"f release github delete\",\"short\":\"-y\",\"long\":\"--yes\",\"description\":\"Skip confirmation\",\"entry_type\":\"flag\"},{\"command\":\"f release github download\",\"short\":null,\"long\":null,\"description\":\"Download release assets\",\"entry_type\":\"subcommand\"},{\"command\":\"f release github download\",\"short\":\"-t\",\"long\":\"--tag\",\"description\":\"Release tag (defaults to latest)\",\"entry_type\":\"flag\"},{\"command\":\"f release github download\",\"short\":\"-o\",\"long\":\"--output\",\"description\":\"Output directory\",\"entry_type\":\"flag\"},{\"command\":\"f release signing\",\"short\":null,\"long\":null,\"description\":\"Manage macOS code signing and GitHub Actions secrets for releases\",\"entry_type\":\"subcommand\"},{\"command\":\"f release signing status\",\"short\":null,\"long\":null,\"description\":\"Show current signing setup status (Keychain + Flow env store)\",\"entry_type\":\"subcommand\"},{\"command\":\"f release signing store\",\"short\":null,\"long\":null,\"description\":\"Store signing secrets into Flow personal env store\",\"entry_type\":\"subcommand\"},{\"command\":\"f release signing store\",\"short\":null,\"long\":\"--p12\",\"description\":\"Path to exported .p12 file (Developer ID Application certificate + key)\",\"entry_type\":\"flag\"},{\"command\":\"f release signing store\",\"short\":null,\"long\":\"--p12-password\",\"description\":\"Password for the .p12 (must match what the release workflow imports with)\",\"entry_type\":\"flag\"},{\"command\":\"f release signing store\",\"short\":null,\"long\":\"--identity\",\"description\":\"Signing identity passed to `codesign` (e.g. \\\"Developer ID Application: ... (TEAMID)\\\")\",\"entry_type\":\"flag\"},{\"command\":\"f release signing store\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Dry run: show what would be stored without writing to env store\",\"entry_type\":\"flag\"},{\"command\":\"f release signing sync\",\"short\":null,\"long\":null,\"description\":\"Sync signing secrets from Flow env store into GitHub Actions secrets\",\"entry_type\":\"subcommand\"},{\"command\":\"f release signing sync\",\"short\":null,\"long\":\"--repo\",\"description\":\"GitHub repo in \\\"owner/repo\\\" form (defaults to repo inferred from current directory)\",\"entry_type\":\"flag\"},{\"command\":\"f release signing sync\",\"short\":null,\"long\":\"--dry-run\",\"description\":\"Dry run: show what would be synced without calling `gh`\",\"entry_type\":\"flag\"},{\"command\":\"f install\",\"short\":null,\"long\":null,\"description\":\"Install a CLI/tool binary (registry, parm, or flox).\",\"entry_type\":\"subcommand\"},{\"command\":\"f install\",\"short\":null,\"long\":\"--registry\",\"description\":\"Registry base URL (defaults to FLOW_REGISTRY_URL)\",\"entry_type\":\"flag\"},{\"command\":\"f install\",\"short\":null,\"long\":\"--backend\",\"description\":\"Install backend (auto tries registry, then parm, then flox)\",\"entry_type\":\"flag\"},{\"command\":\"f install\",\"short\":\"-v\",\"long\":\"--version\",\"description\":\"Version to install (defaults to latest)\",\"entry_type\":\"flag\"},{\"command\":\"f install\",\"short\":null,\"long\":\"--bin\",\"description\":\"Binary name to install (defaults to the package name or manifest default)\",\"entry_type\":\"flag\"},{\"command\":\"f install\",\"short\":null,\"long\":\"--bin-dir\",\"description\":\"Install directory (defaults to ~/bin)\",\"entry_type\":\"flag\"},{\"command\":\"f install\",\"short\":null,\"long\":\"--no-verify\",\"description\":\"Skip checksum verification\",\"entry_type\":\"flag\"},{\"command\":\"f install\",\"short\":null,\"long\":\"--force\",\"description\":\"Overwrite existing binary if present\",\"entry_type\":\"flag\"},{\"command\":\"f install index\",\"short\":null,\"long\":null,\"description\":\"Index flox packages into Typesense\",\"entry_type\":\"subcommand\"},{\"command\":\"f install index\",\"short\":null,\"long\":\"--queries\",\"description\":\"File with newline-separated search terms\",\"entry_type\":\"flag\"},{\"command\":\"f install index\",\"short\":null,\"long\":\"--url\",\"description\":\"Typesense base URL (overrides FLOW_TYPESENSE_URL)\",\"entry_type\":\"flag\"},{\"command\":\"f install index\",\"short\":null,\"long\":\"--api-key\",\"description\":\"Typesense API key (overrides FLOW_TYPESENSE_API_KEY)\",\"entry_type\":\"flag\"},{\"command\":\"f install index\",\"short\":null,\"long\":\"--collection\",\"description\":\"Typesense collection name (overrides FLOW_TYPESENSE_COLLECTION)\",\"entry_type\":\"flag\"},{\"command\":\"f install index\",\"short\":null,\"long\":\"--server\",\"description\":\"Index server URL (defaults to local base server)\",\"entry_type\":\"flag\"},{\"command\":\"f install index\",\"short\":null,\"long\":\"--direct\",\"description\":\"Skip index server and write directly to Typesense\",\"entry_type\":\"flag\"},{\"command\":\"f install index\",\"short\":null,\"long\":\"--per-page\",\"description\":\"Max results per search term\",\"entry_type\":\"flag\"},{\"command\":\"f install index\",\"short\":\"-n\",\"long\":\"--dry-run\",\"description\":\"Dry run (do not write to Typesense)\",\"entry_type\":\"flag\"},{\"command\":\"f registry\",\"short\":null,\"long\":null,\"description\":\"Manage the Flow registry (tokens, setup).\",\"entry_type\":\"subcommand\"},{\"command\":\"f registry init\",\"short\":null,\"long\":null,\"description\":\"Create a registry token and configure worker + env\",\"entry_type\":\"subcommand\"},{\"command\":\"f registry init\",\"short\":\"-w\",\"long\":\"--worker\",\"description\":\"Path to the worker project (defaults to packages/worker)\",\"entry_type\":\"flag\"},{\"command\":\"f registry init\",\"short\":null,\"long\":\"--registry\",\"description\":\"Registry base URL (overrides flow.toml or FLOW_REGISTRY_URL)\",\"entry_type\":\"flag\"},{\"command\":\"f registry init\",\"short\":null,\"long\":\"--token-env\",\"description\":\"Env var name for the registry token\",\"entry_type\":\"flag\"},{\"command\":\"f registry init\",\"short\":null,\"long\":\"--token\",\"description\":\"Provide an explicit token instead of generating one\",\"entry_type\":\"flag\"},{\"command\":\"f registry init\",\"short\":null,\"long\":\"--no-worker\",\"description\":\"Skip updating the worker secret\",\"entry_type\":\"flag\"},{\"command\":\"f registry init\",\"short\":null,\"long\":\"--show-token\",\"description\":\"Print the generated token to stdout\",\"entry_type\":\"flag\"},{\"command\":\"f proxy\",\"short\":null,\"long\":null,\"description\":\"Zero-cost traced reverse proxy for development.\",\"entry_type\":\"subcommand\"},{\"command\":\"f proxy start\",\"short\":null,\"long\":null,\"description\":\"Start the proxy server (reads [[proxies]] from flow.toml)\",\"entry_type\":\"subcommand\"},{\"command\":\"f proxy start\",\"short\":\"-l\",\"long\":\"--listen\",\"description\":\"Listen address (e.g., \\\":8080\\\" or \\\"127.0.0.1:8080\\\")\",\"entry_type\":\"flag\"},{\"command\":\"f proxy start\",\"short\":\"-f\",\"long\":\"--foreground\",\"description\":\"Run in foreground (don't daemonize)\",\"entry_type\":\"flag\"},{\"command\":\"f proxy trace\",\"short\":null,\"long\":null,\"description\":\"View recent request traces\",\"entry_type\":\"subcommand\"},{\"command\":\"f proxy trace\",\"short\":\"-n\",\"long\":\"--count\",\"description\":\"Number of records to show\",\"entry_type\":\"flag\"},{\"command\":\"f proxy trace\",\"short\":\"-f\",\"long\":\"--follow\",\"description\":\"Follow trace in real-time\",\"entry_type\":\"flag\"},{\"command\":\"f proxy trace\",\"short\":null,\"long\":\"--target\",\"description\":\"Filter by target name\",\"entry_type\":\"flag\"},{\"command\":\"f proxy trace\",\"short\":null,\"long\":\"--errors\",\"description\":\"Show only errors (status >= 400)\",\"entry_type\":\"flag\"},{\"command\":\"f proxy trace\",\"short\":null,\"long\":\"--id\",\"description\":\"Filter by trace ID\",\"entry_type\":\"flag\"},{\"command\":\"f proxy last\",\"short\":null,\"long\":null,\"description\":\"Show the last request details\",\"entry_type\":\"subcommand\"},{\"command\":\"f proxy last\",\"short\":null,\"long\":\"--errors\",\"description\":\"Show only errors\",\"entry_type\":\"flag\"},{\"command\":\"f proxy last\",\"short\":null,\"long\":\"--target\",\"description\":\"Filter by target name\",\"entry_type\":\"flag\"},{\"command\":\"f proxy last\",\"short\":null,\"long\":\"--body\",\"description\":\"Include request/response body\",\"entry_type\":\"flag\"},{\"command\":\"f proxy add\",\"short\":null,\"long\":null,\"description\":\"Add a new proxy target\",\"entry_type\":\"subcommand\"},{\"command\":\"f proxy add\",\"short\":\"-n\",\"long\":\"--name\",\"description\":\"Proxy name (auto-suggested if not provided)\",\"entry_type\":\"flag\"},{\"command\":\"f proxy add\",\"short\":null,\"long\":\"--host\",\"description\":\"Host-based routing\",\"entry_type\":\"flag\"},{\"command\":\"f proxy add\",\"short\":null,\"long\":\"--path\",\"description\":\"Path prefix routing\",\"entry_type\":\"flag\"},{\"command\":\"f proxy list\",\"short\":null,\"long\":null,\"description\":\"List configured proxy targets\",\"entry_type\":\"subcommand\"},{\"command\":\"f proxy stop\",\"short\":null,\"long\":null,\"description\":\"Stop the proxy server\",\"entry_type\":\"subcommand\"},{\"command\":\"f domains\",\"short\":null,\"long\":null,\"description\":\"Manage shared local *.localhost routing on port 80.\",\"entry_type\":\"subcommand\"},{\"command\":\"f domains\",\"short\":null,\"long\":\"--engine\",\"description\":\"Routing engine to use (`docker` default, or `native` for experimental C++ daemon)\",\"entry_type\":\"flag\"},{\"command\":\"f domains up\",\"short\":null,\"long\":null,\"description\":\"Start the shared local-domain proxy on port 80\",\"entry_type\":\"subcommand\"},{\"command\":\"f domains down\",\"short\":null,\"long\":null,\"description\":\"Stop the shared local-domain proxy\",\"entry_type\":\"subcommand\"},{\"command\":\"f domains list\",\"short\":null,\"long\":null,\"description\":\"List configured host -> target routes\",\"entry_type\":\"subcommand\"},{\"command\":\"f domains get\",\"short\":null,\"long\":null,\"description\":\"Print the public URL for a configured localhost route\",\"entry_type\":\"subcommand\"},{\"command\":\"f domains get\",\"short\":null,\"long\":\"--target\",\"description\":\"Print the upstream host:port instead of the public URL\",\"entry_type\":\"flag\"},{\"command\":\"f domains add\",\"short\":null,\"long\":null,\"description\":\"Add a localhost route (for example: linsa.localhost -> 127.0.0.1:3481)\",\"entry_type\":\"subcommand\"},{\"command\":\"f domains add\",\"short\":null,\"long\":\"--replace\",\"description\":\"Replace existing route target for this host\",\"entry_type\":\"flag\"},{\"command\":\"f domains rm\",\"short\":null,\"long\":null,\"description\":\"Remove a localhost route\",\"entry_type\":\"subcommand\"},{\"command\":\"f domains doctor\",\"short\":null,\"long\":null,\"description\":\"Show proxy ownership, port 80 conflicts, and route summary\",\"entry_type\":\"subcommand\"},{\"command\":\"f\",\"short\":null,\"long\":\"--help-full\",\"description\":\"Output all commands in machine-readable JSON format for external tools\",\"entry_type\":\"flag\"}]}\n" }, { "path": "src/help_search.rs", "content": "//! Fuzzy search through all Flow CLI commands.\n\nuse anyhow::{Context, Result};\nuse clap::{Command, CommandFactory};\nuse serde::Serialize;\nuse std::io::{BufWriter, Write};\nuse std::process::{Command as Cmd, Stdio};\n\nuse crate::cli::Cli;\n\nconst EMBEDDED_HELP_JSON: &str = include_str!(\"help_full.json\");\nconst HELP_FULL_REGENERATE_ENV: &str = \"FLOW_REGENERATE_HELP_FULL\";\n\n/// Entry format compatible with the `cmd` tool's cache format.\n#[derive(Serialize)]\nstruct Entry {\n command: String,\n short: Option<String>,\n long: Option<String>,\n description: String,\n entry_type: String,\n}\n\n#[derive(Serialize)]\nstruct CommandInfo {\n version: String,\n entries: Vec<Entry>,\n}\n\n/// Collect all commands recursively from clap's command tree.\nfn collect_commands(cmd: &Command, prefix: &str, entries: &mut Vec<(String, String)>) {\n let name = cmd.get_name();\n let full_path = if prefix.is_empty() {\n name.to_string()\n } else {\n format!(\"{} {}\", prefix, name)\n };\n\n if let Some(about) = cmd.get_about() {\n entries.push((full_path.clone(), about.to_string()));\n }\n\n for sub in cmd.get_subcommands() {\n if !sub.is_hide_set() {\n collect_commands(sub, &full_path, entries);\n }\n }\n}\n\n/// Run fuzzy search over all Flow commands.\npub fn run() -> Result<()> {\n let cmd = Cli::command();\n let mut entries = Vec::new();\n\n for sub in cmd.get_subcommands() {\n if !sub.is_hide_set() {\n collect_commands(sub, \"f\", &mut entries);\n }\n }\n\n // Format for fzf: command<tab>description\n let input = entries\n .iter()\n .map(|(cmd, desc)| format!(\"{}\\t{}\", cmd, desc))\n .collect::<Vec<_>>()\n .join(\"\\n\");\n\n let mut fzf = Cmd::new(\"fzf\")\n .args([\n \"--height=50%\",\n \"--reverse\",\n \"--delimiter=\\t\",\n \"--with-nth=1,2\",\n \"--preview-window=hidden\",\n ])\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf - is it installed?\")?;\n\n fzf.stdin.as_mut().unwrap().write_all(input.as_bytes())?;\n\n let output = fzf.wait_with_output()?;\n if !output.status.success() {\n return Ok(()); // User cancelled\n }\n\n let selected = String::from_utf8_lossy(&output.stdout)\n .trim()\n .split('\\t')\n .next()\n .unwrap_or(\"\")\n .to_string();\n\n if !selected.is_empty() {\n // Show help for selected command\n println!();\n let parts: Vec<&str> = selected.split_whitespace().skip(1).collect();\n let mut cmd = Cmd::new(\"f\");\n cmd.args(&parts);\n cmd.arg(\"--help\");\n cmd.status()?;\n }\n\n Ok(())\n}\n\n/// Collect all commands and flags recursively in cmd-tool format.\nfn collect_entries(cmd: &Command, prefix: &str, entries: &mut Vec<Entry>) {\n let name = cmd.get_name();\n let full_path = if prefix.is_empty() {\n name.to_string()\n } else {\n format!(\"{} {}\", prefix, name)\n };\n\n // Add the subcommand itself\n if let Some(about) = cmd.get_about() {\n entries.push(Entry {\n command: full_path.clone(),\n short: None,\n long: None,\n description: about.to_string(),\n entry_type: \"subcommand\".to_string(),\n });\n }\n\n // Add flags/options for this command\n for arg in cmd.get_arguments() {\n if arg.is_hide_set() {\n continue;\n }\n let short = arg.get_short().map(|c| format!(\"-{}\", c));\n let long = arg.get_long().map(|s| format!(\"--{}\", s));\n\n // Skip if no flag representation\n if short.is_none() && long.is_none() {\n continue;\n }\n\n let description = arg.get_help().map(|h| h.to_string()).unwrap_or_default();\n\n entries.push(Entry {\n command: full_path.clone(),\n short,\n long,\n description,\n entry_type: \"flag\".to_string(),\n });\n }\n\n // Recurse into subcommands\n for sub in cmd.get_subcommands() {\n if !sub.is_hide_set() {\n collect_entries(sub, &full_path, entries);\n }\n }\n}\n\n/// Output all commands in JSON format compatible with the `cmd` tool.\npub fn print_full_json() -> Result<()> {\n let stdout = std::io::stdout();\n let mut writer = BufWriter::new(stdout.lock());\n if should_regenerate_help_full() {\n write_generated_full_json(&mut writer)?;\n } else {\n writer.write_all(EMBEDDED_HELP_JSON.as_bytes())?;\n if !EMBEDDED_HELP_JSON.ends_with('\\n') {\n writer.write_all(b\"\\n\")?;\n }\n }\n\n Ok(())\n}\n\nfn should_regenerate_help_full() -> bool {\n matches!(\n std::env::var(HELP_FULL_REGENERATE_ENV)\n .ok()\n .as_deref()\n .map(str::trim)\n .map(str::to_ascii_lowercase)\n .as_deref(),\n Some(\"1\" | \"true\" | \"yes\" | \"on\")\n )\n}\n\nfn write_generated_full_json(writer: &mut impl Write) -> Result<()> {\n let cmd = Cli::command();\n let mut entries = Vec::with_capacity(512);\n\n for sub in cmd.get_subcommands() {\n if !sub.is_hide_set() {\n collect_entries(sub, \"f\", &mut entries);\n }\n }\n\n for arg in cmd.get_arguments() {\n if arg.is_hide_set() {\n continue;\n }\n let short = arg.get_short().map(|c| format!(\"-{}\", c));\n let long = arg.get_long().map(|s| format!(\"--{}\", s));\n\n if short.is_none() && long.is_none() {\n continue;\n }\n\n let description = arg.get_help().map(|h| h.to_string()).unwrap_or_default();\n\n entries.push(Entry {\n command: \"f\".to_string(),\n short,\n long,\n description,\n entry_type: \"flag\".to_string(),\n });\n }\n\n let version = env!(\"CARGO_PKG_VERSION\").to_string();\n let info = CommandInfo { version, entries };\n serde_json::to_writer(&mut *writer, &info)?;\n writer.write_all(b\"\\n\")?;\n Ok(())\n}\n\n#[cfg(test)]\nmod tests {\n use super::{EMBEDDED_HELP_JSON, write_generated_full_json};\n use anyhow::Result;\n\n #[test]\n fn embedded_help_json_matches_current_cli() -> Result<()> {\n let mut generated = Vec::new();\n write_generated_full_json(&mut generated)?;\n assert_eq!(\n String::from_utf8(generated).expect(\"generated help JSON should be UTF-8\"),\n EMBEDDED_HELP_JSON\n );\n Ok(())\n }\n}\n" }, { "path": "src/history.rs", "content": "use std::{\n collections::HashSet,\n fs::{File, OpenOptions},\n io::{Read, Seek, SeekFrom, Write},\n path::{Path, PathBuf},\n time::{SystemTime, UNIX_EPOCH},\n};\n\nuse anyhow::{Context, Result};\nuse serde::{Deserialize, Serialize};\n\nuse crate::config;\nuse crate::secret_redact;\n\nconst HISTORY_REVERSE_SCAN_CHUNK_BYTES: usize = 16 * 1024;\n\n#[derive(Serialize, Deserialize)]\npub struct InvocationRecord {\n pub timestamp_ms: u128,\n pub duration_ms: u128,\n pub project_root: String,\n #[serde(default)]\n pub project_name: Option<String>,\n pub config_path: String,\n pub task_name: String,\n pub command: String,\n #[serde(default)]\n pub user_input: String,\n pub status: Option<i32>,\n pub success: bool,\n pub used_flox: bool,\n pub output: String,\n pub flow_version: String,\n}\n\nimpl InvocationRecord {\n pub fn new(\n project_root: impl Into<String>,\n config_path: impl Into<String>,\n project_name: Option<&str>,\n task_name: impl Into<String>,\n command: impl Into<String>,\n user_input: impl Into<String>,\n used_flox: bool,\n ) -> Self {\n Self {\n timestamp_ms: now_ms(),\n duration_ms: 0,\n project_root: project_root.into(),\n project_name: project_name.map(|s| s.to_string()),\n config_path: config_path.into(),\n task_name: task_name.into(),\n command: command.into(),\n user_input: user_input.into(),\n status: None,\n success: false,\n used_flox,\n output: String::new(),\n flow_version: env!(\"CARGO_PKG_VERSION\").to_string(),\n }\n }\n}\n\npub fn record(invocation: InvocationRecord) -> Result<()> {\n let mut invocation = invocation;\n invocation.command = secret_redact::redact_text(&invocation.command);\n invocation.user_input = secret_redact::redact_text(&invocation.user_input);\n invocation.output = secret_redact::redact_text(&invocation.output);\n\n let path = history_path();\n let _ = config::ensure_global_state_dir()\n .with_context(|| format!(\"failed to create history dir {}\", path.display()))?;\n\n let mut file = OpenOptions::new()\n .create(true)\n .append(true)\n .open(&path)\n .with_context(|| format!(\"failed to open history file {}\", path.display()))?;\n\n let line = serde_json::to_string(&invocation).context(\"failed to serialize invocation\")?;\n writeln!(file, \"{line}\").context(\"failed to write invocation to history\")?;\n Ok(())\n}\n\n/// Print the most recent invocation with only the user input and the resulting output or error.\npub fn print_last_record() -> Result<()> {\n let path = history_path();\n let record = load_last_record(&path)?;\n let Some(rec) = record else {\n if path.exists() {\n println!(\"No valid history entries found in {}\", path.display());\n } else {\n println!(\"No history found at {}\", path.display());\n }\n return Ok(());\n };\n\n let user_input = if rec.user_input.trim().is_empty() {\n rec.task_name.clone()\n } else {\n rec.user_input.clone()\n };\n println!(\"{user_input}\");\n\n if rec.output.trim().is_empty() {\n if !rec.success {\n let status = rec\n .status\n .map(|s| s.to_string())\n .unwrap_or_else(|| \"unknown\".to_string());\n println!(\"error (status: {status})\");\n }\n } else {\n let output = secret_redact::redact_text(&rec.output);\n print!(\"{}\", output);\n if !output.ends_with('\\n') {\n println!();\n }\n }\n\n Ok(())\n}\n\n/// Print the most recent invocation with output and status.\npub fn print_last_record_full() -> Result<()> {\n let path = history_path();\n let record = load_last_record(&path)?;\n let Some(rec) = record else {\n if path.exists() {\n println!(\"No valid history entries found in {}\", path.display());\n } else {\n println!(\"No history found at {}\", path.display());\n }\n return Ok(());\n };\n\n println!(\"task: {}\", rec.task_name);\n println!(\"command: {}\", secret_redact::redact_text(&rec.command));\n println!(\"project: {}\", rec.project_root);\n if let Some(name) = rec.project_name.as_deref() {\n println!(\"project_name: {name}\");\n }\n println!(\"config: {}\", rec.config_path);\n println!(\n \"status: {} (code: {})\",\n if rec.success { \"success\" } else { \"failure\" },\n rec.status\n .map(|s| s.to_string())\n .unwrap_or_else(|| \"unknown\".to_string())\n );\n println!(\"duration_ms: {}\", rec.duration_ms);\n println!(\"flow_version: {}\", rec.flow_version);\n println!(\"--- output ---\");\n print!(\"{}\", secret_redact::redact_text(&rec.output));\n Ok(())\n}\n\nfn load_last_record(path: &Path) -> Result<Option<InvocationRecord>> {\n find_last_record_matching(path, |_| true)\n}\n\n/// Load the last invocation record for a specific project root.\npub fn load_last_record_for_project(project_root: &Path) -> Result<Option<InvocationRecord>> {\n let path = history_path();\n if !path.exists() {\n return Ok(None);\n }\n\n let canonical_root = project_root\n .canonicalize()\n .unwrap_or_else(|_| project_root.to_path_buf());\n let canonical_str = canonical_root.to_string_lossy();\n\n find_last_record_matching(&path, |rec| rec.project_root == canonical_str)\n}\n\npub fn history_path() -> PathBuf {\n config::global_state_dir().join(\"history.jsonl\")\n}\n\n/// Load unique task-history entries, most recent first, deduped by project + task name.\npub fn load_unique_task_records() -> Result<Vec<InvocationRecord>> {\n let path = history_path();\n if !path.exists() {\n return Ok(Vec::new());\n }\n\n let mut seen: HashSet<(String, String)> = HashSet::new();\n let mut records = Vec::new();\n let _ = visit_lines_reverse(&path, |line| {\n if line.trim().is_empty() {\n return None::<()>;\n }\n let record = serde_json::from_str::<InvocationRecord>(line).ok()?;\n let key = (record.project_root.clone(), record.task_name.clone());\n if seen.insert(key) {\n records.push(record);\n }\n None::<()>\n })?;\n Ok(records)\n}\n\nfn find_last_record_matching<F>(path: &Path, mut predicate: F) -> Result<Option<InvocationRecord>>\nwhere\n F: FnMut(&InvocationRecord) -> bool,\n{\n if !path.exists() {\n return Ok(None);\n }\n\n visit_lines_reverse(path, |line| {\n if line.trim().is_empty() {\n return None;\n }\n let record = serde_json::from_str::<InvocationRecord>(line).ok()?;\n if predicate(&record) {\n Some(record)\n } else {\n None\n }\n })\n}\n\nfn visit_lines_reverse<T, F>(path: &Path, mut on_line: F) -> Result<Option<T>>\nwhere\n F: FnMut(&str) -> Option<T>,\n{\n let mut file = File::open(path)\n .with_context(|| format!(\"failed to read history at {}\", path.display()))?;\n let mut pos = file.seek(SeekFrom::End(0))?;\n if pos == 0 {\n return Ok(None);\n }\n\n let mut chunk = vec![0u8; HISTORY_REVERSE_SCAN_CHUNK_BYTES];\n let mut carry = Vec::new();\n\n while pos > 0 {\n let read_len = usize::try_from(pos.min(chunk.len() as u64)).unwrap_or(chunk.len());\n pos -= read_len as u64;\n file.seek(SeekFrom::Start(pos))?;\n file.read_exact(&mut chunk[..read_len])\n .with_context(|| format!(\"failed to read history at {}\", path.display()))?;\n\n let buf = &chunk[..read_len];\n let mut end = read_len;\n while let Some(idx) = buf[..end].iter().rposition(|&byte| byte == b'\\n') {\n if let Some(value) =\n process_reverse_line_segment(&buf[idx + 1..end], &mut carry, &mut on_line)\n {\n return Ok(Some(value));\n }\n end = idx;\n }\n\n if end > 0 {\n let mut combined = Vec::with_capacity(end + carry.len());\n combined.extend_from_slice(&buf[..end]);\n combined.extend_from_slice(&carry);\n carry = combined;\n }\n }\n\n if !carry.is_empty()\n && let Ok(line) = std::str::from_utf8(&carry)\n && let Some(value) = on_line(line.trim_end_matches('\\r'))\n {\n return Ok(Some(value));\n }\n\n Ok(None)\n}\n\nfn process_reverse_line_segment<T, F>(\n segment: &[u8],\n carry: &mut Vec<u8>,\n on_line: &mut F,\n) -> Option<T>\nwhere\n F: FnMut(&str) -> Option<T>,\n{\n if carry.is_empty() {\n let line = std::str::from_utf8(segment).ok()?;\n return on_line(line.trim_end_matches('\\r'));\n }\n\n let suffix = std::mem::take(carry);\n let mut line_bytes = Vec::with_capacity(segment.len() + suffix.len());\n line_bytes.extend_from_slice(segment);\n line_bytes.extend_from_slice(&suffix);\n let line = std::str::from_utf8(&line_bytes).ok()?;\n on_line(line.trim_end_matches('\\r'))\n}\n\nfn now_ms() -> u128 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|d| d.as_millis())\n .unwrap_or(0)\n}\n\n#[cfg(test)]\nmod tests {\n use std::fs;\n\n use tempfile::tempdir;\n\n use super::{InvocationRecord, find_last_record_matching, load_last_record, now_ms};\n\n fn sample_record(project_root: &str, task_name: &str, user_input: &str) -> InvocationRecord {\n InvocationRecord {\n timestamp_ms: now_ms(),\n duration_ms: 1,\n project_root: project_root.to_string(),\n project_name: None,\n config_path: format!(\"{project_root}/flow.toml\"),\n task_name: task_name.to_string(),\n command: \"echo hi\".to_string(),\n user_input: user_input.to_string(),\n status: Some(0),\n success: true,\n used_flox: false,\n output: \"ok\".to_string(),\n flow_version: \"test\".to_string(),\n }\n }\n\n #[test]\n fn load_last_record_reads_from_end_without_full_file_parse() {\n let dir = tempdir().expect(\"tempdir\");\n let path = dir.path().join(\"history.jsonl\");\n let long_output = \"x\".repeat(super::HISTORY_REVERSE_SCAN_CHUNK_BYTES + 256);\n let mut first = sample_record(\"/tmp/a\", \"first\", \"first\");\n first.output = long_output;\n let second = sample_record(\"/tmp/b\", \"second\", \"second\");\n let payload = format!(\n \"{}\\n{}\\n\",\n serde_json::to_string(&first).expect(\"first json\"),\n serde_json::to_string(&second).expect(\"second json\")\n );\n fs::write(&path, payload).expect(\"write history\");\n\n let found = load_last_record(&path)\n .expect(\"load last record\")\n .expect(\"record should exist\");\n assert_eq!(found.task_name, \"second\");\n }\n\n #[test]\n fn find_last_record_matching_finds_latest_matching_project() {\n let dir = tempdir().expect(\"tempdir\");\n let project = dir.path().join(\"project\");\n fs::create_dir_all(&project).expect(\"project dir\");\n let path = dir.path().join(\"history.jsonl\");\n\n let first = sample_record(&project.to_string_lossy(), \"one\", \"one\");\n let second = sample_record(\"/tmp/other\", \"other\", \"other\");\n let third = sample_record(&project.to_string_lossy(), \"two\", \"two\");\n let payload = format!(\n \"{}\\n{}\\n{}\\n\",\n serde_json::to_string(&first).expect(\"first json\"),\n serde_json::to_string(&second).expect(\"second json\"),\n serde_json::to_string(&third).expect(\"third json\")\n );\n fs::write(&path, payload).expect(\"write history\");\n\n let found =\n find_last_record_matching(&path, |rec| rec.project_root == project.to_string_lossy())\n .expect(\"load project record\")\n .expect(\"record should exist\");\n\n assert_eq!(found.task_name, \"two\");\n }\n}\n" }, { "path": "src/hive.rs", "content": "//! Hive agent integration for flow.\n//!\n//! Agents can be defined at three levels:\n//! 1. Project-local: flow.toml [[agents]] or .flow/agents/*.md\n//! 2. Global: ~/.config/flow/agents/*.md or ~/.hive/agents/\n//! 3. Hive registry: ~/.hive/config.json agents\n//!\n//! Agent spec format (Markdown):\n//! ```markdown\n//! # Agent: <name>\n//! # Purpose: <description>\n//! #\n//! # Rules:\n//! # - Rule 1\n//! # - Rule 2\n//! #\n//! # Tools:\n//! # - bash\n//! ```\n\nuse std::collections::HashMap;\nuse std::fs;\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result};\nuse serde::{Deserialize, Serialize};\n\n/// Agent configuration from flow.toml\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct AgentConfig {\n pub name: String,\n #[serde(default)]\n pub description: Option<String>,\n /// System prompt / preamble (inline or file path)\n #[serde(default)]\n pub preamble: Option<String>,\n /// Path to spec file (relative to project root)\n #[serde(default)]\n pub spec: Option<String>,\n /// Tools available to the agent\n #[serde(default)]\n pub tools: Vec<String>,\n /// Model to use (provider-specific)\n #[serde(default)]\n pub model: Option<String>,\n /// Provider: cerebras, deepseek, zai, groq, openrouter\n #[serde(default)]\n pub provider: Option<String>,\n /// Temperature for generation\n #[serde(default)]\n pub temperature: Option<f64>,\n /// Max tokens\n #[serde(default, rename = \"max_tokens\", alias = \"maxTokens\")]\n pub max_tokens: Option<u32>,\n /// Max tool call depth\n #[serde(default, rename = \"max_depth\", alias = \"maxDepth\")]\n pub max_depth: Option<u32>,\n /// Keywords to match for auto-routing\n #[serde(default, rename = \"match_on\", alias = \"matchOn\")]\n pub match_on: Vec<String>,\n /// Context files to include\n #[serde(default)]\n pub context: Vec<String>,\n /// Shortcuts for quick invocation\n #[serde(default)]\n pub shortcuts: Vec<String>,\n}\n\n/// Hive global config from ~/.hive/config.json\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct HiveConfig {\n #[serde(default)]\n pub agents: HashMap<String, HiveAgentSpec>,\n #[serde(default)]\n pub defaults: Option<HiveDefaults>,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct HiveAgentSpec {\n #[serde(default)]\n pub job: Option<String>,\n #[serde(default)]\n pub prompt: Option<String>,\n #[serde(default, rename = \"matchedOn\")]\n pub matched_on: Option<Vec<String>>,\n}\n\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct HiveDefaults {\n #[serde(default)]\n pub provider: Option<String>,\n #[serde(default)]\n pub model: Option<String>,\n}\n\n/// Resolved agent from any source\n#[derive(Debug, Clone)]\npub struct Agent {\n pub name: String,\n pub source: AgentSource,\n pub spec_path: Option<PathBuf>,\n pub config: AgentConfig,\n}\n\n#[derive(Debug, Clone, PartialEq)]\npub enum AgentSource {\n /// From project flow.toml [[agents]]\n ProjectConfig,\n /// From .flow/agents/<name>.md\n ProjectFile,\n /// From ~/.config/flow/agents/<name>.md\n GlobalFlow,\n /// From ~/.hive/agents/<name>/spec.md\n GlobalHive,\n /// From ~/.hive/config.json\n HiveRegistry,\n}\n\nimpl std::fmt::Display for AgentSource {\n fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {\n match self {\n AgentSource::ProjectConfig => write!(f, \"project\"),\n AgentSource::ProjectFile => write!(f, \"project\"),\n AgentSource::GlobalFlow => write!(f, \"global\"),\n AgentSource::GlobalHive => write!(f, \"hive\"),\n AgentSource::HiveRegistry => write!(f, \"hive\"),\n }\n }\n}\n\n/// Load hive global config\npub fn load_hive_config() -> Option<HiveConfig> {\n let path = dirs::home_dir()?.join(\".hive/config.json\");\n let content = fs::read_to_string(path).ok()?;\n serde_json::from_str(&content).ok()\n}\n\n/// Load project config for agents (best effort, returns default if not found)\nfn load_config_for_agents() -> crate::config::Config {\n // Try to find and load flow.toml\n let config_path = PathBuf::from(\"flow.toml\");\n if config_path.exists() {\n if let Ok(cfg) = crate::config::load(&config_path) {\n return cfg;\n }\n }\n // Return default config if not found\n crate::config::Config::default()\n}\n\n/// Find agent spec file in standard locations\nfn find_agent_spec(name: &str) -> Option<(PathBuf, AgentSource)> {\n // 1. Project-local: .flow/agents/<name>.md\n let project_path = PathBuf::from(\".flow/agents\").join(format!(\"{}.md\", name));\n if project_path.exists() {\n return Some((project_path, AgentSource::ProjectFile));\n }\n\n // 2. Global flow: ~/.config/flow/agents/<name>.md\n if let Some(home) = dirs::home_dir() {\n let global_flow = home\n .join(\".config/flow/agents\")\n .join(format!(\"{}.md\", name));\n if global_flow.exists() {\n return Some((global_flow, AgentSource::GlobalFlow));\n }\n\n // 3. Hive agents: ~/.hive/agents/<name>/spec.md\n let hive_spec = home.join(\".hive/agents\").join(name).join(\"spec.md\");\n if hive_spec.exists() {\n return Some((hive_spec, AgentSource::GlobalHive));\n }\n }\n\n None\n}\n\n/// Load agent spec content from file\npub fn load_agent_spec(path: &Path) -> Result<String> {\n fs::read_to_string(path).context(format!(\"Failed to read agent spec: {}\", path.display()))\n}\n\n/// Discover all available agents\npub fn discover_agents(project_agents: &[AgentConfig]) -> Vec<Agent> {\n let mut agents = Vec::new();\n let mut seen = std::collections::HashSet::new();\n\n // 1. Project config agents (highest priority)\n for cfg in project_agents {\n if seen.insert(cfg.name.clone()) {\n let spec_path = cfg.spec.as_ref().map(PathBuf::from);\n agents.push(Agent {\n name: cfg.name.clone(),\n source: AgentSource::ProjectConfig,\n spec_path,\n config: cfg.clone(),\n });\n }\n }\n\n // 2. Project file agents: .flow/agents/*.md\n if let Ok(entries) = fs::read_dir(\".flow/agents\") {\n for entry in entries.filter_map(|e| e.ok()) {\n let path = entry.path();\n if path.extension().map_or(false, |e| e == \"md\") {\n let stem = path\n .file_stem()\n .and_then(|s| s.to_str())\n .map(|s| s.to_string());\n if let Some(name) = stem {\n if seen.insert(name.clone()) {\n agents.push(Agent {\n name: name.clone(),\n source: AgentSource::ProjectFile,\n spec_path: Some(path),\n config: AgentConfig {\n name,\n ..Default::default()\n },\n });\n }\n }\n }\n }\n }\n\n // 3. Global flow agents: ~/.config/flow/agents/*.md\n if let Some(home) = dirs::home_dir() {\n let global_dir = home.join(\".config/flow/agents\");\n if let Ok(entries) = fs::read_dir(&global_dir) {\n for entry in entries.filter_map(|e| e.ok()) {\n let path = entry.path();\n if path.extension().map_or(false, |e| e == \"md\") {\n let stem = path\n .file_stem()\n .and_then(|s| s.to_str())\n .map(|s| s.to_string());\n if let Some(name) = stem {\n if seen.insert(name.clone()) {\n agents.push(Agent {\n name: name.clone(),\n source: AgentSource::GlobalFlow,\n spec_path: Some(path),\n config: AgentConfig {\n name,\n ..Default::default()\n },\n });\n }\n }\n }\n }\n }\n\n // 4. Hive agents: ~/.hive/agents/*/spec.md\n let hive_dir = home.join(\".hive/agents\");\n if let Ok(entries) = fs::read_dir(&hive_dir) {\n for entry in entries.filter_map(|e| e.ok()) {\n let path = entry.path();\n if path.is_dir() {\n let spec_path = path.join(\"spec.md\");\n if spec_path.exists() {\n if let Some(name) = path.file_name().and_then(|s| s.to_str()) {\n if seen.insert(name.to_string()) {\n agents.push(Agent {\n name: name.to_string(),\n source: AgentSource::GlobalHive,\n spec_path: Some(spec_path),\n config: AgentConfig {\n name: name.to_string(),\n ..Default::default()\n },\n });\n }\n }\n }\n }\n }\n }\n }\n\n // 5. Hive registry agents: ~/.hive/config.json\n if let Some(hive_config) = load_hive_config() {\n for (name, spec) in hive_config.agents {\n if seen.insert(name.clone()) {\n agents.push(Agent {\n name: name.clone(),\n source: AgentSource::HiveRegistry,\n spec_path: None,\n config: AgentConfig {\n name,\n description: spec.job.or(spec.prompt),\n ..Default::default()\n },\n });\n }\n }\n }\n\n agents\n}\n\n/// Run a hive agent with a prompt\npub fn run_agent(agent: &str, prompt: &str) -> Result<()> {\n // Check if hive is available\n if which::which(\"hive\").is_err() {\n anyhow::bail!(\"hive not found on PATH. Install from https://github.com/example/hive\");\n }\n\n let status = Command::new(\"hive\")\n .arg(\"agent\")\n .arg(agent)\n .arg(prompt)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"Failed to run hive\")?;\n\n if !status.success() {\n anyhow::bail!(\n \"hive agent '{}' exited with status {:?}\",\n agent,\n status.code()\n );\n }\n\n Ok(())\n}\n\n/// Run an agent interactively (prompt via stdin)\npub fn run_agent_interactive(agent: &str) -> Result<()> {\n if which::which(\"hive\").is_err() {\n anyhow::bail!(\"hive not found on PATH\");\n }\n\n let status = Command::new(\"hive\")\n .arg(\"agent\")\n .arg(agent)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"Failed to run hive\")?;\n\n if !status.success() {\n anyhow::bail!(\n \"hive agent '{}' exited with status {:?}\",\n agent,\n status.code()\n );\n }\n\n Ok(())\n}\n\n/// Create a new agent spec file\npub fn create_agent(name: &str, global: bool) -> Result<PathBuf> {\n let path = if global {\n let home = dirs::home_dir().context(\"Could not find home directory\")?;\n let dir = home.join(\".hive/agents\").join(name);\n fs::create_dir_all(&dir)?;\n dir.join(\"spec.md\")\n } else {\n let dir = PathBuf::from(\".flow/agents\");\n fs::create_dir_all(&dir)?;\n dir.join(format!(\"{}.md\", name))\n };\n\n if path.exists() {\n anyhow::bail!(\"Agent '{}' already exists at {}\", name, path.display());\n }\n\n let template = format!(\n r#\"# Agent: {}\n# Purpose: <describe what this agent does>\n#\n# Rules:\n# - <rule 1>\n# - <rule 2>\n#\n# Tools:\n# - bash\n\"#,\n name\n );\n\n fs::write(&path, template)?;\n Ok(path)\n}\n\n/// Edit an agent spec file\npub fn edit_agent(name: &str) -> Result<()> {\n let (path, _source) =\n find_agent_spec(name).ok_or_else(|| anyhow::anyhow!(\"Agent '{}' not found\", name))?;\n\n let editor = std::env::var(\"EDITOR\").unwrap_or_else(|_| \"vim\".to_string());\n let status = Command::new(&editor)\n .arg(&path)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(format!(\"Failed to open editor '{}'\", editor))?;\n\n if !status.success() {\n anyhow::bail!(\"Editor exited with status {:?}\", status.code());\n }\n\n Ok(())\n}\n\n/// List agents in a formatted table\npub fn list_agents(project_agents: &[AgentConfig]) {\n let agents = discover_agents(project_agents);\n\n if agents.is_empty() {\n println!(\"No agents found.\");\n println!(\"\\nCreate one with: f hive new <name>\");\n return;\n }\n\n println!(\"{:<20} {:<10} {}\", \"NAME\", \"SOURCE\", \"DESCRIPTION\");\n println!(\"{}\", \"-\".repeat(60));\n\n for agent in agents {\n let desc = agent\n .config\n .description\n .as_deref()\n .unwrap_or(\"-\")\n .chars()\n .take(40)\n .collect::<String>();\n println!(\"{:<20} {:<10} {}\", agent.name, agent.source, desc);\n }\n}\n\n/// Get agent by name\npub fn get_agent(name: &str, project_agents: &[AgentConfig]) -> Option<Agent> {\n discover_agents(project_agents)\n .into_iter()\n .find(|a| a.name == name)\n}\n\n/// Match agents for auto-routing based on content\npub fn match_agents(content: &str, project_agents: &[AgentConfig], max: usize) -> Vec<String> {\n let content_lower = content.to_lowercase();\n let mut matches = Vec::new();\n\n // Check project agents first\n for cfg in project_agents {\n if !cfg.match_on.is_empty() {\n let matched = cfg.match_on.iter().any(|term| {\n let needle = term.to_lowercase();\n !needle.is_empty() && content_lower.contains(&needle)\n });\n if matched {\n matches.push(cfg.name.clone());\n }\n }\n }\n\n // Check hive registry agents\n if let Some(hive_config) = load_hive_config() {\n for (name, spec) in hive_config.agents {\n if let Some(terms) = spec.matched_on {\n let matched = terms.iter().any(|term| {\n let needle = term.to_lowercase();\n !needle.is_empty() && content_lower.contains(&needle)\n });\n if matched && !matches.contains(&name) {\n matches.push(name);\n }\n }\n }\n }\n\n matches.truncate(max);\n matches\n}\n\n/// Handle the `f hive` CLI command.\npub fn run_command(cmd: crate::cli::HiveCommand) -> Result<()> {\n use crate::cli::HiveAction;\n\n // Load project config to get agents (if available)\n let cfg = load_config_for_agents();\n\n // Handle direct agent invocation: `f hive fish \"wrap ls\"`\n if !cmd.agent.is_empty() {\n let agent_name = &cmd.agent[0];\n let prompt = if cmd.agent.len() > 1 {\n cmd.agent[1..].join(\" \")\n } else {\n String::new()\n };\n\n if prompt.is_empty() {\n return run_agent_interactive(agent_name);\n } else {\n return run_agent(agent_name, &prompt);\n }\n }\n\n match cmd.action {\n None | Some(HiveAction::List) => {\n list_agents(&cfg.agents);\n }\n Some(HiveAction::Run { agent, prompt }) => {\n let prompt_str = prompt.join(\" \");\n if prompt_str.is_empty() {\n run_agent_interactive(&agent)?;\n } else {\n run_agent(&agent, &prompt_str)?;\n }\n }\n Some(HiveAction::New { name, global }) => {\n let path = create_agent(&name, global)?;\n println!(\"Created agent: {}\", path.display());\n println!(\"\\nEdit with: f hive edit {}\", name);\n }\n Some(HiveAction::Edit { agent }) => {\n if let Some(name) = agent {\n edit_agent(&name)?;\n } else {\n // List agents and ask user to specify\n let agents = discover_agents(&cfg.agents);\n if agents.is_empty() {\n println!(\"No agents found. Create one with: f hive new <name>\");\n } else {\n println!(\"Available agents:\");\n for a in agents {\n println!(\" {}\", a.name);\n }\n println!(\"\\nRun: f hive edit <agent>\");\n }\n }\n }\n Some(HiveAction::Show { agent }) => {\n if let Some(a) = get_agent(&agent, &cfg.agents) {\n if let Some(path) = a.spec_path {\n let content = load_agent_spec(&path)?;\n println!(\"{}\", content);\n } else if let Some(desc) = a.config.description {\n println!(\"# Agent: {}\\n\\n{}\", agent, desc);\n } else {\n println!(\"Agent '{}' has no spec file.\", agent);\n }\n } else {\n anyhow::bail!(\"Agent '{}' not found\", agent);\n }\n }\n }\n\n Ok(())\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn test_agent_source_display() {\n assert_eq!(format!(\"{}\", AgentSource::ProjectConfig), \"project\");\n assert_eq!(format!(\"{}\", AgentSource::GlobalHive), \"hive\");\n }\n}\n" }, { "path": "src/home.rs", "content": "use std::{\n fs,\n path::{Path, PathBuf},\n process::{Command, Stdio},\n};\n\nuse anyhow::{Context, Result, bail};\nuse regex::Regex;\nuse serde::Deserialize;\n\nuse crate::cli::{HomeAction, HomeCommand};\nuse crate::{config, ssh, ssh_keys};\n\nconst DEFAULT_REPOS_ROOT: &str = \"~/repos\";\n\n#[derive(Debug, Clone)]\nstruct RepoInput {\n owner: String,\n repo: String,\n clone_url: String,\n scheme: RepoScheme,\n}\n\n#[derive(Debug, Clone, Copy, PartialEq)]\nenum RepoScheme {\n Https,\n Ssh,\n}\n\n#[derive(Debug, Default, Deserialize)]\nstruct HomeConfigFile {\n #[serde(default)]\n home: Option<HomeConfigSection>,\n #[serde(default)]\n internal_repo: Option<String>,\n #[serde(default)]\n internal_repo_url: Option<String>,\n #[serde(default)]\n kar_repo: Option<String>,\n #[serde(default)]\n kar_repo_url: Option<String>,\n}\n\n#[derive(Debug, Default, Deserialize)]\nstruct HomeConfigSection {\n #[serde(default)]\n internal_repo: Option<String>,\n #[serde(default)]\n internal_repo_url: Option<String>,\n #[serde(default)]\n kar_repo: Option<String>,\n #[serde(default)]\n kar_repo_url: Option<String>,\n}\n\npub fn run(opts: HomeCommand) -> Result<()> {\n if let Some(action) = opts.action {\n match action {\n HomeAction::Setup => return setup(),\n }\n }\n\n ssh::ensure_ssh_env();\n let mode = ssh::ssh_mode();\n if matches!(mode, ssh::SshMode::Force) && !ssh::has_identities() {\n match ssh_keys::ensure_default_identity(24) {\n Ok(()) => {}\n Err(err) => println!(\n \"warning: SSH mode is forced but no key is available ({}). Run `f ssh setup` or `f ssh unlock`.\",\n err\n ),\n }\n }\n let prefer_ssh = ssh::prefer_ssh();\n let home = dirs::home_dir().context(\"Could not find home directory\")?;\n let config_dir = home.join(\"config\");\n let repo_str = opts\n .repo\n .as_ref()\n .context(\"Missing repo. Use `f home <repo>` or `f home setup`.\")?;\n let repo = coerce_repo_scheme(parse_repo_input(repo_str)?, prefer_ssh);\n let flow_bin = std::env::current_exe().unwrap_or_else(|_| PathBuf::from(\"f\"));\n\n ensure_repo(&config_dir, Some(&repo.clone_url), \"config\", false)?;\n\n let internal_url = if let Some(internal) = opts.internal.as_deref() {\n Some(coerce_repo_url(internal, prefer_ssh))\n } else {\n read_internal_repo(&config_dir)?\n .map(|url| coerce_repo_url(&url, prefer_ssh))\n .or_else(|| derive_internal_repo(&repo))\n };\n\n let internal_dir = config_dir.join(\"i\");\n if internal_dir.exists() {\n ensure_repo(&internal_dir, internal_url.as_deref(), \"config/i\", false)?;\n } else if let Some(url) = internal_url.as_deref() {\n ensure_repo(&internal_dir, Some(url), \"config/i\", false)?;\n } else {\n println!(\n \"No internal repo configured; skipping {} (use --internal or add home.toml)\",\n internal_dir.display()\n );\n }\n\n let archived = archive_existing_configs(&config_dir)?;\n apply_config(&config_dir)?;\n\n match ssh::ensure_git_ssh_command() {\n Ok(true) => println!(\"Configured git to use 1Password SSH agent.\"),\n Ok(false) => {}\n Err(err) => println!(\"warning: failed to configure git ssh: {}\", err),\n }\n if !prefer_ssh {\n match ssh::ensure_git_https_insteadof() {\n Ok(true) => println!(\"Configured git to use HTTPS when SSH isn't available.\"),\n Ok(false) => {}\n Err(err) => println!(\"warning: failed to configure git https rewrites: {}\", err),\n }\n }\n if let Some(kar_repo) = resolve_kar_repo(&config_dir)? {\n ensure_kar_repo(&flow_bin, prefer_ssh, &kar_repo)?;\n } else {\n println!(\"No kar repo configured; skipping kar deploy.\");\n }\n validate_setup(&config_dir)?;\n\n if !archived.is_empty() {\n println!(\"\\nMoved existing config files to ~/flow-archive:\");\n for path in archived {\n println!(\" {}\", path.display());\n }\n println!(\"Restore any file by moving it back to its original path.\");\n }\n\n Ok(())\n}\n\npub fn setup() -> Result<()> {\n println!(\"Home setup\");\n println!(\"-----------\");\n\n if !check_git() {\n println!(\"git not found on PATH. Install Xcode Command Line Tools:\");\n println!(\" xcode-select --install\");\n return Ok(());\n }\n\n ssh::ensure_ssh_env();\n\n let ssh_check = check_git_access(\"git@github.com:github/linguist.git\");\n if ssh_check.ok {\n println!(\"✓ GitHub SSH auth works (git@github.com)\");\n } else {\n println!(\"✗ GitHub SSH auth failed (git@github.com)\");\n }\n\n let https_check = check_git_access(\"https://github.com/github/linguist.git\");\n if https_check.ok {\n println!(\"✓ GitHub HTTPS works (https://github.com)\");\n } else {\n println!(\"✗ GitHub HTTPS failed (https://github.com)\");\n }\n\n if !ssh_check.ok && https_check.ok {\n match ssh::ensure_git_https_insteadof() {\n Ok(true) => println!(\"Configured git to use HTTPS when SSH isn't available.\"),\n Ok(false) => {}\n Err(err) => println!(\"warning: failed to configure git https rewrites: {}\", err),\n }\n println!(\"If you want SSH instead, add your key to GitHub and run:\");\n println!(\" f ssh setup\");\n println!(\" ssh -T git@github.com\");\n }\n\n if !ssh_check.ok && !https_check.ok {\n println!(\"GitHub connectivity failed. Check your network or proxy settings.\");\n }\n\n if !ssh_check.ok {\n if ssh_check\n .stderr\n .to_lowercase()\n .contains(\"permission denied (publickey)\")\n {\n println!(\"SSH key is not authorized for GitHub. Add ~/.ssh/id_ed25519.pub to GitHub.\");\n } else if ssh_check\n .stderr\n .to_lowercase()\n .contains(\"host key verification failed\")\n {\n println!(\"Accept GitHub host key first: ssh -T git@github.com\");\n }\n }\n\n println!(\"Done.\");\n Ok(())\n}\n\nfn check_git() -> bool {\n Command::new(\"git\")\n .arg(\"--version\")\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .map(|status| status.success())\n .unwrap_or(false)\n}\n\nstruct GitCheck {\n ok: bool,\n stderr: String,\n}\n\nfn check_git_access(url: &str) -> GitCheck {\n let output = Command::new(\"git\")\n .args([\"ls-remote\", \"--heads\", url])\n .env(\"GIT_TERMINAL_PROMPT\", \"0\")\n .output();\n\n match output {\n Ok(out) => GitCheck {\n ok: out.status.success(),\n stderr: String::from_utf8_lossy(&out.stderr).trim().to_string(),\n },\n Err(err) => GitCheck {\n ok: false,\n stderr: err.to_string(),\n },\n }\n}\n\nfn archive_existing_configs(config_dir: &Path) -> Result<Vec<PathBuf>> {\n let home = dirs::home_dir().context(\"Could not find home directory\")?;\n let archive_root = home.join(\"flow-archive\");\n let mappings = load_link_mappings(config_dir)?;\n let mut moved = Vec::new();\n\n for (source_rel, dest_rel) in mappings {\n let source = config_dir.join(&source_rel);\n if !source.exists() {\n continue;\n }\n\n let dest_rel = normalize_dest_rel(&dest_rel)?;\n let dest = home.join(&dest_rel);\n if !dest.exists() {\n continue;\n }\n\n if is_symlink_to(&dest, &source) {\n continue;\n }\n\n let mut archive_path = archive_root.join(&dest_rel);\n if archive_path.exists() {\n archive_path =\n archive_path.with_extension(format!(\"bak-{}\", chrono::Utc::now().timestamp()));\n }\n\n if let Some(parent) = archive_path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n\n fs::rename(&dest, &archive_path).with_context(|| {\n format!(\n \"failed to move {} to {}\",\n dest.display(),\n archive_path.display()\n )\n })?;\n moved.push(archive_path);\n }\n\n Ok(moved)\n}\n\nfn normalize_dest_rel(dest: &Path) -> Result<PathBuf> {\n let dest_str = dest.to_string_lossy();\n if let Some(stripped) = dest_str.strip_prefix(\"~/\") {\n return Ok(PathBuf::from(stripped));\n }\n if dest.is_absolute() {\n bail!(\n \"absolute paths are not supported in sync links: {}\",\n dest.display()\n );\n }\n Ok(dest.to_path_buf())\n}\n\nfn is_symlink_to(link: &Path, expected: &Path) -> bool {\n let meta = match fs::symlink_metadata(link) {\n Ok(v) => v,\n Err(_) => return false,\n };\n if !meta.file_type().is_symlink() {\n return false;\n }\n\n let target = match fs::read_link(link) {\n Ok(v) => v,\n Err(_) => return false,\n };\n let resolved = if target.is_absolute() {\n target\n } else {\n link.parent().unwrap_or_else(|| Path::new(\".\")).join(target)\n };\n\n let expected = match fs::canonicalize(expected) {\n Ok(v) => v,\n Err(_) => return false,\n };\n let resolved = match fs::canonicalize(resolved) {\n Ok(v) => v,\n Err(_) => return false,\n };\n\n resolved == expected\n}\n\nfn load_link_mappings(config_dir: &Path) -> Result<Vec<(PathBuf, PathBuf)>> {\n let sync_file = config_dir.join(\"sync\").join(\"src\").join(\"main.ts\");\n if sync_file.exists() {\n let raw = fs::read_to_string(&sync_file)\n .with_context(|| format!(\"failed to read {}\", sync_file.display()))?;\n let re =\n Regex::new(r#\"\"([^\"]+)\"\\s*:\\s*\"([^\"]+)\"\"#).context(\"failed to compile link regex\")?;\n let mut links = Vec::new();\n let mut in_links = false;\n for line in raw.lines() {\n let trimmed = line.trim();\n if trimmed.starts_with(\"const LINKS\") {\n in_links = true;\n continue;\n }\n if in_links && trimmed.starts_with('}') {\n break;\n }\n if !in_links {\n continue;\n }\n if let Some(caps) = re.captures(trimmed) {\n let src = caps.get(1).map(|m| m.as_str()).unwrap_or(\"\");\n let dst = caps.get(2).map(|m| m.as_str()).unwrap_or(\"\");\n if !src.is_empty() && !dst.is_empty() {\n links.push((PathBuf::from(src), PathBuf::from(dst)));\n }\n }\n }\n if !links.is_empty() {\n return Ok(links);\n }\n }\n\n Ok(default_link_mappings())\n}\n\nfn default_link_mappings() -> Vec<(PathBuf, PathBuf)> {\n vec![\n (\"fish/config.fish\", \".config/fish/config.fish\"),\n (\"fish/fn.fish\", \".config/fish/fn.fish\"),\n (\"i/karabiner/karabiner.edn\", \".config/karabiner.edn\"),\n (\"i/kar\", \".config/kar\"),\n (\"i/git/.gitconfig\", \".gitconfig\"),\n (\"i/ssh/config\", \".ssh/config\"),\n (\"i/ghost/ghost.toml\", \".config/ghost/ghost.toml\"),\n (\"i/flow\", \".config/flow\"),\n ]\n .into_iter()\n .map(|(src, dst)| (PathBuf::from(src), PathBuf::from(dst)))\n .collect()\n}\n\nfn apply_config(config_dir: &Path) -> Result<()> {\n let sync_script = config_dir.join(\"sync\").join(\"src\").join(\"main.ts\");\n if sync_script.exists() {\n if which::which(\"bun\").is_ok() {\n run_command(\n \"bun\",\n &[sync_script.to_string_lossy().as_ref(), \"link\"],\n Some(config_dir),\n )?;\n ensure_link_targets(config_dir)?;\n return Ok(());\n }\n }\n\n if which::which(\"sync\").is_ok() {\n run_command(\"sync\", &[\"link\"], Some(config_dir))?;\n ensure_link_targets(config_dir)?;\n return Ok(());\n }\n\n let fallback = config_dir.join(\"sh\").join(\"check-config-setup.sh\");\n if fallback.exists() {\n println!(\"sync not available; falling back to {}\", fallback.display());\n run_command(fallback.to_string_lossy().as_ref(), &[], Some(config_dir))?;\n let internal_fallback = config_dir.join(\"sh\").join(\"ensure-i-dotfiles.sh\");\n if internal_fallback.exists() {\n run_command(\n internal_fallback.to_string_lossy().as_ref(),\n &[],\n Some(config_dir),\n )?;\n }\n ensure_link_targets(config_dir)?;\n return Ok(());\n }\n\n println!(\n \"sync tool not available; applying symlinks directly from {}\",\n config_dir.display()\n );\n ensure_link_targets(config_dir)\n}\n\nfn ensure_link_targets(config_dir: &Path) -> Result<()> {\n let home = dirs::home_dir().context(\"Could not find home directory\")?;\n let mappings = load_link_mappings(config_dir)?;\n\n for (source_rel, dest_rel) in mappings {\n let source = config_dir.join(&source_rel);\n if !source.exists() {\n continue;\n }\n\n let dest_rel = normalize_dest_rel(&dest_rel)?;\n let dest = home.join(&dest_rel);\n\n if is_symlink_to(&dest, &source) {\n continue;\n }\n\n if let Ok(meta) = fs::symlink_metadata(&dest) {\n if meta.file_type().is_dir() {\n fs::remove_dir_all(&dest)\n .with_context(|| format!(\"failed to remove {}\", dest.display()))?;\n } else {\n fs::remove_file(&dest)\n .with_context(|| format!(\"failed to remove {}\", dest.display()))?;\n }\n }\n\n if let Some(parent) = dest.parent() {\n if !parent.as_os_str().is_empty() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n }\n\n create_symlink(&source, &dest)?;\n }\n\n Ok(())\n}\n\nfn create_symlink(source: &Path, dest: &Path) -> Result<()> {\n #[cfg(unix)]\n {\n std::os::unix::fs::symlink(source, dest).with_context(|| {\n format!(\n \"failed to symlink {} -> {}\",\n dest.display(),\n source.display()\n )\n })?;\n return Ok(());\n }\n #[cfg(not(unix))]\n {\n bail!(\"symlinks are only supported on unix-like systems\");\n }\n}\n\nfn ensure_kar_repo(flow_bin: &Path, prefer_ssh: bool, repo_url: &str) -> Result<()> {\n let repo_url = coerce_repo_url(repo_url, prefer_ssh);\n let repo = parse_repo_input(&repo_url)?;\n let root = config::expand_path(DEFAULT_REPOS_ROOT);\n let owner_dir = root.join(&repo.owner);\n let repo_path = owner_dir.join(&repo.repo);\n\n ensure_repo(&repo_path, Some(&repo.clone_url), \"kar\", true)?;\n\n let flow_toml = repo_path.join(\"flow.toml\");\n if !flow_toml.exists() {\n println!(\n \"No flow.toml found in {}; skipping f deploy\",\n repo_path.display()\n );\n return Ok(());\n }\n\n println!(\"Deploying kar from {}\", repo_path.display());\n run_command(\n flow_bin.to_string_lossy().as_ref(),\n &[\"deploy\"],\n Some(&repo_path),\n )?;\n Ok(())\n}\n\nfn validate_setup(config_dir: &Path) -> Result<()> {\n let home = dirs::home_dir().context(\"Could not find home directory\")?;\n let mappings = load_link_mappings(config_dir)?;\n let mut missing = Vec::new();\n let mut mismatched = Vec::new();\n\n for (source_rel, dest_rel) in &mappings {\n let source = config_dir.join(source_rel);\n if !source.exists() {\n continue;\n }\n\n let dest_rel = normalize_dest_rel(dest_rel)?;\n let dest = home.join(&dest_rel);\n if !dest.exists() {\n missing.push(dest);\n continue;\n }\n\n if !is_symlink_to(&dest, &source) {\n mismatched.push((dest, source));\n }\n }\n\n let mut critical_missing = Vec::new();\n let kar_config = home.join(\".config/kar/config.ts\");\n if !kar_config.exists() {\n critical_missing.push(kar_config);\n }\n let karabiner_config = home.join(\".config/karabiner.edn\");\n if !karabiner_config.exists() {\n critical_missing.push(karabiner_config);\n }\n\n if missing.is_empty() && mismatched.is_empty() && critical_missing.is_empty() {\n println!(\"Validation: all expected configs are in place.\");\n return Ok(());\n }\n\n println!(\"\\nValidation warnings:\");\n for path in critical_missing {\n println!(\" missing critical config: {}\", path.display());\n }\n for path in missing {\n println!(\" missing link target: {}\", path.display());\n }\n for (dest, source) in mismatched {\n println!(\n \" not linked: {} (expected -> {})\",\n dest.display(),\n source.display()\n );\n }\n\n Ok(())\n}\n\nfn ensure_repo(\n dest: &Path,\n repo_url: Option<&str>,\n label: &str,\n allow_origin_reset: bool,\n) -> Result<()> {\n if dest.exists() {\n if !dest.join(\".git\").exists() {\n bail!(\"{} exists but is not a git repo: {}\", label, dest.display());\n }\n\n if let Some(expected) = repo_url {\n if allow_origin_reset {\n ensure_origin_url(dest, expected)?;\n } else if let Ok(actual) = git_capture(dest, &[\"remote\", \"get-url\", \"origin\"]) {\n if !urls_match(expected, actual.trim()) {\n bail!(\n \"{} origin mismatch: expected {}, got {}\",\n label,\n expected,\n actual.trim()\n );\n }\n }\n }\n\n update_repo(dest)?;\n return Ok(());\n }\n\n let repo_url = repo_url.ok_or_else(|| anyhow::anyhow!(\"{} repo URL required\", label))?;\n clone_repo(repo_url, dest)?;\n Ok(())\n}\n\nfn update_repo(dest: &Path) -> Result<()> {\n run_command(\"git\", &[\"fetch\", \"--prune\", \"origin\"], Some(dest))?;\n let branch = default_branch(dest)?;\n run_command(\n \"git\",\n &[\"checkout\", \"-B\", &branch, &format!(\"origin/{}\", branch)],\n Some(dest),\n )?;\n run_command(\n \"git\",\n &[\"reset\", \"--hard\", &format!(\"origin/{}\", branch)],\n Some(dest),\n )?;\n println!(\"Updated {}\", dest.display());\n Ok(())\n}\n\nfn clone_repo(repo_url: &str, dest: &Path) -> Result<()> {\n if let Some(parent) = dest.parent() {\n if !parent.as_os_str().is_empty() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n }\n\n run_command(\n \"git\",\n &[\"clone\", repo_url, dest.to_string_lossy().as_ref()],\n None,\n )?;\n println!(\"Cloned {}\", dest.display());\n Ok(())\n}\n\nfn ensure_origin_url(dest: &Path, expected: &str) -> Result<()> {\n match git_capture(dest, &[\"remote\", \"get-url\", \"origin\"]) {\n Ok(actual) => {\n let actual = actual.trim();\n let mut needs_reset = !urls_match(expected, actual);\n if !needs_reset {\n if let (Some(expected_scheme), Some(actual_scheme)) =\n (scheme_for_url(expected), scheme_for_url(actual))\n {\n if expected_scheme != actual_scheme {\n needs_reset = true;\n }\n }\n }\n if needs_reset {\n run_command(\n \"git\",\n &[\"remote\", \"set-url\", \"origin\", expected],\n Some(dest),\n )?;\n }\n }\n Err(_) => {\n run_command(\"git\", &[\"remote\", \"add\", \"origin\", expected], Some(dest))?;\n }\n }\n Ok(())\n}\n\nfn default_branch(dest: &Path) -> Result<String> {\n if let Ok(head) = git_capture(dest, &[\"symbolic-ref\", \"refs/remotes/origin/HEAD\"]) {\n if let Some(branch) = head.trim().rsplit('/').next() {\n if !branch.is_empty() {\n return Ok(branch.to_string());\n }\n }\n }\n\n if git_ref_exists(dest, \"refs/remotes/origin/main\")? {\n return Ok(\"main\".to_string());\n }\n if git_ref_exists(dest, \"refs/remotes/origin/master\")? {\n return Ok(\"master\".to_string());\n }\n\n Ok(\"main\".to_string())\n}\n\nfn git_ref_exists(dest: &Path, reference: &str) -> Result<bool> {\n let status = Command::new(\"git\")\n .args([\"rev-parse\", \"--verify\", \"--quiet\", reference])\n .current_dir(dest)\n .stdin(Stdio::null())\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .context(\"failed to run git\")?;\n Ok(status.success())\n}\n\nfn git_capture(dest: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"git\")\n .args(args)\n .current_dir(dest)\n .stdin(Stdio::null())\n .output()\n .context(\"failed to run git\")?;\n if !output.status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())\n}\n\nfn run_command(cmd: &str, args: &[&str], cwd: Option<&Path>) -> Result<()> {\n let mut command = Command::new(cmd);\n command.args(args);\n if let Some(dir) = cwd {\n command.current_dir(dir);\n }\n let status = command\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .with_context(|| format!(\"failed to run {}\", cmd))?;\n if !status.success() {\n bail!(\"{} failed with status {}\", cmd, status);\n }\n Ok(())\n}\n\nfn read_internal_repo(config_dir: &Path) -> Result<Option<String>> {\n let candidates = [config_dir.join(\"home.toml\"), config_dir.join(\".home.toml\")];\n for path in candidates {\n if !path.exists() {\n continue;\n }\n let raw = fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n let parsed: HomeConfigFile =\n toml::from_str(&raw).with_context(|| format!(\"failed to parse {}\", path.display()))?;\n let from_section = parsed\n .home\n .as_ref()\n .and_then(|h| h.internal_repo.clone().or(h.internal_repo_url.clone()));\n let flat = parsed.internal_repo.or(parsed.internal_repo_url);\n if from_section.is_some() {\n return Ok(from_section);\n }\n if flat.is_some() {\n return Ok(flat);\n }\n }\n Ok(None)\n}\n\nfn resolve_kar_repo(config_dir: &Path) -> Result<Option<String>> {\n if let Ok(value) = std::env::var(\"FLOW_HOME_KAR_REPO\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(Some(trimmed.to_string()));\n }\n }\n read_kar_repo(config_dir)\n}\n\nfn read_kar_repo(config_dir: &Path) -> Result<Option<String>> {\n let candidates = [config_dir.join(\"home.toml\"), config_dir.join(\".home.toml\")];\n for path in candidates {\n if !path.exists() {\n continue;\n }\n let raw = fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n let parsed: HomeConfigFile =\n toml::from_str(&raw).with_context(|| format!(\"failed to parse {}\", path.display()))?;\n let from_section = parsed\n .home\n .as_ref()\n .and_then(|h| h.kar_repo.clone().or(h.kar_repo_url.clone()));\n let flat = parsed.kar_repo.or(parsed.kar_repo_url);\n if from_section.is_some() {\n return Ok(from_section);\n }\n if flat.is_some() {\n return Ok(flat);\n }\n }\n Ok(None)\n}\n\nfn derive_internal_repo(repo: &RepoInput) -> Option<String> {\n let suffix = format!(\"{}-i\", repo.repo);\n match repo.scheme {\n RepoScheme::Https => Some(format!(\"https://github.com/{}/{}.git\", repo.owner, suffix)),\n RepoScheme::Ssh => Some(format!(\"git@github.com:{}/{}.git\", repo.owner, suffix)),\n }\n}\n\nfn parse_repo_input(input: &str) -> Result<RepoInput> {\n let trimmed = input.trim().trim_end_matches('/');\n if trimmed.is_empty() {\n bail!(\"repo URL is required\");\n }\n\n if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n return parse_owner_repo(rest, RepoScheme::Ssh);\n }\n\n if let Some(rest) = trimmed.strip_prefix(\"ssh://git@github.com/\") {\n return parse_owner_repo(rest, RepoScheme::Ssh);\n }\n\n if let Some(rest) = trimmed.strip_prefix(\"https://github.com/\") {\n return parse_owner_repo(rest, RepoScheme::Https);\n }\n\n if let Some(rest) = trimmed.strip_prefix(\"http://github.com/\") {\n return parse_owner_repo(rest, RepoScheme::Https);\n }\n\n if let Some(rest) = trimmed.strip_prefix(\"github.com/\") {\n return parse_owner_repo(rest, RepoScheme::Https);\n }\n\n if trimmed.contains('/') {\n return parse_owner_repo(trimmed, RepoScheme::Https);\n }\n\n bail!(\"unable to parse GitHub repo from: {}\", input)\n}\n\nfn parse_owner_repo(raw: &str, scheme: RepoScheme) -> Result<RepoInput> {\n let cleaned = raw.trim().trim_end_matches(\".git\").trim_end_matches('/');\n let mut parts = cleaned.splitn(2, '/');\n let owner = parts.next().unwrap_or(\"\").trim();\n let repo = parts.next().unwrap_or(\"\").trim();\n if owner.is_empty() || repo.is_empty() {\n bail!(\"unable to parse GitHub repo from: {}\", raw);\n }\n\n let clone_url = match scheme {\n RepoScheme::Https => format!(\"https://github.com/{}/{}.git\", owner, repo),\n RepoScheme::Ssh => format!(\"git@github.com:{}/{}.git\", owner, repo),\n };\n\n Ok(RepoInput {\n owner: owner.to_string(),\n repo: repo.to_string(),\n clone_url,\n scheme,\n })\n}\n\nfn coerce_repo_scheme(repo: RepoInput, prefer_ssh: bool) -> RepoInput {\n let desired = if prefer_ssh {\n RepoScheme::Ssh\n } else {\n RepoScheme::Https\n };\n if repo.scheme == desired {\n return repo;\n }\n\n let clone_url = match desired {\n RepoScheme::Https => format!(\"https://github.com/{}/{}.git\", repo.owner, repo.repo),\n RepoScheme::Ssh => format!(\"git@github.com:{}/{}.git\", repo.owner, repo.repo),\n };\n\n RepoInput {\n owner: repo.owner,\n repo: repo.repo,\n clone_url,\n scheme: desired,\n }\n}\n\nfn coerce_repo_url(raw: &str, prefer_ssh: bool) -> String {\n match parse_repo_input(raw) {\n Ok(repo) => coerce_repo_scheme(repo, prefer_ssh).clone_url,\n Err(_) => raw.to_string(),\n }\n}\n\nfn urls_match(a: &str, b: &str) -> bool {\n normalize_repo_url(a) == normalize_repo_url(b)\n}\n\nfn normalize_repo_url(raw: &str) -> String {\n let trimmed = raw.trim().trim_end_matches('/').trim_end_matches(\".git\");\n if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n return format!(\"github.com/{}\", rest);\n }\n if let Some(rest) = trimmed.strip_prefix(\"ssh://git@github.com/\") {\n return format!(\"github.com/{}\", rest);\n }\n if let Some(rest) = trimmed.strip_prefix(\"https://github.com/\") {\n return format!(\"github.com/{}\", rest);\n }\n if let Some(rest) = trimmed.strip_prefix(\"http://github.com/\") {\n return format!(\"github.com/{}\", rest);\n }\n if let Some(rest) = trimmed.strip_prefix(\"github.com/\") {\n return format!(\"github.com/{}\", rest);\n }\n trimmed.to_string()\n}\n\nfn scheme_for_url(raw: &str) -> Option<RepoScheme> {\n let trimmed = raw.trim();\n if trimmed.starts_with(\"git@github.com:\") || trimmed.starts_with(\"ssh://git@github.com/\") {\n return Some(RepoScheme::Ssh);\n }\n if trimmed.starts_with(\"https://github.com/\") || trimmed.starts_with(\"http://github.com/\") {\n return Some(RepoScheme::Https);\n }\n None\n}\n" }, { "path": "src/http_client.rs", "content": "use std::collections::HashMap;\nuse std::sync::{Mutex, OnceLock};\nuse std::time::Duration;\n\nuse anyhow::{Context, Result};\nuse reqwest::blocking::Client;\n\nstatic BLOCKING_CLIENTS: OnceLock<Mutex<HashMap<u64, Client>>> = OnceLock::new();\n\nfn timeout_key(timeout: Duration) -> u64 {\n timeout.as_millis().min(u64::MAX as u128) as u64\n}\n\n/// Reuse blocking reqwest clients by timeout bucket to avoid repeated TLS/client init.\npub fn blocking_with_timeout(timeout: Duration) -> Result<Client> {\n let clients = BLOCKING_CLIENTS.get_or_init(|| Mutex::new(HashMap::new()));\n let key = timeout_key(timeout);\n let mut guard = clients\n .lock()\n .map_err(|_| anyhow::anyhow!(\"http client cache mutex poisoned\"))?;\n\n if let Some(client) = guard.get(&key) {\n return Ok(client.clone());\n }\n\n let client = Client::builder()\n .timeout(timeout)\n .build()\n .with_context(|| format!(\"failed to build http client with timeout {:?}\", timeout))?;\n guard.insert(key, client.clone());\n Ok(client)\n}\n" }, { "path": "src/hub.rs", "content": "use std::{net::IpAddr, time::Duration};\n\nuse anyhow::Result;\nuse reqwest::blocking::Client;\n\nuse crate::{\n cli::{HubAction, HubCommand, HubOpts},\n daemon, docs, supervisor,\n};\n\n/// Flow acts as a thin launcher that makes sure the lin hub daemon is running.\npub fn run(cmd: HubCommand) -> Result<()> {\n let action = cmd.action.unwrap_or(HubAction::Start);\n let opts = cmd.opts;\n\n match action {\n HubAction::Start => {\n ensure_daemon(&opts)?;\n if opts.docs_hub {\n let docs_opts = crate::cli::DocsHubOpts {\n host: \"127.0.0.1\".to_string(),\n port: 4410,\n hub_root: \"~/.config/flow/docs-hub\".to_string(),\n template_root: \"~/new/docs\".to_string(),\n code_root: \"~/code\".to_string(),\n org_root: \"~/org\".to_string(),\n no_ai: true,\n no_open: true,\n sync_only: false,\n };\n docs::ensure_docs_hub_daemon(&docs_opts)?;\n }\n Ok(())\n }\n HubAction::Stop => {\n stop_daemon(&opts)?;\n docs::stop_docs_hub_daemon()?;\n Ok(())\n }\n }\n}\n\nfn ensure_daemon(opts: &HubOpts) -> Result<()> {\n let host = opts.host;\n let port = opts.port;\n\n if hub_healthy(host, port) {\n if !opts.no_ui {\n println!(\n \"Lin watcher daemon already running at {}\",\n format_addr(host, port)\n );\n }\n return Ok(());\n }\n\n supervisor::ensure_running(true, !opts.no_ui)?;\n\n let action = crate::cli::DaemonAction::Start {\n name: \"lin\".to_string(),\n };\n if !supervisor::try_handle_daemon_action(&action, None)? {\n daemon::start_daemon_with_path(\"lin\", None)?;\n }\n\n if !opts.no_ui {\n println!(\"Lin watcher daemon ensured at {}\", format_addr(host, port));\n }\n Ok(())\n}\n\nfn stop_daemon(opts: &HubOpts) -> Result<()> {\n let action = crate::cli::DaemonAction::Stop {\n name: \"lin\".to_string(),\n };\n if supervisor::is_running() {\n if !supervisor::try_handle_daemon_action(&action, None)? {\n daemon::stop_daemon_with_path(\"lin\", None)?;\n }\n } else {\n daemon::stop_daemon_with_path(\"lin\", None)?;\n }\n if !opts.no_ui {\n println!(\"Lin hub stopped (if it was running).\");\n }\n Ok(())\n}\n\n/// Check if the hub is healthy and responding.\npub fn hub_healthy(host: IpAddr, port: u16) -> bool {\n let url = format_health_url(host, port);\n let client = Client::builder()\n .timeout(Duration::from_millis(750))\n .build();\n\n let Ok(client) = client else {\n return false;\n };\n\n client\n .get(url)\n .send()\n .and_then(|resp| resp.error_for_status())\n .map(|_| true)\n .unwrap_or(false)\n}\n\nfn format_addr(host: IpAddr, port: u16) -> String {\n match host {\n IpAddr::V4(_) => format!(\"http://{host}:{port}\"),\n IpAddr::V6(_) => format!(\"http://[{host}]:{port}\"),\n }\n}\n\nfn format_health_url(host: IpAddr, port: u16) -> String {\n match host {\n IpAddr::V4(_) => format!(\"http://{host}:{port}/health\"),\n IpAddr::V6(_) => format!(\"http://[{host}]:{port}/health\"),\n }\n}\n" }, { "path": "src/indexer.rs", "content": "use std::{\n env, fs,\n path::{Path, PathBuf},\n process::Command,\n time::{SystemTime, UNIX_EPOCH},\n};\n\nuse anyhow::{Context, Result, bail};\nuse rusqlite::Connection;\n\nuse crate::cli::IndexOpts;\n\npub fn run(opts: IndexOpts) -> Result<()> {\n let codanna_path = which::which(&opts.binary).with_context(|| {\n format!(\n \"failed to locate '{}' on PATH – install Codanna or pass --binary\",\n opts.binary\n )\n })?;\n\n let project_root = resolve_project_root(opts.project_root)?;\n\n ensure_codanna_initialized(&codanna_path, &project_root)?;\n run_codanna_index(&codanna_path, &project_root)?;\n let payload = capture_index_stats(&codanna_path, &project_root)?;\n let db_path = persist_snapshot(&project_root, &codanna_path, &payload, opts.database)?;\n\n println!(\"Codanna index snapshot stored at {}\", db_path.display());\n\n Ok(())\n}\n\nfn resolve_project_root(path: Option<PathBuf>) -> Result<PathBuf> {\n let raw_path = match path {\n Some(p) if p.is_absolute() => p,\n Some(p) => env::current_dir()?.join(p),\n None => env::current_dir()?,\n };\n\n raw_path\n .canonicalize()\n .with_context(|| format!(\"failed to resolve project root at {}\", raw_path.display()))\n}\n\nfn ensure_codanna_initialized(binary: &Path, project_root: &Path) -> Result<()> {\n let settings = project_root.join(\".codanna/settings.toml\");\n if settings.exists() {\n return Ok(());\n }\n\n println!(\n \"No Codanna settings found at {} – running 'codanna init'.\",\n settings.display()\n );\n let status = Command::new(binary)\n .arg(\"init\")\n .current_dir(project_root)\n .status()\n .with_context(|| \"failed to spawn 'codanna init'\")?;\n\n if status.success() {\n Ok(())\n } else {\n bail!(\n \"'codanna init' exited with status {}\",\n status.code().unwrap_or(-1)\n );\n }\n}\n\nfn run_codanna_index(binary: &Path, project_root: &Path) -> Result<()> {\n println!(\"Indexing project {} via Codanna...\", project_root.display());\n let status = Command::new(binary)\n .arg(\"index\")\n .arg(\"--progress\")\n .arg(\".\")\n .current_dir(project_root)\n .status()\n .with_context(|| \"failed to spawn 'codanna index'\")?;\n\n if status.success() {\n Ok(())\n } else {\n bail!(\n \"'codanna index' exited with status {}\",\n status.code().unwrap_or(-1)\n );\n }\n}\n\nfn capture_index_stats(binary: &Path, project_root: &Path) -> Result<String> {\n println!(\"Fetching Codanna index metadata...\");\n let output = Command::new(binary)\n .arg(\"mcp\")\n .arg(\"get_index_info\")\n .arg(\"--json\")\n .current_dir(project_root)\n .output()\n .with_context(|| \"failed to run 'codanna mcp get_index_info --json'\")?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"'codanna mcp get_index_info' failed: {}\", stderr.trim());\n }\n\n let json: serde_json::Value = serde_json::from_slice(&output.stdout)\n .with_context(|| \"failed to parse JSON from 'codanna mcp get_index_info --json'\")?;\n\n serde_json::to_string_pretty(&json).with_context(|| \"failed to serialize Codanna stats payload\")\n}\n\nfn persist_snapshot(\n project_root: &Path,\n binary: &Path,\n payload: &str,\n override_path: Option<PathBuf>,\n) -> Result<PathBuf> {\n let db_path = override_path.unwrap_or_else(default_db_path);\n if let Some(parent) = db_path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create directory {}\", parent.display()))?;\n }\n\n let conn = Connection::open(&db_path)\n .with_context(|| format!(\"failed to open sqlite database at {}\", db_path.display()))?;\n\n conn.execute(\n \"CREATE TABLE IF NOT EXISTS index_runs (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n repo_path TEXT NOT NULL,\n codanna_binary TEXT NOT NULL,\n indexed_at INTEGER NOT NULL,\n payload TEXT NOT NULL\n )\",\n [],\n )\n .with_context(|| \"failed to create index_runs table\")?;\n\n let repo_str = project_root.display().to_string();\n let binary_str = binary.display().to_string();\n let timestamp = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .with_context(|| \"system clock before UNIX_EPOCH\")?\n .as_secs() as i64;\n\n conn.execute(\n \"INSERT INTO index_runs (repo_path, codanna_binary, indexed_at, payload)\n VALUES (?1, ?2, ?3, ?4)\",\n (&repo_str, &binary_str, timestamp, payload),\n )\n .with_context(|| \"failed to insert index snapshot\")?;\n\n Ok(db_path)\n}\n\nfn default_db_path() -> PathBuf {\n if let Some(home) = env::var_os(\"HOME\") {\n PathBuf::from(home).join(\".db/flow/flow.sqlite\")\n } else {\n PathBuf::from(\".db/flow/flow.sqlite\")\n }\n}\n" }, { "path": "src/info.rs", "content": "use std::{\n collections::HashSet,\n fs,\n path::{Path, PathBuf},\n};\n\nuse anyhow::Result;\nuse serde::Deserialize;\n\n/// Show project information including git remotes and flow.toml settings.\npub fn run() -> Result<()> {\n let cwd = std::env::current_dir()?;\n\n println!(\"Project: {}\", cwd.display());\n println!();\n\n if let Some(git) = git_info(&cwd) {\n print_git_info(&git);\n } else {\n println!(\"Git: not a git repository\");\n }\n\n println!();\n\n // Show flow.toml info\n if let Some(flow_config) = crate::project_snapshot::find_flow_toml_upwards(&cwd) {\n print_flow_info(&flow_config);\n } else {\n println!(\"Flow: no flow.toml found\");\n }\n\n Ok(())\n}\n\n#[derive(Debug)]\nstruct GitInfo {\n branch: Option<String>,\n remotes: Vec<(String, String)>,\n}\n\n#[derive(Debug)]\nstruct GitRepoPaths {\n git_dir: PathBuf,\n common_dir: PathBuf,\n}\n\nfn print_git_info(git: &GitInfo) {\n if let Some(branch) = git.branch.as_deref() {\n println!(\"Branch: {}\", branch);\n }\n\n if !git.remotes.is_empty() {\n println!();\n println!(\"Remotes:\");\n for (name, url) in &git.remotes {\n println!(\" {} = {}\", name, url);\n }\n }\n\n if let Some((_, upstream)) = git\n .remotes\n .iter()\n .find(|(name, _)| name.eq_ignore_ascii_case(\"upstream\"))\n {\n println!();\n println!(\"Upstream: {}\", upstream);\n println!(\" Run `f sync` to pull from upstream and push to origin\");\n }\n}\n\nfn git_info(cwd: &Path) -> Option<GitInfo> {\n let repo_root = find_git_root(cwd)?;\n let repo = resolve_git_paths(&repo_root)?;\n let branch = read_git_branch(&repo.git_dir.join(\"HEAD\"));\n let remotes = parse_git_remotes(&repo.common_dir.join(\"config\"));\n Some(GitInfo { branch, remotes })\n}\n\nfn find_git_root(start: &Path) -> Option<PathBuf> {\n let mut current = if start.is_dir() {\n start.to_path_buf()\n } else {\n start.parent()?.to_path_buf()\n };\n loop {\n let dot_git = current.join(\".git\");\n if dot_git.is_dir() || dot_git.is_file() {\n return Some(current);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\nfn resolve_git_paths(repo_root: &Path) -> Option<GitRepoPaths> {\n let dot_git = repo_root.join(\".git\");\n let git_dir = if dot_git.is_dir() {\n dot_git\n } else {\n resolve_git_dir_file(&dot_git)?\n };\n let common_dir = resolve_common_git_dir(&git_dir);\n Some(GitRepoPaths {\n git_dir,\n common_dir,\n })\n}\n\nfn resolve_git_dir_file(dot_git_file: &Path) -> Option<PathBuf> {\n let content = fs::read_to_string(dot_git_file).ok()?;\n let gitdir = content.strip_prefix(\"gitdir:\")?.trim();\n let path = PathBuf::from(gitdir);\n let resolved = if path.is_absolute() {\n path\n } else {\n dot_git_file.parent()?.join(path)\n };\n Some(resolved.canonicalize().unwrap_or(resolved))\n}\n\nfn resolve_common_git_dir(git_dir: &Path) -> PathBuf {\n let commondir = git_dir.join(\"commondir\");\n let Ok(content) = fs::read_to_string(&commondir) else {\n return git_dir.to_path_buf();\n };\n let trimmed = content.trim();\n if trimmed.is_empty() {\n return git_dir.to_path_buf();\n }\n let path = PathBuf::from(trimmed);\n let resolved = if path.is_absolute() {\n path\n } else {\n git_dir.join(path)\n };\n resolved.canonicalize().unwrap_or(resolved)\n}\n\nfn read_git_branch(head_path: &Path) -> Option<String> {\n let content = fs::read_to_string(head_path).ok()?;\n let head = content.trim();\n let branch = head.strip_prefix(\"ref: refs/heads/\")?.trim();\n if branch.is_empty() {\n None\n } else {\n Some(branch.to_string())\n }\n}\n\nfn parse_git_remotes(config_path: &Path) -> Vec<(String, String)> {\n let Ok(content) = fs::read_to_string(config_path) else {\n return Vec::new();\n };\n\n let mut remotes = Vec::new();\n let mut seen = HashSet::new();\n let mut current_remote: Option<String> = None;\n\n for raw_line in content.lines() {\n let line = raw_line.trim();\n if line.is_empty() || line.starts_with('#') || line.starts_with(';') {\n continue;\n }\n if line.starts_with('[') && line.ends_with(']') {\n current_remote = parse_remote_section(line);\n continue;\n }\n let Some(remote) = current_remote.as_deref() else {\n continue;\n };\n let Some((key, value)) = line.split_once('=') else {\n continue;\n };\n if key.trim().eq_ignore_ascii_case(\"url\") {\n let url = value.trim().to_string();\n let dedupe_key = format!(\"{remote}\\n{url}\");\n if seen.insert(dedupe_key) {\n remotes.push((remote.to_string(), url));\n }\n }\n }\n\n remotes\n}\n\nfn parse_remote_section(section: &str) -> Option<String> {\n let inner = section.strip_prefix('[')?.strip_suffix(']')?.trim();\n let rest = inner.strip_prefix(\"remote\")?.trim();\n let name = rest.strip_prefix('\"')?.strip_suffix('\"')?.trim();\n if name.is_empty() {\n None\n } else {\n Some(name.to_string())\n }\n}\n\nfn print_flow_info(flow_toml: &Path) {\n let content = match std::fs::read_to_string(flow_toml) {\n Ok(c) => c,\n Err(_) => return,\n };\n\n let parsed: InfoConfig = match toml::from_str(&content) {\n Ok(v) => v,\n Err(_) => return,\n };\n\n println!(\"Flow: {}\", flow_toml.display());\n\n // Show [flow] section info\n if let Some(flow) = parsed.flow.as_ref() {\n if let Some(name) = flow.name.as_deref() {\n println!(\" name = {}\", name);\n }\n if let Some(upstream) = flow.upstream.as_deref() {\n println!(\" upstream = {}\", upstream);\n }\n }\n\n if let Some(upstream) = parsed.upstream.as_ref() {\n println!();\n println!(\"[upstream]\");\n if let Some(url) = upstream.url.as_deref() {\n println!(\" url = {}\", url);\n }\n if let Some(branch) = upstream.branch.as_deref() {\n println!(\" branch = {}\", branch);\n }\n }\n\n if !parsed.tasks.is_empty() {\n println!();\n println!(\"Tasks: {}\", parsed.tasks.len());\n }\n}\n\n#[derive(Debug, Deserialize)]\nstruct InfoConfig {\n #[serde(default)]\n flow: Option<InfoFlowSection>,\n #[serde(default)]\n upstream: Option<InfoUpstreamSection>,\n #[serde(default)]\n tasks: Vec<InfoTaskSection>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct InfoFlowSection {\n #[serde(default)]\n name: Option<String>,\n #[serde(default)]\n upstream: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct InfoUpstreamSection {\n #[serde(default)]\n url: Option<String>,\n #[serde(default)]\n branch: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct InfoTaskSection {}\n\n#[cfg(test)]\nmod tests {\n use std::fs;\n\n use tempfile::tempdir;\n\n use super::{\n find_git_root, parse_git_remotes, read_git_branch, resolve_common_git_dir,\n resolve_git_dir_file,\n };\n\n #[test]\n fn parse_git_remotes_reads_unique_remote_urls() {\n let dir = tempdir().expect(\"tempdir\");\n let path = dir.path().join(\"config\");\n fs::write(\n &path,\n r#\"\n[remote \"origin\"]\n url = git@github.com:nikivdev/flow.git\n fetch = +refs/heads/*:refs/remotes/origin/*\n[remote \"origin\"]\n url = git@github.com:nikivdev/flow.git\n[remote \"upstream\"]\n url = git@github.com:openai/codex.git\n\"#,\n )\n .expect(\"write config\");\n\n let remotes = parse_git_remotes(&path);\n assert_eq!(remotes.len(), 2);\n assert_eq!(remotes[0].0, \"origin\");\n assert_eq!(remotes[1].0, \"upstream\");\n }\n\n #[test]\n fn read_git_branch_reads_symbolic_head() {\n let dir = tempdir().expect(\"tempdir\");\n let head = dir.path().join(\"HEAD\");\n fs::write(&head, \"ref: refs/heads/main\\n\").expect(\"write head\");\n assert_eq!(read_git_branch(&head).as_deref(), Some(\"main\"));\n }\n\n #[test]\n fn resolve_git_dir_file_supports_relative_gitdir() {\n let dir = tempdir().expect(\"tempdir\");\n let repo = dir.path().join(\"repo\");\n let actual = dir.path().join(\"actual-git\");\n fs::create_dir_all(&repo).expect(\"repo dir\");\n fs::create_dir_all(&actual).expect(\"git dir\");\n let dot_git = repo.join(\".git\");\n fs::write(&dot_git, \"gitdir: ../actual-git\\n\").expect(\"write gitdir\");\n\n let resolved = resolve_git_dir_file(&dot_git).expect(\"resolve gitdir\");\n assert_eq!(resolved, actual.canonicalize().unwrap_or(actual));\n }\n\n #[test]\n fn resolve_common_git_dir_uses_commondir_when_present() {\n let dir = tempdir().expect(\"tempdir\");\n let git_dir = dir.path().join(\"git/worktrees/repo\");\n let common = dir.path().join(\"git\");\n fs::create_dir_all(&git_dir).expect(\"gitdir\");\n fs::create_dir_all(&common).expect(\"common dir\");\n fs::write(git_dir.join(\"commondir\"), \"../..\\n\").expect(\"write commondir\");\n\n let resolved = resolve_common_git_dir(&git_dir);\n assert_eq!(resolved, common.canonicalize().unwrap_or(common));\n }\n\n #[test]\n fn find_git_root_walks_up_to_repo_root() {\n let dir = tempdir().expect(\"tempdir\");\n let repo = dir.path().join(\"repo\");\n let nested = repo.join(\"a/b\");\n fs::create_dir_all(repo.join(\".git\")).expect(\"git dir\");\n fs::create_dir_all(&nested).expect(\"nested dir\");\n\n let root = find_git_root(&nested).expect(\"git root\");\n assert_eq!(root, repo);\n }\n}\n" }, { "path": "src/init.rs", "content": "use std::{\n fs,\n path::{Path, PathBuf},\n};\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::InitOpts;\n\nconst TEMPLATE: &str = r#\"version = 1\n\n[[tasks]]\nname = \"setup\"\ncommand = \"\"\ndescription = \"Project setup (fill me)\"\nshortcuts = [\"s\"]\n\n[[tasks]]\nname = \"dev\"\ncommand = \"\"\ndescription = \"Start dev server (fill me)\"\ndependencies = [\"setup\"]\nshortcuts = [\"d\"]\n\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n\n# Bun-focused optional test gate:\n#\n#[commit.testing]\n#mode = \"block\"\n#runner = \"bun\"\n#bun_repo_strict = true\n#require_related_tests = true\n#ai_scratch_test_dir = \".ai/test\"\n#run_ai_scratch_tests = true\n#allow_ai_scratch_to_satisfy_gate = false\n#max_local_gate_seconds = 20\n\"#;\n\npub(crate) fn write_template(path: &Path) -> Result<()> {\n if let Some(parent) = path.parent() {\n if !parent.as_os_str().is_empty() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create directory {}\", parent.display()))?;\n }\n }\n\n fs::write(path, TEMPLATE).with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(())\n}\n\npub fn run(opts: InitOpts) -> Result<()> {\n let target = resolve_path(opts.path);\n if target.exists() {\n bail!(\"{} already exists; refusing to overwrite\", target.display());\n }\n\n write_template(&target)?;\n println!(\"created {}\", target.display());\n Ok(())\n}\n\nfn resolve_path(path: Option<PathBuf>) -> PathBuf {\n match path {\n Some(p) if p.is_absolute() => p,\n Some(p) => std::env::current_dir()\n .unwrap_or_else(|_| PathBuf::from(\".\"))\n .join(p),\n None => std::env::current_dir()\n .unwrap_or_else(|_| PathBuf::from(\".\"))\n .join(\"flow.toml\"),\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn template_includes_codex_skill_baseline() {\n assert!(TEMPLATE.contains(\"[skills]\"));\n assert!(TEMPLATE.contains(\"install = [\\\"quality-bun-feature-delivery\\\"]\"));\n assert!(TEMPLATE.contains(\"[skills.codex]\"));\n assert!(TEMPLATE.contains(\"[commit.skill_gate]\"));\n assert!(TEMPLATE.contains(\"quality-bun-feature-delivery = 2\"));\n }\n}\n" }, { "path": "src/install.rs", "content": "use std::collections::HashMap;\nuse std::env;\nuse std::fs;\nuse std::io::{self, IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\nuse reqwest::blocking::Client;\nuse serde::Deserialize;\n\nuse crate::cli::{InstallBackend, InstallIndexOpts, InstallOpts};\nuse crate::config::FloxInstallSpec;\nuse crate::registry;\n\npub fn run(mut opts: InstallOpts) -> Result<()> {\n if opts\n .name\n .as_deref()\n .map(|name| name.trim().is_empty())\n .unwrap_or(true)\n {\n opts.backend = InstallBackend::Flox;\n opts.name = Some(prompt_flox_package()?);\n }\n\n match opts.backend {\n InstallBackend::Registry => registry::install(normalize_registry_install_opts(opts)),\n InstallBackend::Flox => install_with_flox(&opts),\n InstallBackend::Parm => install_with_parm(&opts),\n InstallBackend::Auto => install_with_auto(&opts),\n }\n}\n\nfn install_with_auto(opts: &InstallOpts) -> Result<()> {\n let mut errors: Vec<String> = Vec::new();\n\n if registry_configured(opts) {\n let registry_opts = normalize_registry_install_opts(opts.clone());\n match registry::install(registry_opts) {\n Ok(()) => return Ok(()),\n Err(err) => {\n if is_existing_destination_error(&err) {\n return Err(err);\n }\n eprintln!(\"WARN registry install failed: {err}\");\n errors.push(format!(\"registry: {err}\"));\n }\n }\n }\n\n if should_try_parm(opts) {\n match install_with_parm(opts) {\n Ok(()) => return Ok(()),\n Err(err) => {\n if is_existing_destination_error(&err) {\n return Err(err);\n }\n eprintln!(\"WARN parm install failed: {err}\");\n errors.push(format!(\"parm: {err}\"));\n }\n }\n } else if let Some(name) = opts\n .name\n .as_deref()\n .map(str::trim)\n .filter(|n| !n.is_empty())\n {\n eprintln!(\n \"INFO skipping parm fallback for '{}' (no owner/repo mapping; set FLOW_INSTALL_OWNER or pass owner/repo)\",\n name\n );\n }\n\n match install_with_flox(opts) {\n Ok(()) => Ok(()),\n Err(err) => {\n errors.push(format!(\"flox: {err}\"));\n bail!(\n \"install failed after trying auto backends:\\n- {}\",\n errors.join(\"\\n- \")\n );\n }\n }\n}\n\nfn is_existing_destination_error(err: &anyhow::Error) -> bool {\n err.to_string().contains(\"already exists\")\n}\n\npub fn run_index(opts: InstallIndexOpts) -> Result<()> {\n let flox_bin = resolve_flox_bin()?;\n let Some(config) = typesense_config_with_overrides(&opts) else {\n bail!(\"Typesense config missing (set FLOW_TYPESENSE_URL or pass --url)\");\n };\n\n let queries = load_index_queries(opts.query, opts.queries)?;\n if queries.is_empty() {\n bail!(\"no queries provided\");\n }\n\n let mut all_entries: HashMap<String, FloxDisplayEntry> = HashMap::new();\n for query in queries {\n let results = flox_search_with_aliases(&flox_bin, &query)?;\n for entry in results {\n all_entries.entry(entry.pkg_path.clone()).or_insert(entry);\n }\n }\n\n if all_entries.is_empty() {\n println!(\"No results to index.\");\n return Ok(());\n }\n\n if opts.dry_run {\n println!(\"Would index {} packages into Typesense.\", all_entries.len());\n return Ok(());\n }\n\n typesense_ensure_collection(&config)?;\n typesense_import(&config, all_entries.values().cloned().collect())?;\n println!(\"Indexed {} packages into Typesense.\", all_entries.len());\n Ok(())\n}\n\nfn registry_configured(_opts: &InstallOpts) -> bool {\n // Registry is always available — defaults to https://myflow.sh\n true\n}\n\nfn install_with_flox(opts: &InstallOpts) -> Result<()> {\n let name = opts.name.as_deref().unwrap_or(\"\").trim();\n if name.is_empty() {\n bail!(\"package name is required\");\n }\n\n let install_root = tool_root()?;\n let flox_pkg = resolve_flox_pkg_name(name);\n let spec = FloxInstallSpec {\n pkg_path: flox_pkg.to_string(),\n pkg_group: Some(\"tools\".to_string()),\n version: opts.version.clone(),\n systems: None,\n priority: None,\n };\n\n ensure_flox_tools_env(&install_root, &[(flox_pkg.to_string(), spec)])?;\n\n let bin_name = opts.bin.clone().unwrap_or_else(|| name.to_string());\n let bin_dir = opts.bin_dir.clone().unwrap_or_else(default_bin_dir);\n fs::create_dir_all(&bin_dir)\n .with_context(|| format!(\"failed to create {}\", bin_dir.display()))?;\n\n let shim_path = bin_dir.join(&bin_name);\n if shim_path.exists() && !opts.force {\n if shim_matches(&shim_path, &install_root, &bin_name).unwrap_or(false) {\n println!(\"{} already installed via flox.\", bin_name);\n return Ok(());\n }\n if prompt_overwrite(&shim_path)? {\n // continue and overwrite\n } else {\n bail!(\n \"{} already exists (use --force to overwrite or --bin to install under a different name)\",\n shim_path.display()\n );\n }\n }\n\n write_flox_shim(&shim_path, &install_root, &bin_name)?;\n\n if flox_pkg != name {\n println!(\n \"Installed {} (flox package {}) via flox (shim at {})\",\n name,\n flox_pkg,\n shim_path.display()\n );\n } else {\n println!(\n \"Installed {} via flox (shim at {})\",\n name,\n shim_path.display()\n );\n }\n if !path_in_env(&bin_dir) {\n println!(\"Add {} to PATH to use it everywhere.\", bin_dir.display());\n }\n Ok(())\n}\n\nfn install_with_parm(opts: &InstallOpts) -> Result<()> {\n let name = opts.name.as_deref().unwrap_or(\"\").trim();\n if name.is_empty() {\n bail!(\"package name is required\");\n }\n\n if !opts.bin.is_none() {\n // Parm determines which executables exist inside the release asset.\n // We keep Flow's `--bin` flag for other backends, but it doesn't map cleanly.\n eprintln!(\"Note: --bin is ignored for --backend parm\");\n }\n if opts.force {\n eprintln!(\"Note: --force is ignored for --backend parm\");\n }\n\n let bin_dir = opts.bin_dir.clone().unwrap_or_else(default_bin_dir);\n fs::create_dir_all(&bin_dir)\n .with_context(|| format!(\"failed to create {}\", bin_dir.display()))?;\n\n let owner_repo = resolve_owner_repo(name)?;\n let owner_repo = match opts\n .version\n .as_deref()\n .map(|v| v.trim())\n .filter(|v| !v.is_empty())\n {\n Some(version) => format!(\"{}@{}\", owner_repo, version),\n None => owner_repo,\n };\n\n let parm_bin = which::which(\"parm\").context(\n \"parm not found on PATH. Install it first (macOS/Linux):\\n curl -fsSL https://raw.githubusercontent.com/yhoundz/parm/master/scripts/install.sh | sh\",\n )?;\n\n // Configure parm to symlink into the same directory Flow uses for tools.\n // This makes installs predictable and avoids relying on parm defaults.\n let config_status = Command::new(&parm_bin)\n .args([\n \"config\",\n \"set\",\n &format!(\"parm_bin_path={}\", bin_dir.display()),\n ])\n .stdin(Stdio::null())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run parm config set\")?;\n if !config_status.success() {\n bail!(\"parm config set failed\");\n }\n\n let mut cmd = Command::new(&parm_bin);\n cmd.args([\"install\", &owner_repo]);\n if opts.no_verify {\n cmd.arg(\"--no-verify\");\n }\n\n if let Some(token) = resolve_github_token()? {\n cmd.env(\"PARM_GITHUB_TOKEN\", token);\n }\n\n let status = cmd\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run parm install\")?;\n if !status.success() {\n bail!(\"parm install failed\");\n }\n\n if !path_in_env(&bin_dir) {\n println!(\"Add {} to PATH to use it everywhere.\", bin_dir.display());\n }\n Ok(())\n}\n\nfn resolve_owner_repo(raw: &str) -> Result<String> {\n if raw.contains('/') {\n return Ok(raw.to_string());\n }\n\n if let Some(mapped) = known_owner_repo(raw) {\n return Ok(mapped.to_string());\n }\n\n // Prefer explicit env var; fall back to Flow personal env store.\n let owner = resolve_install_owner();\n\n let Some(owner) = owner else {\n bail!(\n \"package name '{}' is missing owner (expected owner/repo).\\nSet FLOW_INSTALL_OWNER (env or Flow personal env store), use a known alias (flow/rise), or pass owner/repo directly.\",\n raw\n );\n };\n\n Ok(format!(\"{}/{}\", owner, raw))\n}\n\nfn should_try_parm(opts: &InstallOpts) -> bool {\n let Some(name) = opts\n .name\n .as_deref()\n .map(str::trim)\n .filter(|n| !n.is_empty())\n else {\n return false;\n };\n name.contains('/') || known_owner_repo(name).is_some() || resolve_install_owner().is_some()\n}\n\nfn known_owner_repo(name: &str) -> Option<&'static str> {\n match name {\n \"f\" | \"flow\" | \"lin\" => Some(\"nikivdev/flow\"),\n \"rise\" => Some(\"nikivdev/rise\"),\n \"seq\" | \"seqd\" => Some(\"nikivdev/seq\"),\n _ => None,\n }\n}\n\nfn normalize_registry_install_opts(mut opts: InstallOpts) -> InstallOpts {\n let Some(raw) = opts.name.clone().map(|n| n.trim().to_string()) else {\n return opts;\n };\n if raw.is_empty() {\n return opts;\n }\n let (package, default_bin) = registry_alias(&raw);\n if package != raw {\n opts.name = Some(package.to_string());\n if opts.bin.is_none() {\n if let Some(bin) = default_bin {\n opts.bin = Some(bin.to_string());\n }\n }\n }\n opts\n}\n\nfn registry_alias(raw: &str) -> (&str, Option<&str>) {\n match raw {\n \"f\" => (\"flow\", Some(\"f\")),\n \"lin\" => (\"flow\", Some(\"lin\")),\n \"seqd\" => (\"seq\", Some(\"seqd\")),\n \"seq\" => (\"seq\", Some(\"seq\")),\n _ => (raw, None),\n }\n}\n\nfn resolve_install_owner() -> Option<String> {\n std::env::var(\"FLOW_INSTALL_OWNER\")\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n .or_else(|| {\n crate::env::get_personal_env_var(\"FLOW_INSTALL_OWNER\")\n .ok()\n .flatten()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n })\n}\n\nfn resolve_github_token() -> Result<Option<String>> {\n for key in [\"PARM_GITHUB_TOKEN\", \"GITHUB_TOKEN\", \"GH_TOKEN\"] {\n if let Ok(value) = std::env::var(key) {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(Some(trimmed.to_string()));\n }\n }\n }\n\n for key in [\n \"PARM_GITHUB_TOKEN\",\n \"GITHUB_TOKEN\",\n \"GH_TOKEN\",\n \"FLOW_GITHUB_TOKEN\",\n ] {\n if let Ok(Some(value)) = crate::env::get_personal_env_var(key) {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(Some(trimmed.to_string()));\n }\n }\n }\n\n Ok(None)\n}\n\nfn ensure_flox_tools_env(root: &Path, packages: &[(String, FloxInstallSpec)]) -> Result<()> {\n let flox_bin = resolve_flox_bin()?;\n\n if flox_env_ok(&flox_bin, root).is_err() {\n let flox_dir = root.join(\".flox\");\n if flox_dir.exists() {\n fs::remove_dir_all(&flox_dir)\n .with_context(|| format!(\"failed to remove {}\", flox_dir.display()))?;\n }\n }\n\n let flox_dir = root.join(\".flox\");\n if !flox_dir.exists() {\n flox_run(\n &flox_bin,\n &[\n \"init\".to_string(),\n \"--bare\".to_string(),\n \"-d\".to_string(),\n root.display().to_string(),\n ],\n )?;\n }\n\n for (name, spec) in packages {\n let pkg = match spec.version.as_deref() {\n Some(version) if !version.trim().is_empty() => format!(\"{name}@{version}\"),\n _ => name.to_string(),\n };\n flox_run(\n &flox_bin,\n &[\n \"install\".to_string(),\n \"-d\".to_string(),\n root.display().to_string(),\n pkg,\n ],\n )?;\n }\n\n if let Err(err) = flox_env_ok(&flox_bin, root) {\n bail!(\"flox env still invalid after reset: {err}\");\n }\n Ok(())\n}\n\nfn resolve_flox_bin() -> Result<PathBuf> {\n if let Ok(path) = env::var(\"FLOX_BIN\") {\n let bin = PathBuf::from(path);\n if bin.exists() {\n return Ok(bin);\n }\n }\n if let Ok(path) = which::which(\"flox\") {\n return Ok(path);\n }\n bail!(\"flox not found on PATH\")\n}\n\nfn flox_run(flox_bin: &Path, args: &[String]) -> Result<()> {\n let status = std::process::Command::new(flox_bin)\n .args(args)\n .status()\n .with_context(|| format!(\"failed to run flox {}\", args.join(\" \")))?;\n if !status.success() {\n bail!(\"flox {} failed\", args.join(\" \"));\n }\n Ok(())\n}\n\nfn flox_env_ok(flox_bin: &Path, root: &Path) -> Result<()> {\n let output = std::process::Command::new(flox_bin)\n .arg(\"activate\")\n .arg(\"-d\")\n .arg(root)\n .arg(\"--\")\n .arg(\"/bin/sh\")\n .arg(\"-c\")\n .arg(\"true\")\n .output()\n .context(\"failed to run flox activate\")?;\n if output.status.success() {\n return Ok(());\n }\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"{}\", stderr.trim());\n}\n\nfn resolve_flox_pkg_name(name: &str) -> &str {\n match name {\n \"jj\" => \"jujutsu\",\n _ => name,\n }\n}\n\nfn prompt_flox_package() -> Result<String> {\n if !io::stdin().is_terminal() {\n bail!(\"package name is required (interactive search needs a TTY)\");\n }\n\n if which::which(\"fzf\").is_err() {\n return prompt_line(\"Package name\", None);\n }\n\n let query = prompt_line(\"Search flox for\", None)?;\n let query = query.trim();\n if query.is_empty() {\n bail!(\"package name is required\");\n }\n\n let entries = match typesense_config() {\n Some(config) => match typesense_search(&config, query) {\n Ok(entries) if !entries.is_empty() => entries,\n Ok(_) => {\n let flox_bin = resolve_flox_bin()?;\n flox_search_with_aliases(&flox_bin, query)?\n }\n Err(err) => {\n eprintln!(\"WARN typesense search failed: {err}\");\n let flox_bin = resolve_flox_bin()?;\n flox_search_with_aliases(&flox_bin, query)?\n }\n },\n None => {\n let flox_bin = resolve_flox_bin()?;\n flox_search_with_aliases(&flox_bin, query)?\n }\n };\n if entries.is_empty() {\n bail!(\"no flox packages found for \\\"{}\\\"\", query);\n }\n\n let mut input = String::new();\n for entry in &entries {\n let version = entry.version.as_deref().unwrap_or(\"-\");\n let desc = entry\n .description\n .as_deref()\n .filter(|d| !d.trim().is_empty())\n .unwrap_or(\"No description\");\n let alias_note = entry\n .alias\n .as_deref()\n .map(|alias| format!(\" (alias for {})\", alias))\n .unwrap_or_default();\n input.push_str(&format!(\n \"{}\\t{}\\t{}{}\\n\",\n entry.pkg_path, version, desc, alias_note\n ));\n }\n\n let mut child = std::process::Command::new(\"fzf\")\n .args([\n \"--height=50%\",\n \"--reverse\",\n \"--delimiter=\\t\",\n \"--with-nth=1,3\",\n \"--prompt=flox> \",\n \"--preview=echo Version: {2}\\\\n\\\\n{3}\",\n \"--preview-window=right,60%,wrap\",\n ])\n .stdin(std::process::Stdio::piped())\n .stdout(std::process::Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n child\n .stdin\n .as_mut()\n .context(\"failed to open fzf stdin\")?\n .write_all(input.as_bytes())?;\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n bail!(\"no package selected\");\n }\n\n let selection = String::from_utf8(output.stdout).context(\"fzf output was not valid UTF-8\")?;\n let selected = selection.trim().split('\\t').next().unwrap_or(\"\");\n if selected.is_empty() {\n bail!(\"no package selected\");\n }\n Ok(selected.to_string())\n}\n\n#[derive(Clone, Debug, Deserialize)]\nstruct FloxSearchEntry {\n #[serde(rename = \"pkg_path\")]\n pkg_path: String,\n description: Option<String>,\n version: Option<String>,\n}\n\n#[derive(Clone, Debug)]\nstruct FloxDisplayEntry {\n pkg_path: String,\n description: Option<String>,\n version: Option<String>,\n alias: Option<String>,\n}\n\n#[derive(Clone, Debug)]\nstruct TypesenseConfig {\n url: String,\n api_key: String,\n collection: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct TypesenseSearchResponse {\n hits: Vec<TypesenseHit>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct TypesenseHit {\n document: TypesenseDoc,\n}\n\n#[derive(Debug, Deserialize)]\nstruct TypesenseDoc {\n #[serde(rename = \"pkg_path\")]\n pkg_path: String,\n description: Option<String>,\n version: Option<String>,\n}\n\nfn typesense_config() -> Option<TypesenseConfig> {\n let url = env::var(\"FLOW_TYPESENSE_URL\").ok()?;\n let api_key = env::var(\"FLOW_TYPESENSE_API_KEY\").unwrap_or_default();\n let collection =\n env::var(\"FLOW_TYPESENSE_COLLECTION\").unwrap_or_else(|_| \"flox-packages\".to_string());\n Some(TypesenseConfig {\n url,\n api_key,\n collection,\n })\n}\n\nfn typesense_config_with_overrides(opts: &InstallIndexOpts) -> Option<TypesenseConfig> {\n let url = opts\n .url\n .clone()\n .or_else(|| env::var(\"FLOW_TYPESENSE_URL\").ok())?;\n let api_key = opts\n .api_key\n .clone()\n .or_else(|| env::var(\"FLOW_TYPESENSE_API_KEY\").ok())\n .unwrap_or_default();\n let collection = opts.collection.clone();\n Some(TypesenseConfig {\n url,\n api_key,\n collection,\n })\n}\n\nfn typesense_search(config: &TypesenseConfig, query: &str) -> Result<Vec<FloxDisplayEntry>> {\n let client = Client::builder()\n .timeout(std::time::Duration::from_secs(5))\n .build()?;\n let url = format!(\n \"{}/collections/{}/documents/search\",\n config.url.trim_end_matches('/'),\n config.collection\n );\n let payload = serde_json::json!({\n \"q\": query,\n \"query_by\": \"pkg_path,description\",\n \"per_page\": 200,\n });\n let mut request = client.post(url).json(&payload);\n if !config.api_key.is_empty() {\n request = request.header(\"X-TYPESENSE-API-KEY\", &config.api_key);\n }\n let response = request.send().context(\"failed to query typesense\")?;\n if !response.status().is_success() {\n bail!(\"typesense returned {}\", response.status());\n }\n let body: TypesenseSearchResponse = response\n .json()\n .context(\"failed to parse typesense response\")?;\n let mut entries = Vec::new();\n for hit in body.hits {\n entries.push(FloxDisplayEntry {\n pkg_path: hit.document.pkg_path,\n description: hit.document.description,\n version: hit.document.version,\n alias: None,\n });\n }\n Ok(entries)\n}\n\nfn typesense_ensure_collection(config: &TypesenseConfig) -> Result<()> {\n let client = Client::builder()\n .timeout(std::time::Duration::from_secs(5))\n .build()?;\n let base = config.url.trim_end_matches('/');\n let get_url = format!(\"{}/collections/{}\", base, config.collection);\n let mut request = client.get(&get_url);\n if !config.api_key.is_empty() {\n request = request.header(\"X-TYPESENSE-API-KEY\", &config.api_key);\n }\n let resp = request\n .send()\n .context(\"failed to check typesense collection\")?;\n if resp.status().is_success() {\n return Ok(());\n }\n if resp.status().as_u16() != 404 {\n bail!(\"typesense collection check failed ({})\", resp.status());\n }\n\n let create_url = format!(\"{}/collections\", base);\n let schema = serde_json::json!({\n \"name\": config.collection,\n \"fields\": [\n { \"name\": \"id\", \"type\": \"string\" },\n { \"name\": \"pkg_path\", \"type\": \"string\" },\n { \"name\": \"description\", \"type\": \"string\", \"optional\": true },\n { \"name\": \"version\", \"type\": \"string\", \"optional\": true }\n ],\n \"default_sorting_field\": \"pkg_path\"\n });\n let mut create_req = client.post(&create_url).json(&schema);\n if !config.api_key.is_empty() {\n create_req = create_req.header(\"X-TYPESENSE-API-KEY\", &config.api_key);\n }\n let resp = create_req\n .send()\n .context(\"failed to create typesense collection\")?;\n if !resp.status().is_success() {\n bail!(\"typesense collection create failed ({})\", resp.status());\n }\n Ok(())\n}\n\nfn typesense_import(config: &TypesenseConfig, entries: Vec<FloxDisplayEntry>) -> Result<()> {\n let client = Client::builder()\n .timeout(std::time::Duration::from_secs(20))\n .build()?;\n let base = config.url.trim_end_matches('/');\n let url = format!(\n \"{}/collections/{}/documents/import?action=upsert\",\n base, config.collection\n );\n let mut body = String::new();\n for entry in entries {\n let doc = serde_json::json!({\n \"id\": entry.pkg_path,\n \"pkg_path\": entry.pkg_path,\n \"description\": entry.description,\n \"version\": entry.version\n });\n body.push_str(&doc.to_string());\n body.push('\\n');\n }\n let mut request = client.post(&url).body(body);\n if !config.api_key.is_empty() {\n request = request.header(\"X-TYPESENSE-API-KEY\", &config.api_key);\n }\n let resp = request.send().context(\"failed to import into typesense\")?;\n if !resp.status().is_success() {\n bail!(\"typesense import failed ({})\", resp.status());\n }\n Ok(())\n}\n\nfn load_index_queries(query: Option<String>, path: Option<PathBuf>) -> Result<Vec<String>> {\n let mut out = Vec::new();\n if let Some(path) = path {\n let content = fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n for line in content.lines() {\n let trimmed = line.trim();\n if trimmed.is_empty() || trimmed.starts_with('#') {\n continue;\n }\n out.push(trimmed.to_string());\n }\n }\n if let Some(query) = query {\n let trimmed = query.trim();\n if !trimmed.is_empty() {\n out.push(trimmed.to_string());\n }\n }\n if out.is_empty() && io::stdin().is_terminal() {\n let input = prompt_line(\"Search term to index\", None)?;\n let trimmed = input.trim();\n if !trimmed.is_empty() {\n out.push(trimmed.to_string());\n }\n }\n Ok(out)\n}\n\nfn flox_search_with_aliases(flox_bin: &Path, query: &str) -> Result<Vec<FloxDisplayEntry>> {\n let mut seen = HashMap::<String, FloxDisplayEntry>::new();\n\n let mut queries = vec![query.to_string()];\n if let Some(extra) = flox_query_aliases(query) {\n queries.extend(extra.iter().map(|q| q.to_string()));\n }\n\n for q in queries {\n let results = flox_search(flox_bin, &q)?;\n for result in results {\n let entry = FloxDisplayEntry {\n pkg_path: result.pkg_path.clone(),\n description: result.description.clone(),\n version: result.version.clone(),\n alias: None,\n };\n seen.entry(result.pkg_path).or_insert(entry);\n }\n }\n\n if let Some(alias_targets) = flox_query_aliases(query) {\n for alias_target in alias_targets {\n let alias_results = flox_search(flox_bin, alias_target)?;\n let picked = alias_results\n .iter()\n .find(|entry| entry.pkg_path == *alias_target)\n .or_else(|| alias_results.first());\n if let Some(result) = picked {\n seen.insert(\n result.pkg_path.clone(),\n FloxDisplayEntry {\n pkg_path: result.pkg_path.clone(),\n description: result.description.clone(),\n version: result.version.clone(),\n alias: Some(query.to_string()),\n },\n );\n }\n }\n }\n\n let mut entries: Vec<_> = seen.into_values().collect();\n entries.sort_by(|a, b| flox_entry_rank(a, query).cmp(&flox_entry_rank(b, query)));\n Ok(entries)\n}\n\nfn flox_query_aliases(query: &str) -> Option<&'static [&'static str]> {\n match query {\n \"jj\" => Some(&[\"jujutsu\"]),\n _ => None,\n }\n}\n\nfn flox_entry_rank(entry: &FloxDisplayEntry, query: &str) -> (u8, String) {\n if entry.pkg_path == query {\n return (0, entry.pkg_path.clone());\n }\n if entry.alias.is_some() {\n return (1, entry.pkg_path.clone());\n }\n if entry\n .description\n .as_deref()\n .map(|d| d.to_ascii_lowercase().contains(&query.to_ascii_lowercase()))\n .unwrap_or(false)\n {\n return (2, entry.pkg_path.clone());\n }\n (3, entry.pkg_path.clone())\n}\n\nfn flox_search(flox_bin: &Path, query: &str) -> Result<Vec<FloxSearchEntry>> {\n let output = std::process::Command::new(flox_bin)\n .arg(\"search\")\n .arg(\"--json\")\n .arg(\"-a\")\n .arg(query)\n .output()\n .with_context(|| format!(\"failed to run flox search {}\", query))?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"flox search failed: {}\", stderr.trim());\n }\n let stdout =\n String::from_utf8(output.stdout).context(\"flox search output was not valid UTF-8\")?;\n let entries: Vec<FloxSearchEntry> = serde_json::from_str(&stdout)\n .with_context(|| format!(\"failed to parse flox search output for {}\", query))?;\n Ok(entries)\n}\n\nfn prompt_line(message: &str, default: Option<&str>) -> Result<String> {\n if let Some(default) = default {\n print!(\"{message} [{default}]: \");\n } else {\n print!(\"{message}: \");\n }\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n return Ok(default.unwrap_or(\"\").to_string());\n }\n Ok(trimmed.to_string())\n}\n\nfn tool_root() -> Result<PathBuf> {\n let home = dirs::home_dir().context(\"failed to resolve home directory\")?;\n Ok(home.join(\".config\").join(\"flow\").join(\"tools\"))\n}\n\nfn write_flox_shim(dest: &Path, env_root: &Path, bin: &str) -> Result<()> {\n let script = format!(\n \"#!/bin/sh\\nexec flox activate -d \\\"{}\\\" -- \\\"{}\\\" \\\"$@\\\"\\n\",\n env_root.display(),\n bin\n );\n fs::write(dest, script).with_context(|| format!(\"failed to write {}\", dest.display()))?;\n #[cfg(unix)]\n {\n use std::os::unix::fs::PermissionsExt;\n let mut perms = fs::metadata(dest)?.permissions();\n perms.set_mode(0o755);\n fs::set_permissions(dest, perms)?;\n }\n Ok(())\n}\n\nfn shim_matches(dest: &Path, env_root: &Path, bin: &str) -> Result<bool> {\n let content =\n fs::read_to_string(dest).with_context(|| format!(\"failed to read {}\", dest.display()))?;\n let expected = format!(\n \"#!/bin/sh\\nexec flox activate -d \\\"{}\\\" -- \\\"{}\\\" \\\"$@\\\"\\n\",\n env_root.display(),\n bin\n );\n Ok(content == expected)\n}\n\nfn prompt_overwrite(path: &Path) -> Result<bool> {\n if !io::stdin().is_terminal() {\n return Ok(false);\n }\n print!(\"{} already exists. Overwrite? [y/N]: \", path.display());\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n Ok(answer == \"y\" || answer == \"yes\")\n}\n\nfn default_bin_dir() -> PathBuf {\n let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from(\".\"));\n let local = home.join(\".local\").join(\"bin\");\n if local.exists() {\n return local;\n }\n let bin = home.join(\"bin\");\n if bin.exists() {\n return bin;\n }\n local\n}\n\nfn path_in_env(bin_dir: &Path) -> bool {\n let Ok(path) = env::var(\"PATH\") else {\n return false;\n };\n env::split_paths(&path).any(|entry| entry == bin_dir)\n}\n" }, { "path": "src/invariants.rs", "content": "//! Standalone invariant checking for projects.\n//!\n//! Reads [invariants] from flow.toml and checks the working tree or staged diff.\n\nuse std::fs;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result};\n\nuse crate::config::{self, InvariantsConfig};\n\n/// A single invariant finding.\n#[derive(Debug)]\npub struct Finding {\n pub severity: String,\n pub category: String,\n pub message: String,\n pub file: Option<String>,\n}\n\n/// Result of running invariant checks.\n#[derive(Debug)]\npub struct Report {\n pub findings: Vec<Finding>,\n pub invariants_loaded: bool,\n pub mode: String,\n}\n\n/// Check project invariants against the working tree.\n/// If `staged_only` is true, checks only staged (cached) diff.\npub fn check(root: &Path, staged_only: bool) -> Result<Report> {\n let cfg = config::load_or_default(root.join(\"flow.toml\"));\n let Some(inv) = cfg.invariants else {\n println!(\"No [invariants] section in flow.toml\");\n return Ok(Report {\n findings: Vec::new(),\n invariants_loaded: false,\n mode: \"off\".to_string(),\n });\n };\n let mode = inv.mode.as_deref().unwrap_or(\"warn\").to_ascii_lowercase();\n if mode == \"off\" {\n println!(\"Invariants are disabled (mode=off).\");\n return Ok(Report {\n findings: Vec::new(),\n invariants_loaded: true,\n mode,\n });\n }\n\n let mut findings = Vec::new();\n\n // Get diff.\n let diff_args = if staged_only {\n vec![\"diff\", \"--cached\"]\n } else {\n vec![\"diff\", \"HEAD\"]\n };\n let diff = git_capture(root, &diff_args).unwrap_or_default();\n let changed_files = changed_files_from_diff(&diff);\n\n // 1. Forbidden patterns in diff.\n check_forbidden_patterns(&inv, &diff, &mut findings);\n\n // 2. Dependency policy.\n if let Some(deps_config) = &inv.deps {\n let policy = deps_config.policy.as_deref().unwrap_or(\"approval_required\");\n if policy == \"approval_required\" && !deps_config.approved.is_empty() {\n check_deps(root, &changed_files, &deps_config.approved, &mut findings);\n }\n }\n\n // 3. File size limits.\n if let Some(files_config) = &inv.files {\n if let Some(max_lines) = files_config.max_lines {\n check_file_sizes(root, &changed_files, max_lines, &mut findings);\n }\n }\n\n // Print results.\n print_report(&inv, &findings);\n\n let has_blocking = findings\n .iter()\n .any(|f| f.severity == \"critical\" || f.severity == \"warning\");\n if mode == \"block\" && has_blocking {\n anyhow::bail!(\n \"Invariant violations found (mode=block): {} finding(s)\",\n findings.len()\n );\n }\n\n Ok(Report {\n findings,\n invariants_loaded: true,\n mode,\n })\n}\n\nfn check_forbidden_patterns(inv: &InvariantsConfig, diff: &str, findings: &mut Vec<Finding>) {\n // Skip flow.toml itself — it contains the forbidden list definitions.\n let skip_files = [\"flow.toml\"];\n\n for pattern in &inv.forbidden {\n let pat_lower = pattern.to_lowercase();\n let mut current_file: Option<String> = None;\n let mut skip_current = false;\n for line in diff.lines() {\n if line.starts_with(\"+++ b/\") {\n let file = line\n .strip_prefix(\"+++ b/\")\n .unwrap_or(\"\")\n .trim()\n .trim_matches('\"');\n current_file = Some(file.to_string());\n skip_current = skip_files.iter().any(|s| file.ends_with(s));\n continue;\n }\n if current_file\n .as_deref()\n .is_some_and(|f| f.trim().trim_matches('\"').ends_with(\"flow.toml\"))\n {\n continue;\n }\n if skip_current {\n continue;\n }\n if !line.starts_with('+') || line.starts_with(\"+++\") {\n continue;\n }\n if line.to_lowercase().contains(&pat_lower) {\n findings.push(Finding {\n severity: \"warning\".to_string(),\n category: \"forbidden\".to_string(),\n message: format!(\"Forbidden pattern '{}' found\", pattern),\n file: current_file.clone(),\n });\n break;\n }\n }\n }\n}\n\nfn check_deps(\n root: &Path,\n changed_files: &[String],\n approved: &[String],\n findings: &mut Vec<Finding>,\n) {\n // Check all package.json files in repo, not just changed ones.\n let pkg_files: Vec<PathBuf> = if changed_files.iter().any(|f| f.ends_with(\"package.json\")) {\n changed_files\n .iter()\n .filter(|f| f.ends_with(\"package.json\"))\n .map(|f| root.join(f))\n .collect()\n } else {\n // Also check existing package.json for a full health scan.\n find_package_jsons(root)\n };\n\n for pkg_path in pkg_files {\n let Ok(contents) = fs::read_to_string(&pkg_path) else {\n continue;\n };\n let rel = pkg_path\n .strip_prefix(root)\n .unwrap_or(&pkg_path)\n .display()\n .to_string();\n check_unapproved_deps(&contents, approved, &rel, findings);\n }\n}\n\nfn check_unapproved_deps(\n package_json: &str,\n approved: &[String],\n file_path: &str,\n findings: &mut Vec<Finding>,\n) {\n let Ok(parsed) = serde_json::from_str::<serde_json::Value>(package_json) else {\n return;\n };\n\n let dep_sections = [\"dependencies\", \"devDependencies\", \"peerDependencies\"];\n for section in &dep_sections {\n if let Some(deps) = parsed.get(section).and_then(|v| v.as_object()) {\n for dep_name in deps.keys() {\n if !approved.iter().any(|a| a == dep_name) {\n findings.push(Finding {\n severity: \"warning\".to_string(),\n category: \"deps\".to_string(),\n message: format!(\"'{}' ({}) not on approved list\", dep_name, section),\n file: Some(file_path.to_string()),\n });\n }\n }\n }\n }\n}\n\nfn check_file_sizes(\n root: &Path,\n changed_files: &[String],\n max_lines: u32,\n findings: &mut Vec<Finding>,\n) {\n for file in changed_files {\n let full = root.join(file);\n if let Ok(contents) = fs::read_to_string(&full) {\n let line_count = contents.lines().count() as u32;\n if line_count > max_lines {\n findings.push(Finding {\n severity: \"warning\".to_string(),\n category: \"files\".to_string(),\n message: format!(\"{} lines (max {})\", line_count, max_lines),\n file: Some(file.clone()),\n });\n }\n }\n }\n}\n\nfn find_package_jsons(root: &Path) -> Vec<PathBuf> {\n let mut result = Vec::new();\n let root_pkg = root.join(\"package.json\");\n if root_pkg.exists() {\n result.push(root_pkg);\n }\n // Check common subdirs.\n for subdir in &[\"api/ts\", \"web\", \"packages\"] {\n let pkg = root.join(subdir).join(\"package.json\");\n if pkg.exists() {\n result.push(pkg);\n }\n }\n result\n}\n\nfn print_report(inv: &InvariantsConfig, findings: &[Finding]) {\n println!(\"Invariants loaded from flow.toml\\n\");\n\n if let Some(style) = inv.architecture_style.as_deref() {\n println!(\" Architecture: {}\", style);\n }\n if !inv.non_negotiable.is_empty() {\n println!(\" Non-negotiable rules: {}\", inv.non_negotiable.len());\n }\n if !inv.forbidden.is_empty() {\n println!(\" Forbidden patterns: {}\", inv.forbidden.len());\n }\n if !inv.terminology.is_empty() {\n println!(\" Terminology terms: {}\", inv.terminology.len());\n }\n if let Some(deps) = &inv.deps {\n println!(\" Approved deps: {}\", deps.approved.len());\n }\n if let Some(files) = &inv.files {\n if let Some(max) = files.max_lines {\n println!(\" Max lines per file: {}\", max);\n }\n }\n\n println!();\n\n if findings.is_empty() {\n println!(\"No findings.\");\n return;\n }\n\n let warnings = findings.iter().filter(|f| f.severity == \"warning\").count();\n let notes = findings.iter().filter(|f| f.severity == \"note\").count();\n let criticals = findings.iter().filter(|f| f.severity == \"critical\").count();\n\n println!(\n \"Findings: {} critical, {} warning, {} note\\n\",\n criticals, warnings, notes\n );\n\n for f in findings {\n let icon = match f.severity.as_str() {\n \"critical\" => \"!!\",\n \"warning\" => \"!\",\n _ => \"i\",\n };\n let loc = f.file.as_deref().unwrap_or(\"(repo)\");\n println!(\" [{}:{}] {} — {}\", icon, f.category, loc, f.message);\n }\n}\n\nfn changed_files_from_diff(diff: &str) -> Vec<String> {\n let mut files = Vec::new();\n for line in diff.lines() {\n if let Some(path) = line.strip_prefix(\"+++ b/\") {\n if path != \"/dev/null\" {\n files.push(path.to_string());\n }\n }\n }\n files.sort();\n files.dedup();\n files\n}\n\nfn git_capture(workdir: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"git\")\n .current_dir(workdir)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use std::collections::HashMap;\n\n #[test]\n fn forbidden_scan_ignores_flow_toml_lines() {\n let inv = InvariantsConfig {\n forbidden: vec![\"useState(\".to_string()],\n terminology: HashMap::new(),\n ..Default::default()\n };\n let diff = r#\"diff --git a/flow.toml b/flow.toml\n+++ b/flow.toml\n+forbidden = [\"useState(\"]\ndiff --git a/web/app.tsx b/web/app.tsx\n+++ b/web/app.tsx\n+const x = useState(0)\n\"#;\n\n let mut findings = Vec::new();\n check_forbidden_patterns(&inv, diff, &mut findings);\n\n assert_eq!(findings.len(), 1);\n assert_eq!(findings[0].file.as_deref(), Some(\"web/app.tsx\"));\n }\n\n #[test]\n fn dep_scan_marks_unapproved_as_warning() {\n let pkg = r#\"{\n \"dependencies\": { \"react\": \"^18.0.0\", \"@reatom/core\": \"^3.0.0\" }\n }\"#;\n let approved = vec![\"@reatom/core\".to_string()];\n let mut findings = Vec::new();\n\n check_unapproved_deps(pkg, &approved, \"package.json\", &mut findings);\n\n assert_eq!(findings.len(), 1);\n assert_eq!(findings[0].severity, \"warning\");\n assert!(findings[0].message.contains(\"react\"));\n }\n}\n" }, { "path": "src/jazz_state.rs", "content": "use std::fs;\nuse std::path::{Path, PathBuf};\nuse std::sync::{Arc, Mutex, OnceLock};\nuse std::thread;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result};\nuse futures::executor::block_on;\nuse groove::ObjectId;\nuse groove::sql::{Database, DatabaseError};\nuse groove_rocksdb::RocksEnvironment;\n\nuse crate::{config, history::InvocationRecord};\n\nconst CATALOG_ID_FILE: &str = \"catalog.id\";\nconst DEFAULT_DB_DIR: &str = \".config/flow/jazz2\";\nconst DEFAULT_REPO_ROOT: &str = \"~/repos/garden-co/jazz2\";\nconst OUTPUT_LIMIT: usize = 80_000;\n\nstatic DB: OnceLock<Mutex<Option<Database>>> = OnceLock::new();\n\npub fn record_task_run(record: &InvocationRecord) -> Result<()> {\n if env_flag(\"FLOW_JAZZ2_DISABLE\") {\n return Ok(());\n }\n\n if let Err(err) = with_db(|db| {\n ensure_schema(db).context(\"ensure jazz2 schema\")?;\n insert_task_run(db, record).context(\"insert task run\")?;\n Ok(())\n }) {\n if is_lock_error(&err) {\n return Ok(());\n }\n return Err(err);\n }\n Ok(())\n}\n\nfn with_db<F>(op: F) -> Result<()>\nwhere\n F: FnOnce(&Database) -> Result<()>,\n{\n let mutex = DB.get_or_init(|| Mutex::new(None));\n let mut guard = mutex.lock().expect(\"jazz2 db mutex poisoned\");\n if guard.is_none() {\n *guard = Some(open_db_with_retry().context(\"open jazz2 state db\")?);\n }\n let db = guard.as_ref().expect(\"jazz2 db missing after init\");\n op(db)\n}\n\nfn env_flag(name: &str) -> bool {\n std::env::var(name)\n .ok()\n .map(|value| {\n matches!(\n value.trim().to_ascii_lowercase().as_str(),\n \"1\" | \"true\" | \"yes\" | \"on\"\n )\n })\n .unwrap_or(false)\n}\n\nfn open_db() -> Result<Database> {\n use groove::Environment;\n\n let path = state_dir();\n fs::create_dir_all(&path).with_context(|| format!(\"create jazz2 dir {}\", path.display()))?;\n\n let env: Arc<dyn Environment> =\n Arc::new(RocksEnvironment::open(&path).context(\"open rocksdb env\")?);\n if let Some(catalog_id) = load_catalog_id(&path)? {\n if let Ok(db) = block_on(Database::from_env(Arc::clone(&env), catalog_id)) {\n return Ok(db);\n }\n }\n\n let db = Database::new(env);\n save_catalog_id(&path, db.catalog_object_id())?;\n Ok(db)\n}\n\nfn open_db_with_retry() -> Result<Database> {\n let mut last_err: Option<anyhow::Error> = None;\n for _ in 0..3 {\n match open_db() {\n Ok(db) => return Ok(db),\n Err(err) => {\n last_err = Some(err);\n thread::sleep(Duration::from_millis(60));\n }\n }\n }\n Err(last_err.unwrap_or_else(|| anyhow::anyhow!(\"open jazz2 failed\")))\n}\n\nfn is_lock_error(err: &anyhow::Error) -> bool {\n err.chain().any(|cause| {\n let msg = cause.to_string().to_lowercase();\n msg.contains(\"lock\") || msg.contains(\"resource temporarily unavailable\")\n })\n}\n\npub fn state_dir() -> PathBuf {\n if let Ok(path) = std::env::var(\"FLOW_JAZZ2_PATH\") {\n return config::expand_path(&path);\n }\n let repo_root = config::expand_path(DEFAULT_REPO_ROOT);\n if repo_root.exists() {\n return repo_root.join(\".jazz2\");\n }\n std::env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(DEFAULT_DB_DIR)\n}\n\nfn load_catalog_id(base: &Path) -> Result<Option<ObjectId>> {\n let path = base.join(CATALOG_ID_FILE);\n if !path.exists() {\n return Ok(None);\n }\n let contents = fs::read_to_string(&path).with_context(|| format!(\"read {}\", path.display()))?;\n let trimmed = contents.trim();\n if trimmed.is_empty() {\n return Ok(None);\n }\n let id = trimmed\n .parse::<ObjectId>()\n .with_context(|| format!(\"parse catalog id {}\", trimmed))?;\n Ok(Some(id))\n}\n\nfn save_catalog_id(base: &Path, id: ObjectId) -> Result<()> {\n let path = base.join(CATALOG_ID_FILE);\n fs::write(&path, id.to_string()).with_context(|| format!(\"write {}\", path.display()))\n}\n\nfn ensure_schema(db: &Database) -> Result<()> {\n let sql = r#\"\n CREATE TABLE flow_task_runs (\n project_root STRING NOT NULL,\n project_name STRING,\n config_path STRING NOT NULL,\n task STRING NOT NULL,\n command STRING NOT NULL,\n user_input STRING NOT NULL,\n success BOOL NOT NULL,\n status I64,\n duration_ms I64 NOT NULL,\n timestamp_ms I64 NOT NULL,\n flow_version STRING NOT NULL,\n used_flox BOOL NOT NULL,\n output STRING NOT NULL\n )\n \"#;\n\n match db.execute(sql) {\n Ok(_) => Ok(()),\n Err(DatabaseError::TableExists(_)) => Ok(()),\n Err(err) => Err(anyhow::anyhow!(\"create table failed: {:?}\", err)),\n }\n}\n\nfn insert_task_run(db: &Database, record: &InvocationRecord) -> Result<()> {\n let status = record\n .status\n .map(|value| value.to_string())\n .unwrap_or_else(|| \"NULL\".to_string());\n let duration_ms = record.duration_ms.min(i64::MAX as u128) as i64;\n let timestamp_ms = record.timestamp_ms.min(i64::MAX as u128) as i64;\n let project_name = record\n .project_name\n .as_ref()\n .map(|value| format!(\"'{}'\", sql_escape(value)))\n .unwrap_or_else(|| \"NULL\".to_string());\n let output = truncate_output(&record.output, OUTPUT_LIMIT);\n\n let sql = format!(\n \"INSERT INTO flow_task_runs \\\n (project_root, project_name, config_path, task, command, user_input, success, status, \\\n duration_ms, timestamp_ms, flow_version, used_flox, output) \\\n VALUES ('{}', {}, '{}', '{}', '{}', '{}', {}, {}, {}, {}, '{}', {}, '{}')\",\n sql_escape(&record.project_root),\n project_name,\n sql_escape(&record.config_path),\n sql_escape(&record.task_name),\n sql_escape(&record.command),\n sql_escape(&record.user_input),\n if record.success { \"true\" } else { \"false\" },\n status,\n duration_ms,\n timestamp_ms,\n sql_escape(&record.flow_version),\n if record.used_flox { \"true\" } else { \"false\" },\n sql_escape(&output),\n );\n\n db.execute(&sql)\n .map(|_| ())\n .map_err(|err| anyhow::anyhow!(\"insert failed: {:?}\", err))\n}\n\nfn sql_escape(value: &str) -> String {\n // Replace single quotes with backticks since groove SQL doesn't handle '' escaping well\n // Also remove null bytes\n value.replace('\\'', \"`\").replace('\\0', \"\")\n}\n\nfn truncate_output(value: &str, limit: usize) -> String {\n if value.len() <= limit {\n return value.to_string();\n }\n\n let mut start = value.len() - limit;\n while start < value.len() && !value.is_char_boundary(start) {\n start += 1;\n }\n\n let mut truncated = String::from(\"... \");\n truncated.push_str(&value[start..]);\n truncated\n}\n" }, { "path": "src/jazz_state_stub.rs", "content": "use anyhow::Result;\n\nuse crate::base_tool;\nuse crate::config;\nuse crate::history::InvocationRecord;\n\nconst DEFAULT_DB_DIR: &str = \".config/flow/jazz2\";\nconst DEFAULT_REPO_ROOT: &str = \"~/repos/garden-co/jazz2\";\n\npub fn record_task_run(record: &InvocationRecord) -> Result<()> {\n // Best-effort: never fail the parent task run if base isn't installed or errors out.\n let Some(bin) = base_tool::resolve_bin() else {\n return Ok(());\n };\n\n let Ok(payload) = serde_json::to_string(record) else {\n return Ok(());\n };\n\n let args: Vec<String> = vec![\"ingest\".to_string(), \"task-run\".to_string()];\n let _ = base_tool::run_with_stdin(&bin, &args, &payload);\n Ok(())\n}\n\npub fn state_dir() -> std::path::PathBuf {\n if let Ok(path) = std::env::var(\"FLOW_JAZZ2_PATH\") {\n return config::expand_path(&path);\n }\n let repo_root = config::expand_path(DEFAULT_REPO_ROOT);\n if repo_root.exists() {\n return repo_root.join(\".jazz2\");\n }\n std::env::var_os(\"HOME\")\n .map(std::path::PathBuf::from)\n .unwrap_or_else(|| std::path::PathBuf::from(\".\"))\n .join(DEFAULT_DB_DIR)\n}\n" }, { "path": "src/jj.rs", "content": "use std::collections::HashSet;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::{\n JjAction, JjBookmarkAction, JjCommand, JjPushOpts, JjRebaseOpts, JjStatusOpts, JjSyncOpts,\n JjWorkspaceAction,\n};\nuse crate::config;\nuse crate::vcs;\n\nstruct JjContext {\n workspace_root: PathBuf,\n repo_root: PathBuf,\n}\n\npub fn run(cmd: JjCommand) -> Result<()> {\n match cmd\n .action\n .unwrap_or(JjAction::Status(JjStatusOpts::default()))\n {\n JjAction::Init { path } => run_init(path),\n JjAction::Status(opts) => run_status(opts),\n JjAction::Fetch => run_fetch(),\n JjAction::Rebase(opts) => run_rebase(opts),\n JjAction::Push(opts) => run_push(opts),\n JjAction::Sync(opts) => run_sync(opts),\n JjAction::Workspace(action) => run_workspace(action),\n JjAction::Bookmark(action) => run_bookmark(action),\n }\n}\n\npub fn run_workflow_status(raw: bool) -> Result<()> {\n run_status(JjStatusOpts { raw })\n}\n\nfn run_init(path: Option<PathBuf>) -> Result<()> {\n vcs::ensure_jj_installed()?;\n let root = path.unwrap_or(std::env::current_dir().context(\"failed to read current dir\")?);\n let root = root.canonicalize().unwrap_or(root);\n\n if is_jj_repo(&root) {\n println!(\"JJ already initialized at {}\", root.display());\n return Ok(());\n }\n\n let has_git = root.join(\".git\").exists();\n if has_git {\n jj_run_in(&root, &[\"git\", \"init\", \"--colocate\"])?;\n } else {\n jj_run_in(&root, &[\"git\", \"init\"])?;\n }\n\n let repo_root = vcs::ensure_jj_repo_in(&root)?;\n let branch = default_branch(&repo_root);\n let remote = default_remote(&repo_root);\n let auto_track = auto_track_enabled(&repo_root);\n\n if jj_run_in(&repo_root, &[\"git\", \"fetch\"]).is_err() {\n println!(\"⚠ jj git fetch failed (no remote yet?)\");\n return Ok(());\n }\n\n if auto_track {\n let track_ref = format!(\"{}@{}\", branch, remote);\n if jj_run_in(&repo_root, &[\"bookmark\", \"track\", &track_ref]).is_err() {\n println!(\"⚠ Failed to track {}\", track_ref);\n }\n }\n\n println!(\"✓ JJ initialized (colocated: {})\", has_git);\n Ok(())\n}\n\nfn current_context() -> Result<JjContext> {\n let workspace_root = vcs::ensure_jj_repo()?;\n let repo_root = repo_root_for_workspace(&workspace_root)?;\n Ok(JjContext {\n workspace_root,\n repo_root,\n })\n}\n\nfn repo_root_for_workspace(workspace_root: &Path) -> Result<PathBuf> {\n let git_root = jj_capture_in(workspace_root, &[\"git\", \"root\"])?;\n repo_root_from_git_root(git_root.trim()).map(PathBuf::from)\n}\n\nfn repo_root_from_git_root(git_root: &str) -> Result<&str> {\n let trimmed = git_root.trim();\n if trimmed.is_empty() {\n bail!(\"jj git root returned an empty path\");\n }\n if let Some(parent) = trimmed.strip_suffix(\"/.git\") {\n return Ok(parent);\n }\n if let Some(parent) = trimmed.strip_suffix(\"\\\\.git\") {\n return Ok(parent);\n }\n Ok(trimmed)\n}\n\nfn run_status(opts: JjStatusOpts) -> Result<()> {\n let ctx = current_context()?;\n if opts.raw {\n return jj_run_in(&ctx.workspace_root, &[\"status\"]);\n }\n\n let snapshot = collect_status_snapshot(&ctx)?;\n print_status_snapshot(&snapshot);\n Ok(())\n}\n\nfn run_fetch() -> Result<()> {\n let ctx = current_context()?;\n ensure_git_not_busy(&ctx.repo_root)?;\n jj_run_in(&ctx.workspace_root, &[\"git\", \"fetch\"])\n}\n\nfn run_rebase(opts: JjRebaseOpts) -> Result<()> {\n let ctx = current_context()?;\n ensure_git_not_busy(&ctx.repo_root)?;\n let remote = default_remote(&ctx.repo_root);\n let dest = opts.dest.unwrap_or_else(|| default_branch(&ctx.repo_root));\n let target = resolve_rebase_target(&ctx.workspace_root, &dest, &remote);\n jj_run_in(&ctx.workspace_root, &[\"rebase\", \"-d\", &target])\n}\n\nfn run_push(opts: JjPushOpts) -> Result<()> {\n let ctx = current_context()?;\n ensure_git_not_busy(&ctx.repo_root)?;\n if opts.all {\n return jj_run_in(&ctx.workspace_root, &[\"git\", \"push\", \"--all\"]);\n }\n let Some(bookmark) = opts.bookmark else {\n bail!(\"Specify a bookmark or pass --all\");\n };\n jj_run_in(\n &ctx.workspace_root,\n &[\"git\", \"push\", \"--bookmark\", &bookmark],\n )\n}\n\nfn run_sync(opts: JjSyncOpts) -> Result<()> {\n let ctx = current_context()?;\n ensure_git_not_busy(&ctx.repo_root)?;\n let remote = opts\n .remote\n .unwrap_or_else(|| default_remote(&ctx.repo_root));\n let dest = opts.dest.unwrap_or_else(|| default_branch(&ctx.repo_root));\n\n jj_run_in(&ctx.workspace_root, &[\"git\", \"fetch\"])?;\n let target = resolve_rebase_target(&ctx.workspace_root, &dest, &remote);\n jj_run_in(&ctx.workspace_root, &[\"rebase\", \"-d\", &target])?;\n\n // Check for conflicts after rebase\n let has_conflicts = jj_capture_in(\n &ctx.workspace_root,\n &[\"log\", \"-r\", \"conflicts()\", \"--no-graph\", \"-T\", \"commit_id\"],\n )\n .map(|out| !out.trim().is_empty())\n .unwrap_or(false);\n if has_conflicts {\n let details = jj_capture_in(\n &ctx.workspace_root,\n &[\"log\", \"-r\", \"conflicts()\", \"--no-graph\"],\n )\n .unwrap_or_default();\n eprintln!(\"\\n⚠ Rebase produced conflicts:\");\n for line in details.lines().filter(|l| !l.trim().is_empty()) {\n eprintln!(\" {}\", line.trim());\n }\n eprintln!(\"\\nResolve with: jj resolve\");\n }\n\n if opts.no_push {\n return Ok(());\n }\n\n let Some(bookmark) = opts.bookmark else {\n return Ok(());\n };\n jj_run_in(\n &ctx.workspace_root,\n &[\"git\", \"push\", \"--bookmark\", &bookmark],\n )\n}\n\nfn run_workspace(action: JjWorkspaceAction) -> Result<()> {\n let ctx = current_context()?;\n match action {\n JjWorkspaceAction::List => jj_run_in(&ctx.workspace_root, &[\"workspace\", \"list\"]),\n JjWorkspaceAction::Add { name, path, rev } => {\n let workspace_path = match path {\n Some(p) => p,\n None => workspace_default_path(&ctx.repo_root, &name)?,\n };\n run_workspace_add(&ctx.workspace_root, &name, workspace_path, rev.as_deref())\n }\n JjWorkspaceAction::Lane {\n name,\n path,\n base,\n remote,\n no_fetch,\n } => {\n ensure_git_not_busy(&ctx.repo_root)?;\n let remote = remote.unwrap_or_else(|| default_remote(&ctx.repo_root));\n if !no_fetch {\n if let Err(err) = jj_run_in(&ctx.workspace_root, &[\"git\", \"fetch\"]) {\n eprintln!(\"⚠ jj git fetch failed: {err}\");\n eprintln!(\" continuing with current local refs\");\n }\n }\n let workspace_path = match path {\n Some(p) => p,\n None => workspace_default_path(&ctx.repo_root, &name)?,\n };\n let base_rev = base.unwrap_or_else(|| {\n let dest = default_branch(&ctx.repo_root);\n resolve_rebase_target(&ctx.workspace_root, &dest, &remote)\n });\n run_workspace_add(\n &ctx.workspace_root,\n &name,\n workspace_path.clone(),\n Some(&base_rev),\n )?;\n println!(\"Lane {} is anchored at {}\", name, base_rev);\n println!(\"Next: cd {}\", workspace_path.display());\n println!(\n \"Optional bookmark: f jj bookmark create {} --rev @ --track --remote {}\",\n name, remote\n );\n Ok(())\n }\n JjWorkspaceAction::Review {\n branch,\n path,\n base,\n remote,\n no_fetch,\n } => {\n let remote = remote.unwrap_or_else(|| default_remote(&ctx.repo_root));\n if !no_fetch {\n ensure_git_not_busy(&ctx.repo_root)?;\n if let Err(err) = jj_run_in(&ctx.workspace_root, &[\"git\", \"fetch\"]) {\n eprintln!(\"⚠ jj git fetch failed: {err}\");\n eprintln!(\" continuing with current local refs\");\n }\n }\n\n let workspace_name = review_workspace_name(&branch);\n if workspace_name.is_empty() {\n bail!(\"Invalid review branch name: {}\", branch);\n }\n\n let workspace_path = match path {\n Some(p) => p,\n None => workspace_default_path(&ctx.repo_root, &workspace_name)?,\n };\n\n if let Some(existing_path) =\n existing_workspace_path(&ctx.workspace_root, &ctx.repo_root, &workspace_name)?\n {\n if existing_path != workspace_path {\n bail!(\n \"Workspace {} already exists at {}\",\n workspace_name,\n existing_path.display()\n );\n }\n println!(\n \"Reusing review workspace {} at {}\",\n workspace_name,\n existing_path.display()\n );\n } else {\n let resolution = resolve_review_workspace_base(\n &ctx.repo_root,\n &branch,\n &remote,\n base.as_deref(),\n );\n run_workspace_add(\n &ctx.workspace_root,\n &workspace_name,\n workspace_path.clone(),\n Some(&resolution.rev),\n )?;\n println!(\n \"Review branch {} resolved via {}\",\n branch, resolution.source\n );\n }\n\n println!(\"Next: cd {}\", workspace_path.display());\n println!(\n \"Use `jj` / `f jj` inside this workspace. Git commands still point at the colocated main checkout.\"\n );\n println!(\n \"When you are ready to publish from JJ: f jj bookmark create {} --rev @ --track --remote {}\",\n branch, remote\n );\n Ok(())\n }\n }\n}\n\nfn run_workspace_add(\n repo_root: &Path,\n name: &str,\n workspace_path: PathBuf,\n rev: Option<&str>,\n) -> Result<()> {\n if let Some(parent) = workspace_path.parent() {\n std::fs::create_dir_all(parent)?;\n }\n let path_str = workspace_path\n .to_str()\n .ok_or_else(|| anyhow::anyhow!(\"invalid workspace path\"))?\n .to_string();\n let args = workspace_add_args(&path_str, name, rev);\n jj_run_owned_in(repo_root, &args)?;\n if let Some(rev) = rev.filter(|v| !v.trim().is_empty()) {\n println!(\n \"Created workspace {} at {} (base: {})\",\n name,\n workspace_path.display(),\n rev.trim()\n );\n } else {\n println!(\"Created workspace {} at {}\", name, workspace_path.display());\n }\n Ok(())\n}\n\nfn workspace_add_args(destination: &str, name: &str, rev: Option<&str>) -> Vec<String> {\n let mut args = vec![\n \"workspace\".to_string(),\n \"add\".to_string(),\n destination.to_string(),\n \"--name\".to_string(),\n name.to_string(),\n ];\n if let Some(rev) = rev {\n let trimmed = rev.trim();\n if !trimmed.is_empty() {\n args.push(\"--revision\".to_string());\n args.push(trimmed.to_string());\n }\n }\n args\n}\n\nfn run_bookmark(action: JjBookmarkAction) -> Result<()> {\n let ctx = current_context()?;\n match action {\n JjBookmarkAction::List => jj_run_in(&ctx.workspace_root, &[\"bookmark\", \"list\"]),\n JjBookmarkAction::Track { name, remote } => {\n let remote = remote.unwrap_or_else(|| default_remote(&ctx.repo_root));\n let track_ref = format!(\"{}@{}\", name, remote);\n jj_run_in(&ctx.workspace_root, &[\"bookmark\", \"track\", &track_ref])\n }\n JjBookmarkAction::Create {\n name,\n rev,\n track,\n remote,\n } => {\n let rev = rev.unwrap_or_else(|| \"@\".to_string());\n jj_run_in(\n &ctx.workspace_root,\n &[\"bookmark\", \"create\", &name, \"-r\", &rev],\n )?;\n\n let should_track = track.unwrap_or_else(|| auto_track_enabled(&ctx.repo_root));\n if should_track {\n let remote = remote.unwrap_or_else(|| default_remote(&ctx.repo_root));\n let track_ref = format!(\"{}@{}\", name, remote);\n if jj_run_in(&ctx.workspace_root, &[\"bookmark\", \"track\", &track_ref]).is_err() {\n println!(\"⚠ Failed to track {}\", track_ref);\n }\n }\n Ok(())\n }\n }\n}\n\nstruct WorkflowStatusSnapshot {\n workspace_root: PathBuf,\n repo_root: PathBuf,\n workspace_name: String,\n current_ref: String,\n current_role: &'static str,\n home_branch: String,\n intake_branch: String,\n remote: String,\n trunk_ref: String,\n home_unique_to_trunk: usize,\n trunk_unique_to_home: usize,\n leaves: Vec<LeafBranchStatus>,\n workspaces: Vec<WorkspaceStatus>,\n working_copy_lines: Vec<String>,\n}\n\nstruct LeafBranchStatus {\n name: String,\n kind: &'static str,\n unique_commits: usize,\n tracked_remote: bool,\n workspace_name: Option<String>,\n is_current: bool,\n}\n\nstruct WorkspaceStatus {\n name: String,\n is_current: bool,\n path_exists: bool,\n}\n\nfn collect_status_snapshot(ctx: &JjContext) -> Result<WorkflowStatusSnapshot> {\n let default_branch = default_branch(&ctx.repo_root);\n let remote = default_remote(&ctx.repo_root);\n let workspace_name = current_workspace_name(&ctx.workspace_root)?;\n let current_bookmarks = local_bookmarks_at_rev(&ctx.workspace_root, \"@\");\n let parent_bookmarks = local_bookmarks_at_rev(&ctx.workspace_root, \"@-\");\n let all_bookmarks = jj_bookmark_names(&ctx.workspace_root)?;\n let all_local_bookmarks = all_bookmarks\n .iter()\n .filter(|name| !name.contains('@'))\n .cloned()\n .collect::<HashSet<_>>();\n let current_git_branch = git_current_branch(&ctx.repo_root).unwrap_or_default();\n let home_branch = infer_home_branch(\n &ctx.repo_root,\n &default_branch,\n ¤t_bookmarks,\n &parent_bookmarks,\n &all_local_bookmarks,\n );\n let intake_branch = derive_intake_branch(&home_branch);\n let current_ref = infer_current_ref(\n &workspace_name,\n ¤t_git_branch,\n &home_branch,\n &intake_branch,\n &default_branch,\n ¤t_bookmarks,\n &parent_bookmarks,\n );\n let current_role = classify_branch_role(¤t_ref, &home_branch, &intake_branch);\n let remote_trunk_ref = format!(\"{default_branch}@{remote}\");\n let trunk_ref = if all_bookmarks.contains(&remote_trunk_ref) {\n remote_trunk_ref\n } else {\n default_branch.clone()\n };\n let leaf_names: Vec<String> = all_local_bookmarks\n .iter()\n .filter(|name| is_leaf_branch(name))\n .cloned()\n .collect();\n let workspace_names = jj_workspace_names(&ctx.workspace_root)?;\n let mut leaves = Vec::new();\n for name in leaf_names {\n let workspace_name_for_branch = workspace_name_for_branch(&name)\n .filter(|candidate| workspace_names.contains(candidate));\n leaves.push(LeafBranchStatus {\n kind: leaf_branch_kind(&name),\n unique_commits: count_unique_commits(&ctx.workspace_root, &name, &home_branch),\n tracked_remote: all_bookmarks.contains(&format!(\"{name}@{remote}\")),\n workspace_name: workspace_name_for_branch,\n is_current: name == current_ref,\n name,\n });\n }\n leaves.sort_by(|left, right| left.name.cmp(&right.name));\n\n let mut workspaces: Vec<WorkspaceStatus> = workspace_names\n .into_iter()\n .map(|name| WorkspaceStatus {\n path_exists: inferred_workspace_path(&ctx.repo_root, &name).exists(),\n is_current: name == workspace_name,\n name,\n })\n .collect();\n workspaces.sort_by(|left, right| left.name.cmp(&right.name));\n\n let working_copy_output = jj_capture_in(&ctx.workspace_root, &[\"status\"])?;\n Ok(WorkflowStatusSnapshot {\n workspace_root: ctx.workspace_root.clone(),\n repo_root: ctx.repo_root.clone(),\n workspace_name,\n current_ref,\n current_role,\n home_branch: home_branch.clone(),\n intake_branch,\n remote,\n trunk_ref: trunk_ref.clone(),\n home_unique_to_trunk: count_unique_commits(&ctx.workspace_root, &home_branch, &trunk_ref),\n trunk_unique_to_home: count_unique_commits(&ctx.workspace_root, &trunk_ref, &home_branch),\n leaves,\n workspaces,\n working_copy_lines: working_copy_output\n .lines()\n .map(|line| line.to_string())\n .collect(),\n })\n}\n\nfn print_status_snapshot(snapshot: &WorkflowStatusSnapshot) {\n println!(\"JJ Workflow Status\");\n println!();\n println!(\"Repo: {}\", snapshot.repo_root.display());\n println!(\n \"Workspace: {} ({})\",\n snapshot.workspace_name,\n snapshot.workspace_root.display()\n );\n println!(\n \"Current: {} [{}]\",\n snapshot.current_ref, snapshot.current_role\n );\n println!(\n \"Home: {} ({} commit(s) not in {})\",\n snapshot.home_branch, snapshot.home_unique_to_trunk, snapshot.trunk_ref\n );\n println!(\"Intake: {}\", snapshot.intake_branch);\n println!(\n \"Trunk: {} ({} commit(s) not in {})\",\n snapshot.trunk_ref, snapshot.trunk_unique_to_home, snapshot.home_branch\n );\n println!(\"Remote: {}\", snapshot.remote);\n println!();\n println!(\"Leaf Branches:\");\n if snapshot.leaves.is_empty() {\n println!(\" none\");\n } else {\n for leaf in &snapshot.leaves {\n let current = if leaf.is_current { \" current\" } else { \"\" };\n let tracked = if leaf.tracked_remote {\n format!(\" tracked@{}\", snapshot.remote)\n } else {\n \" local-only\".to_string()\n };\n let workspace = leaf\n .workspace_name\n .as_deref()\n .map(|name| format!(\" workspace={name}\"))\n .unwrap_or_default();\n println!(\n \" {} [{}] {} commit(s) over {}{}{}{}\",\n leaf.name,\n leaf.kind,\n leaf.unique_commits,\n snapshot.home_branch,\n tracked,\n workspace,\n current\n );\n }\n }\n println!();\n println!(\"Workspaces:\");\n for workspace in &snapshot.workspaces {\n let marker = if workspace.is_current { \"*\" } else { \"-\" };\n let suffix = if workspace.path_exists {\n \"\"\n } else {\n \" (expected path missing)\"\n };\n println!(\" {} {}{}\", marker, workspace.name, suffix);\n }\n println!();\n println!(\"Working Copy:\");\n for line in &snapshot.working_copy_lines {\n println!(\" {}\", line);\n }\n println!();\n println!(\"Suggested Next:\");\n if snapshot.current_role == \"review\" || snapshot.current_role == \"codex\" {\n println!(\" f jj push --bookmark {}\", snapshot.current_ref);\n println!(\n \" jj rebase -b {} -o {}\",\n snapshot.current_ref, snapshot.home_branch\n );\n } else {\n println!(\" f jj sync --bookmark {}\", snapshot.home_branch);\n println!(\n \" f jj workspace review review/{}-topic\",\n snapshot.home_branch\n );\n }\n}\n\nfn current_workspace_name(workspace_root: &Path) -> Result<String> {\n let output = jj_capture_in(\n workspace_root,\n &[\"log\", \"-r\", \"@\", \"--no-graph\", \"-T\", \"working_copies\"],\n )?;\n let trimmed = output.trim().trim_end_matches('@').trim();\n if trimmed.is_empty() {\n Ok(\"default\".to_string())\n } else {\n Ok(trimmed.to_string())\n }\n}\n\nfn configured_home_branch(repo_root: &Path) -> Option<String> {\n load_jj_config(repo_root)\n .and_then(|cfg| cfg.home_branch)\n .map(|value| value.trim().to_string())\n .filter(|value| !value.is_empty())\n}\n\nfn git_current_branch(repo_root: &Path) -> Option<String> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"branch\", \"--show-current\"])\n .output()\n .ok()?;\n if !output.status.success() {\n return None;\n }\n let value = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if value.is_empty() { None } else { Some(value) }\n}\n\nfn infer_home_branch(\n repo_root: &Path,\n default_branch: &str,\n current_bookmarks: &[String],\n parent_bookmarks: &[String],\n all_bookmarks: &HashSet<String>,\n) -> String {\n if let Some(home_branch) = configured_home_branch(repo_root) {\n return home_branch;\n }\n if let Some(git_branch) =\n git_current_branch(repo_root).filter(|name| is_home_branch_candidate(name, default_branch))\n {\n return git_branch;\n }\n for bookmark in current_bookmarks\n .iter()\n .chain(parent_bookmarks.iter())\n .chain(all_bookmarks.iter())\n {\n if is_home_branch_candidate(bookmark, default_branch) {\n return bookmark.clone();\n }\n }\n default_branch.to_string()\n}\n\nfn derive_intake_branch(home_branch: &str) -> String {\n if home_branch.trim().is_empty() || home_branch == \"main\" {\n \"main-intake\".to_string()\n } else {\n format!(\"{home_branch}-main-intake\")\n }\n}\n\nfn infer_current_ref(\n workspace_name: &str,\n current_git_branch: &str,\n home_branch: &str,\n intake_branch: &str,\n default_branch: &str,\n current_bookmarks: &[String],\n parent_bookmarks: &[String],\n) -> String {\n let candidates: Vec<String> = current_bookmarks\n .iter()\n .chain(parent_bookmarks.iter())\n .cloned()\n .collect();\n if let Some(match_by_workspace) = candidates\n .iter()\n .find(|name| workspace_name_for_branch(name).as_deref() == Some(workspace_name))\n {\n return match_by_workspace.clone();\n }\n if workspace_name == \"default\"\n && !current_git_branch.is_empty()\n && !is_leaf_branch(current_git_branch)\n {\n return current_git_branch.to_string();\n }\n if let Some(leaf) = candidates.iter().find(|name| is_leaf_branch(name)) {\n return leaf.clone();\n }\n if candidates.iter().any(|name| name == home_branch) {\n return home_branch.to_string();\n }\n if candidates.iter().any(|name| name == intake_branch) {\n return intake_branch.to_string();\n }\n if let Some(plain) = candidates\n .iter()\n .find(|name| is_home_branch_candidate(name, default_branch))\n {\n return plain.clone();\n }\n if !home_branch.is_empty() {\n return home_branch.to_string();\n }\n default_branch.to_string()\n}\n\nfn classify_branch_role(name: &str, home_branch: &str, intake_branch: &str) -> &'static str {\n if name == home_branch {\n \"home\"\n } else if name == intake_branch {\n \"intake\"\n } else if name.starts_with(\"review/\") {\n \"review\"\n } else if name.starts_with(\"codex/\") {\n \"codex\"\n } else {\n \"other\"\n }\n}\n\nfn is_home_branch_candidate(name: &str, default_branch: &str) -> bool {\n !name.trim().is_empty()\n && !is_leaf_branch(name)\n && !is_intake_branch(name)\n && name != default_branch\n && !name.contains('@')\n}\n\nfn is_intake_branch(name: &str) -> bool {\n name == \"main-intake\" || name.ends_with(\"-main-intake\")\n}\n\nfn is_leaf_branch(name: &str) -> bool {\n name.starts_with(\"review/\") || name.starts_with(\"codex/\")\n}\n\nfn leaf_branch_kind(name: &str) -> &'static str {\n if name.starts_with(\"review/\") {\n \"review\"\n } else {\n \"codex\"\n }\n}\n\nfn workspace_name_for_branch(name: &str) -> Option<String> {\n let value = review_workspace_name(name);\n if value.is_empty() { None } else { Some(value) }\n}\n\nfn local_bookmarks_at_rev(workspace_root: &Path, rev: &str) -> Vec<String> {\n let output = jj_capture_in(\n workspace_root,\n &[\"log\", \"-r\", rev, \"--no-graph\", \"-T\", \"bookmarks\"],\n )\n .unwrap_or_default();\n parse_bookmark_tokens(&output)\n}\n\nfn jj_bookmark_names(workspace_root: &Path) -> Result<HashSet<String>> {\n let output = jj_capture_in(\n workspace_root,\n &[\n \"bookmark\",\n \"list\",\n \"--all-remotes\",\n \"-T\",\n \"if(remote, name ++ \\\"@\\\" ++ remote, name) ++ \\\"\\\\n\\\"\",\n ],\n )?;\n Ok(parse_bookmark_list_names(&output)\n .into_iter()\n .collect::<HashSet<_>>())\n}\n\nfn parse_bookmark_tokens(output: &str) -> Vec<String> {\n output\n .split_whitespace()\n .filter(|token| !token.contains('@'))\n .map(|token| token.trim().to_string())\n .filter(|token| !token.is_empty())\n .collect()\n}\n\nfn parse_bookmark_list_names(output: &str) -> Vec<String> {\n output\n .lines()\n .filter_map(|line| {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n return None;\n }\n let name = trimmed\n .split_once(':')\n .map(|(name, _)| name.trim())\n .unwrap_or(trimmed);\n Some(name.to_string())\n })\n .filter(|name| !name.is_empty())\n .collect()\n}\n\nfn jj_workspace_names(workspace_root: &Path) -> Result<HashSet<String>> {\n let output = jj_capture_in(\n workspace_root,\n &[\"workspace\", \"list\", \"-T\", \"name ++ \\\"\\\\n\\\"\"],\n )?;\n Ok(parse_workspace_names(&output).into_iter().collect())\n}\n\nfn parse_workspace_names(output: &str) -> Vec<String> {\n output\n .lines()\n .map(|line| line.trim())\n .filter(|line| !line.is_empty())\n .map(ToString::to_string)\n .collect()\n}\n\nfn inferred_workspace_path(repo_root: &Path, name: &str) -> PathBuf {\n if name == \"default\" {\n repo_root.to_path_buf()\n } else {\n workspace_default_path(repo_root, name).unwrap_or_else(|_| repo_root.to_path_buf())\n }\n}\n\nfn count_unique_commits(workspace_root: &Path, branch: &str, base: &str) -> usize {\n if branch == base {\n return 0;\n }\n let revset = format!(\"ancestors({branch}) ~ ancestors({base})\");\n jj_capture_in(\n workspace_root,\n &[\n \"log\",\n \"-r\",\n &revset,\n \"--no-graph\",\n \"-T\",\n \"commit_id ++ \\\"\\\\n\\\"\",\n ],\n )\n .map(|output| {\n output\n .lines()\n .filter(|line| !line.trim().is_empty())\n .count()\n })\n .unwrap_or(0)\n}\n\nfn resolve_rebase_target(repo_root: &Path, dest: &str, remote: &str) -> String {\n if jj_bookmark_exists(repo_root, dest) {\n dest.to_string()\n } else {\n format!(\"{}@{}\", dest, remote)\n }\n}\n\nfn jj_bookmark_exists(repo_root: &Path, name: &str) -> bool {\n jj_bookmark_names(repo_root)\n .map(|bookmarks| bookmarks.contains(name))\n .unwrap_or(false)\n}\n\nfn default_branch(repo_root: &Path) -> String {\n if let Some(cfg) = load_jj_config(repo_root) {\n if let Some(branch) = cfg.default_branch {\n return branch;\n }\n }\n if git_ref_exists(repo_root, \"refs/heads/main\")\n || git_ref_exists(repo_root, \"refs/remotes/origin/main\")\n {\n return \"main\".to_string();\n }\n if git_ref_exists(repo_root, \"refs/heads/master\")\n || git_ref_exists(repo_root, \"refs/remotes/origin/master\")\n {\n return \"master\".to_string();\n }\n \"main\".to_string()\n}\n\nfn default_remote(repo_root: &Path) -> String {\n config::preferred_git_remote_for_repo(repo_root)\n}\n\nfn auto_track_enabled(repo_root: &Path) -> bool {\n load_jj_config(repo_root)\n .and_then(|cfg| cfg.auto_track)\n .unwrap_or(false)\n}\n\nfn load_jj_config(repo_root: &Path) -> Option<config::JjConfig> {\n let local = repo_root.join(\"flow.toml\");\n if local.exists() {\n if let Ok(cfg) = config::load(&local) {\n if cfg.jj.is_some() {\n return cfg.jj;\n }\n }\n }\n let global = config::default_config_path();\n if global.exists() {\n if let Ok(cfg) = config::load(&global) {\n if cfg.jj.is_some() {\n return cfg.jj;\n }\n }\n }\n None\n}\n\nfn review_workspace_name(branch: &str) -> String {\n let trimmed = branch.trim().trim_matches('/');\n let mut out = String::new();\n let mut previous_was_dash = false;\n for ch in trimmed.chars() {\n let normalized = if ch.is_ascii_alphanumeric() || ch == '.' || ch == '_' || ch == '-' {\n previous_was_dash = false;\n ch\n } else {\n if previous_was_dash {\n continue;\n }\n previous_was_dash = true;\n '-'\n };\n out.push(normalized);\n }\n out.trim_matches('-').to_string()\n}\n\nfn existing_workspace_path(\n workspace_root: &Path,\n repo_root: &Path,\n name: &str,\n) -> Result<Option<PathBuf>> {\n if !jj_workspace_names(workspace_root)?.contains(name) {\n return Ok(None);\n }\n Ok(Some(inferred_workspace_path(repo_root, name)))\n}\n\nstruct ReviewWorkspaceBase {\n rev: String,\n source: String,\n}\n\nfn resolve_review_workspace_base(\n repo_root: &Path,\n branch: &str,\n remote: &str,\n explicit_base: Option<&str>,\n) -> ReviewWorkspaceBase {\n if let Some(base) = explicit_base.map(str::trim).filter(|base| !base.is_empty()) {\n return ReviewWorkspaceBase {\n rev: base.to_string(),\n source: format!(\"explicit base {}\", base),\n };\n }\n\n if let Some(commit) = git_ref_commit(repo_root, &format!(\"refs/heads/{branch}\")) {\n return ReviewWorkspaceBase {\n rev: commit.clone(),\n source: format!(\"local branch {branch} ({})\", short_commit(&commit)),\n };\n }\n\n let remote_ref = format!(\"refs/remotes/{remote}/{branch}\");\n if let Some(commit) = git_ref_commit(repo_root, &remote_ref) {\n return ReviewWorkspaceBase {\n rev: commit.clone(),\n source: format!(\n \"remote branch {remote}/{branch} ({})\",\n short_commit(&commit)\n ),\n };\n }\n\n let dest = default_branch(repo_root);\n let fallback = resolve_rebase_target(repo_root, &dest, remote);\n ReviewWorkspaceBase {\n rev: fallback.clone(),\n source: format!(\"fallback trunk {}\", fallback),\n }\n}\n\nfn git_ref_commit(repo_root: &Path, reference: &str) -> Option<String> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"rev-parse\", reference])\n .output()\n .ok()?;\n if !output.status.success() {\n return None;\n }\n let sha = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if sha.is_empty() { None } else { Some(sha) }\n}\n\nfn short_commit(commit: &str) -> &str {\n const SHORT_COMMIT_LEN: usize = 12;\n let end = commit\n .char_indices()\n .nth(SHORT_COMMIT_LEN)\n .map(|(idx, _)| idx)\n .unwrap_or(commit.len());\n &commit[..end]\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use tempfile::tempdir;\n\n #[test]\n fn default_remote_uses_git_remote_when_set() {\n let dir = tempdir().expect(\"tempdir\");\n let repo_root = dir.path();\n\n std::fs::write(\n repo_root.join(\"flow.toml\"),\n \"[git]\\nremote = \\\"myflow-i\\\"\\n\",\n )\n .expect(\"write flow.toml\");\n\n assert_eq!(default_remote(repo_root), \"myflow-i\");\n }\n\n #[test]\n fn workspace_add_args_use_modern_jj_shape() {\n let args = workspace_add_args(\"/tmp/ws-fix-otp\", \"fix-otp\", None);\n assert_eq!(\n args,\n vec![\"workspace\", \"add\", \"/tmp/ws-fix-otp\", \"--name\", \"fix-otp\",]\n );\n }\n\n #[test]\n fn workspace_add_args_include_revision_when_set() {\n let args = workspace_add_args(\"/tmp/ws-testflight\", \"testflight\", Some(\"main@upstream\"));\n assert_eq!(\n args,\n vec![\n \"workspace\",\n \"add\",\n \"/tmp/ws-testflight\",\n \"--name\",\n \"testflight\",\n \"--revision\",\n \"main@upstream\",\n ]\n );\n }\n\n #[test]\n fn review_workspace_name_sanitizes_review_branch() {\n assert_eq!(\n review_workspace_name(\"review/nikiv-designer-reactron-rs-rust-first\"),\n \"review-nikiv-designer-reactron-rs-rust-first\"\n );\n assert_eq!(\n review_workspace_name(\"/review//messy branch/\"),\n \"review-messy-branch\"\n );\n }\n\n #[test]\n fn resolve_review_workspace_base_prefers_explicit_base() {\n let dir = tempdir().expect(\"tempdir\");\n let repo_root = dir.path();\n\n let resolved =\n resolve_review_workspace_base(repo_root, \"review/demo\", \"origin\", Some(\"main@origin\"));\n\n assert_eq!(resolved.rev, \"main@origin\");\n assert_eq!(resolved.source, \"explicit base main@origin\");\n }\n\n #[test]\n fn resolve_review_workspace_base_uses_local_branch_commit() {\n let dir = tempdir().expect(\"tempdir\");\n let repo_root = dir.path();\n init_git_repo(repo_root);\n\n git(repo_root, &[\"checkout\", \"-q\", \"-b\", \"review/demo\"]);\n let expected = git_capture(repo_root, &[\"rev-parse\", \"refs/heads/review/demo\"]);\n\n let resolved = resolve_review_workspace_base(repo_root, \"review/demo\", \"origin\", None);\n\n assert_eq!(resolved.rev, expected);\n assert!(resolved.source.starts_with(\"local branch review/demo (\"));\n }\n\n #[test]\n fn parse_workspace_names_skips_blank_lines() {\n let parsed = parse_workspace_names(\"\\ndefault\\nreview-demo\\n\\n\");\n\n assert_eq!(parsed, vec![\"default\", \"review-demo\"]);\n }\n\n #[test]\n fn parse_bookmark_list_names_supports_structured_template_output() {\n let parsed = parse_bookmark_list_names(\"main\\nmain@origin\\nreview/demo\\n\");\n\n assert_eq!(parsed, vec![\"main\", \"main@origin\", \"review/demo\"]);\n }\n\n #[test]\n fn repo_root_from_git_root_handles_colocated_git_dir() {\n let repo_root = repo_root_from_git_root(\"/tmp/prom/.git\").expect(\"repo root\");\n assert_eq!(repo_root, \"/tmp/prom\");\n }\n\n #[test]\n fn infer_current_ref_prefers_workspace_named_leaf_branch() {\n let current = infer_current_ref(\n \"review-nikiv-feature\",\n \"nikiv\",\n \"nikiv\",\n \"nikiv-main-intake\",\n \"main\",\n &[],\n &[String::from(\"nikiv\"), String::from(\"review/nikiv-feature\")],\n );\n\n assert_eq!(current, \"review/nikiv-feature\");\n }\n\n fn init_git_repo(repo_root: &Path) {\n git(repo_root, &[\"init\", \"-q\"]);\n git(repo_root, &[\"config\", \"user.name\", \"Flow Tests\"]);\n git(\n repo_root,\n &[\"config\", \"user.email\", \"flow-tests@example.com\"],\n );\n std::fs::write(repo_root.join(\"README.md\"), \"init\\n\").expect(\"write README\");\n git(repo_root, &[\"add\", \"README.md\"]);\n git(repo_root, &[\"commit\", \"-q\", \"-m\", \"init\"]);\n }\n\n fn git(repo_root: &Path, args: &[&str]) {\n let status = Command::new(\"git\")\n .current_dir(repo_root)\n .args(args)\n .status()\n .expect(\"run git\");\n assert!(status.success(), \"git {:?} failed\", args);\n }\n\n fn git_capture(repo_root: &Path, args: &[&str]) -> String {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .expect(\"run git\");\n assert!(output.status.success(), \"git {:?} failed\", args);\n String::from_utf8_lossy(&output.stdout).trim().to_string()\n }\n}\n\nfn is_jj_repo(path: &Path) -> bool {\n Command::new(\"jj\")\n .current_dir(path)\n .arg(\"root\")\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .status()\n .map(|s| s.success())\n .unwrap_or(false)\n}\n\nfn jj_run_in(repo_root: &Path, args: &[&str]) -> Result<()> {\n let output = Command::new(\"jj\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run jj {}\", args.join(\" \")))?;\n let stdout = String::from_utf8_lossy(&output.stdout);\n if !stdout.trim().is_empty() {\n print!(\"{}\", stdout);\n }\n let stderr = String::from_utf8_lossy(&output.stderr);\n for line in stderr.lines() {\n if line.contains(\"Refused to snapshot\") {\n continue;\n }\n eprintln!(\"{}\", line);\n }\n if !output.status.success() {\n bail!(\"jj {} failed\", args.join(\" \"));\n }\n Ok(())\n}\n\nfn jj_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"jj\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run jj {}\", args.join(\" \")))?;\n if !output.status.success() {\n bail!(\"jj {} failed\", args.join(\" \"));\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nfn jj_run_owned_in(repo_root: &Path, args: &[String]) -> Result<()> {\n let refs: Vec<&str> = args.iter().map(String::as_str).collect();\n jj_run_in(repo_root, &refs)\n}\n\nfn git_ref_exists(repo_root: &Path, name: &str) -> bool {\n Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"show-ref\", \"--verify\", name])\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .status()\n .map(|s| s.success())\n .unwrap_or(false)\n}\n\nfn ensure_git_not_busy(repo_root: &Path) -> Result<()> {\n let git_dir = git_dir(repo_root)?;\n let rebase = git_dir.join(\"rebase-merge\").exists() || git_dir.join(\"rebase-apply\").exists();\n let merge = git_dir.join(\"MERGE_HEAD\").exists();\n let cherry_pick = git_dir.join(\"CHERRY_PICK_HEAD\").exists();\n let revert = git_dir.join(\"REVERT_HEAD\").exists();\n let bisect = git_dir.join(\"BISECT_LOG\").exists();\n let unmerged = git_unmerged_files(repo_root);\n\n if rebase || merge || cherry_pick || revert || bisect || !unmerged.is_empty() {\n bail!(\"Git operation in progress. Run `f git-repair` first.\");\n }\n Ok(())\n}\n\nfn git_unmerged_files(repo_root: &Path) -> Vec<String> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"diff\", \"--name-only\", \"--diff-filter=U\"])\n .output();\n match output {\n Ok(out) => String::from_utf8_lossy(&out.stdout)\n .lines()\n .filter(|l| !l.trim().is_empty())\n .map(|l| l.trim().to_string())\n .collect(),\n Err(_) => Vec::new(),\n }\n}\n\nfn git_dir(repo_root: &Path) -> Result<PathBuf> {\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"rev-parse\", \"--git-dir\"])\n .output()\n .context(\"failed to locate git directory\")?;\n if !output.status.success() {\n bail!(\"Not a git repository\");\n }\n let raw = String::from_utf8_lossy(&output.stdout).trim().to_string();\n let dir = PathBuf::from(raw);\n if dir.is_absolute() {\n Ok(dir)\n } else {\n Ok(repo_root.join(dir))\n }\n}\n\nfn workspace_default_path(repo_root: &Path, name: &str) -> Result<PathBuf> {\n let home = std::env::var(\"HOME\").context(\"HOME not set\")?;\n let repo_name = repo_root\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(\"repo\");\n Ok(PathBuf::from(home)\n .join(\".jj\")\n .join(\"workspaces\")\n .join(repo_name)\n .join(name))\n}\n" }, { "path": "src/json_parse.rs", "content": "use anyhow::{Result, anyhow};\nuse serde::de::DeserializeOwned;\n\n#[inline]\npub fn parse_json_line<T: DeserializeOwned>(line: &str) -> Result<T> {\n #[cfg(all(\n feature = \"linux-host-simd-json\",\n target_os = \"linux\",\n any(target_arch = \"x86_64\", target_arch = \"aarch64\")\n ))]\n {\n let mut buf = line.as_bytes().to_vec();\n return simd_json::serde::from_slice(&mut buf)\n .map_err(|err| anyhow!(\"failed to decode json line with simd-json: {err}\"));\n }\n\n #[cfg(not(all(\n feature = \"linux-host-simd-json\",\n target_os = \"linux\",\n any(target_arch = \"x86_64\", target_arch = \"aarch64\")\n )))]\n {\n serde_json::from_str(line).map_err(|err| anyhow!(\"failed to decode json line: {err}\"))\n }\n}\n\n#[inline]\npub fn parse_json_bytes_in_place<T: DeserializeOwned>(bytes: &mut [u8]) -> Result<T> {\n #[cfg(all(\n feature = \"linux-host-simd-json\",\n target_os = \"linux\",\n any(target_arch = \"x86_64\", target_arch = \"aarch64\")\n ))]\n {\n return simd_json::serde::from_slice(bytes)\n .map_err(|err| anyhow!(\"failed to decode json bytes with simd-json: {err}\"));\n }\n\n #[cfg(not(all(\n feature = \"linux-host-simd-json\",\n target_os = \"linux\",\n any(target_arch = \"x86_64\", target_arch = \"aarch64\")\n )))]\n {\n serde_json::from_slice(bytes).map_err(|err| anyhow!(\"failed to decode json bytes: {err}\"))\n }\n}\n" }, { "path": "src/latest.rs", "content": "use std::path::PathBuf;\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::DeployCommand;\nuse crate::deploy;\n\npub fn run() -> Result<()> {\n let flow_root = flow_repo_root()?;\n update_flow_repo(&flow_root)?;\n rebuild_flow(&flow_root)?;\n reload_fish_shell()?;\n Ok(())\n}\n\nfn flow_repo_root() -> Result<PathBuf> {\n let root = dirs::home_dir()\n .context(\"failed to resolve home directory\")?\n .join(\"code/flow\");\n if !root.exists() {\n bail!(\"flow repo not found at {}\", root.display());\n }\n Ok(root)\n}\n\nfn update_flow_repo(root: &PathBuf) -> Result<()> {\n println!(\"Updating {}\", root.display());\n let status = Command::new(\"git\")\n .args([\n \"-C\",\n root.to_str().unwrap_or(\"\"),\n \"pull\",\n \"--rebase\",\n \"--autostash\",\n ])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run git pull\")?;\n if !status.success() {\n bail!(\"git pull failed\");\n }\n Ok(())\n}\n\nfn rebuild_flow(root: &PathBuf) -> Result<()> {\n let prev = std::env::current_dir().context(\"failed to read current directory\")?;\n std::env::set_current_dir(root)\n .with_context(|| format!(\"failed to switch to {}\", root.display()))?;\n let result = deploy::run(DeployCommand { action: None });\n std::env::set_current_dir(prev).context(\"failed to restore previous directory\")?;\n result\n}\n\nfn reload_fish_shell() -> Result<()> {\n if std::env::var(\"FISH_VERSION\").is_err() {\n return Ok(());\n }\n if !atty::is(atty::Stream::Stdout) {\n return Ok(());\n }\n\n println!(\"Reloading fish shell...\");\n #[cfg(unix)]\n {\n use std::os::unix::process::CommandExt;\n let err = Command::new(\"fish\").arg(\"-l\").exec();\n bail!(\"failed to exec fish: {}\", err);\n }\n #[cfg(not(unix))]\n {\n let _ = Command::new(\"fish\").arg(\"-l\").status();\n Ok(())\n }\n}\n" }, { "path": "src/lib.rs", "content": "pub mod activity_log;\npub mod agent_setup;\npub mod agents;\npub mod ai;\npub mod ai_context;\npub mod ai_everruns;\npub mod ai_server;\npub mod ai_taskd;\npub mod ai_tasks;\npub mod ai_test;\npub mod analytics;\npub mod archive;\npub mod ask;\npub mod auth;\npub mod base_tool;\npub mod branches;\npub mod changes;\npub mod cli;\npub mod code;\npub mod codex_memory;\npub mod codex_runtime;\npub mod codex_skill_eval;\npub mod codex_telemetry;\npub mod codex_text;\npub mod codexd;\npub mod commit;\npub mod commits;\npub mod config;\npub mod daemon;\npub mod daemon_snapshot;\npub mod db;\npub mod deploy;\npub mod deploy_setup;\npub mod deps;\npub mod discover;\npub mod docs;\npub mod doctor;\npub mod domains;\npub mod env;\npub mod env_setup;\npub mod explain_commits;\npub mod ext;\npub mod features;\npub mod fish_install;\npub mod fish_trace;\npub mod fix;\npub mod fixup;\npub mod flox;\npub mod gh_release;\npub mod git_guard;\npub mod gitignore_policy;\npub mod hash;\npub mod health;\npub mod help_search;\npub mod history;\npub mod hive;\npub mod home;\npub mod http_client;\npub mod hub;\npub mod info;\npub mod init;\npub mod install;\npub mod invariants;\n#[path = \"jazz_state_stub.rs\"]\npub mod jazz_state;\npub mod jj;\npub mod json_parse;\npub mod latest;\npub mod lifecycle;\npub mod lmstudio;\npub mod log_server;\npub mod log_store;\npub mod macos;\npub mod notify;\npub mod opentui_prompt;\npub mod otp;\npub mod palette;\npub mod parallel;\n#[cfg(test)]\nmod path_hygiene;\npub mod pr_edit;\npub mod processes;\npub mod project_snapshot;\npub mod projects;\npub mod proxy;\npub mod publish;\npub mod push;\npub mod recipe;\npub mod registry;\npub mod release;\npub mod release_signing;\npub mod repo_capsule;\npub mod repos;\npub mod reviews_todo;\npub mod rl_signals;\npub mod running;\npub mod sealer_crypto;\npub mod secret_redact;\npub mod seq_client;\npub mod seq_rpc;\npub mod services;\npub mod setup;\npub mod skills;\npub mod ssh;\npub mod ssh_keys;\npub mod start;\npub mod storage;\npub mod supervisor;\npub mod sync;\npub mod task_failure_agents;\npub mod task_match;\npub mod tasks;\npub mod todo;\npub mod tools;\n#[path = \"traces_stub.rs\"]\npub mod traces;\npub mod undo;\npub mod upgrade;\npub mod upstream;\npub mod url_inspect;\npub mod usage;\npub mod vcs;\npub mod watchers;\npub mod web;\npub mod workflow;\n\n/// Initialize tracing with a default filter if `RUST_LOG` is unset.\npub fn init_tracing() {\n let default_filter = \"flowd=info,axum=warn,tower=warn\";\n let filter_layer = std::env::var(\"RUST_LOG\").unwrap_or_else(|_| default_filter.to_string());\n\n tracing_subscriber::fmt()\n .with_env_filter(filter_layer)\n .with_target(false)\n .compact()\n .init();\n}\n" }, { "path": "src/lifecycle.rs", "content": "use std::net::IpAddr;\nuse std::path::{Path, PathBuf};\nuse std::sync::{Mutex, OnceLock};\n\nuse anyhow::{Context, Result, anyhow, bail};\n\nuse crate::{\n cli::{\n DomainsAction, DomainsAddOpts, DomainsCommand, DomainsEngineArg, DomainsRmOpts, KillOpts,\n LifecycleRunOpts, TaskRunOpts,\n },\n config::{self, Config, LifecycleDomainsConfig},\n domains, processes, tasks,\n};\n\nstatic RUNTIME_PREFERRED_URL: OnceLock<Mutex<Option<String>>> = OnceLock::new();\n\npub fn run_up(opts: LifecycleRunOpts) -> Result<()> {\n let project = resolve_project_config(&opts.config)?;\n let lifecycle = project.config.lifecycle.clone().unwrap_or_default();\n let preferred_url = if let Some(domains_cfg) = lifecycle.domains.as_ref() {\n match ensure_domains_up(domains_cfg) {\n Ok(()) => lifecycle_preferred_url(domains_cfg),\n Err(err) => {\n eprintln!(\n \"WARN lifecycle domains unavailable; continuing without localhost routing\"\n );\n eprintln!(\"WARN {}\", err);\n None\n }\n }\n } else {\n None\n };\n let _preferred_url_guard = ScopedPreferredUrl::set(preferred_url);\n\n let ran_task = match lifecycle.up_task.as_deref() {\n Some(task) => run_required_task(&project.flow_path, task, opts.args)?,\n None => run_optional_task_chain(&project.flow_path, &[\"up\", \"dev\"], opts.args)?,\n };\n\n if !ran_task {\n bail!(\n \"No lifecycle up task found. Define task 'up' or 'dev', or set [lifecycle].up_task in {}\",\n project.flow_path.display()\n );\n }\n\n Ok(())\n}\n\npub fn run_down(opts: LifecycleRunOpts) -> Result<()> {\n let project = resolve_project_config(&opts.config)?;\n let lifecycle = project.config.lifecycle.clone().unwrap_or_default();\n\n let mut task_ran = match lifecycle.down_task.as_deref() {\n Some(task) => run_required_task(&project.flow_path, task, opts.args.clone())?,\n None => run_optional_task_chain(&project.flow_path, &[\"down\"], opts.args.clone())?,\n };\n\n if !task_ran && lifecycle.down_task.is_none() {\n processes::kill_processes(KillOpts {\n config: project.flow_path.clone(),\n task: None,\n pid: None,\n all: true,\n force: false,\n timeout: 5,\n })?;\n task_ran = true;\n }\n\n let mut domain_action_ran = false;\n if let Some(domains_cfg) = lifecycle.domains.as_ref() {\n domain_action_ran = run_domains_down(domains_cfg)?;\n }\n\n if !task_ran && !domain_action_ran {\n bail!(\n \"No lifecycle down action found. Define task 'down', set [lifecycle].down_task, or enable [lifecycle.domains] cleanup in {}\",\n project.flow_path.display()\n );\n }\n\n Ok(())\n}\n\nfn run_required_task(config_path: &Path, task_name: &str, args: Vec<String>) -> Result<bool> {\n match run_task(config_path, task_name, args) {\n Ok(()) => Ok(true),\n Err(err) if is_task_not_found(&err) => {\n bail!(\"lifecycle task '{}' not found\", task_name);\n }\n Err(err) => Err(err),\n }\n}\n\nfn run_optional_task_chain(\n config_path: &Path,\n candidates: &[&str],\n args: Vec<String>,\n) -> Result<bool> {\n for name in candidates {\n match run_task(config_path, name, args.clone()) {\n Ok(()) => return Ok(true),\n Err(err) if is_task_not_found(&err) => continue,\n Err(err) => return Err(err),\n }\n }\n Ok(false)\n}\n\nfn run_task(config_path: &Path, task_name: &str, args: Vec<String>) -> Result<()> {\n tasks::run(TaskRunOpts {\n config: config_path.to_path_buf(),\n delegate_to_hub: false,\n hub_host: IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: task_name.to_string(),\n args,\n })\n}\n\nfn ensure_domains_up(cfg: &LifecycleDomainsConfig) -> Result<()> {\n let host = lifecycle_domain_host(cfg)?;\n let target = lifecycle_domain_target(cfg)?;\n let engine = parse_domains_engine(cfg.engine.as_deref())?;\n\n add_lifecycle_route(engine, host, target)?;\n for alias in &cfg.aliases {\n let alias_host = alias\n .host\n .as_deref()\n .map(str::trim)\n .filter(|v| !v.is_empty())\n .ok_or_else(|| anyhow!(\"lifecycle.domains.aliases[].host is required\"))?;\n let alias_target = alias\n .target\n .as_deref()\n .map(str::trim)\n .filter(|v| !v.is_empty())\n .ok_or_else(|| anyhow!(\"lifecycle.domains.aliases[].target is required\"))?;\n add_lifecycle_route(engine, alias_host, alias_target)?;\n }\n\n domains::run(DomainsCommand {\n engine,\n action: Some(DomainsAction::Up),\n })?;\n\n println!(\"Lifecycle domains ready: http://{}\", host);\n\n Ok(())\n}\n\nfn lifecycle_preferred_url(cfg: &LifecycleDomainsConfig) -> Option<String> {\n let host = lifecycle_domain_host(cfg).ok()?;\n Some(format!(\"http://{}\", host))\n}\n\nfn run_domains_down(cfg: &LifecycleDomainsConfig) -> Result<bool> {\n let mut changed = false;\n let engine = parse_domains_engine(cfg.engine.as_deref())?;\n\n if cfg.remove_on_down.unwrap_or(false) {\n let host = lifecycle_domain_host(cfg)\n .map_err(|_| anyhow!(\"lifecycle.domains.host is required when remove_on_down=true\"))?;\n remove_lifecycle_route(engine, host)?;\n for alias in &cfg.aliases {\n let alias_host = alias\n .host\n .as_deref()\n .map(str::trim)\n .filter(|v| !v.is_empty())\n .ok_or_else(|| {\n anyhow!(\"lifecycle.domains.aliases[].host is required when remove_on_down=true\")\n })?;\n remove_lifecycle_route(engine, alias_host)?;\n }\n changed = true;\n }\n\n if cfg.stop_proxy_on_down.unwrap_or(false) {\n domains::run(DomainsCommand {\n engine,\n action: Some(DomainsAction::Down),\n })?;\n changed = true;\n }\n\n Ok(changed)\n}\n\nfn lifecycle_domain_host(cfg: &LifecycleDomainsConfig) -> Result<&str> {\n cfg.host\n .as_deref()\n .map(str::trim)\n .filter(|v| !v.is_empty())\n .ok_or_else(|| anyhow!(\"lifecycle.domains.host is required\"))\n}\n\nfn lifecycle_domain_target(cfg: &LifecycleDomainsConfig) -> Result<&str> {\n cfg.target\n .as_deref()\n .map(str::trim)\n .filter(|v| !v.is_empty())\n .ok_or_else(|| anyhow!(\"lifecycle.domains.target is required\"))\n}\n\nfn add_lifecycle_route(engine: Option<DomainsEngineArg>, host: &str, target: &str) -> Result<()> {\n domains::run(DomainsCommand {\n engine,\n action: Some(DomainsAction::Add(DomainsAddOpts {\n host: host.to_string(),\n target: target.to_string(),\n replace: true,\n })),\n })\n}\n\nfn remove_lifecycle_route(engine: Option<DomainsEngineArg>, host: &str) -> Result<()> {\n domains::run(DomainsCommand {\n engine,\n action: Some(DomainsAction::Rm(DomainsRmOpts {\n host: host.to_string(),\n })),\n })\n}\n\nfn parse_domains_engine(raw: Option<&str>) -> Result<Option<DomainsEngineArg>> {\n let Some(raw) = raw else {\n return Ok(None);\n };\n let engine = match raw.trim().to_ascii_lowercase().as_str() {\n \"docker\" => DomainsEngineArg::Docker,\n \"native\" => DomainsEngineArg::Native,\n other => bail!(\n \"invalid lifecycle.domains.engine '{}': expected 'docker' or 'native'\",\n other\n ),\n };\n Ok(Some(engine))\n}\n\nfn resolve_project_config(config_arg: &Path) -> Result<ProjectConfig> {\n let cwd = std::env::current_dir().context(\"Failed to read current directory\")?;\n let flow_path = resolve_flow_path(config_arg, &cwd)?;\n let cfg = config::load(&flow_path)\n .with_context(|| format!(\"Failed to load {}\", flow_path.display()))?;\n Ok(ProjectConfig {\n flow_path,\n config: cfg,\n })\n}\n\nfn resolve_flow_path(config_arg: &Path, cwd: &Path) -> Result<PathBuf> {\n if config_arg.is_absolute() {\n if config_arg.exists() {\n return Ok(config_arg.to_path_buf());\n }\n bail!(\"config path not found: {}\", config_arg.display());\n }\n\n let direct = cwd.join(config_arg);\n if direct.exists() {\n return Ok(direct);\n }\n\n if config_arg == Path::new(\"flow.toml\") {\n if let Some(found) = find_flow_toml_upwards(cwd) {\n return Ok(found);\n }\n }\n\n bail!(\"config path not found: {}\", direct.display());\n}\n\nfn find_flow_toml_upwards(start: &Path) -> Option<PathBuf> {\n let mut cur = start.to_path_buf();\n loop {\n let cand = cur.join(\"flow.toml\");\n if cand.exists() {\n return Some(cand);\n }\n if !cur.pop() {\n break;\n }\n }\n None\n}\n\nfn is_task_not_found(err: &anyhow::Error) -> bool {\n let msg = err.to_string().to_ascii_lowercase();\n msg.contains(\"task '\") && msg.contains(\"not found\")\n}\n\npub(crate) fn runtime_preferred_url() -> Option<String> {\n preferred_url_slot()\n .lock()\n .unwrap_or_else(|e| e.into_inner())\n .clone()\n}\n\nfn preferred_url_slot() -> &'static Mutex<Option<String>> {\n RUNTIME_PREFERRED_URL.get_or_init(|| Mutex::new(None))\n}\n\nstruct ScopedPreferredUrl {\n prev: Option<String>,\n}\n\nimpl ScopedPreferredUrl {\n fn set(value: Option<String>) -> Self {\n let mut guard = preferred_url_slot()\n .lock()\n .unwrap_or_else(|e| e.into_inner());\n let prev = guard.clone();\n *guard = value;\n Self { prev }\n }\n}\n\nimpl Drop for ScopedPreferredUrl {\n fn drop(&mut self) {\n let mut guard = preferred_url_slot()\n .lock()\n .unwrap_or_else(|e| e.into_inner());\n *guard = self.prev.clone();\n }\n}\n\nstruct ProjectConfig {\n flow_path: PathBuf,\n config: Config,\n}\n" }, { "path": "src/lmstudio.rs", "content": "//! Simple LM Studio API client for task matching.\n\nuse anyhow::{Context, Result};\nuse reqwest::blocking::Client;\nuse serde::{Deserialize, Serialize};\n\nconst DEFAULT_PORT: u16 = 1234;\nconst DEFAULT_MODEL: &str = \"qwen3-8b\";\n\n#[derive(Debug, Serialize)]\nstruct ChatRequest {\n model: String,\n messages: Vec<ChatMessage>,\n temperature: f32,\n}\n\n#[derive(Debug, Serialize)]\nstruct ChatMessage {\n role: String,\n content: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ChatResponse {\n choices: Vec<Choice>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct Choice {\n message: Option<ResponseMessage>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ResponseMessage {\n content: String,\n}\n\n/// Send a prompt to LM Studio and get a response.\npub fn quick_prompt(prompt: &str, model: Option<&str>, port: Option<u16>) -> Result<String> {\n let prompt = prompt.trim();\n let model = model.unwrap_or(DEFAULT_MODEL);\n let port = port.unwrap_or(DEFAULT_PORT);\n\n let client = Client::builder()\n .timeout(std::time::Duration::from_secs(30))\n .build()\n .context(\"failed to create HTTP client\")?;\n\n let url = format!(\"http://localhost:{port}/v1/chat/completions\");\n\n let body = ChatRequest {\n model: model.to_string(),\n messages: vec![ChatMessage {\n role: \"user\".to_string(),\n content: prompt.to_string(),\n }],\n temperature: 0.1, // Low temperature for deterministic task matching\n };\n\n let resp = client\n .post(&url)\n .json(&body)\n .send()\n .with_context(|| format!(\"failed to connect to LM Studio at localhost:{port}\"))?;\n\n if !resp.status().is_success() {\n anyhow::bail!(\n \"LM Studio returned status {}: {}\",\n resp.status(),\n resp.text().unwrap_or_default()\n );\n }\n\n let text_body = resp.text().context(\"failed to read LM Studio response\")?;\n let parsed: ChatResponse =\n serde_json::from_str(&text_body).context(\"failed to parse LM Studio response\")?;\n\n let text = parsed\n .choices\n .first()\n .and_then(|c| c.message.as_ref())\n .map(|m| m.content.trim().to_string())\n .unwrap_or_default();\n\n Ok(text)\n}\n\n/// Check if LM Studio is running and accessible.\n#[allow(dead_code)]\npub fn is_available(port: Option<u16>) -> bool {\n let port = port.unwrap_or(DEFAULT_PORT);\n let client = match Client::builder()\n .timeout(std::time::Duration::from_secs(2))\n .build()\n {\n Ok(c) => c,\n Err(_) => return false,\n };\n\n let url = format!(\"http://localhost:{port}/v1/models\");\n client\n .get(&url)\n .send()\n .map(|r| r.status().is_success())\n .unwrap_or(false)\n}\n" }, { "path": "src/log_server.rs", "content": "use std::fs;\nuse std::net::SocketAddr;\nuse std::path::PathBuf;\nuse std::process::Command;\nuse std::sync::Arc;\nuse std::sync::atomic::{AtomicI64, Ordering};\nuse std::time::Duration;\n\nuse anyhow::{Context, Result, bail};\nuse axum::{\n Router,\n extract::{Json as AxumJson, Path as AxumPath, Query, State},\n http::{Method, StatusCode},\n response::{\n IntoResponse, Json,\n sse::{Event, KeepAlive, Sse},\n },\n routing::{get, post},\n};\nuse futures::stream::{self, Stream, StreamExt};\nuse reqwest::blocking::Client;\nuse serde::Deserialize;\nuse serde_json::json;\nuse tower_http::cors::{Any, CorsLayer};\n\nuse crate::cli::{ServerAction, ServerOpts};\nuse crate::log_store::{self, LogEntry, LogQuery};\nuse crate::pr_edit::PrEditService;\nuse crate::{ai, config, daemon_snapshot, explain_commits, projects, skills, workflow};\n\n#[derive(Clone)]\nstruct AppState {\n pr_edit: Arc<tokio::sync::RwLock<Option<Arc<PrEditService>>>>,\n pr_edit_error: Arc<tokio::sync::RwLock<Option<String>>>,\n}\n\n/// Run the flow HTTP server for log ingestion.\npub fn run(opts: ServerOpts) -> Result<()> {\n let host = opts.host.clone();\n let port = opts.port;\n\n match opts.action {\n Some(ServerAction::Stop) => stop_server(),\n Some(ServerAction::Foreground) => run_foreground(&host, port),\n None => ensure_server(&host, port),\n }\n}\n\n/// Ensure server is running in background, start if not\nfn ensure_server(host: &str, port: u16) -> Result<()> {\n if server_healthy(host, port) {\n println!(\"Flow server already running at http://{}:{}\", host, port);\n return Ok(());\n }\n\n // Kill stale process if exists\n if let Some(pid) = load_server_pid()? {\n if process_alive(pid) {\n terminate_process(pid).ok();\n }\n remove_server_pid().ok();\n }\n\n // Start in background\n let exe = std::env::current_exe().context(\"failed to get current exe\")?;\n let mut cmd = Command::new(exe);\n cmd.arg(\"server\")\n .arg(\"--host\")\n .arg(host)\n .arg(\"--port\")\n .arg(port.to_string())\n .arg(\"foreground\")\n .stdin(std::process::Stdio::null())\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null());\n\n let child = cmd.spawn().context(\"failed to start server process\")?;\n persist_server_pid(child.id())?;\n\n // Wait for health\n for _ in 0..20 {\n std::thread::sleep(Duration::from_millis(100));\n if server_healthy(host, port) {\n println!(\"Flow server started at http://{}:{}\", host, port);\n return Ok(());\n }\n }\n\n println!(\n \"Flow server starting at http://{}:{} (may take a moment)\",\n host, port\n );\n Ok(())\n}\n\n/// Run server in foreground (used by background process)\nfn run_foreground(host: &str, port: u16) -> Result<()> {\n // Initialize database and schema on startup\n let conn = log_store::open_log_db().context(\"failed to initialize log database\")?;\n drop(conn);\n\n let addr: SocketAddr = format!(\"{}:{}\", host, port)\n .parse()\n .context(\"invalid host:port\")?;\n\n let rt = tokio::runtime::Runtime::new().context(\"failed to create tokio runtime\")?;\n\n rt.block_on(async {\n let cors = CorsLayer::new()\n .allow_origin(Any)\n .allow_methods([Method::GET, Method::POST, Method::OPTIONS])\n .allow_headers(Any);\n\n // Start PR edit watcher in the background so it can never block the server startup.\n let pr_edit = Arc::new(tokio::sync::RwLock::new(None));\n let pr_edit_error = Arc::new(tokio::sync::RwLock::new(None));\n {\n let pr_edit = Arc::clone(&pr_edit);\n let pr_edit_error = Arc::clone(&pr_edit_error);\n tokio::spawn(async move {\n match PrEditService::start().await {\n Ok(svc) => {\n *pr_edit.write().await = Some(svc);\n *pr_edit_error.write().await = None;\n tracing::info!(\"pr-edit watcher started\");\n }\n Err(err) => {\n *pr_edit_error.write().await = Some(format!(\"{err:#}\"));\n tracing::warn!(?err, \"failed to start pr-edit watcher\");\n }\n }\n });\n }\n let state = AppState {\n pr_edit,\n pr_edit_error,\n };\n\n let router = Router::new()\n .route(\"/health\", get(health))\n .route(\"/codex/skills\", get(codex_skills))\n .route(\"/codex/eval\", get(codex_eval))\n .route(\"/codex/resolve\", post(codex_resolve))\n .route(\"/codex/skills/sync\", post(codex_skills_sync))\n .route(\"/codex/skills/reload\", post(codex_skills_reload))\n .route(\"/daemons\", get(daemons))\n .route(\"/daemons/{name}/start\", post(daemon_start))\n .route(\"/daemons/{name}/stop\", post(daemon_stop))\n .route(\"/daemons/{name}/restart\", post(daemon_restart))\n .route(\"/logs/ingest\", post(logs_ingest))\n .route(\"/logs/query\", get(logs_query))\n .route(\"/logs/errors/stream\", get(logs_errors_stream))\n .route(\"/pr-edit/status\", get(pr_edit_status))\n .route(\"/pr-edit/rescan\", post(pr_edit_rescan))\n // Flow projects + AI sessions\n .route(\"/projects\", get(projects_list_all))\n .route(\"/projects/{name}/sessions\", get(project_sessions))\n .route(\"/sessions/{id}\", get(session_detail))\n .route(\"/workflow/overview\", get(workflow_overview))\n .route(\n \"/projects/{name}/commit-explanations\",\n get(project_commit_explanations),\n )\n .route(\n \"/projects/{name}/commit-explanations/{sha}\",\n get(project_commit_explanation_detail),\n )\n .layer(cors)\n .with_state(state);\n\n let listener = tokio::net::TcpListener::bind(addr)\n .await\n .context(\"failed to bind server\")?;\n\n axum::serve(listener, router)\n .await\n .context(\"server error\")?;\n\n Ok(())\n })\n}\n\nfn stop_server() -> Result<()> {\n if let Some(pid) = load_server_pid()? {\n terminate_process(pid).ok();\n remove_server_pid().ok();\n println!(\"Flow server stopped\");\n } else {\n println!(\"Flow server not running\");\n }\n Ok(())\n}\n\nfn server_pid_path() -> PathBuf {\n std::env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".config/flow/server.pid\")\n}\n\nfn load_server_pid() -> Result<Option<u32>> {\n let path = server_pid_path();\n if !path.exists() {\n return Ok(None);\n }\n let contents = fs::read_to_string(&path)?;\n let pid: u32 = contents.trim().parse().unwrap_or(0);\n Ok(if pid == 0 { None } else { Some(pid) })\n}\n\nfn persist_server_pid(pid: u32) -> Result<()> {\n let path = server_pid_path();\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n fs::write(&path, pid.to_string())?;\n Ok(())\n}\n\nfn remove_server_pid() -> Result<()> {\n let path = server_pid_path();\n if path.exists() {\n fs::remove_file(path).ok();\n }\n Ok(())\n}\n\nfn server_healthy(host: &str, port: u16) -> bool {\n let url = format!(\"http://{}:{}/health\", host, port);\n Client::builder()\n .timeout(Duration::from_millis(500))\n .build()\n .ok()\n .and_then(|c| c.get(&url).send().ok())\n .map(|r| r.status().is_success())\n .unwrap_or(false)\n}\n\nfn process_alive(pid: u32) -> bool {\n Command::new(\"kill\")\n .arg(\"-0\")\n .arg(pid.to_string())\n .status()\n .map(|s| s.success())\n .unwrap_or(false)\n}\n\nfn terminate_process(pid: u32) -> Result<()> {\n let status = Command::new(\"kill\")\n .arg(pid.to_string())\n .status()\n .context(\"failed to kill process\")?;\n if status.success() {\n Ok(())\n } else {\n bail!(\"kill failed\")\n }\n}\n\nasync fn health() -> impl IntoResponse {\n Json(json!({ \"status\": \"ok\" }))\n}\n\n#[derive(Debug, Deserialize)]\nstruct CodexSkillsQuery {\n path: Option<String>,\n limit: Option<usize>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct CodexEvalQuery {\n path: Option<String>,\n limit: Option<usize>,\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct CodexSkillsSyncRequest {\n path: Option<String>,\n #[serde(default)]\n skills: Vec<String>,\n #[serde(default)]\n force: bool,\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct CodexSkillsReloadRequest {\n path: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct CodexResolveRequest {\n path: Option<String>,\n query: String,\n #[serde(default)]\n exact_cwd: bool,\n}\n\nfn resolve_codex_skills_target(path: Option<&str>) -> PathBuf {\n let candidate = path\n .map(config::expand_path)\n .unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| config::expand_path(\"~\")));\n if candidate.is_absolute() {\n candidate\n } else {\n std::env::current_dir()\n .unwrap_or_else(|_| config::expand_path(\"~\"))\n .join(candidate)\n }\n}\n\nasync fn codex_skills(Query(query): Query<CodexSkillsQuery>) -> impl IntoResponse {\n let target_path = resolve_codex_skills_target(query.path.as_deref());\n let limit = query.limit.unwrap_or(12).clamp(1, 50);\n let result = tokio::task::spawn_blocking(move || {\n ai::codex_skills_dashboard_snapshot(&target_path, limit)\n })\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"codex skills task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn codex_eval(Query(query): Query<CodexEvalQuery>) -> impl IntoResponse {\n let target_path = resolve_codex_skills_target(query.path.as_deref());\n let limit = query.limit.unwrap_or(200).clamp(20, 1000);\n let result = tokio::task::spawn_blocking(move || ai::codex_eval_snapshot(&target_path, limit))\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"codex eval task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn codex_resolve(AxumJson(payload): AxumJson<CodexResolveRequest>) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n ai::codex_resolve_inspector(payload.path, payload.query, payload.exact_cwd)\n })\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"codex resolve task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn codex_skills_sync(AxumJson(payload): AxumJson<CodexSkillsSyncRequest>) -> impl IntoResponse {\n let target_path = resolve_codex_skills_target(payload.path.as_deref());\n let result = tokio::task::spawn_blocking(move || {\n let installed = ai::codex_skill_source_sync(&target_path, &payload.skills, payload.force)?;\n Ok::<_, anyhow::Error>(json!({\n \"targetPath\": target_path.display().to_string(),\n \"installed\": installed,\n }))\n })\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(snapshot)).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"codex skills sync task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn codex_skills_reload(\n AxumJson(payload): AxumJson<CodexSkillsReloadRequest>,\n) -> impl IntoResponse {\n let target_path = resolve_codex_skills_target(payload.path.as_deref());\n let result = tokio::task::spawn_blocking(move || {\n let reloaded = skills::reload_codex_skills_for_cwd(&target_path)?;\n Ok::<_, anyhow::Error>(json!({\n \"targetPath\": target_path.display().to_string(),\n \"reloaded\": reloaded,\n }))\n })\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(snapshot)).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"codex skills reload task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn daemons() -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(|| daemon_snapshot::load_daemon_snapshot(None)).await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"daemon snapshot task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn daemon_start(AxumPath(name): AxumPath<String>) -> impl IntoResponse {\n daemon_action_response(name, daemon_snapshot::FlowDaemonAction::Start).await\n}\n\nasync fn daemon_stop(AxumPath(name): AxumPath<String>) -> impl IntoResponse {\n daemon_action_response(name, daemon_snapshot::FlowDaemonAction::Stop).await\n}\n\nasync fn daemon_restart(AxumPath(name): AxumPath<String>) -> impl IntoResponse {\n daemon_action_response(name, daemon_snapshot::FlowDaemonAction::Restart).await\n}\n\nasync fn daemon_action_response(\n name: String,\n action: daemon_snapshot::FlowDaemonAction,\n) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n daemon_snapshot::run_daemon_action(&name, action, None)\n })\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"daemon action task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn pr_edit_status(State(state): State<AppState>) -> impl IntoResponse {\n let guard = state.pr_edit.read().await;\n match guard.as_ref() {\n Some(svc) => (StatusCode::OK, Json(svc.status_snapshot().await)).into_response(),\n None => {\n let err = state.pr_edit_error.read().await.clone();\n (\n StatusCode::SERVICE_UNAVAILABLE,\n Json(json!({ \"error\": \"pr-edit watcher not running\", \"detail\": err })),\n )\n .into_response()\n }\n }\n}\n\nasync fn pr_edit_rescan(State(state): State<AppState>) -> impl IntoResponse {\n let guard = state.pr_edit.read().await;\n match guard.as_ref() {\n Some(svc) => match svc.rescan().await {\n Ok(()) => (StatusCode::OK, Json(json!({ \"ok\": true }))).into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n },\n None => {\n let err = state.pr_edit_error.read().await.clone();\n (\n StatusCode::SERVICE_UNAVAILABLE,\n Json(json!({ \"error\": \"pr-edit watcher not running\", \"detail\": err })),\n )\n .into_response()\n }\n }\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(untagged)]\nenum IngestRequest {\n Single(LogEntry),\n Batch(Vec<LogEntry>),\n}\n\nasync fn logs_ingest(Json(payload): Json<IngestRequest>) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n let mut conn = match log_store::open_log_db() {\n Ok(c) => c,\n Err(e) => return Err(e),\n };\n\n match payload {\n IngestRequest::Single(entry) => {\n let id = log_store::insert_log(&conn, &entry)?;\n Ok(json!({ \"inserted\": 1, \"ids\": [id] }))\n }\n IngestRequest::Batch(entries) => {\n let ids = log_store::insert_logs(&mut conn, &entries)?;\n Ok(json!({ \"inserted\": ids.len(), \"ids\": ids }))\n }\n }\n })\n .await;\n\n match result {\n Ok(Ok(response)) => (StatusCode::OK, Json(response)).into_response(),\n Ok(Err(err)) => {\n tracing::error!(?err, \"log ingest failed\");\n (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response()\n }\n Err(err) => {\n tracing::error!(?err, \"log ingest task panicked\");\n (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": \"internal error\" })),\n )\n .into_response()\n }\n }\n}\n\nasync fn logs_query(Query(query): Query<LogQuery>) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n let conn = log_store::open_log_db()?;\n log_store::query_logs(&conn, &query)\n })\n .await;\n\n match result {\n Ok(Ok(entries)) => (StatusCode::OK, Json(entries)).into_response(),\n Ok(Err(err)) => {\n tracing::error!(?err, \"log query failed\");\n (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response()\n }\n Err(err) => {\n tracing::error!(?err, \"log query task panicked\");\n (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": \"internal error\" })),\n )\n .into_response()\n }\n }\n}\n\n// ============================================================================\n// Flow Projects + AI Sessions\n// ============================================================================\n\n/// GET /projects - List all registered Flow projects.\nasync fn projects_list_all() -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(|| projects::list_projects()).await;\n match result {\n Ok(Ok(entries)) => (StatusCode::OK, Json(json!({ \"projects\": entries }))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n }\n}\n\n/// GET /projects/:name/sessions - List AI sessions for a project.\nasync fn project_sessions(AxumPath(name): AxumPath<String>) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n let project = projects::resolve_project(&name)?;\n let project = project.ok_or_else(|| anyhow::anyhow!(\"project not found: {}\", name))?;\n ai::get_sessions_for_web(&project.project_root)\n })\n .await;\n\n match result {\n Ok(Ok(sessions)) => (StatusCode::OK, Json(json!({ \"sessions\": sessions }))).into_response(),\n Ok(Err(err)) => {\n let status = if err.to_string().contains(\"not found\") {\n StatusCode::NOT_FOUND\n } else {\n StatusCode::INTERNAL_SERVER_ERROR\n };\n (status, Json(json!({ \"error\": err.to_string() }))).into_response()\n }\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n }\n}\n\n/// GET /workflow/overview - List repo/workspace/branch/PR workflow state for registered projects.\nasync fn workflow_overview() -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(workflow::load_workflow_overview).await;\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n }\n}\n\n#[derive(Debug, Deserialize)]\nstruct SessionDetailQuery {\n project: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct CommitExplanationsQuery {\n limit: Option<usize>,\n}\n\n/// GET /sessions/:id?project=/path/to/root - Get full session conversation.\nasync fn session_detail(\n AxumPath(session_id): AxumPath<String>,\n Query(query): Query<SessionDetailQuery>,\n) -> impl IntoResponse {\n let Some(project) = query\n .project\n .as_deref()\n .map(str::trim)\n .filter(|s| !s.is_empty())\n else {\n return (\n StatusCode::BAD_REQUEST,\n Json(json!({ \"error\": \"missing ?project= query parameter\" })),\n )\n .into_response();\n };\n let project_root = std::path::PathBuf::from(project);\n\n let result = tokio::task::spawn_blocking(move || {\n ai::get_sessions_for_web(&project_root)\n .map(|sessions| sessions.into_iter().find(|s| s.id == session_id))\n })\n .await;\n\n match result {\n Ok(Ok(Some(session))) => (StatusCode::OK, Json(json!(session))).into_response(),\n Ok(Ok(None)) => (\n StatusCode::NOT_FOUND,\n Json(json!({ \"error\": \"session not found\" })),\n )\n .into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n }\n}\n\n/// GET /projects/:name/commit-explanations?limit=50 - List commit explanations for a project.\nasync fn project_commit_explanations(\n AxumPath(name): AxumPath<String>,\n Query(query): Query<CommitExplanationsQuery>,\n) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n let project = projects::resolve_project(&name)?;\n let project = project.ok_or_else(|| anyhow::anyhow!(\"project not found: {}\", name))?;\n explain_commits::list_explained_commits(&project.project_root, query.limit)\n })\n .await;\n\n match result {\n Ok(Ok(commits)) => (StatusCode::OK, Json(json!({ \"commits\": commits }))).into_response(),\n Ok(Err(err)) => {\n let status = if err.to_string().contains(\"not found\") {\n StatusCode::NOT_FOUND\n } else {\n StatusCode::INTERNAL_SERVER_ERROR\n };\n (status, Json(json!({ \"error\": err.to_string() }))).into_response()\n }\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n }\n}\n\n/// GET /projects/:name/commit-explanations/:sha - Get one commit explanation by SHA/prefix.\nasync fn project_commit_explanation_detail(\n AxumPath((name, sha)): AxumPath<(String, String)>,\n) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n let project = projects::resolve_project(&name)?;\n let project = project.ok_or_else(|| anyhow::anyhow!(\"project not found: {}\", name))?;\n explain_commits::get_explained_commit(&project.project_root, &sha)\n })\n .await;\n\n match result {\n Ok(Ok(Some(commit))) => (StatusCode::OK, Json(json!(commit))).into_response(),\n Ok(Ok(None)) => (\n StatusCode::NOT_FOUND,\n Json(json!({ \"error\": \"commit explanation not found\" })),\n )\n .into_response(),\n Ok(Err(err)) => {\n let status = if err.to_string().contains(\"not found\") {\n StatusCode::NOT_FOUND\n } else {\n StatusCode::INTERNAL_SERVER_ERROR\n };\n (status, Json(json!({ \"error\": err.to_string() }))).into_response()\n }\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n }\n}\n\n/// SSE stream of error logs - polls DB and emits new errors\nasync fn logs_errors_stream() -> Sse<impl Stream<Item = Result<Event, std::convert::Infallible>>> {\n let last_id = Arc::new(AtomicI64::new(0));\n\n // Get current max ID to start from\n if let Ok(conn) = log_store::open_log_db() {\n if let Ok(entries) = log_store::query_logs(\n &conn,\n &LogQuery {\n log_type: Some(\"error\".to_string()),\n limit: 1,\n ..Default::default()\n },\n ) {\n if let Some(entry) = entries.first() {\n last_id.store(entry.id, Ordering::SeqCst);\n }\n }\n }\n\n let stream = stream::unfold(last_id, |last_id| async move {\n tokio::time::sleep(Duration::from_millis(500)).await;\n\n let current_last = last_id.load(Ordering::SeqCst);\n let new_errors = tokio::task::spawn_blocking(move || {\n let conn = match log_store::open_log_db() {\n Ok(c) => c,\n Err(_) => return Vec::new(),\n };\n\n log_store::query_logs(\n &conn,\n &LogQuery {\n log_type: Some(\"error\".to_string()),\n limit: 100,\n ..Default::default()\n },\n )\n .unwrap_or_default()\n .into_iter()\n .filter(|e| e.id > current_last)\n .collect::<Vec<_>>()\n })\n .await\n .unwrap_or_default();\n\n let events: Vec<Result<Event, std::convert::Infallible>> = new_errors\n .into_iter()\n .map(|entry| {\n last_id.store(\n entry.id.max(last_id.load(Ordering::SeqCst)),\n Ordering::SeqCst,\n );\n let data = serde_json::to_string(&entry).unwrap_or_default();\n Ok(Event::default().data(data))\n })\n .collect();\n\n Some((stream::iter(events), last_id))\n })\n .flatten();\n\n Sse::new(stream).keep_alive(KeepAlive::default())\n}\n" }, { "path": "src/log_store.rs", "content": "use anyhow::{Context, Result};\nuse rusqlite::{Connection, params};\nuse serde::{Deserialize, Serialize};\n\nuse crate::db;\nuse crate::secret_redact;\n\n/// A log entry for ingestion and storage.\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct LogEntry {\n pub project: String,\n pub content: String,\n pub timestamp: i64, // unix ms\n #[serde(rename = \"type\")]\n pub log_type: String, // \"log\" | \"error\"\n pub service: String, // task name or custom service\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub stack: Option<String>,\n #[serde(default = \"default_format\")]\n pub format: String, // \"json\" | \"text\"\n}\n\nfn default_format() -> String {\n \"text\".to_string()\n}\n\n/// Stored log entry with ID.\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct StoredLogEntry {\n pub id: i64,\n #[serde(flatten)]\n pub entry: LogEntry,\n}\n\n/// Query parameters for filtering logs.\n#[derive(Debug, Clone, Deserialize)]\npub struct LogQuery {\n pub project: Option<String>,\n pub service: Option<String>,\n #[serde(rename = \"type\")]\n pub log_type: Option<String>,\n pub since: Option<i64>, // timestamp ms\n pub until: Option<i64>, // timestamp ms\n #[serde(default = \"default_limit\")]\n pub limit: usize,\n #[serde(default)]\n pub offset: usize,\n}\n\nfn default_limit() -> usize {\n 100\n}\n\nimpl Default for LogQuery {\n fn default() -> Self {\n Self {\n project: None,\n service: None,\n log_type: None,\n since: None,\n until: None,\n limit: default_limit(),\n offset: 0,\n }\n }\n}\n\n/// Initialize the logs table schema.\npub fn init_schema(conn: &Connection) -> Result<()> {\n conn.execute_batch(\n r#\"\n CREATE TABLE IF NOT EXISTS logs (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n project TEXT NOT NULL,\n content TEXT NOT NULL,\n timestamp INTEGER NOT NULL,\n log_type TEXT NOT NULL,\n service TEXT NOT NULL,\n stack TEXT,\n format TEXT NOT NULL DEFAULT 'text'\n );\n CREATE INDEX IF NOT EXISTS idx_logs_project ON logs(project);\n CREATE INDEX IF NOT EXISTS idx_logs_timestamp ON logs(timestamp);\n CREATE INDEX IF NOT EXISTS idx_logs_type ON logs(log_type);\n CREATE INDEX IF NOT EXISTS idx_logs_service ON logs(service);\n \"#,\n )\n .context(\"failed to create logs schema\")?;\n Ok(())\n}\n\n/// Insert a single log entry.\npub fn insert_log(conn: &Connection, entry: &LogEntry) -> Result<i64> {\n let sanitized = sanitize_entry(entry);\n conn.execute(\n r#\"\n INSERT INTO logs (project, content, timestamp, log_type, service, stack, format)\n VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)\n \"#,\n params![\n sanitized.project,\n sanitized.content,\n sanitized.timestamp,\n sanitized.log_type,\n sanitized.service,\n sanitized.stack,\n sanitized.format,\n ],\n )\n .context(\"failed to insert log\")?;\n Ok(conn.last_insert_rowid())\n}\n\n/// Insert multiple log entries in a transaction.\npub fn insert_logs(conn: &mut Connection, entries: &[LogEntry]) -> Result<Vec<i64>> {\n let tx = conn.transaction()?;\n let mut ids = Vec::with_capacity(entries.len());\n\n for entry in entries {\n let sanitized = sanitize_entry(entry);\n tx.execute(\n r#\"\n INSERT INTO logs (project, content, timestamp, log_type, service, stack, format)\n VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)\n \"#,\n params![\n sanitized.project,\n sanitized.content,\n sanitized.timestamp,\n sanitized.log_type,\n sanitized.service,\n sanitized.stack,\n sanitized.format,\n ],\n )\n .context(\"failed to insert log\")?;\n ids.push(tx.last_insert_rowid());\n }\n\n tx.commit()?;\n Ok(ids)\n}\n\n/// Query logs with filters.\npub fn query_logs(conn: &Connection, query: &LogQuery) -> Result<Vec<StoredLogEntry>> {\n let mut sql = String::from(\n \"SELECT id, project, content, timestamp, log_type, service, stack, format FROM logs WHERE 1=1\",\n );\n let mut params_vec: Vec<Box<dyn rusqlite::ToSql>> = Vec::new();\n\n if let Some(ref project) = query.project {\n sql.push_str(\" AND project = ?\");\n params_vec.push(Box::new(project.clone()));\n }\n if let Some(ref service) = query.service {\n sql.push_str(\" AND service = ?\");\n params_vec.push(Box::new(service.clone()));\n }\n if let Some(ref log_type) = query.log_type {\n sql.push_str(\" AND log_type = ?\");\n params_vec.push(Box::new(log_type.clone()));\n }\n if let Some(since) = query.since {\n sql.push_str(\" AND timestamp >= ?\");\n params_vec.push(Box::new(since));\n }\n if let Some(until) = query.until {\n sql.push_str(\" AND timestamp <= ?\");\n params_vec.push(Box::new(until));\n }\n\n sql.push_str(\" ORDER BY timestamp DESC LIMIT ? OFFSET ?\");\n params_vec.push(Box::new(query.limit as i64));\n params_vec.push(Box::new(query.offset as i64));\n\n let params_refs: Vec<&dyn rusqlite::ToSql> = params_vec.iter().map(|p| p.as_ref()).collect();\n\n let mut stmt = conn.prepare(&sql)?;\n let rows = stmt.query_map(params_refs.as_slice(), |row| {\n let content: String = row.get(2)?;\n let stack: Option<String> = row.get(6)?;\n Ok(StoredLogEntry {\n id: row.get(0)?,\n entry: LogEntry {\n project: row.get(1)?,\n content: secret_redact::redact_text(&content),\n timestamp: row.get(3)?,\n log_type: row.get(4)?,\n service: row.get(5)?,\n stack: stack.map(|value| secret_redact::redact_text(&value)),\n format: row.get(7)?,\n },\n })\n })?;\n\n let mut entries = Vec::new();\n for row in rows {\n entries.push(row?);\n }\n Ok(entries)\n}\n\n/// Get error logs for a project (convenience function).\npub fn get_errors(conn: &Connection, project: &str, limit: usize) -> Result<Vec<StoredLogEntry>> {\n query_logs(\n conn,\n &LogQuery {\n project: Some(project.to_string()),\n log_type: Some(\"error\".to_string()),\n limit,\n ..Default::default()\n },\n )\n}\n\n/// Open database and ensure schema exists.\npub fn open_log_db() -> Result<Connection> {\n let conn = db::open_db()?;\n init_schema(&conn)?;\n Ok(conn)\n}\n\nfn sanitize_entry(entry: &LogEntry) -> LogEntry {\n LogEntry {\n project: entry.project.clone(),\n content: secret_redact::redact_text(&entry.content),\n timestamp: entry.timestamp,\n log_type: entry.log_type.clone(),\n service: entry.service.clone(),\n stack: entry\n .stack\n .as_ref()\n .map(|value| secret_redact::redact_text(value)),\n format: entry.format.clone(),\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn test_insert_and_query() {\n let conn = Connection::open_in_memory().unwrap();\n init_schema(&conn).unwrap();\n\n let entry = LogEntry {\n project: \"test-project\".to_string(),\n content: \"Test log message\".to_string(),\n timestamp: 1234567890000,\n log_type: \"log\".to_string(),\n service: \"web\".to_string(),\n stack: None,\n format: \"text\".to_string(),\n };\n\n let id = insert_log(&conn, &entry).unwrap();\n assert!(id > 0);\n\n let results = query_logs(\n &conn,\n &LogQuery {\n project: Some(\"test-project\".to_string()),\n ..Default::default()\n },\n )\n .unwrap();\n\n assert_eq!(results.len(), 1);\n assert_eq!(results[0].entry.content, \"Test log message\");\n }\n\n #[test]\n fn test_error_query() {\n let conn = Connection::open_in_memory().unwrap();\n init_schema(&conn).unwrap();\n\n let log_entry = LogEntry {\n project: \"test\".to_string(),\n content: \"Normal log\".to_string(),\n timestamp: 1000,\n log_type: \"log\".to_string(),\n service: \"api\".to_string(),\n stack: None,\n format: \"text\".to_string(),\n };\n\n let error_entry = LogEntry {\n project: \"test\".to_string(),\n content: \"Error occurred\".to_string(),\n timestamp: 2000,\n log_type: \"error\".to_string(),\n service: \"api\".to_string(),\n stack: Some(\"at main.rs:10\".to_string()),\n format: \"text\".to_string(),\n };\n\n insert_log(&conn, &log_entry).unwrap();\n insert_log(&conn, &error_entry).unwrap();\n\n let errors = get_errors(&conn, \"test\", 10).unwrap();\n assert_eq!(errors.len(), 1);\n assert_eq!(errors[0].entry.log_type, \"error\");\n }\n}\n" }, { "path": "src/logs.rs", "content": "use std::{\n io::{BufRead, BufReader},\n thread,\n time::Duration,\n};\n\nuse anyhow::{Context, Result, bail};\nuse reqwest::blocking::Client;\n\nuse crate::{\n cli::LogsOpts,\n servers::{LogLine, LogStream, ServerSnapshot},\n};\n\npub fn run(opts: LogsOpts) -> Result<()> {\n if opts.follow && opts.server.is_none() {\n bail!(\"--follow requires specifying --server <name>\");\n }\n\n let base_url = format!(\"http://{}:{}\", opts.host, opts.port);\n let use_color = !opts.no_color;\n let client = Client::builder()\n .timeout(std::time::Duration::from_secs(5))\n .build()\n .context(\"failed to build HTTP client\")?;\n\n if let Some(server) = opts.server.as_deref() {\n if opts.follow {\n stream_server_logs(server, opts.host, opts.port, use_color)?;\n } else {\n let logs = fetch_logs(&client, &base_url, server, opts.limit)?;\n print_logs(&logs, use_color);\n }\n return Ok(());\n }\n\n match fetch_all_logs(&client, &base_url, opts.limit) {\n Ok(logs) => print_logs(&logs, use_color),\n Err(err) => {\n eprintln!(\n \"failed to load aggregated logs: {err:?}\\nfallback: fetching per-server logs...\"\n );\n let servers = list_servers(&client, &base_url)?;\n for snapshot in servers {\n println!(\"== {} ==\", snapshot.name);\n let logs = fetch_logs(&client, &base_url, &snapshot.name, opts.limit)?;\n print_logs(&logs, use_color);\n println!();\n }\n }\n }\n\n Ok(())\n}\n\nfn list_servers(client: &Client, base: &str) -> Result<Vec<ServerSnapshot>> {\n client\n .get(format!(\"{base}/servers\"))\n .send()\n .context(\"failed to fetch server list\")?\n .error_for_status()\n .context(\"server list returned non-success status\")?\n .json::<Vec<ServerSnapshot>>()\n .context(\"failed to decode server list json\")\n}\n\nfn fetch_logs(client: &Client, base: &str, server: &str, limit: usize) -> Result<Vec<LogLine>> {\n client\n .get(format!(\"{base}/servers/{server}/logs\"))\n .query(&[(\"limit\", limit.to_string())])\n .send()\n .with_context(|| format!(\"failed to request logs for {server}\"))?\n .error_for_status()\n .with_context(|| format!(\"server {server} returned error status\"))?\n .json::<Vec<LogLine>>()\n .with_context(|| format!(\"failed to decode log payload for {server}\"))\n}\n\nfn fetch_all_logs(client: &Client, base: &str, limit: usize) -> Result<Vec<LogLine>> {\n client\n .get(format!(\"{base}/logs\"))\n .query(&[(\"limit\", limit.to_string())])\n .send()\n .context(\"failed to request aggregated logs\")?\n .error_for_status()\n .context(\"aggregated logs endpoint returned error status\")?\n .json::<Vec<LogLine>>()\n .context(\"failed to decode aggregated logs payload\")\n}\n\nfn stream_server_logs(server: &str, host: std::net::IpAddr, port: u16, color: bool) -> Result<()> {\n println!(\"Streaming logs for {server} (Ctrl+C to stop)...\");\n let client = Client::builder()\n .timeout(None)\n .build()\n .context(\"failed to build streaming client\")?;\n\n let url = format!(\"http://{host}:{port}/servers/{server}/logs/stream\");\n let mut backoff = Duration::from_secs(1);\n\n loop {\n match client.get(&url).send() {\n Ok(response) => match response.error_for_status() {\n Ok(resp) => {\n backoff = Duration::from_secs(1);\n let mut reader = BufReader::new(resp);\n let mut line = String::new();\n while reader.read_line(&mut line)? != 0 {\n if let Some(payload) = line.trim().strip_prefix(\"data:\") {\n let trimmed = payload.trim();\n if trimmed.is_empty() {\n line.clear();\n continue;\n }\n match serde_json::from_str::<LogLine>(trimmed) {\n Ok(entry) => print_log_line(&entry, color),\n Err(err) => eprintln!(\"failed to decode log entry: {err:?}\"),\n }\n }\n line.clear();\n }\n eprintln!(\"log stream closed, reconnecting...\");\n }\n Err(err) => {\n eprintln!(\"log stream error: {err}; retrying...\");\n }\n },\n Err(err) => {\n eprintln!(\"failed to connect to log stream: {err:?}\");\n }\n }\n\n thread::sleep(backoff);\n backoff = (backoff * 2).min(Duration::from_secs(30));\n }\n}\n\nfn print_logs(logs: &[LogLine], color: bool) {\n if logs.is_empty() {\n println!(\"(no logs)\\n\");\n return;\n }\n\n for line in logs {\n print_log_line(line, color);\n }\n}\n\nfn print_log_line(line: &LogLine, color: bool) {\n let stream = match line.stream {\n LogStream::Stdout => \"stdout\",\n LogStream::Stderr => \"stderr\",\n };\n if color {\n match line.stream {\n LogStream::Stdout => {\n println!(\n \"\\x1b[38;5;36m[{}][stdout]\\x1b[0m {}\",\n line.server,\n line.line.trim_end()\n );\n }\n LogStream::Stderr => {\n println!(\"🔴 {}\", line.line.trim_end());\n }\n }\n } else {\n println!(\"[{}][{}] {}\", line.server, stream, line.line.trim_end());\n }\n}\n" }, { "path": "src/macos.rs", "content": "//! macOS launchd service management.\n//!\n//! Provides tools to list, audit, enable, and disable macOS launch agents and daemons.\n//! Helps keep the system clean by identifying bloatware and unwanted background processes.\n\nuse std::collections::HashMap;\nuse std::io::{self, IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\nuse serde::Serialize;\n\nuse crate::cli::{\n MacosAction, MacosAuditOpts, MacosCleanOpts, MacosCommand, MacosDisableOpts, MacosEnableOpts,\n MacosInfoOpts, MacosListOpts,\n};\nuse crate::config::{self, MacosConfig};\n\n/// Service location type.\n#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum ServiceType {\n /// ~/Library/LaunchAgents\n UserAgent,\n /// /Library/LaunchAgents\n SystemAgent,\n /// /Library/LaunchDaemons\n SystemDaemon,\n}\n\nimpl ServiceType {\n fn as_str(&self) -> &'static str {\n match self {\n ServiceType::UserAgent => \"user-agent\",\n ServiceType::SystemAgent => \"system-agent\",\n ServiceType::SystemDaemon => \"system-daemon\",\n }\n }\n\n fn requires_sudo(&self) -> bool {\n matches!(self, ServiceType::SystemAgent | ServiceType::SystemDaemon)\n }\n\n fn domain(&self) -> String {\n match self {\n ServiceType::UserAgent => format!(\"gui/{}\", get_uid()),\n ServiceType::SystemAgent | ServiceType::SystemDaemon => \"system\".to_string(),\n }\n }\n}\n\n/// Service category for classification.\n#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum ServiceCategory {\n Apple,\n Custom,\n Database,\n Docker,\n Vpn,\n Ai,\n Bloatware,\n Development,\n Unknown,\n}\n\nimpl ServiceCategory {\n fn as_str(&self) -> &'static str {\n match self {\n ServiceCategory::Apple => \"apple\",\n ServiceCategory::Custom => \"custom\",\n ServiceCategory::Database => \"database\",\n ServiceCategory::Docker => \"docker\",\n ServiceCategory::Vpn => \"vpn\",\n ServiceCategory::Ai => \"ai\",\n ServiceCategory::Bloatware => \"bloatware\",\n ServiceCategory::Development => \"development\",\n ServiceCategory::Unknown => \"unknown\",\n }\n }\n}\n\n/// Represents a discovered launchd service.\n#[derive(Debug, Clone, Serialize)]\npub struct LaunchdService {\n /// Service identifier (e.g., com.apple.Finder).\n pub id: String,\n /// Path to the plist file.\n pub plist_path: PathBuf,\n /// Whether the service is currently loaded.\n pub loaded: bool,\n /// Whether the service is currently running.\n pub running: bool,\n /// Process ID if running.\n pub pid: Option<u32>,\n /// Service type (user agent, system agent, system daemon).\n pub service_type: ServiceType,\n /// Service category.\n pub category: ServiceCategory,\n /// Program or ProgramArguments from plist.\n pub program: Option<String>,\n}\n\n/// Audit recommendation for a service.\n#[derive(Debug, Clone, Serialize)]\npub struct AuditRecommendation {\n pub service: LaunchdService,\n pub action: RecommendedAction,\n pub reason: String,\n}\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum RecommendedAction {\n Keep,\n Disable,\n Review,\n}\n\npub fn run(cmd: MacosCommand) -> Result<()> {\n match cmd.action {\n Some(MacosAction::List(opts)) => run_list(opts),\n Some(MacosAction::Status) => run_status(),\n Some(MacosAction::Audit(opts)) => run_audit(opts),\n Some(MacosAction::Info(opts)) => run_info(opts),\n Some(MacosAction::Disable(opts)) => run_disable(opts),\n Some(MacosAction::Enable(opts)) => run_enable(opts),\n Some(MacosAction::Clean(opts)) => run_clean(opts),\n None => run_status(),\n }\n}\n\nfn run_list(opts: MacosListOpts) -> Result<()> {\n let services = discover_services()?;\n\n let filtered: Vec<_> = services\n .into_iter()\n .filter(|s| {\n if opts.user && !matches!(s.service_type, ServiceType::UserAgent) {\n return false;\n }\n if opts.system && matches!(s.service_type, ServiceType::UserAgent) {\n return false;\n }\n true\n })\n .collect();\n\n if opts.json {\n println!(\"{}\", serde_json::to_string_pretty(&filtered)?);\n return Ok(());\n }\n\n println!(\"Discovered {} services\\n\", filtered.len());\n\n // Group by type\n let mut by_type: HashMap<&str, Vec<&LaunchdService>> = HashMap::new();\n for svc in &filtered {\n by_type\n .entry(svc.service_type.as_str())\n .or_default()\n .push(svc);\n }\n\n for (type_name, services) in by_type.iter() {\n println!(\"{}:\", type_name);\n for svc in services {\n let status = if svc.running {\n format!(\"running (pid {})\", svc.pid.unwrap_or(0))\n } else if svc.loaded {\n \"loaded\".to_string()\n } else {\n \"disabled\".to_string()\n };\n println!(\" {} [{}] - {}\", svc.id, svc.category.as_str(), status);\n }\n println!();\n }\n\n Ok(())\n}\n\nfn run_status() -> Result<()> {\n let services = discover_services()?;\n\n // Filter to non-Apple running services\n let running: Vec<_> = services\n .iter()\n .filter(|s| s.running && s.category != ServiceCategory::Apple)\n .collect();\n\n if running.is_empty() {\n println!(\"No non-Apple services currently running.\");\n return Ok(());\n }\n\n println!(\"Running non-Apple services:\\n\");\n for svc in running {\n let pid_str = svc.pid.map(|p| format!(\" (pid {})\", p)).unwrap_or_default();\n println!(\" {} [{}]{}\", svc.id, svc.category.as_str(), pid_str);\n if let Some(prog) = &svc.program {\n println!(\" {}\", prog);\n }\n }\n\n Ok(())\n}\n\nfn run_audit(opts: MacosAuditOpts) -> Result<()> {\n let services = discover_services()?;\n let macos_config = load_macos_config();\n let recommendations = audit_services(&services, &macos_config);\n\n if opts.json {\n println!(\"{}\", serde_json::to_string_pretty(&recommendations)?);\n return Ok(());\n }\n\n let to_disable: Vec<_> = recommendations\n .iter()\n .filter(|r| r.action == RecommendedAction::Disable)\n .collect();\n let to_review: Vec<_> = recommendations\n .iter()\n .filter(|r| r.action == RecommendedAction::Review)\n .collect();\n\n if to_disable.is_empty() && to_review.is_empty() {\n println!(\"All services look good! No recommendations.\");\n return Ok(());\n }\n\n if !to_disable.is_empty() {\n println!(\"Recommended to DISABLE ({}):\\n\", to_disable.len());\n for rec in &to_disable {\n println!(\" {} [{}]\", rec.service.id, rec.service.category.as_str());\n println!(\" Reason: {}\", rec.reason);\n }\n println!();\n }\n\n if !to_review.is_empty() {\n println!(\"Recommended to REVIEW ({}):\\n\", to_review.len());\n for rec in &to_review {\n println!(\" {} [{}]\", rec.service.id, rec.service.category.as_str());\n println!(\" Reason: {}\", rec.reason);\n }\n println!();\n }\n\n if !to_disable.is_empty() {\n println!(\n \"Run `f macos clean` to disable {} bloatware services.\",\n to_disable.len()\n );\n }\n\n Ok(())\n}\n\nfn run_info(opts: MacosInfoOpts) -> Result<()> {\n let services = discover_services()?;\n\n let svc = services\n .iter()\n .find(|s| s.id == opts.service)\n .ok_or_else(|| anyhow::anyhow!(\"Service '{}' not found\", opts.service))?;\n\n println!(\"Service: {}\", svc.id);\n println!(\"Type: {}\", svc.service_type.as_str());\n println!(\"Category:{}\", svc.category.as_str());\n println!(\"Plist: {}\", svc.plist_path.display());\n println!(\"Loaded: {}\", svc.loaded);\n println!(\"Running: {}\", svc.running);\n if let Some(pid) = svc.pid {\n println!(\"PID: {}\", pid);\n }\n if let Some(prog) = &svc.program {\n println!(\"Program: {}\", prog);\n }\n\n // Show plist content\n println!(\"\\nPlist contents:\");\n if let Ok(content) = std::fs::read_to_string(&svc.plist_path) {\n println!(\"{}\", content);\n }\n\n Ok(())\n}\n\nfn run_disable(opts: MacosDisableOpts) -> Result<()> {\n let services = discover_services()?;\n\n let svc = services\n .iter()\n .find(|s| s.id == opts.service)\n .ok_or_else(|| anyhow::anyhow!(\"Service '{}' not found\", opts.service))?;\n\n if svc.category == ServiceCategory::Apple {\n bail!(\n \"Refusing to disable Apple service '{}'. This could break your system.\",\n svc.id\n );\n }\n\n if !opts.yes {\n print!(\"Disable service '{}'? [y/N] \", svc.id);\n io::stdout().flush()?;\n\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n if !input.trim().eq_ignore_ascii_case(\"y\") {\n println!(\"Cancelled.\");\n return Ok(());\n }\n }\n\n disable_service(svc)?;\n println!(\"Disabled service '{}'\", svc.id);\n\n Ok(())\n}\n\nfn run_enable(opts: MacosEnableOpts) -> Result<()> {\n let services = discover_services()?;\n\n let svc = services\n .iter()\n .find(|s| s.id == opts.service)\n .ok_or_else(|| anyhow::anyhow!(\"Service '{}' not found\", opts.service))?;\n\n enable_service(svc)?;\n println!(\"Enabled service '{}'\", svc.id);\n\n Ok(())\n}\n\nfn run_clean(opts: MacosCleanOpts) -> Result<()> {\n let services = discover_services()?;\n let macos_config = load_macos_config();\n let recommendations = audit_services(&services, &macos_config);\n\n let to_disable: Vec<_> = recommendations\n .iter()\n .filter(|r| r.action == RecommendedAction::Disable)\n .collect();\n\n if to_disable.is_empty() {\n println!(\"No bloatware services found to clean.\");\n return Ok(());\n }\n\n println!(\"Services to disable ({}):\\n\", to_disable.len());\n for rec in &to_disable {\n println!(\" {} - {}\", rec.service.id, rec.reason);\n }\n println!();\n\n if opts.dry_run {\n println!(\"Dry run - no changes made.\");\n return Ok(());\n }\n\n if !opts.yes && io::stdin().is_terminal() {\n print!(\"Disable these {} services? [y/N] \", to_disable.len());\n io::stdout().flush()?;\n\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n if !input.trim().eq_ignore_ascii_case(\"y\") {\n println!(\"Cancelled.\");\n return Ok(());\n }\n }\n\n let mut disabled = 0;\n let mut failed = 0;\n for rec in to_disable {\n match disable_service(&rec.service) {\n Ok(()) => {\n println!(\"Disabled: {}\", rec.service.id);\n disabled += 1;\n }\n Err(e) => {\n eprintln!(\"Failed to disable {}: {}\", rec.service.id, e);\n failed += 1;\n }\n }\n }\n\n println!(\"\\nDisabled {} services, {} failed.\", disabled, failed);\n\n Ok(())\n}\n\n/// Discover all launchd services from the standard locations.\nfn discover_services() -> Result<Vec<LaunchdService>> {\n let mut services = Vec::new();\n\n // User agents\n if let Some(home) = dirs::home_dir() {\n let user_agents = home.join(\"Library/LaunchAgents\");\n if user_agents.exists() {\n discover_in_dir(&user_agents, ServiceType::UserAgent, &mut services)?;\n }\n }\n\n // System agents\n let system_agents = Path::new(\"/Library/LaunchAgents\");\n if system_agents.exists() {\n discover_in_dir(system_agents, ServiceType::SystemAgent, &mut services)?;\n }\n\n // System daemons\n let system_daemons = Path::new(\"/Library/LaunchDaemons\");\n if system_daemons.exists() {\n discover_in_dir(system_daemons, ServiceType::SystemDaemon, &mut services)?;\n }\n\n // Enrich with launchctl status\n enrich_with_launchctl_status(&mut services);\n\n Ok(services)\n}\n\nfn discover_in_dir(\n dir: &Path,\n service_type: ServiceType,\n services: &mut Vec<LaunchdService>,\n) -> Result<()> {\n let entries = std::fs::read_dir(dir)\n .with_context(|| format!(\"Failed to read directory: {}\", dir.display()))?;\n\n for entry in entries.flatten() {\n let path = entry.path();\n if path.extension().map(|e| e == \"plist\").unwrap_or(false) {\n if let Some(svc) = parse_plist(&path, service_type) {\n services.push(svc);\n }\n }\n }\n\n Ok(())\n}\n\n/// Parse a plist file and extract service information.\nfn parse_plist(path: &Path, service_type: ServiceType) -> Option<LaunchdService> {\n // Use plutil to convert to JSON\n let output = Command::new(\"plutil\")\n .args([\"-convert\", \"json\", \"-o\", \"-\"])\n .arg(path)\n .output()\n .ok()?;\n\n if !output.status.success() {\n return None;\n }\n\n let json: serde_json::Value = serde_json::from_slice(&output.stdout).ok()?;\n\n let label = json.get(\"Label\")?.as_str()?.to_string();\n let program = json\n .get(\"Program\")\n .and_then(|v| v.as_str())\n .map(|s| s.to_string())\n .or_else(|| {\n json.get(\"ProgramArguments\")\n .and_then(|v| v.as_array())\n .and_then(|arr| arr.first())\n .and_then(|v| v.as_str())\n .map(|s| s.to_string())\n });\n\n let category = categorize_service(&label);\n\n Some(LaunchdService {\n id: label,\n plist_path: path.to_path_buf(),\n loaded: false,\n running: false,\n pid: None,\n service_type,\n category,\n program,\n })\n}\n\n/// Enrich services with launchctl status information.\nfn enrich_with_launchctl_status(services: &mut [LaunchdService]) {\n // Query user domain\n let uid = get_uid();\n if let Ok(output) = Command::new(\"launchctl\").args([\"list\"]).output() {\n if output.status.success() {\n let stdout = String::from_utf8_lossy(&output.stdout);\n parse_launchctl_list(&stdout, services);\n }\n }\n\n // For system services, we need to check separately\n // (requires sudo for full info, but we can get some info without)\n if let Ok(_output) = Command::new(\"launchctl\")\n .args([\"print\", &format!(\"gui/{}\", uid)])\n .output()\n {\n // Parse the print output for more detailed status\n // (This is optional and provides additional detail)\n }\n}\n\nfn parse_launchctl_list(output: &str, services: &mut [LaunchdService]) {\n for line in output.lines().skip(1) {\n // Format: PID Status Label\n let parts: Vec<&str> = line.split_whitespace().collect();\n if parts.len() >= 3 {\n let pid_str = parts[0];\n let label = parts[2];\n\n if let Some(svc) = services.iter_mut().find(|s| s.id == label) {\n svc.loaded = true;\n if pid_str != \"-\" {\n if let Ok(pid) = pid_str.parse::<u32>() {\n svc.running = true;\n svc.pid = Some(pid);\n }\n }\n }\n }\n }\n}\n\n/// Categorize a service based on its identifier.\nfn categorize_service(label: &str) -> ServiceCategory {\n if label.starts_with(\"com.apple.\") {\n return ServiceCategory::Apple;\n }\n\n // Known bloatware patterns\n if is_known_bloatware(label) {\n return ServiceCategory::Bloatware;\n }\n\n // Database services\n if label.contains(\"postgres\")\n || label.contains(\"mysql\")\n || label.contains(\"redis\")\n || label.contains(\"mongo\")\n {\n return ServiceCategory::Database;\n }\n\n // Docker\n if label.contains(\"docker\") || label.contains(\"orbstack\") {\n return ServiceCategory::Docker;\n }\n\n // VPN\n if label.contains(\"vpn\")\n || label.contains(\"wireguard\")\n || label.contains(\"tailscale\")\n || label.contains(\"nordvpn\")\n {\n return ServiceCategory::Vpn;\n }\n\n // AI tools\n if label.contains(\"lmstudio\") || label.contains(\"ollama\") || label.contains(\"copilot\") {\n return ServiceCategory::Ai;\n }\n\n // Development\n if label.contains(\"homebrew\")\n || label.contains(\"nix\")\n || label.contains(\"watchman\")\n || label.contains(\"github\")\n {\n return ServiceCategory::Development;\n }\n\n ServiceCategory::Unknown\n}\n\n/// Check if a service is known bloatware.\nfn is_known_bloatware(label: &str) -> bool {\n let bloatware_patterns = [\n \"com.google.keystone\",\n \"com.google.GoogleUpdater\",\n \"com.adobe.ARMDC\",\n \"com.adobe.ARMDCHelper\",\n \"com.adobe.AdobeCreativeCloud\",\n \"com.adobe.acc\",\n \"us.zoom.ZoomDaemon\",\n \"us.zoom.updater\",\n \"com.microsoft.update\",\n \"com.microsoft.autoupdate\",\n \"com.dropbox.\",\n \"com.spotify.webhelper\",\n \"com.valvesoftware.steam\",\n \"com.skype.\",\n \"com.slack.update\",\n ];\n\n for pattern in bloatware_patterns {\n if label.starts_with(pattern) || label.contains(pattern) {\n return true;\n }\n }\n\n false\n}\n\n/// Audit services and generate recommendations.\nfn audit_services(\n services: &[LaunchdService],\n config: &Option<MacosConfig>,\n) -> Vec<AuditRecommendation> {\n let mut recommendations = Vec::new();\n\n for svc in services {\n // Skip Apple services\n if svc.category == ServiceCategory::Apple {\n continue;\n }\n\n // Check if explicitly allowed\n if let Some(cfg) = config {\n if is_pattern_match(&svc.id, &cfg.allowed) {\n continue;\n }\n }\n\n // Check if explicitly blocked\n if let Some(cfg) = config {\n if is_pattern_match(&svc.id, &cfg.blocked) {\n recommendations.push(AuditRecommendation {\n service: svc.clone(),\n action: RecommendedAction::Disable,\n reason: \"Matched blocked pattern in flow.toml\".to_string(),\n });\n continue;\n }\n }\n\n // Known bloatware\n if svc.category == ServiceCategory::Bloatware {\n recommendations.push(AuditRecommendation {\n service: svc.clone(),\n action: RecommendedAction::Disable,\n reason: \"Known bloatware/updater service\".to_string(),\n });\n continue;\n }\n\n // Unknown services that are running\n if svc.category == ServiceCategory::Unknown && svc.running {\n recommendations.push(AuditRecommendation {\n service: svc.clone(),\n action: RecommendedAction::Review,\n reason: \"Unknown running service\".to_string(),\n });\n }\n }\n\n recommendations\n}\n\n/// Check if a label matches any of the patterns.\nfn is_pattern_match(label: &str, patterns: &[String]) -> bool {\n for pattern in patterns {\n if pattern.ends_with('*') {\n let prefix = &pattern[..pattern.len() - 1];\n if label.starts_with(prefix) {\n return true;\n }\n } else if label == pattern {\n return true;\n }\n }\n false\n}\n\n/// Disable a launchd service.\nfn disable_service(svc: &LaunchdService) -> Result<()> {\n let domain = svc.service_type.domain();\n\n // First bootout (unload)\n if svc.loaded {\n let target = format!(\"{}/{}\", domain, svc.id);\n let mut cmd = if svc.service_type.requires_sudo() {\n let mut c = Command::new(\"sudo\");\n c.args([\"launchctl\", \"bootout\", &target]);\n c\n } else {\n let mut c = Command::new(\"launchctl\");\n c.args([\"bootout\", &target]);\n c\n };\n\n let output = cmd.output()?;\n if !output.status.success() {\n // Bootout may fail if not loaded, continue to disable\n let stderr = String::from_utf8_lossy(&output.stderr);\n if !stderr.contains(\"No such process\") && !stderr.contains(\"Could not find service\") {\n // Log but don't fail - the service might already be unloaded\n tracing::debug!(\"bootout warning: {}\", stderr);\n }\n }\n }\n\n // Then disable\n let target = format!(\"{}/{}\", domain, svc.id);\n let mut cmd = if svc.service_type.requires_sudo() {\n let mut c = Command::new(\"sudo\");\n c.args([\"launchctl\", \"disable\", &target]);\n c\n } else {\n let mut c = Command::new(\"launchctl\");\n c.args([\"disable\", &target]);\n c\n };\n\n let output = cmd.output()?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"Failed to disable service: {}\", stderr);\n }\n\n Ok(())\n}\n\n/// Enable a launchd service.\nfn enable_service(svc: &LaunchdService) -> Result<()> {\n let domain = svc.service_type.domain();\n\n // First enable\n let target = format!(\"{}/{}\", domain, svc.id);\n let mut cmd = if svc.service_type.requires_sudo() {\n let mut c = Command::new(\"sudo\");\n c.args([\"launchctl\", \"enable\", &target]);\n c\n } else {\n let mut c = Command::new(\"launchctl\");\n c.args([\"enable\", &target]);\n c\n };\n\n let output = cmd.output()?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"Failed to enable service: {}\", stderr);\n }\n\n // Then bootstrap (load)\n let mut cmd = if svc.service_type.requires_sudo() {\n let mut c = Command::new(\"sudo\");\n c.args([\"launchctl\", \"bootstrap\", &domain]);\n c.arg(&svc.plist_path);\n c\n } else {\n let mut c = Command::new(\"launchctl\");\n c.args([\"bootstrap\", &domain]);\n c.arg(&svc.plist_path);\n c\n };\n\n let output = cmd.output()?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n // Bootstrap may fail if already loaded\n if !stderr.contains(\"already loaded\") && !stderr.contains(\"service already loaded\") {\n bail!(\"Failed to bootstrap service: {}\", stderr);\n }\n }\n\n Ok(())\n}\n\n/// Get the current user's UID.\nfn get_uid() -> u32 {\n unsafe { libc::getuid() }\n}\n\n/// Load macOS config from global flow.toml.\nfn load_macos_config() -> Option<MacosConfig> {\n let config_path = config::default_config_path();\n if !config_path.exists() {\n return None;\n }\n\n let cfg = config::load_or_default(&config_path);\n cfg.macos\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn test_categorize_apple() {\n assert_eq!(\n categorize_service(\"com.apple.Finder\"),\n ServiceCategory::Apple\n );\n }\n\n #[test]\n fn test_categorize_bloatware() {\n assert_eq!(\n categorize_service(\"com.google.keystone.agent\"),\n ServiceCategory::Bloatware\n );\n assert_eq!(\n categorize_service(\"com.adobe.ARMDC.Agent\"),\n ServiceCategory::Bloatware\n );\n }\n\n #[test]\n fn test_is_known_bloatware() {\n assert!(is_known_bloatware(\"com.google.keystone.agent\"));\n assert!(is_known_bloatware(\"com.adobe.ARMDCHelper.plist\"));\n assert!(is_known_bloatware(\"us.zoom.ZoomDaemon\"));\n assert!(!is_known_bloatware(\"com.apple.Finder\"));\n }\n\n #[test]\n fn test_pattern_match() {\n let patterns = vec![\"com.nikiv.*\".to_string(), \"exact.match\".to_string()];\n\n assert!(is_pattern_match(\"com.nikiv.service\", &patterns));\n assert!(is_pattern_match(\"com.nikiv.other\", &patterns));\n assert!(is_pattern_match(\"exact.match\", &patterns));\n assert!(!is_pattern_match(\"com.other.service\", &patterns));\n }\n}\n" }, { "path": "src/main.rs", "content": "use std::net::IpAddr;\nuse std::path::Path;\nuse std::time::Instant;\n\nuse anyhow::{Result, bail};\nuse clap::{Parser, error::ErrorKind};\nuse flowd::{\n agents, ai, ai_test, analytics, archive, auth, branches, changes,\n cli::{\n Cli, Commands, InstallAction, ProxyAction, ProxyCommand, RerunOpts, ReviewAction,\n ShellAction, ShellCommand, TaskRunOpts, TasksOpts, TraceAction,\n },\n code, commit, commits, daemon, deploy, deps, docs, doctor, domains, env, explain_commits, ext,\n fish_install, fish_trace, fix, fixup, git_guard, gitignore_policy, hash, health, help_search,\n history, hive, home, hub, info, init, init_tracing, install, invariants, jj, latest, lifecycle,\n log_server, macos, notify, otp, palette, parallel, processes, projects, proxy, publish, push,\n recipe, registry, release, repos, reviews_todo, seq_rpc, services, setup, skills, ssh_keys,\n storage, supervisor, sync, task_match, tasks, todo, tools, traces, undo, upgrade, upstream,\n url_inspect, usage, web,\n};\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nstruct StartupPolicy {\n load_global_secrets: bool,\n sync_skills: bool,\n}\n\nimpl StartupPolicy {\n const NONE: Self = Self {\n load_global_secrets: false,\n sync_skills: false,\n };\n const SECRETS_ONLY: Self = Self {\n load_global_secrets: true,\n sync_skills: false,\n };\n const FULL: Self = Self {\n load_global_secrets: true,\n sync_skills: true,\n };\n}\n\nfn main() -> Result<()> {\n init_tracing();\n\n let raw_args: Vec<String> = std::env::args().collect();\n let analytics_capture = usage::command_capture(&raw_args);\n let is_analytics_command = usage::is_analytics_command(&raw_args);\n let started_at = Instant::now();\n\n let result = (|| -> Result<()> {\n // Handle `f ?` for fuzzy help search before clap parsing\n if raw_args.get(1).map(|s| s.as_str()) == Some(\"?\") {\n return help_search::run();\n }\n\n // Handle --help-full early for instant output\n if raw_args.iter().any(|s| s == \"--help-full\") {\n return help_search::print_full_json();\n }\n\n let cli = match Cli::try_parse_from(&raw_args) {\n Ok(cli) => cli,\n Err(err) => {\n if matches!(\n err.kind(),\n ErrorKind::UnknownArgument | ErrorKind::InvalidSubcommand\n ) {\n // Fallback: treat first positional as task name and rest as args.\n let mut iter = raw_args.into_iter();\n let _bin = iter.next();\n if let Some(task_name) = iter.next() {\n let args: Vec<String> = iter.collect();\n apply_startup_policy(StartupPolicy::SECRETS_ONLY);\n return tasks::run_with_discovery(&task_name, args);\n }\n }\n err.exit()\n }\n };\n\n apply_startup_policy(startup_policy_for(cli.command.as_ref()));\n\n match cli.command {\n Some(Commands::Hub(cmd)) => {\n hub::run(cmd)?;\n }\n Some(Commands::Init(opts)) => {\n init::run(opts)?;\n }\n Some(Commands::ShellInit(opts)) => {\n shell_init(&opts.shell);\n }\n Some(Commands::Shell(cmd)) => {\n shell_command(cmd);\n }\n Some(Commands::New(opts)) => {\n code::new_from_template(opts)?;\n }\n Some(Commands::Home(cmd)) => {\n home::run(cmd)?;\n }\n Some(Commands::Archive(opts)) => {\n archive::run(opts)?;\n }\n Some(Commands::Doctor(opts)) => {\n doctor::run(opts)?;\n }\n Some(Commands::Health(opts)) => {\n health::run(opts)?;\n }\n Some(Commands::Invariants(opts)) => {\n let root = std::env::current_dir()?;\n invariants::check(&root, opts.staged)?;\n }\n Some(Commands::Tasks(cmd)) => {\n tasks::run_tasks_command(cmd)?;\n }\n Some(Commands::Fast(opts)) => {\n tasks::run_fast(opts)?;\n }\n Some(Commands::Up(opts)) => {\n lifecycle::run_up(opts)?;\n }\n Some(Commands::Down(opts)) => {\n lifecycle::run_down(opts)?;\n }\n Some(Commands::AiTestNew(opts)) => {\n ai_test::run(opts)?;\n }\n Some(Commands::Global(cmd)) => {\n tasks::run_global(cmd)?;\n }\n Some(Commands::Run(opts)) => {\n tasks::run(opts)?;\n }\n Some(Commands::Search) => {\n palette::run_global()?;\n }\n Some(Commands::LastCmd) => {\n // Prefer fish shell traces if available, fall back to flow history\n if fish_trace::load_last_record()?.is_some() {\n fish_trace::print_last_fish_cmd()?;\n } else {\n history::print_last_record()?;\n }\n }\n Some(Commands::LastCmdFull) => {\n // Prefer fish shell traces if available, fall back to flow history\n if fish_trace::load_last_record()?.is_some() {\n fish_trace::print_last_fish_cmd_full()?;\n } else {\n history::print_last_record_full()?;\n }\n }\n Some(Commands::FishLast) => {\n fish_trace::print_last_fish_cmd()?;\n }\n Some(Commands::FishLastFull) => {\n fish_trace::print_last_fish_cmd_full()?;\n }\n Some(Commands::FishInstall(opts)) => {\n fish_install::run(opts)?;\n }\n Some(Commands::Rerun(opts)) => {\n rerun(opts)?;\n }\n Some(Commands::Ps(opts)) => {\n processes::show_project_processes(opts)?;\n }\n Some(Commands::Kill(opts)) => {\n processes::kill_processes(opts)?;\n }\n Some(Commands::Logs(opts)) => {\n processes::show_task_logs(opts)?;\n }\n Some(Commands::Trace(cmd)) => {\n if let Some(action) = cmd.action {\n match action {\n TraceAction::Session(opts) => {\n traces::run_session(opts)?;\n }\n }\n } else {\n traces::run(cmd.events)?;\n }\n }\n Some(Commands::Projects) => {\n projects::show_projects()?;\n }\n Some(Commands::Sessions(opts)) => {\n ai::run_sessions(&opts)?;\n }\n Some(Commands::Active(opts)) => {\n projects::handle_active(opts)?;\n }\n Some(Commands::Server(opts)) => {\n log_server::run(opts)?;\n }\n Some(Commands::Web(opts)) => {\n web::run(opts)?;\n }\n Some(Commands::Match(opts)) => {\n task_match::run(task_match::MatchOpts {\n args: opts.query,\n model: opts.model,\n port: Some(opts.port),\n execute: !opts.dry_run,\n })?;\n }\n Some(Commands::Ask(opts)) => {\n flowd::ask::run(flowd::ask::AskOpts {\n args: opts.query,\n model: opts.model,\n url: opts.url,\n })?;\n }\n Some(Commands::Branches(cmd)) => {\n branches::run(cmd)?;\n }\n Some(Commands::Status(opts)) => {\n jj::run_workflow_status(opts.raw)?;\n }\n Some(Commands::Commit(opts)) => {\n // Default: fast commit lane with deferred Codex deep review.\n let mut force = opts.force || opts.approved;\n let mut message_arg = opts.message_arg.as_deref();\n let mut open_review = opts.review;\n if !force {\n if let Some(arg) = message_arg {\n if arg == \"force\"\n && opts.message.is_none()\n && opts.fast.is_none()\n && !opts.queue\n && !opts.no_queue\n {\n force = true;\n message_arg = None;\n } else if arg == \"review\"\n && opts.message.is_none()\n && opts.fast.is_none()\n && !opts.queue\n && !opts.no_queue\n {\n open_review = true;\n message_arg = None;\n }\n }\n }\n let queue = commit::resolve_commit_queue_mode(opts.queue, opts.no_queue || force)\n .with_open_review(open_review);\n let push = !opts.no_push;\n let explicit_blocking = opts.slow\n || opts.dry\n || opts.context\n || opts.sync\n || opts.codex\n || opts.review_model.is_some()\n || opts.skip_quality\n || opts.skip_docs\n || opts.skip_tests\n || opts.message.is_some()\n || message_arg.is_some();\n let implicit_quick = !opts.quick\n && !explicit_blocking\n && opts.fast.is_none()\n && commit::commit_quick_default_enabled();\n if opts.quick || implicit_quick {\n if implicit_quick {\n println!(\n \"ℹ️ using fast commit + deferred Codex deep review by default. Pass --slow for blocking pre-commit review.\"\n );\n }\n commit::run_quick_then_async_review(\n push,\n queue,\n opts.hashed,\n &opts.paths,\n opts.fast.as_deref(),\n )?;\n return Ok(());\n }\n if let Some(message) = opts.fast.as_deref() {\n commit::run_fast(message, push, queue, opts.hashed, &opts.paths)?;\n return Ok(());\n }\n let review_selection =\n commit::resolve_review_selection_v2(opts.codex, opts.review_model.clone());\n let author_message = opts.message.as_deref().or(message_arg);\n if opts.dry {\n commit::dry_run_context()?;\n } else if opts.sync {\n commit::run_with_check_sync(\n push,\n opts.context,\n review_selection,\n author_message,\n opts.tokens,\n true,\n queue,\n opts.hashed,\n &opts.paths,\n commit::CommitGateOverrides {\n skip_quality: opts.skip_quality,\n skip_docs: opts.skip_docs,\n skip_tests: opts.skip_tests,\n },\n )?;\n } else {\n commit::run_with_check_with_gitedit(\n push,\n opts.context,\n review_selection,\n author_message,\n opts.tokens,\n queue,\n opts.hashed,\n &opts.paths,\n commit::CommitGateOverrides {\n skip_quality: opts.skip_quality,\n skip_docs: opts.skip_docs,\n skip_tests: opts.skip_tests,\n },\n )?;\n }\n }\n Some(Commands::CommitQueue(cmd)) => {\n commit::run_commit_queue(cmd)?;\n }\n Some(Commands::ReviewsTodo(cmd)) => {\n reviews_todo::run(cmd)?;\n }\n Some(Commands::Pr(opts)) => {\n commit::run_pr(opts)?;\n }\n Some(Commands::Gitignore(cmd)) => {\n gitignore_policy::run(cmd)?;\n }\n Some(Commands::Recipe(cmd)) => {\n recipe::run(cmd)?;\n }\n Some(Commands::Review(cmd)) => match cmd.action {\n Some(ReviewAction::Latest) | None => {\n commit::open_latest_queue_review()?;\n }\n Some(ReviewAction::Copy { hash }) => {\n commit::copy_review_prompt(hash.as_deref())?;\n }\n },\n Some(Commands::GitRepair(opts)) => {\n git_guard::run_git_repair(opts)?;\n }\n Some(Commands::Jj(cmd)) => {\n jj::run(cmd)?;\n }\n Some(Commands::CommitSimple(opts)) => {\n // Simple commit without review - always sync (fast, no hub)\n let mut force = opts.force || opts.approved;\n let mut open_review = opts.review;\n if !force {\n if let Some(arg) = opts.message_arg.as_deref() {\n if arg == \"force\" && opts.message.is_none() && opts.fast.is_none() {\n force = true;\n } else if arg == \"review\"\n && opts.message.is_none()\n && opts.fast.is_none()\n && !opts.queue\n && !opts.no_queue\n {\n open_review = true;\n }\n }\n }\n let queue = commit::resolve_commit_queue_mode(opts.queue, opts.no_queue || force)\n .with_open_review(open_review);\n let push = !opts.no_push;\n commit::run_sync(push, queue, opts.hashed, &opts.paths)?;\n }\n Some(Commands::CommitWithCheck(opts)) => {\n // Review but no gitedit sync\n let mut force = opts.force || opts.approved;\n let mut open_review = opts.review;\n if !force {\n if let Some(arg) = opts.message_arg.as_deref() {\n if arg == \"force\" && opts.message.is_none() && opts.fast.is_none() {\n force = true;\n } else if arg == \"review\"\n && opts.message.is_none()\n && opts.fast.is_none()\n && !opts.queue\n && !opts.no_queue\n {\n open_review = true;\n }\n }\n }\n let queue = commit::resolve_commit_queue_mode(opts.queue, opts.no_queue || force)\n .with_open_review(open_review);\n let push = !opts.no_push;\n if opts.quick {\n commit::run_quick_then_async_review(\n push,\n queue,\n opts.hashed,\n &opts.paths,\n opts.fast.as_deref(),\n )?;\n return Ok(());\n }\n let review_selection =\n commit::resolve_review_selection_v2(opts.codex, opts.review_model.clone());\n if opts.dry {\n commit::dry_run_context()?;\n } else if opts.sync {\n commit::run_with_check_sync(\n push,\n opts.context,\n review_selection,\n opts.message.as_deref(),\n opts.tokens,\n false,\n queue,\n opts.hashed,\n &opts.paths,\n commit::CommitGateOverrides {\n skip_quality: opts.skip_quality,\n skip_docs: opts.skip_docs,\n skip_tests: opts.skip_tests,\n },\n )?;\n } else {\n commit::run_with_check(\n push,\n opts.context,\n review_selection,\n opts.message.as_deref(),\n opts.tokens,\n queue,\n opts.hashed,\n &opts.paths,\n commit::CommitGateOverrides {\n skip_quality: opts.skip_quality,\n skip_docs: opts.skip_docs,\n skip_tests: opts.skip_tests,\n },\n )?;\n }\n }\n Some(Commands::Fix(opts)) => {\n fix::run(opts)?;\n }\n Some(Commands::Undo(cmd)) => {\n undo::run(cmd)?;\n }\n Some(Commands::Fixup(opts)) => {\n fixup::run(opts)?;\n }\n Some(Commands::Changes(cmd)) => {\n changes::run(cmd)?;\n }\n Some(Commands::Diff(cmd)) => {\n changes::run_diff(cmd)?;\n }\n Some(Commands::Hash(opts)) => {\n hash::run(opts)?;\n }\n Some(Commands::Daemon(cmd)) => {\n daemon::run(cmd)?;\n }\n Some(Commands::Supervisor(cmd)) => {\n supervisor::run(cmd)?;\n }\n Some(Commands::Ai(cmd)) => {\n ai::run(cmd.action)?;\n }\n Some(Commands::Codex { action }) => {\n ai::run_provider(ai::Provider::Codex, action)?;\n }\n Some(Commands::Cursor { action }) => {\n ai::run_provider(ai::Provider::Cursor, action)?;\n }\n Some(Commands::Claude { action }) => {\n ai::run_provider(ai::Provider::Claude, action)?;\n }\n Some(Commands::Env(cmd)) => {\n env::run(cmd.action)?;\n }\n Some(Commands::Otp(cmd)) => {\n otp::run(cmd)?;\n }\n Some(Commands::Auth(opts)) => {\n auth::run(opts)?;\n }\n Some(Commands::Services(cmd)) => {\n services::run(cmd)?;\n }\n Some(Commands::Macos(cmd)) => {\n macos::run(cmd)?;\n }\n Some(Commands::Ssh(cmd)) => {\n ssh_keys::run(cmd.action)?;\n }\n Some(Commands::Todo(cmd)) => {\n todo::run(cmd)?;\n }\n Some(Commands::Ext(cmd)) => {\n ext::run(cmd)?;\n }\n Some(Commands::Skills(cmd)) => {\n skills::run(cmd)?;\n }\n Some(Commands::Url(cmd)) => {\n url_inspect::run(cmd)?;\n }\n Some(Commands::Deps(cmd)) => {\n deps::run(cmd)?;\n }\n Some(Commands::Db(cmd)) => {\n storage::run(cmd)?;\n }\n Some(Commands::Tools(cmd)) => {\n tools::run(cmd)?;\n }\n Some(Commands::Notify(cmd)) => {\n notify::run(cmd)?;\n }\n Some(Commands::Commits(cmd)) => {\n commits::run(cmd)?;\n }\n Some(Commands::SeqRpc(cmd)) => {\n seq_rpc::run(cmd)?;\n }\n Some(Commands::ExplainCommits(cmd)) => {\n explain_commits::run_cli(cmd)?;\n }\n Some(Commands::Setup(opts)) => {\n setup::run(opts)?;\n }\n Some(Commands::Agents(cmd)) => {\n agents::run(cmd)?;\n }\n Some(Commands::Hive(cmd)) => {\n hive::run_command(cmd)?;\n }\n Some(Commands::Sync(cmd)) => {\n sync::run(cmd)?;\n }\n Some(Commands::Checkout(cmd)) => {\n sync::run_checkout(cmd)?;\n }\n Some(Commands::Switch(cmd)) => {\n sync::run_switch(cmd)?;\n }\n Some(Commands::Push(cmd)) => {\n push::run(cmd)?;\n }\n Some(Commands::Info) => {\n info::run()?;\n }\n Some(Commands::Upstream(cmd)) => {\n upstream::run(cmd)?;\n }\n Some(Commands::Deploy(cmd)) => {\n deploy::run(cmd)?;\n }\n Some(Commands::Prod(cmd)) => {\n deploy::run_prod(cmd)?;\n }\n Some(Commands::Publish(cmd)) => {\n publish::run(cmd)?;\n }\n Some(Commands::Clone(opts)) => {\n repos::clone_git_like(opts)?;\n }\n Some(Commands::Repos(cmd)) => {\n repos::run(cmd)?;\n }\n Some(Commands::Code(cmd)) => {\n code::run(cmd)?;\n }\n Some(Commands::Migrate(cmd)) => {\n code::run_migrate(cmd)?;\n }\n Some(Commands::Parallel(cmd)) => {\n parallel::run(cmd)?;\n }\n Some(Commands::Docs(cmd)) => {\n docs::run(cmd)?;\n }\n Some(Commands::Upgrade(opts)) => {\n upgrade::run(opts)?;\n }\n Some(Commands::Latest) => {\n latest::run()?;\n }\n Some(Commands::Release(cmd)) => {\n release::run(cmd)?;\n }\n Some(Commands::Install(cmd)) => {\n if let Some(InstallAction::Index(opts)) = cmd.action.clone() {\n install::run_index(opts)?;\n } else {\n install::run(cmd.opts)?;\n }\n }\n Some(Commands::Registry(cmd)) => {\n registry::run(cmd)?;\n }\n Some(Commands::Analytics(cmd)) => {\n analytics::run(cmd)?;\n }\n Some(Commands::Proxy(cmd)) => {\n proxy_command(cmd)?;\n }\n Some(Commands::Domains(cmd)) => {\n domains::run(cmd)?;\n }\n Some(Commands::TaskShortcut(args)) => {\n let Some(task_name) = args.first() else {\n bail!(\"no task name provided\");\n };\n if let Err(err) = tasks::run_with_discovery(task_name, args[1..].to_vec()) {\n if is_task_not_found(&err) {\n return Err(err);\n }\n return Err(err);\n }\n }\n None => {\n palette::run(TasksOpts::default())?;\n }\n }\n\n Ok(())\n })();\n\n usage::record_command_result(&analytics_capture, started_at.elapsed(), &result);\n usage::maybe_prompt_for_opt_in(is_analytics_command, result.is_ok());\n result\n}\n\nfn apply_startup_policy(policy: StartupPolicy) {\n let policy = apply_startup_env_overrides(policy);\n if policy.load_global_secrets {\n flowd::config::load_global_secrets();\n }\n if policy.sync_skills {\n skills::auto_sync_skills();\n }\n}\n\nfn apply_startup_env_overrides(mut policy: StartupPolicy) -> StartupPolicy {\n if let Some(value) = env_truthy_override(\"FLOW_STARTUP_LOAD_GLOBAL_SECRETS\") {\n policy.load_global_secrets = value;\n }\n if let Some(value) = env_truthy_override(\"FLOW_STARTUP_SYNC_SKILLS\") {\n policy.sync_skills = value;\n }\n policy\n}\n\nfn env_truthy_override(key: &str) -> Option<bool> {\n let value = std::env::var(key).ok()?;\n let normalized = value.trim().to_ascii_lowercase();\n match normalized.as_str() {\n \"1\" | \"true\" | \"yes\" | \"on\" => Some(true),\n \"0\" | \"false\" | \"no\" | \"off\" => Some(false),\n _ => None,\n }\n}\n\nfn startup_policy_for(command: Option<&Commands>) -> StartupPolicy {\n use flowd::cli::{AnalyticsAction, GlobalAction, ProxyAction, ReposAction, TasksAction};\n\n match command {\n None => StartupPolicy::NONE,\n Some(Commands::Search) => StartupPolicy::NONE,\n Some(Commands::ShellInit(_)) => StartupPolicy::NONE,\n Some(Commands::Shell(_)) => StartupPolicy::NONE,\n Some(Commands::Init(_)) => StartupPolicy::NONE,\n Some(Commands::New(_)) => StartupPolicy::NONE,\n Some(Commands::Archive(_)) => StartupPolicy::NONE,\n Some(Commands::Doctor(_)) => StartupPolicy::NONE,\n Some(Commands::Health(_)) => StartupPolicy::NONE,\n Some(Commands::Invariants(_)) => StartupPolicy::NONE,\n Some(Commands::Projects) => StartupPolicy::NONE,\n Some(Commands::Active(_)) => StartupPolicy::NONE,\n Some(Commands::LastCmd) => StartupPolicy::NONE,\n Some(Commands::LastCmdFull) => StartupPolicy::NONE,\n Some(Commands::FishLast) => StartupPolicy::NONE,\n Some(Commands::FishLastFull) => StartupPolicy::NONE,\n Some(Commands::FishInstall(_)) => StartupPolicy::NONE,\n Some(Commands::Ps(_)) => StartupPolicy::NONE,\n Some(Commands::Logs(_)) => StartupPolicy::NONE,\n Some(Commands::Trace(_)) => StartupPolicy::NONE,\n Some(Commands::Branches(_)) => StartupPolicy::NONE,\n Some(Commands::Status(_)) => StartupPolicy::NONE,\n Some(Commands::Changes(_)) => StartupPolicy::NONE,\n Some(Commands::Diff(_)) => StartupPolicy::NONE,\n Some(Commands::Hash(_)) => StartupPolicy::NONE,\n Some(Commands::Daemon(_)) => StartupPolicy::NONE,\n Some(Commands::Supervisor(_)) => StartupPolicy::NONE,\n Some(Commands::Macos(_)) => StartupPolicy::NONE,\n Some(Commands::Ssh(_)) => StartupPolicy::NONE,\n Some(Commands::Todo(_)) => StartupPolicy::NONE,\n Some(Commands::Ext(_)) => StartupPolicy::NONE,\n Some(Commands::Tools(_)) => StartupPolicy::NONE,\n Some(Commands::Notify(_)) => StartupPolicy::NONE,\n Some(Commands::Commits(_)) => StartupPolicy::NONE,\n Some(Commands::SeqRpc(_)) => StartupPolicy::NONE,\n Some(Commands::ExplainCommits(_)) => StartupPolicy::NONE,\n Some(Commands::Info) => StartupPolicy::NONE,\n Some(Commands::Upstream(_)) => StartupPolicy::NONE,\n Some(Commands::Latest) => StartupPolicy::NONE,\n Some(Commands::Url(_)) => StartupPolicy::SECRETS_ONLY,\n Some(Commands::Analytics(cmd)) => match cmd.action.as_ref() {\n None\n | Some(&AnalyticsAction::Status)\n | Some(&AnalyticsAction::Enable)\n | Some(&AnalyticsAction::Disable)\n | Some(&AnalyticsAction::Export)\n | Some(&AnalyticsAction::Purge) => StartupPolicy::NONE,\n },\n Some(Commands::Tasks(cmd)) => match cmd.action.as_ref() {\n None\n | Some(TasksAction::List(_))\n | Some(TasksAction::Dupes(_))\n | Some(TasksAction::InitAi(_))\n | Some(TasksAction::Daemon(_)) => StartupPolicy::NONE,\n Some(TasksAction::BuildAi(_)) | Some(TasksAction::RunAi(_)) => {\n StartupPolicy::SECRETS_ONLY\n }\n },\n Some(Commands::Global(cmd)) => match (cmd.action.as_ref(), cmd.list, cmd.task.as_ref()) {\n (Some(GlobalAction::List), _, _) | (None, true, _) | (None, false, None) => {\n StartupPolicy::NONE\n }\n _ => StartupPolicy::SECRETS_ONLY,\n },\n Some(Commands::Sessions(opts)) => {\n if opts.summarize || opts.handoff {\n StartupPolicy::SECRETS_ONLY\n } else {\n StartupPolicy::NONE\n }\n }\n Some(Commands::Proxy(cmd)) => match &cmd.action {\n ProxyAction::Trace(_)\n | ProxyAction::Last(_)\n | ProxyAction::Add(_)\n | ProxyAction::List\n | ProxyAction::Stop => StartupPolicy::NONE,\n ProxyAction::Start(_) => StartupPolicy::SECRETS_ONLY,\n },\n Some(Commands::Repos(cmd)) => match cmd.action.as_ref() {\n None | Some(ReposAction::Capsule(_)) | Some(ReposAction::Alias(_)) => {\n StartupPolicy::NONE\n }\n _ => StartupPolicy::SECRETS_ONLY,\n },\n Some(Commands::Ai(_)) => StartupPolicy::FULL,\n Some(Commands::Codex { .. }) => StartupPolicy::FULL,\n Some(Commands::Cursor { .. }) => StartupPolicy::FULL,\n Some(Commands::Claude { .. }) => StartupPolicy::FULL,\n Some(Commands::Commit(_))\n | Some(Commands::CommitQueue(_))\n | Some(Commands::CommitSimple(_))\n | Some(Commands::CommitWithCheck(_))\n | Some(Commands::Fix(_))\n | Some(Commands::Fixup(_))\n | Some(Commands::Skills(_))\n | Some(Commands::Setup(_)) => StartupPolicy::FULL,\n Some(Commands::Run(_))\n | Some(Commands::Fast(_))\n | Some(Commands::Up(_))\n | Some(Commands::Down(_))\n | Some(Commands::Rerun(_))\n | Some(Commands::Kill(_))\n | Some(Commands::Server(_))\n | Some(Commands::Web(_))\n | Some(Commands::Match(_))\n | Some(Commands::Ask(_))\n | Some(Commands::Review(_))\n | Some(Commands::ReviewsTodo(_))\n | Some(Commands::Pr(_))\n | Some(Commands::Gitignore(_))\n | Some(Commands::Recipe(_))\n | Some(Commands::GitRepair(_))\n | Some(Commands::Jj(_))\n | Some(Commands::Env(_))\n | Some(Commands::Otp(_))\n | Some(Commands::Auth(_))\n | Some(Commands::Services(_))\n | Some(Commands::Deps(_))\n | Some(Commands::Db(_))\n | Some(Commands::Home(_))\n | Some(Commands::Hub(_))\n | Some(Commands::AiTestNew(_))\n | Some(Commands::Code(_))\n | Some(Commands::Migrate(_))\n | Some(Commands::Parallel(_))\n | Some(Commands::Docs(_))\n | Some(Commands::Upgrade(_))\n | Some(Commands::Release(_))\n | Some(Commands::Install(_))\n | Some(Commands::Registry(_))\n | Some(Commands::Domains(_))\n | Some(Commands::Sync(_))\n | Some(Commands::Checkout(_))\n | Some(Commands::Switch(_))\n | Some(Commands::Push(_))\n | Some(Commands::Deploy(_))\n | Some(Commands::Prod(_))\n | Some(Commands::Publish(_))\n | Some(Commands::Clone(_))\n | Some(Commands::TaskShortcut(_))\n | Some(Commands::Agents(_))\n | Some(Commands::Hive(_)) => StartupPolicy::SECRETS_ONLY,\n Some(Commands::Undo(_)) => StartupPolicy::NONE,\n }\n}\n\nfn rerun(opts: RerunOpts) -> Result<()> {\n let project_root = if opts.config.is_absolute() {\n opts.config.parent().unwrap_or(Path::new(\".\")).to_path_buf()\n } else {\n std::env::current_dir().unwrap_or_else(|_| Path::new(\".\").to_path_buf())\n };\n\n let record = history::load_last_record_for_project(&project_root)?;\n let Some(rec) = record else {\n bail!(\"no previous task found for this project\");\n };\n\n // Parse user_input to extract task name and args (respecting shell quoting)\n let parts = shell_words::split(&rec.user_input).unwrap_or_else(|_| vec![rec.task_name.clone()]);\n let task_name = parts.first().cloned().unwrap_or(rec.task_name.clone());\n let args: Vec<String> = parts.into_iter().skip(1).collect();\n\n println!(\"Re-running: {}\", rec.user_input);\n\n tasks::run(TaskRunOpts {\n config: opts.config,\n delegate_to_hub: false,\n hub_host: IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: task_name,\n args,\n })\n}\n\nfn is_task_not_found(err: &anyhow::Error) -> bool {\n let msg = err.to_string().to_ascii_lowercase();\n msg.contains(\"task '\") && msg.contains(\"not found\")\n}\n\nfn shell_command(cmd: ShellCommand) {\n match cmd.action.unwrap_or(ShellAction::Reset) {\n ShellAction::Reset => {\n shell_reset();\n }\n ShellAction::FixTerminal => {\n shell_fix_terminal();\n }\n }\n}\n\nfn shell_reset() {\n let home = dirs::home_dir().expect(\"no home directory\");\n let config_path = home.join(\"config\").join(\"fish\").join(\"config.fish\");\n if std::env::var(\"FISH_VERSION\").is_ok() {\n println!(\"Run: source {}\", config_path.display());\n } else {\n println!(\n \"Refresh your shell session (fish): source {}\",\n config_path.display()\n );\n }\n}\n\nfn shell_fix_terminal() {\n let status = std::process::Command::new(\"fish\")\n .arg(\"-c\")\n .arg(\"set -Ua fish_features no-query-term\")\n .status();\n match status {\n Ok(status) if status.success() => {\n println!(\"Disabled fish terminal query (no-query-term). Restart fish to apply.\");\n }\n _ => {\n println!(\"Run in fish: set -Ua fish_features no-query-term\");\n println!(\"Then restart fish to apply.\");\n }\n }\n}\n\nfn shell_init(shell: &str) {\n use std::fs;\n use std::io::Write;\n\n let home = dirs::home_dir().expect(\"no home directory\");\n let config_dir = home.join(\"config\");\n\n match shell {\n \"fish\" => {\n let config_fish = config_dir.join(\"fish\").join(\"config.fish\");\n\n println!(\"No fish integration changes applied.\");\n println!(\n \"Manage your fish config manually: {}\",\n config_fish.display()\n );\n }\n \"zsh\" => {\n let zshrc = config_dir.join(\"zsh\").join(\".zshrc\");\n\n if zshrc.exists() {\n let content = fs::read_to_string(&zshrc).unwrap_or_default();\n if content.contains(\"# flow:start\") {\n println!(\"Already set up in {}\", zshrc.display());\n return;\n }\n }\n\n let snippet = r#\"\n# flow:start\nf() {\n local bin\n if [[ -x ~/.local/bin/f ]]; then\n bin=~/.local/bin/f\n else\n bin=$(command -v f)\n fi\n\n case \"$1\" in\n new)\n local output\n output=$(\"$bin\" \"$@\" 2>&1)\n echo \"$output\"\n local created\n created=$(echo \"$output\" | grep -oE 'Created .+' | cut -d' ' -f2-)\n if [[ -n \"$created\" && -d \"$created\" ]]; then\n cd \"$created\"\n fi\n ;;\n *)\n \"$bin\" \"$@\"\n ;;\n esac\n}\n# flow:end\n\"#;\n\n let mut file = match fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(&zshrc)\n {\n Ok(f) => f,\n Err(e) => {\n eprintln!(\"Failed to open {}: {}\", zshrc.display(), e);\n return;\n }\n };\n\n if let Err(e) = file.write_all(snippet.as_bytes()) {\n eprintln!(\"Failed to write to {}: {}\", zshrc.display(), e);\n return;\n }\n\n println!(\"Added flow integration to {}\", zshrc.display());\n }\n _ => {\n eprintln!(\"Unsupported shell: {}\", shell);\n eprintln!(\"Supported: fish, zsh\");\n }\n }\n}\n\n/// Handle proxy commands\nfn proxy_command(cmd: ProxyCommand) -> Result<()> {\n // Helper to load config from current directory\n let load_project_config = || -> Result<flowd::config::Config> {\n let cwd = std::env::current_dir()?;\n let flow_toml = cwd.join(\"flow.toml\");\n if flow_toml.exists() {\n flowd::config::load(&flow_toml)\n } else {\n // Try global config\n let global = dirs::config_dir()\n .map(|d| d.join(\"flow\").join(\"flow.toml\"))\n .filter(|p| p.exists());\n if let Some(path) = global {\n flowd::config::load(&path)\n } else {\n bail!(\"No flow.toml found in current directory or global config\");\n }\n }\n };\n\n match cmd.action {\n ProxyAction::Start(opts) => {\n // Load config\n let config = load_project_config()?;\n let proxy_config = config.proxy.unwrap_or_default();\n let targets = config.proxies;\n\n if targets.is_empty() {\n bail!(\"No proxy targets configured. Add [[proxies]] to flow.toml\");\n }\n\n // Override listen if provided\n let proxy_config = if let Some(listen) = opts.listen {\n proxy::ProxyConfig {\n listen,\n ..proxy_config\n }\n } else {\n proxy_config\n };\n\n // Start server\n let rt = tokio::runtime::Runtime::new()?;\n rt.block_on(proxy::start(proxy_config, targets))?;\n }\n ProxyAction::Trace(opts) => {\n proxy::trace_last(opts.count)?;\n }\n ProxyAction::Last(_opts) => {\n proxy::trace_last(1)?;\n }\n ProxyAction::Add(opts) => {\n println!(\"To add a proxy, edit flow.toml:\");\n println!();\n println!(\"[[proxies]]\");\n println!(\n \"name = \\\"{}\\\"\",\n opts.name.unwrap_or_else(|| \"myservice\".to_string())\n );\n println!(\"target = \\\"{}\\\"\", opts.target);\n if let Some(host) = opts.host {\n println!(\"host = \\\"{}\\\"\", host);\n }\n if let Some(path) = opts.path {\n println!(\"path = \\\"{}\\\"\", path);\n }\n }\n ProxyAction::List => {\n let config = load_project_config()?;\n if config.proxies.is_empty() {\n println!(\"No proxy targets configured.\");\n println!(\"Add [[proxies]] sections to flow.toml\");\n } else {\n println!(\n \"{:<15} {:<25} {:<15} {:<15}\",\n \"NAME\", \"TARGET\", \"HOST\", \"PATH\"\n );\n println!(\"{}\", \"-\".repeat(70));\n for p in &config.proxies {\n println!(\n \"{:<15} {:<25} {:<15} {:<15}\",\n p.name,\n p.target,\n p.host.as_deref().unwrap_or(\"-\"),\n p.path.as_deref().unwrap_or(\"-\")\n );\n }\n }\n }\n ProxyAction::Stop => {\n println!(\"Proxy stop not implemented yet. Use Ctrl+C or kill the process.\");\n }\n }\n Ok(())\n}\n\n#[cfg(test)]\nmod tests {\n use std::path::PathBuf;\n\n use super::{StartupPolicy, startup_policy_for};\n use flowd::cli::{\n AiAction, AiCommand, AnalyticsCommand, Commands, GlobalAction, GlobalCommand,\n RepoAliasAction, RepoAliasCommand, RepoCapsuleOpts, ReposAction, ReposCommand,\n SessionsOpts, StatusOpts, TasksAction, TasksBuildAiOpts, TasksCommand, TasksListOpts,\n UrlAction, UrlCommand, UrlCrawlOpts, UrlCrawlSource, UrlInspectOpts, UrlInspectProvider,\n };\n\n #[test]\n fn startup_policy_skips_common_local_read_only_commands() {\n assert_eq!(startup_policy_for(None), StartupPolicy::NONE);\n assert_eq!(\n startup_policy_for(Some(&Commands::Status(StatusOpts::default()))),\n StartupPolicy::NONE\n );\n assert_eq!(\n startup_policy_for(Some(&Commands::Tasks(TasksCommand {\n action: Some(TasksAction::List(TasksListOpts {\n config: PathBuf::from(\"flow.toml\"),\n dupes: false,\n })),\n }))),\n StartupPolicy::NONE\n );\n assert_eq!(\n startup_policy_for(Some(&Commands::Analytics(AnalyticsCommand {\n action: None,\n }))),\n StartupPolicy::NONE\n );\n assert_eq!(\n startup_policy_for(Some(&Commands::Url(UrlCommand {\n action: UrlAction::Inspect(UrlInspectOpts {\n url: \"https://example.com\".to_string(),\n json: false,\n full: false,\n provider: UrlInspectProvider::Auto,\n timeout_s: 20.0,\n }),\n }))),\n StartupPolicy::SECRETS_ONLY\n );\n assert_eq!(\n startup_policy_for(Some(&Commands::Url(UrlCommand {\n action: UrlAction::Crawl(UrlCrawlOpts {\n url: \"https://developers.cloudflare.com\".to_string(),\n json: false,\n full: false,\n limit: 10,\n depth: 2,\n records: 5,\n source: UrlCrawlSource::All,\n render: false,\n include_external_links: false,\n include_subdomains: false,\n include_patterns: Vec::new(),\n exclude_patterns: Vec::new(),\n max_age_s: None,\n wait_timeout_s: 60.0,\n poll_interval_s: 2.0,\n }),\n }))),\n StartupPolicy::SECRETS_ONLY\n );\n }\n\n #[test]\n fn startup_policy_keeps_execution_paths_loading_secrets() {\n assert_eq!(\n startup_policy_for(Some(&Commands::Tasks(TasksCommand {\n action: Some(TasksAction::BuildAi(TasksBuildAiOpts {\n name: \"ai:flow/noop\".to_string(),\n root: PathBuf::from(\".\"),\n force: false,\n })),\n }))),\n StartupPolicy::SECRETS_ONLY\n );\n assert_eq!(\n startup_policy_for(Some(&Commands::Global(GlobalCommand {\n action: Some(GlobalAction::Run {\n task: \"setup\".to_string(),\n args: vec![],\n }),\n task: None,\n list: false,\n args: vec![],\n }))),\n StartupPolicy::SECRETS_ONLY\n );\n }\n\n #[test]\n fn startup_policy_syncs_skills_for_ai_heavy_paths() {\n assert_eq!(\n startup_policy_for(Some(&Commands::Ai(AiCommand {\n action: Some(AiAction::List),\n }))),\n StartupPolicy::FULL\n );\n assert_eq!(\n startup_policy_for(Some(&Commands::Sessions(SessionsOpts {\n provider: \"all\".to_string(),\n count: None,\n list: false,\n full: false,\n summarize: true,\n handoff: false,\n }))),\n StartupPolicy::SECRETS_ONLY\n );\n }\n\n #[test]\n fn startup_policy_keeps_repos_capsule_on_fast_path() {\n assert_eq!(\n startup_policy_for(Some(&Commands::Repos(ReposCommand {\n action: Some(ReposAction::Capsule(RepoCapsuleOpts {\n path: None,\n refresh: false,\n json: false,\n })),\n }))),\n StartupPolicy::NONE\n );\n }\n\n #[test]\n fn startup_policy_keeps_repos_alias_on_fast_path() {\n assert_eq!(\n startup_policy_for(Some(&Commands::Repos(ReposCommand {\n action: Some(ReposAction::Alias(RepoAliasCommand {\n action: Some(RepoAliasAction::List { json: false }),\n })),\n }))),\n StartupPolicy::NONE\n );\n }\n}\n" }, { "path": "src/notify.rs", "content": "//! Notify command - sends proposals and alerts to Lin app.\n\nuse crate::cli::NotifyCommand;\nuse anyhow::{Context, Result};\nuse serde::{Deserialize, Serialize};\nuse std::fs;\nuse std::path::PathBuf;\nuse std::time::{SystemTime, UNIX_EPOCH};\nuse uuid::Uuid;\n\n/// Proposal format matching Lin's ProposalService.swift\n#[derive(Debug, Serialize, Deserialize)]\nstruct Proposal {\n id: String,\n timestamp: i64,\n title: String,\n action: String,\n context: Option<String>,\n #[serde(rename = \"expires_at\")]\n expires_at: i64,\n}\n\n/// Alert format for Lin's NotificationBannerManager.\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct Alert {\n id: String,\n timestamp: i64,\n text: String,\n kind: String, // \"info\", \"warning\", \"error\", \"success\"\n #[serde(rename = \"expires_at\")]\n expires_at: i64,\n}\n\n/// Get the path to Lin's proposals.json file.\nfn get_proposals_path() -> Result<PathBuf> {\n let home = dirs::home_dir().context(\"Could not find home directory\")?;\n let path = home\n .join(\"Library\")\n .join(\"Application Support\")\n .join(\"Lin\")\n .join(\"proposals.json\");\n Ok(path)\n}\n\n/// Run the notify command - write a proposal to Lin's proposals.json.\npub fn run(cmd: NotifyCommand) -> Result<()> {\n let proposals_path = get_proposals_path()?;\n\n // Ensure the directory exists\n if let Some(parent) = proposals_path.parent() {\n fs::create_dir_all(parent)?;\n }\n\n // Read existing proposals\n let mut proposals: Vec<Proposal> = if proposals_path.exists() {\n let content = fs::read_to_string(&proposals_path)?;\n serde_json::from_str(&content).unwrap_or_default()\n } else {\n Vec::new()\n };\n\n // Get current timestamp\n let now = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .context(\"Time went backwards\")?\n .as_secs() as i64;\n\n // Create title from action if not provided\n let title = cmd.title.unwrap_or_else(|| {\n // Extract a nice title from the action\n let action = &cmd.action;\n if action.starts_with(\"f \") {\n format!(\"Run: {}\", &action[2..])\n } else {\n format!(\"Run: {}\", action)\n }\n });\n\n // Create new proposal\n let proposal = Proposal {\n id: Uuid::new_v4().to_string(),\n timestamp: now,\n title,\n action: cmd.action.clone(),\n context: cmd.context,\n expires_at: now + cmd.expires as i64,\n };\n\n // Add to proposals\n proposals.push(proposal);\n\n // Write back\n let content = serde_json::to_string_pretty(&proposals)?;\n fs::write(&proposals_path, content)?;\n\n println!(\"Proposal sent to Lin: {}\", cmd.action);\n\n Ok(())\n}\n\n// ============================================================================\n// Alerts API (for commit rejections, errors, etc.)\n// ============================================================================\n\n/// Get the path to Lin's alerts.json file.\nfn get_alerts_path() -> Result<PathBuf> {\n let home = dirs::home_dir().context(\"Could not find home directory\")?;\n let path = home\n .join(\"Library\")\n .join(\"Application Support\")\n .join(\"Lin\")\n .join(\"alerts.json\");\n Ok(path)\n}\n\n/// Alert kind for Lin's NotificationBannerManager.\n#[derive(Debug, Clone, Copy)]\npub enum AlertKind {\n Info,\n Warning,\n Error,\n Success,\n}\n\nimpl AlertKind {\n fn as_str(&self) -> &'static str {\n match self {\n AlertKind::Info => \"info\",\n AlertKind::Warning => \"warning\",\n AlertKind::Error => \"error\",\n AlertKind::Success => \"success\",\n }\n }\n}\n\n/// Send an alert to Lin's notification banner.\n/// Alerts are shown as floating banners - errors/warnings stay for 10+ seconds.\npub fn send_alert(text: &str, kind: AlertKind) -> Result<()> {\n let alerts_path = get_alerts_path()?;\n\n // Ensure the directory exists\n if let Some(parent) = alerts_path.parent() {\n fs::create_dir_all(parent)?;\n }\n\n // Read existing alerts\n let mut alerts: Vec<Alert> = if alerts_path.exists() {\n let content = fs::read_to_string(&alerts_path)?;\n serde_json::from_str(&content).unwrap_or_default()\n } else {\n Vec::new()\n };\n\n // Get current timestamp\n let now = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .context(\"Time went backwards\")?\n .as_secs() as i64;\n\n // Determine expiry based on kind (warnings/errors stay longer)\n let duration = match kind {\n AlertKind::Error | AlertKind::Warning => 30, // 30 seconds for errors/warnings\n AlertKind::Success => 5,\n AlertKind::Info => 10,\n };\n\n // Create new alert\n let alert = Alert {\n id: Uuid::new_v4().to_string(),\n timestamp: now,\n text: text.to_string(),\n kind: kind.as_str().to_string(),\n expires_at: now + duration,\n };\n\n // Add to alerts\n alerts.push(alert);\n\n // Clean up old alerts (keep last 20)\n if alerts.len() > 20 {\n let skip_count = alerts.len() - 20;\n alerts = alerts.into_iter().skip(skip_count).collect();\n }\n\n // Write back\n let content = serde_json::to_string_pretty(&alerts)?;\n fs::write(&alerts_path, content)?;\n\n Ok(())\n}\n\n/// Send an error alert to Lin.\npub fn send_error(text: &str) -> Result<()> {\n send_alert(text, AlertKind::Error)\n}\n\n/// Send a warning alert to Lin.\npub fn send_warning(text: &str) -> Result<()> {\n send_alert(text, AlertKind::Warning)\n}\n" }, { "path": "src/opentui_prompt.rs", "content": "use std::io::{self, IsTerminal};\n\nuse crossterm::event::{self, Event, KeyCode, KeyEventKind, KeyModifiers};\nuse crossterm::terminal::{disable_raw_mode, enable_raw_mode};\n\nuse opentui_lite::{ATTR_BOLD, BORDER_SIMPLE, Color, OpenTui};\n\npub fn confirm(title: &str, lines: &[String], default_yes: bool) -> Option<bool> {\n if !io::stdin().is_terminal() || !io::stdout().is_terminal() {\n return None;\n }\n\n let (width, height) = crossterm::terminal::size().ok()?;\n let opentui = OpenTui::load().ok()?;\n let renderer = opentui\n .create_renderer(width as u32, height as u32, false)\n .ok()?;\n\n renderer.setup_terminal(true);\n\n let _raw = RawModeGuard::new().ok()?;\n\n let bg = Color::rgb(0.06, 0.07, 0.09);\n let border = Color::rgb(0.32, 0.42, 0.62);\n let text = Color::rgb(0.92, 0.94, 0.96);\n let muted = Color::rgb(0.68, 0.72, 0.78);\n let accent = Color::rgb(0.90, 0.76, 0.34);\n\n let buffer = renderer.next_buffer();\n buffer.clear(bg);\n\n let packed_options = 0b1_1111u32;\n buffer.draw_box(\n 0,\n 0,\n width as u32,\n height as u32,\n &BORDER_SIMPLE,\n packed_options,\n border,\n bg,\n Some(title),\n );\n\n let max_width = width.saturating_sub(4) as usize;\n let mut y = 2u32;\n\n let title_line = truncate_width(title, max_width);\n buffer.draw_text(&title_line, 3, y, text, None, ATTR_BOLD);\n y += 2;\n\n for line in lines {\n if y >= height.saturating_sub(3) as u32 {\n break;\n }\n let line = truncate_width(line, max_width);\n buffer.draw_text(&line, 3, y, text, None, 0);\n y += 1;\n }\n\n let hint = if default_yes {\n \"Enter/Y = yes, N/Esc = no\"\n } else {\n \"Enter/N = no, Y = yes\"\n };\n let hint_line = truncate_width(hint, max_width);\n let hint_y = height.saturating_sub(2) as u32;\n buffer.draw_text(&hint_line, 3, hint_y, muted, None, 0);\n\n let action = if default_yes {\n \"[Y] Confirm\"\n } else {\n \"[N] Cancel\"\n };\n let action_line = truncate_width(action, max_width);\n buffer.draw_text(\n &action_line,\n 3,\n hint_y.saturating_sub(1),\n accent,\n None,\n ATTR_BOLD,\n );\n\n renderer.render(true);\n\n let answer = loop {\n match event::read() {\n Ok(Event::Key(key)) if key.kind == KeyEventKind::Press => match key.code {\n KeyCode::Enter => break default_yes,\n KeyCode::Char('y') | KeyCode::Char('Y') => break true,\n KeyCode::Char('n') | KeyCode::Char('N') => break false,\n KeyCode::Esc => break false,\n KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => break false,\n _ => {}\n },\n Ok(_) => {}\n Err(_) => break default_yes,\n }\n };\n\n renderer.clear_terminal();\n renderer.suspend();\n\n Some(answer)\n}\n\nstruct RawModeGuard;\n\nimpl RawModeGuard {\n fn new() -> std::io::Result<Self> {\n enable_raw_mode()?;\n Ok(Self)\n }\n}\n\nimpl Drop for RawModeGuard {\n fn drop(&mut self) {\n let _ = disable_raw_mode();\n }\n}\n\nfn truncate_width(input: &str, max: usize) -> String {\n if input.len() <= max {\n return input.to_string();\n }\n input.chars().take(max).collect::<String>()\n}\n" }, { "path": "src/otp.rs", "content": "use std::time::{SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result, bail};\nuse data_encoding::BASE32_NOPAD;\nuse hmac::{Hmac, Mac};\nuse reqwest::blocking::Client;\nuse serde::Deserialize;\nuse sha1::Sha1;\nuse sha2::{Sha256, Sha512};\nuse url::Url;\n\nuse crate::cli::{OtpAction, OtpCommand};\nuse crate::env;\n\n#[derive(Debug, Clone)]\nstruct ConnectConfig {\n host: String,\n token: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct Vault {\n id: String,\n name: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ItemSummary {\n id: String,\n title: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct Field {\n #[serde(rename = \"type\")]\n field_type: String,\n label: Option<String>,\n value: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct FullItem {\n #[allow(dead_code)]\n id: String,\n title: String,\n fields: Option<Vec<Field>>,\n}\n\npub fn run(cmd: OtpCommand) -> Result<()> {\n match cmd.action {\n OtpAction::Get { vault, item, field } => {\n let config = load_connect_config()?;\n let code = fetch_totp(&config, &vault, &item, field.as_deref())?;\n println!(\"{code}\");\n }\n }\n Ok(())\n}\n\nfn load_connect_config() -> Result<ConnectConfig> {\n let host = std::env::var(\"OP_CONNECT_HOST\")\n .or_else(|_| std::env::var(\"OP_CONNECT_URL\"))\n .map_err(|_| anyhow::anyhow!(\"OP_CONNECT_HOST is not set\"))?;\n\n let token = std::env::var(\"OP_CONNECT_TOKEN\").ok().or_else(|| {\n env::fetch_personal_env_vars(&[\"OP_CONNECT_TOKEN\".to_string()])\n .ok()\n .and_then(|vars| vars.get(\"OP_CONNECT_TOKEN\").cloned())\n });\n\n let Some(token) = token else {\n bail!(\"OP_CONNECT_TOKEN not found in env or Flow env store\");\n };\n\n Ok(ConnectConfig { host, token })\n}\n\nfn fetch_totp(\n config: &ConnectConfig,\n vault_ref: &str,\n item_ref: &str,\n field_label: Option<&str>,\n) -> Result<String> {\n let client = Client::builder()\n .build()\n .context(\"failed to build HTTP client\")?;\n\n let vault_id = resolve_vault_id(&client, config, vault_ref)?;\n let item_id = resolve_item_id(&client, config, &vault_id, item_ref)?;\n let item = fetch_item(&client, config, &vault_id, &item_id)?;\n\n let totp_uri = extract_totp_uri(&item, field_label)?;\n compute_totp(&totp_uri)\n}\n\nfn resolve_vault_id(client: &Client, config: &ConnectConfig, vault_ref: &str) -> Result<String> {\n let url = format!(\"{}/v1/vaults\", config.host.trim_end_matches('/'));\n let vaults: Vec<Vault> = client\n .get(url)\n .bearer_auth(&config.token)\n .send()\n .context(\"failed to list 1Password vaults\")?\n .error_for_status()\n .context(\"1Password connect returned an error for vault list\")?\n .json()\n .context(\"failed to parse vault list\")?;\n\n if let Some(vault) = vaults\n .iter()\n .find(|v| v.id == vault_ref || v.name == vault_ref)\n {\n return Ok(vault.id.clone());\n }\n\n bail!(\"vault not found: {}\", vault_ref);\n}\n\nfn resolve_item_id(\n client: &Client,\n config: &ConnectConfig,\n vault_id: &str,\n item_ref: &str,\n) -> Result<String> {\n let url = format!(\n \"{}/v1/vaults/{}/items\",\n config.host.trim_end_matches('/'),\n vault_id\n );\n let items: Vec<ItemSummary> = client\n .get(url)\n .bearer_auth(&config.token)\n .send()\n .context(\"failed to list 1Password items\")?\n .error_for_status()\n .context(\"1Password connect returned an error for item list\")?\n .json()\n .context(\"failed to parse item list\")?;\n\n if let Some(item) = items\n .iter()\n .find(|i| i.id == item_ref || i.title == item_ref)\n {\n return Ok(item.id.clone());\n }\n\n bail!(\"item not found: {}\", item_ref);\n}\n\nfn fetch_item(\n client: &Client,\n config: &ConnectConfig,\n vault_id: &str,\n item_id: &str,\n) -> Result<FullItem> {\n let url = format!(\n \"{}/v1/vaults/{}/items/{}\",\n config.host.trim_end_matches('/'),\n vault_id,\n item_id\n );\n let item: FullItem = client\n .get(url)\n .bearer_auth(&config.token)\n .send()\n .context(\"failed to fetch 1Password item\")?\n .error_for_status()\n .context(\"1Password connect returned an error for item fetch\")?\n .json()\n .context(\"failed to parse item\")?;\n Ok(item)\n}\n\nfn extract_totp_uri(item: &FullItem, field_label: Option<&str>) -> Result<String> {\n let fields = item.fields.as_ref().ok_or_else(|| {\n anyhow::anyhow!(\"item '{}' has no fields; expected a TOTP field\", item.title)\n })?;\n\n let mut candidates: Vec<&Field> = fields\n .iter()\n .filter(|field| field.field_type.eq_ignore_ascii_case(\"TOTP\"))\n .collect();\n\n if let Some(label) = field_label {\n let label_lower = label.to_lowercase();\n candidates = candidates\n .into_iter()\n .filter(|field| {\n field\n .label\n .as_ref()\n .map(|l| l.to_lowercase() == label_lower)\n .unwrap_or(false)\n })\n .collect();\n }\n\n let field = candidates\n .first()\n .ok_or_else(|| anyhow::anyhow!(\"no TOTP field found in item '{}'\", item.title))?;\n\n let value = field\n .value\n .as_ref()\n .ok_or_else(|| anyhow::anyhow!(\"TOTP field in '{}' has no value\", item.title))?;\n\n Ok(value.clone())\n}\n\nfn compute_totp(uri: &str) -> Result<String> {\n if !uri.starts_with(\"otpauth://\") {\n return compute_totp_from_secret(uri, 30, 6, \"SHA1\");\n }\n\n let url = Url::parse(uri).context(\"failed to parse otpauth URI\")?;\n if url.scheme() != \"otpauth\" {\n bail!(\"unsupported OTP URI scheme: {}\", url.scheme());\n }\n\n let mut secret: Option<String> = None;\n let mut digits: u32 = 6;\n let mut period: u64 = 30;\n let mut algorithm = \"SHA1\".to_string();\n\n for (key, value) in url.query_pairs() {\n match key.as_ref() {\n \"secret\" => secret = Some(value.to_string()),\n \"digits\" => digits = value.parse::<u32>().unwrap_or(6),\n \"period\" => period = value.parse::<u64>().unwrap_or(30),\n \"algorithm\" => algorithm = value.to_string(),\n _ => {}\n }\n }\n\n let secret = secret.ok_or_else(|| anyhow::anyhow!(\"otpauth URI missing secret\"))?;\n compute_totp_from_secret(&secret, period, digits, &algorithm)\n}\n\nfn compute_totp_from_secret(\n secret: &str,\n period: u64,\n digits: u32,\n algorithm: &str,\n) -> Result<String> {\n let key = decode_base32(secret)?;\n\n let timestamp = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .context(\"system clock before Unix epoch\")?\n .as_secs();\n let counter = timestamp / period;\n\n let msg = counter.to_be_bytes();\n let algo_upper = algorithm.to_uppercase();\n\n let hash = if algo_upper == \"SHA256\" {\n hmac_sha256(&key, &msg)\n } else if algo_upper == \"SHA512\" {\n hmac_sha512(&key, &msg)\n } else {\n hmac_sha1(&key, &msg)\n };\n\n let offset = (hash[hash.len() - 1] & 0x0f) as usize;\n let slice = &hash[offset..offset + 4];\n let mut code = ((u32::from(slice[0]) & 0x7f) << 24)\n | (u32::from(slice[1]) << 16)\n | (u32::from(slice[2]) << 8)\n | u32::from(slice[3]);\n let modulo = 10u32.pow(digits);\n code %= modulo;\n\n Ok(format!(\"{:0width$}\", code, width = digits as usize))\n}\n\nfn decode_base32(secret: &str) -> Result<Vec<u8>> {\n let normalized = secret.trim().replace(' ', \"\").to_uppercase();\n BASE32_NOPAD\n .decode(normalized.as_bytes())\n .context(\"failed to decode base32 secret\")\n}\n\nfn hmac_sha1(key: &[u8], msg: &[u8]) -> Vec<u8> {\n let mut mac = Hmac::<Sha1>::new_from_slice(key).expect(\"HMAC accepts any key size\");\n mac.update(msg);\n mac.finalize().into_bytes().to_vec()\n}\n\nfn hmac_sha256(key: &[u8], msg: &[u8]) -> Vec<u8> {\n let mut mac = Hmac::<Sha256>::new_from_slice(key).expect(\"HMAC accepts any key size\");\n mac.update(msg);\n mac.finalize().into_bytes().to_vec()\n}\n\nfn hmac_sha512(key: &[u8], msg: &[u8]) -> Vec<u8> {\n let mut mac = Hmac::<Sha512>::new_from_slice(key).expect(\"HMAC accepts any key size\");\n mac.update(msg);\n mac.finalize().into_bytes().to_vec()\n}\n" }, { "path": "src/palette.rs", "content": "use std::{\n io::Write,\n path::PathBuf,\n process::{Command, Stdio},\n};\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::{\n ai_tasks,\n cli::TasksOpts,\n config::{self, TaskConfig},\n discover::DiscoveredTask,\n project_snapshot::ProjectSnapshot,\n};\n\npub fn run(opts: TasksOpts) -> Result<()> {\n let entries = build_entries(Some(opts))?;\n present(entries)\n}\n\n/// Show global commands/tasks only (no project flow.toml required).\npub fn run_global() -> Result<()> {\n let entries = build_entries(None)?;\n present(entries)\n}\n\nstruct FzfResult<'a> {\n entry: &'a PaletteEntry,\n with_args: bool,\n}\n\nfn run_fzf<'a>(entries: &'a [PaletteEntry]) -> Result<Option<FzfResult<'a>>> {\n let mut child = Command::new(\"fzf\")\n .arg(\"--prompt\")\n .arg(\"f> \")\n .arg(\"--expect\")\n .arg(\"tab\") // tab to run with args prompt\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n {\n let stdin = child.stdin.as_mut().context(\"failed to open fzf stdin\")?;\n for entry in entries {\n writeln!(stdin, \"{}\", entry.display)?;\n }\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n let raw = String::from_utf8(output.stdout).context(\"fzf output was not valid UTF-8\")?;\n let mut lines = raw.lines();\n\n // First line is the key pressed (if any from --expect)\n let key = lines.next().unwrap_or(\"\");\n let with_args = key == \"tab\";\n\n // Second line is the selection\n let selection = lines.next().unwrap_or(\"\").trim();\n if selection.is_empty() {\n return Ok(None);\n }\n\n let entry = entries.iter().find(|entry| entry.display == selection);\n Ok(entry.map(|e| FzfResult {\n entry: e,\n with_args,\n }))\n}\n\nfn run_entry(entry: &PaletteEntry, extra_args: Vec<String>) -> Result<()> {\n let exe = std::env::current_exe().context(\"failed to resolve current executable\")?;\n let status = Command::new(exe)\n .args(&entry.exec)\n .args(&extra_args)\n .status()\n .with_context(|| format!(\"failed to run {}\", entry.display))?;\n\n if status.success() {\n Ok(())\n } else {\n bail!(\n \"{} exited with status {}\",\n entry.display,\n status.code().unwrap_or(-1)\n );\n }\n}\n\nfn present(entries: Vec<PaletteEntry>) -> Result<()> {\n if entries.is_empty() {\n println!(\"No commands or tasks available. Add entries to flow.toml or global config.\");\n return Ok(());\n }\n\n if which::which(\"fzf\").is_err() {\n println!(\"fzf not found on PATH – install it to use fuzzy selection.\");\n println!(\"Available commands:\");\n for entry in &entries {\n println!(\" {}\", entry.display);\n }\n return Ok(());\n }\n\n if let Some(result) = run_fzf(&entries)? {\n let extra_args = if result.with_args {\n prompt_for_args(&result.entry.display)?\n } else {\n Vec::new()\n };\n run_entry(result.entry, extra_args)?;\n }\n\n Ok(())\n}\n\nfn prompt_for_args(task_display: &str) -> Result<Vec<String>> {\n use std::io::{self, BufRead};\n\n // Extract task name from display (e.g., \"[task] foo – description\" -> \"foo\")\n let task_name = task_display\n .strip_prefix(\"[task] \")\n .and_then(|s| s.split(\" – \").next())\n .and_then(|s| s.split(\" (\").next()) // handle \"(path)\" suffix\n .unwrap_or(\"task\");\n\n // Show hint about quoting for args with spaces\n println!(\"(tip: use quotes for args with spaces, e.g. 'my prompt')\");\n print!(\"f {} \", task_name);\n io::stdout().flush()?;\n\n let stdin = io::stdin();\n let line = stdin.lock().lines().next();\n let input = match line {\n Some(Ok(s)) => s,\n _ => return Ok(Vec::new()),\n };\n\n let args = shell_words::split(&input).context(\"failed to parse arguments\")?;\n Ok(args)\n}\n\nstruct PaletteEntry {\n display: String,\n exec: Vec<String>,\n}\n\nimpl PaletteEntry {\n fn new(display: &str, exec: Vec<String>) -> Self {\n Self {\n display: display.to_string(),\n exec,\n }\n }\n\n fn from_task(task: &TaskConfig, config_arg: &str) -> Self {\n let summary = task\n .description\n .as_deref()\n .unwrap_or_else(|| task.command.as_str());\n let display = format!(\"[task] {} – {}\", task.name, truncate(summary, 96));\n let exec = vec![\n \"run\".into(),\n \"--config\".into(),\n config_arg.to_string(),\n task.name.clone(),\n ];\n\n Self { display, exec }\n }\n\n fn from_discovered(discovered: &DiscoveredTask) -> Self {\n let summary = discovered\n .task\n .description\n .as_deref()\n .unwrap_or_else(|| discovered.task.command.as_str());\n\n let display = if let Some(path_label) = discovered.path_label() {\n format!(\n \"[task] {} ({}) – {}\",\n discovered.task.name,\n path_label,\n truncate(summary, 80)\n )\n } else {\n format!(\n \"[task] {} – {}\",\n discovered.task.name,\n truncate(summary, 96)\n )\n };\n\n let exec = vec![\n \"run\".into(),\n \"--config\".into(),\n discovered.config_path.display().to_string(),\n discovered.task.name.clone(),\n ];\n\n Self { display, exec }\n }\n\n fn from_ai_task(task: &ai_tasks::DiscoveredAiTask) -> Self {\n let summary = if task.description.trim().is_empty() {\n format!(\"moon run {}\", task.path.display())\n } else {\n task.description.trim().to_string()\n };\n let display = format!(\"[task] {} – {}\", task.id, truncate(&summary, 96));\n let exec = vec![task.id.clone()];\n Self { display, exec }\n }\n}\n\nfn build_entries(project_opts: Option<TasksOpts>) -> Result<Vec<PaletteEntry>> {\n let mut entries = Vec::new();\n let global_cfg = load_if_exists(config::default_config_path())?;\n let mut has_project = false;\n\n if let Some(opts) = project_opts {\n let snapshot = ProjectSnapshot::from_task_config(&opts.config, false)?;\n\n if snapshot.has_any_tasks() {\n has_project = true;\n for discovered in &snapshot.discovery.tasks {\n entries.push(PaletteEntry::from_discovered(discovered));\n }\n for task in &snapshot.ai_tasks {\n entries.push(PaletteEntry::from_ai_task(task));\n }\n }\n }\n\n if has_project {\n return Ok(entries);\n }\n\n entries.extend(builtin_entries());\n\n if let Some((global_path, cfg)) = global_cfg {\n let arg = global_path.display().to_string();\n for task in &cfg.tasks {\n entries.push(PaletteEntry::from_task(task, &arg));\n }\n }\n\n Ok(entries)\n}\n\nfn builtin_entries() -> Vec<PaletteEntry> {\n let entries = vec![\n PaletteEntry::new(\"[cmd] hub – ensure daemon is running\", vec![\"hub\".into()]),\n PaletteEntry::new(\n \"[cmd] search – global commands/tasks\",\n vec![\"search\".into()],\n ),\n PaletteEntry::new(\"[cmd] init – scaffold flow.toml\", vec![\"init\".into()]),\n ];\n\n entries\n}\n\nfn load_if_exists(path: PathBuf) -> Result<Option<(PathBuf, config::Config)>> {\n if path.exists() {\n let cfg = config::load(&path)?;\n Ok(Some((path, cfg)))\n } else {\n Ok(None)\n }\n}\n\nfn truncate(input: &str, max: usize) -> String {\n let mut out = String::new();\n for ch in input.chars() {\n if out.chars().count() + 1 >= max {\n break;\n }\n out.push(ch);\n }\n if out.len() < input.len() {\n out.push('…');\n }\n out\n}\n" }, { "path": "src/parallel.rs", "content": "//! Parallel task runner with pretty status display.\n\nuse std::io::{self, Write};\nuse std::process::Stdio;\nuse std::sync::Arc;\nuse std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};\nuse std::time::{Duration, Instant};\n\nuse anyhow::{Result, bail};\nuse crossterm::terminal;\nuse tokio::io::{AsyncBufReadExt, BufReader};\nuse tokio::process::Command;\nuse tokio::sync::{Mutex, Semaphore};\n\n// ANSI escape codes\nconst RESET: &str = \"\\x1b[0m\";\nconst BOLD: &str = \"\\x1b[1m\";\nconst DIM: &str = \"\\x1b[2m\";\nconst RED: &str = \"\\x1b[31m\";\nconst GREEN: &str = \"\\x1b[32m\";\nconst BLUE: &str = \"\\x1b[34m\";\nconst MAGENTA: &str = \"\\x1b[35m\";\nconst CYAN: &str = \"\\x1b[36m\";\nconst CLEAR_LINE: &str = \"\\x1b[2K\";\nconst HIDE_CURSOR: &str = \"\\x1b[?25l\";\nconst SHOW_CURSOR: &str = \"\\x1b[?25h\";\n\n// Spinner frames\nconst SPINNER_FRAMES: &[&str] = &[\"⠋\", \"⠙\", \"⠹\", \"⠸\", \"⠼\", \"⠴\", \"⠦\", \"⠧\", \"⠇\", \"⠏\"];\nconst SPINNER_COLORS: &[&str] = &[CYAN, BLUE, MAGENTA, BLUE];\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\npub enum TaskStatus {\n Pending,\n Running,\n Success,\n Failure,\n Skipped,\n}\n\n#[derive(Debug, Clone)]\npub struct Task {\n pub label: String,\n pub command: String,\n pub status: TaskStatus,\n pub last_line: String,\n pub exit_code: Option<i32>,\n pub output: Vec<String>,\n pub duration: Option<Duration>,\n}\n\nimpl Task {\n pub fn new(label: impl Into<String>, command: impl Into<String>) -> Self {\n Self {\n label: label.into(),\n command: command.into(),\n status: TaskStatus::Pending,\n last_line: String::new(),\n exit_code: None,\n output: Vec::new(),\n duration: None,\n }\n }\n}\n\npub struct ParallelRunner {\n tasks: Arc<Mutex<Vec<Task>>>,\n max_jobs: usize,\n fail_fast: bool,\n spinner_index: AtomicUsize,\n lines_printed: AtomicUsize,\n should_stop: AtomicBool,\n first_failure_code: Arc<Mutex<Option<i32>>>,\n}\n\nimpl ParallelRunner {\n pub fn new(tasks: Vec<Task>, max_jobs: usize, fail_fast: bool) -> Self {\n Self {\n tasks: Arc::new(Mutex::new(tasks)),\n max_jobs,\n fail_fast,\n spinner_index: AtomicUsize::new(0),\n lines_printed: AtomicUsize::new(0),\n should_stop: AtomicBool::new(false),\n first_failure_code: Arc::new(Mutex::new(None)),\n }\n }\n\n fn get_spinner(&self) -> String {\n let idx = self.spinner_index.load(Ordering::Relaxed);\n let frame = SPINNER_FRAMES[idx % SPINNER_FRAMES.len()];\n let color = SPINNER_COLORS[idx % SPINNER_COLORS.len()];\n format!(\"{}{}{}\", color, frame, RESET)\n }\n\n fn terminal_width() -> usize {\n terminal::size().map(|(w, _)| w as usize).unwrap_or(80)\n }\n\n fn truncate_line(text: &str, max_width: usize) -> String {\n if text.len() <= max_width {\n return text.to_string();\n }\n if max_width <= 1 {\n return text.chars().take(max_width).collect();\n }\n format!(\"{}…\", &text[..max_width - 1])\n }\n\n fn strip_ansi(text: &str) -> String {\n let mut result = String::with_capacity(text.len());\n let mut chars = text.chars().peekable();\n\n while let Some(c) = chars.next() {\n if c == '\\x1b' {\n // Skip escape sequence\n if chars.peek() == Some(&'[') {\n chars.next();\n while let Some(&next) = chars.peek() {\n chars.next();\n if next.is_ascii_alphabetic() {\n break;\n }\n }\n }\n } else {\n result.push(c);\n }\n }\n result\n }\n\n fn format_task_line(&self, task: &Task, label_width: usize) -> String {\n let term_width = Self::terminal_width();\n\n let icon = match task.status {\n TaskStatus::Pending => format!(\"{}○{}\", DIM, RESET),\n TaskStatus::Running => self.get_spinner(),\n TaskStatus::Success => format!(\"{}✓{}\", GREEN, RESET),\n TaskStatus::Failure => format!(\"{}✗{}\", RED, RESET),\n TaskStatus::Skipped => format!(\"{}○{}\", DIM, RESET),\n };\n\n let label = format!(\"{:width$}\", task.label, width = label_width);\n let prefix = format!(\"{} {}{}{}\", icon, BOLD, label, RESET);\n let prefix_len = 1 + 1 + label_width;\n\n match task.status {\n TaskStatus::Success => {\n if let Some(dur) = task.duration {\n format!(\"{} {}({:.1}s){}\", prefix, DIM, dur.as_secs_f64(), RESET)\n } else {\n prefix\n }\n }\n TaskStatus::Failure => {\n format!(\n \"{} {}(exit {}){}\",\n prefix,\n DIM,\n task.exit_code.unwrap_or(-1),\n RESET\n )\n }\n TaskStatus::Skipped => {\n format!(\"{} {}(skipped){}\", prefix, DIM, RESET)\n }\n TaskStatus::Pending => prefix,\n TaskStatus::Running => {\n if !task.last_line.is_empty() {\n let clean = Self::strip_ansi(&task.last_line)\n .chars()\n .filter(|c| c.is_ascii_graphic() || *c == ' ')\n .collect::<String>();\n let available = term_width.saturating_sub(prefix_len + 3);\n if available > 0 {\n let truncated = Self::truncate_line(&clean, available);\n format!(\"{} {}{}{}\", prefix, DIM, truncated, RESET)\n } else {\n prefix\n }\n } else {\n prefix\n }\n }\n }\n }\n\n async fn render_display(&self) {\n let tasks = self.tasks.lock().await;\n let lines_printed = self.lines_printed.load(Ordering::Relaxed);\n\n // Move cursor up\n if lines_printed > 0 {\n print!(\"\\x1b[{}A\", lines_printed);\n }\n\n let label_width = tasks.iter().map(|t| t.label.len()).max().unwrap_or(0);\n\n for task in tasks.iter() {\n let line = self.format_task_line(task, label_width);\n println!(\"{}{}\", CLEAR_LINE, line);\n }\n\n self.lines_printed.store(tasks.len(), Ordering::Relaxed);\n let _ = io::stdout().flush();\n }\n\n async fn run_task(&self, task_idx: usize, semaphore: Arc<Semaphore>) {\n let _permit = semaphore.acquire().await.unwrap();\n\n if self.should_stop.load(Ordering::Relaxed) {\n let mut tasks = self.tasks.lock().await;\n tasks[task_idx].status = TaskStatus::Skipped;\n return;\n }\n\n let command = {\n let mut tasks = self.tasks.lock().await;\n tasks[task_idx].status = TaskStatus::Running;\n tasks[task_idx].command.clone()\n };\n\n let start = Instant::now();\n\n let mut child = match Command::new(\"sh\")\n .arg(\"-c\")\n .arg(&command)\n .stdout(Stdio::piped())\n .stderr(Stdio::piped())\n .spawn()\n {\n Ok(c) => c,\n Err(e) => {\n let mut tasks = self.tasks.lock().await;\n tasks[task_idx].status = TaskStatus::Failure;\n tasks[task_idx].exit_code = Some(-1);\n tasks[task_idx]\n .output\n .push(format!(\"Failed to spawn: {}\", e));\n tasks[task_idx].duration = Some(start.elapsed());\n\n if self.fail_fast {\n self.should_stop.store(true, Ordering::Relaxed);\n let mut first = self.first_failure_code.lock().await;\n if first.is_none() {\n *first = Some(-1);\n }\n }\n return;\n }\n };\n\n // Read stdout and stderr\n let stdout = child.stdout.take();\n let stderr = child.stderr.take();\n\n let tasks_clone = Arc::clone(&self.tasks);\n let idx = task_idx;\n\n let stdout_handle = if let Some(stdout) = stdout {\n let tasks = Arc::clone(&tasks_clone);\n Some(tokio::spawn(async move {\n let mut reader = BufReader::new(stdout).lines();\n while let Ok(Some(line)) = reader.next_line().await {\n let mut tasks = tasks.lock().await;\n tasks[idx].output.push(format!(\"{}\\n\", line));\n tasks[idx].last_line = line;\n }\n }))\n } else {\n None\n };\n\n let stderr_handle = if let Some(stderr) = stderr {\n let tasks = Arc::clone(&tasks_clone);\n Some(tokio::spawn(async move {\n let mut reader = BufReader::new(stderr).lines();\n while let Ok(Some(line)) = reader.next_line().await {\n let mut tasks = tasks.lock().await;\n tasks[idx].output.push(format!(\"{}\\n\", line));\n if tasks[idx].last_line.is_empty() {\n tasks[idx].last_line = line;\n }\n }\n }))\n } else {\n None\n };\n\n // Wait for process\n let status = child.wait().await;\n let duration = start.elapsed();\n\n // Wait for output readers\n if let Some(h) = stdout_handle {\n let _ = h.await;\n }\n if let Some(h) = stderr_handle {\n let _ = h.await;\n }\n\n let exit_code = status.map(|s| s.code().unwrap_or(-1)).unwrap_or(-1);\n\n {\n let mut tasks = self.tasks.lock().await;\n tasks[task_idx].exit_code = Some(exit_code);\n tasks[task_idx].duration = Some(duration);\n\n if exit_code == 0 {\n tasks[task_idx].status = TaskStatus::Success;\n } else {\n tasks[task_idx].status = TaskStatus::Failure;\n if self.fail_fast {\n self.should_stop.store(true, Ordering::Relaxed);\n }\n let mut first = self.first_failure_code.lock().await;\n if first.is_none() {\n *first = Some(exit_code);\n }\n }\n }\n }\n\n pub async fn run(self: Arc<Self>) -> i32 {\n // Hide cursor\n print!(\"{}\", HIDE_CURSOR);\n let _ = io::stdout().flush();\n\n let semaphore = Arc::new(Semaphore::new(self.max_jobs));\n let task_count = self.tasks.lock().await.len();\n\n // Spawn all tasks\n let mut handles = Vec::new();\n for i in 0..task_count {\n let sem = Arc::clone(&semaphore);\n let runner = Arc::clone(&self);\n handles.push(tokio::spawn(async move {\n runner.run_task(i, sem).await;\n }));\n }\n\n // Spinner loop\n let spinner_handle = {\n let runner = Arc::clone(&self);\n tokio::spawn(async move {\n loop {\n if runner.should_stop.load(Ordering::Relaxed) {\n let tasks = runner.tasks.lock().await;\n if tasks.iter().all(|t| {\n matches!(\n t.status,\n TaskStatus::Success | TaskStatus::Failure | TaskStatus::Skipped\n )\n }) {\n break;\n }\n }\n\n runner.spinner_index.fetch_add(1, Ordering::Relaxed);\n runner.render_display().await;\n tokio::time::sleep(Duration::from_millis(80)).await;\n\n let tasks = runner.tasks.lock().await;\n if tasks.iter().all(|t| {\n matches!(\n t.status,\n TaskStatus::Success | TaskStatus::Failure | TaskStatus::Skipped\n )\n }) {\n break;\n }\n }\n })\n };\n\n // Wait for all tasks\n for h in handles {\n let _ = h.await;\n }\n\n self.should_stop.store(true, Ordering::Relaxed);\n let _ = spinner_handle.await;\n\n // Final render\n self.render_display().await;\n\n // Print failures\n let tasks = self.tasks.lock().await;\n let failed: Vec<_> = tasks\n .iter()\n .filter(|t| t.status == TaskStatus::Failure)\n .collect();\n\n if !failed.is_empty() {\n println!();\n for task in failed {\n println!(\n \"{}{}━━━ {} (exit {}) ━━━{}\",\n RED,\n BOLD,\n task.label,\n task.exit_code.unwrap_or(-1),\n RESET\n );\n let output = task.output.join(\"\");\n if !output.trim().is_empty() {\n print!(\"{}\", output);\n }\n println!();\n }\n }\n\n // Show cursor\n print!(\"{}\", SHOW_CURSOR);\n let _ = io::stdout().flush();\n\n self.first_failure_code.lock().await.unwrap_or(0)\n }\n}\n\n/// Run tasks in parallel with pretty output.\npub async fn run_parallel(\n tasks: Vec<(&str, &str)>,\n max_jobs: usize,\n fail_fast: bool,\n) -> Result<()> {\n if tasks.is_empty() {\n bail!(\"No tasks specified\");\n }\n\n let tasks: Vec<Task> = tasks\n .into_iter()\n .map(|(label, cmd)| Task::new(label, cmd))\n .collect();\n\n let runner = Arc::new(ParallelRunner::new(tasks, max_jobs, fail_fast));\n let exit_code = runner.run().await;\n\n if exit_code != 0 {\n std::process::exit(exit_code);\n }\n\n Ok(())\n}\n\n/// CLI entry point for `f parallel`.\npub fn run(cmd: crate::cli::ParallelCommand) -> Result<()> {\n use tokio::runtime::Runtime;\n\n if cmd.tasks.is_empty() {\n bail!(\"No tasks specified. Usage: f parallel 'echo hello' 'echo world' or 'label:command'\");\n }\n\n // Parse tasks: either \"label:command\" or just \"command\" (auto-labeled)\n let tasks: Vec<(String, String)> = cmd\n .tasks\n .iter()\n .enumerate()\n .map(|(i, t)| {\n if let Some((label, command)) = t.split_once(':') {\n (label.to_string(), command.to_string())\n } else {\n // Auto-generate label from command or use index\n let label = t\n .split_whitespace()\n .next()\n .unwrap_or(&format!(\"task{}\", i + 1))\n .to_string();\n (label, t.to_string())\n }\n })\n .collect();\n\n let max_jobs = cmd.jobs.unwrap_or_else(|| {\n std::thread::available_parallelism()\n .map(|n| n.get())\n .unwrap_or(4)\n });\n\n let rt = Runtime::new()?;\n rt.block_on(async {\n let task_refs: Vec<(&str, &str)> = tasks\n .iter()\n .map(|(l, c)| (l.as_str(), c.as_str()))\n .collect();\n run_parallel(task_refs, max_jobs, cmd.fail_fast).await\n })\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[tokio::test]\n async fn test_parallel_success() {\n let tasks = vec![\n Task::new(\"echo1\", \"echo hello\"),\n Task::new(\"echo2\", \"echo world\"),\n ];\n let runner = Arc::new(ParallelRunner::new(tasks, 4, false));\n let code = runner.run().await;\n assert_eq!(code, 0);\n }\n\n #[tokio::test]\n async fn test_parallel_failure() {\n let tasks = vec![Task::new(\"fail\", \"exit 1\"), Task::new(\"pass\", \"echo ok\")];\n let runner = Arc::new(ParallelRunner::new(tasks, 4, false));\n let code = runner.run().await;\n assert_eq!(code, 1);\n }\n}\n" }, { "path": "src/path_hygiene.rs", "content": "#[cfg(test)]\nmod tests {\n use std::fs;\n use std::path::{Path, PathBuf};\n\n fn scan_dir(root: &Path, hits: &mut Vec<String>) {\n let entries = fs::read_dir(root).unwrap_or_else(|err| {\n panic!(\"failed to read {}: {err}\", root.display());\n });\n for entry in entries {\n let entry = entry.expect(\"read_dir entry\");\n let path = entry.path();\n if path.is_dir() {\n scan_dir(&path, hits);\n continue;\n }\n scan_file(&path, hits);\n }\n }\n\n fn scan_file(path: &Path, hits: &mut Vec<String>) {\n let Ok(contents) = fs::read_to_string(path) else {\n return;\n };\n let prefix = format!(\"/{}/\", \"Users\");\n let banned = [\n format!(\"{prefix}{}\", \"nikiv\"),\n format!(\"{prefix}{}\", \"nikitavoloboev\"),\n ];\n for (line_no, line) in contents.lines().enumerate() {\n if banned.iter().any(|needle| line.contains(needle)) {\n hits.push(format!(\"{}:{}\", path.display(), line_no + 1));\n }\n }\n }\n\n #[test]\n fn repo_avoids_committed_absolute_user_home_paths() {\n let root = PathBuf::from(env!(\"CARGO_MANIFEST_DIR\"));\n let mut hits = Vec::new();\n\n for rel in [\n \"src\",\n \"docs\",\n \".ai/skills\",\n \"flow.toml\",\n \"readme.md\",\n \"install.sh\",\n ] {\n let path = root.join(rel);\n if path.is_dir() {\n scan_dir(&path, &mut hits);\n } else {\n scan_file(&path, &mut hits);\n }\n }\n\n assert!(\n hits.is_empty(),\n \"use ~/ instead of absolute home paths in committed files:\\n{}\",\n hits.join(\"\\n\")\n );\n }\n}\n" }, { "path": "src/pr_edit.rs", "content": "use std::{\n collections::HashMap,\n path::{Path, PathBuf},\n process::Command,\n sync::Arc,\n time::{Duration, SystemTime, UNIX_EPOCH},\n};\n\nuse anyhow::{Context, Result, bail};\nuse notify::RecursiveMode;\nuse notify_debouncer_mini::new_debouncer;\nuse serde::{Deserialize, Serialize};\nuse sha2::{Digest, Sha256};\nuse tokio::sync::{RwLock, mpsc};\n\nconst STATUS_FILENAME: &str = \"status.json\";\nconst INDEX_FILENAME: &str = \".index.json\";\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct PrMeta {\n pub repo: String, // \"owner/repo\"\n pub pr: u64,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum SyncState {\n Clean,\n Dirty,\n Syncing,\n Error,\n Unknown,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct FileStatus {\n pub path: String,\n #[serde(default)]\n pub meta: Option<PrMeta>,\n pub state: SyncState,\n #[serde(default)]\n pub last_synced_at_ms: Option<i64>,\n #[serde(default)]\n pub last_error: Option<String>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\npub struct StatusSnapshot {\n pub updated_at_ms: i64,\n pub files: Vec<FileStatus>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\nstruct IndexFile {\n version: u32,\n files: HashMap<String, PrMeta>,\n}\n\n#[derive(Clone)]\npub struct PrEditService {\n dir: PathBuf,\n statuses: Arc<RwLock<HashMap<PathBuf, FileStatusInternal>>>,\n index: Arc<RwLock<IndexFile>>,\n gh_token: Arc<RwLock<Option<String>>>,\n client: reqwest::Client,\n}\n\n#[derive(Debug, Clone)]\nstruct FileStatusInternal {\n public: FileStatus,\n last_digest_hex: Option<String>, // sha256(title + \"\\n\" + body)\n}\n\nimpl PrEditService {\n pub async fn start() -> Result<Arc<Self>> {\n let debug = std::env::var_os(\"FLOW_PR_EDIT_DEBUG\").is_some();\n let dbg = |msg: &str| {\n if debug {\n eprintln!(\"[pr-edit] {msg}\");\n }\n };\n\n dbg(\"start\");\n let dir = pr_edit_dir()?;\n std::fs::create_dir_all(&dir)?;\n\n dbg(\"load index\");\n let index = load_index(&dir).unwrap_or_default();\n let svc = Arc::new(Self {\n dir,\n statuses: Arc::new(RwLock::new(HashMap::new())),\n index: Arc::new(RwLock::new(index)),\n gh_token: Arc::new(RwLock::new(None)),\n client: reqwest::Client::builder()\n .user_agent(\"flow-pr-edit\")\n .timeout(Duration::from_secs(20))\n .build()\n .context(\"failed to build GitHub HTTP client\")?,\n });\n\n // Initial scan so status.json exists and the dashboard has something to show.\n dbg(\"rescan\");\n svc.rescan().await?;\n\n // Ensure status.json exists even if directory is empty.\n dbg(\"write status.json\");\n let _ = svc.write_status_json().await;\n\n // Start watcher thread -> tokio event channel.\n dbg(\"spawn watcher thread\");\n let (tx, rx) = mpsc::channel::<PathBuf>(256);\n spawn_watcher_thread(svc.dir.clone(), tx)?;\n\n // Manager loop: debounce + sync.\n dbg(\"spawn manager loop\");\n let svc_clone = Arc::clone(&svc);\n tokio::spawn(async move {\n if let Err(err) = svc_clone.run_loop(rx).await {\n tracing::warn!(?err, \"pr-edit watcher loop exited\");\n }\n });\n\n dbg(\"ready\");\n Ok(svc)\n }\n\n pub async fn status_snapshot(&self) -> StatusSnapshot {\n let map = self.statuses.read().await;\n let mut files: Vec<FileStatus> = map.values().map(|s| s.public.clone()).collect();\n files.sort_by(|a, b| a.path.cmp(&b.path));\n StatusSnapshot {\n updated_at_ms: now_ms(),\n files,\n }\n }\n\n pub async fn rescan(&self) -> Result<()> {\n let dir = self.dir.clone();\n let files = list_md_files(&dir)?;\n let idx = self.index.read().await.clone();\n\n let mut scanned: Vec<(PathBuf, String, Option<PrMeta>)> = Vec::with_capacity(files.len());\n for path in files {\n let key = path.to_string_lossy().to_string();\n let meta = std::fs::read_to_string(&path)\n .ok()\n .and_then(|t| parse_frontmatter(&t))\n .or_else(|| idx.files.get(&key).cloned());\n scanned.push((path, key, meta));\n }\n\n let mut statuses = self.statuses.write().await;\n for (path, key, meta) in scanned {\n let entry = statuses.entry(path).or_insert_with(|| FileStatusInternal {\n public: FileStatus {\n path: key,\n meta: meta.clone(),\n state: SyncState::Unknown,\n last_synced_at_ms: None,\n last_error: None,\n },\n last_digest_hex: None,\n });\n\n entry.public.meta = meta;\n // Don't auto-sync on startup; just show whether mapping exists.\n entry.public.state = if entry.public.meta.is_some() {\n SyncState::Clean\n } else {\n SyncState::Unknown\n };\n // Preserve last_synced_at_ms / last_error / last_digest_hex from previous runtime.\n }\n drop(statuses);\n self.write_status_json().await?;\n Ok(())\n }\n\n async fn run_loop(self: Arc<Self>, mut rx: mpsc::Receiver<PathBuf>) -> Result<()> {\n let debounce = Duration::from_millis(1250);\n let mut pending: HashMap<PathBuf, tokio::time::Instant> = HashMap::new();\n\n loop {\n let next_deadline = pending.values().min().copied();\n tokio::select! {\n maybe_path = rx.recv() => {\n let Some(path) = maybe_path else { break; };\n if path.file_name().and_then(|n| n.to_str()) == Some(INDEX_FILENAME) {\n let _ = self.reload_index_from_disk().await;\n // Refresh status snapshot so newly mapped files show meta.\n let _ = self.write_status_json().await;\n continue;\n }\n if should_ignore_event_path(&self.dir, &path) {\n continue;\n }\n pending.insert(path, tokio::time::Instant::now() + debounce);\n }\n _ = async {\n if let Some(t) = next_deadline {\n tokio::time::sleep_until(t).await;\n } else {\n tokio::time::sleep(Duration::from_millis(250)).await;\n }\n } => {\n let now = tokio::time::Instant::now();\n let due: Vec<PathBuf> = pending\n .iter()\n .filter_map(|(p, t)| if *t <= now { Some(p.clone()) } else { None })\n .collect();\n if due.is_empty() {\n continue;\n }\n for p in &due {\n pending.remove(p);\n }\n\n let mut any_changed = false;\n for path in due {\n if let Err(err) = self.sync_file(&path).await {\n tracing::debug!(?err, path=%path.display(), \"pr-edit sync failed\");\n }\n any_changed = true;\n }\n if any_changed {\n let _ = self.write_status_json().await;\n }\n }\n }\n }\n\n Ok(())\n }\n\n async fn sync_file(&self, path: &Path) -> Result<()> {\n let text = match std::fs::read_to_string(path) {\n Ok(t) => t,\n Err(_) => return Ok(()), // deleted/unreadable\n };\n\n // Resolve PR identity.\n let fm = parse_frontmatter(&text);\n let idx = if fm.is_none() {\n self.lookup_index(path).await\n } else {\n None\n };\n let meta = fm.or(idx);\n\n // Parse PR title/body from markdown.\n let (title, body) = match parse_title_body(&text) {\n Ok(v) => v,\n Err(err) => {\n self.set_error(path, meta, format!(\"{err:#}\")).await;\n return Ok(());\n }\n };\n\n let digest_hex = compute_digest_hex(&title, &body);\n\n {\n let mut statuses = self.statuses.write().await;\n let entry = statuses\n .entry(path.to_path_buf())\n .or_insert_with(|| FileStatusInternal {\n public: FileStatus {\n path: path.to_string_lossy().to_string(),\n meta: meta.clone(),\n state: SyncState::Unknown,\n last_synced_at_ms: None,\n last_error: None,\n },\n last_digest_hex: None,\n });\n entry.public.meta = meta.clone();\n\n if entry.last_digest_hex.as_deref() == Some(&digest_hex)\n && entry.public.last_error.is_none()\n {\n entry.public.state = SyncState::Clean;\n return Ok(());\n }\n\n entry.public.state = SyncState::Syncing;\n entry.public.last_error = None;\n }\n\n let Some(meta) = meta else {\n self.set_error(\n path,\n None,\n \"missing PR metadata (add YAML frontmatter with repo/pr)\".to_string(),\n )\n .await;\n return Ok(());\n };\n\n // Ensure token exists (cached).\n let token = match self.get_gh_token().await {\n Ok(t) => t,\n Err(err) => {\n self.set_error(path, Some(meta), format!(\"{err:#}\")).await;\n return Ok(());\n }\n };\n\n // PATCH the PR issue (PRs are issues too).\n let url = format!(\n \"https://api.github.com/repos/{}/issues/{}\",\n meta.repo, meta.pr\n );\n let resp = match self\n .client\n .patch(url)\n .bearer_auth(token)\n .json(&serde_json::json!({ \"title\": title, \"body\": body }))\n .send()\n .await\n {\n Ok(r) => r,\n Err(err) => {\n self.set_error(\n path,\n Some(meta),\n format!(\"GitHub PATCH request failed: {err:#}\"),\n )\n .await;\n return Ok(());\n }\n };\n\n if !resp.status().is_success() {\n let status = resp.status();\n let body_text = resp.text().await.unwrap_or_default();\n self.set_error(\n path,\n Some(meta),\n format!(\"GitHub API error {status}: {body_text}\"),\n )\n .await;\n return Ok(());\n }\n\n let mut statuses = self.statuses.write().await;\n let entry = statuses\n .entry(path.to_path_buf())\n .or_insert_with(|| FileStatusInternal {\n public: FileStatus {\n path: path.to_string_lossy().to_string(),\n meta: Some(meta.clone()),\n state: SyncState::Unknown,\n last_synced_at_ms: None,\n last_error: None,\n },\n last_digest_hex: None,\n });\n entry.public.meta = Some(meta);\n entry.public.state = SyncState::Clean;\n entry.public.last_synced_at_ms = Some(now_ms());\n entry.public.last_error = None;\n entry.last_digest_hex = Some(digest_hex);\n\n Ok(())\n }\n\n async fn lookup_index(&self, path: &Path) -> Option<PrMeta> {\n let key = path.to_string_lossy().to_string();\n let guard = self.index.read().await;\n guard.files.get(&key).cloned()\n }\n\n async fn set_error(&self, path: &Path, meta: Option<PrMeta>, err: String) {\n let mut statuses = self.statuses.write().await;\n let entry = statuses\n .entry(path.to_path_buf())\n .or_insert_with(|| FileStatusInternal {\n public: FileStatus {\n path: path.to_string_lossy().to_string(),\n meta: meta.clone(),\n state: SyncState::Error,\n last_synced_at_ms: None,\n last_error: Some(err.clone()),\n },\n last_digest_hex: None,\n });\n entry.public.meta = meta;\n entry.public.state = SyncState::Error;\n entry.public.last_error = Some(err);\n }\n\n async fn get_gh_token(&self) -> Result<String> {\n if let Some(t) = self.gh_token.read().await.clone() {\n return Ok(t);\n }\n\n let out = Command::new(\"gh\")\n .args([\"auth\", \"token\"])\n .output()\n .context(\"failed to run `gh auth token`\")?;\n if !out.status.success() {\n bail!(\"`gh auth token` failed; run `gh auth login`\");\n }\n let token = String::from_utf8_lossy(&out.stdout).trim().to_string();\n if token.is_empty() {\n bail!(\"`gh auth token` returned empty token\");\n }\n\n *self.gh_token.write().await = Some(token.clone());\n Ok(token)\n }\n\n async fn write_status_json(&self) -> Result<()> {\n let snapshot = self.status_snapshot().await;\n let json = serde_json::to_string_pretty(&snapshot)?;\n\n let tmp = self.dir.join(format!(\".{STATUS_FILENAME}.tmp\"));\n let out = self.dir.join(STATUS_FILENAME);\n std::fs::write(&tmp, json)?;\n // Best-effort atomic replace.\n let _ = std::fs::rename(&tmp, &out);\n Ok(())\n }\n\n pub fn pr_edit_dir_path(&self) -> &Path {\n &self.dir\n }\n\n async fn reload_index_from_disk(&self) -> Result<()> {\n let dir = self.dir.clone();\n let idx = tokio::task::spawn_blocking(move || load_index(&dir))\n .await\n .context(\"index reload task panicked\")??;\n *self.index.write().await = idx;\n Ok(())\n }\n}\n\nfn pr_edit_dir() -> Result<PathBuf> {\n let home = dirs::home_dir().context(\"could not resolve home directory\")?;\n Ok(home.join(\".flow\").join(\"pr-edit\"))\n}\n\nfn list_md_files(dir: &Path) -> Result<Vec<PathBuf>> {\n let mut out = Vec::new();\n let entries =\n std::fs::read_dir(dir).with_context(|| format!(\"failed to read {}\", dir.display()))?;\n for ent in entries {\n let Ok(ent) = ent else {\n continue;\n };\n let p = ent.path();\n if is_md_file(&p) {\n out.push(p);\n }\n }\n Ok(out)\n}\n\nfn is_md_file(path: &Path) -> bool {\n if !path.is_file() {\n return false;\n }\n let Some(ext) = path.extension().and_then(|e| e.to_str()) else {\n return false;\n };\n if ext != \"md\" {\n return false;\n }\n let name = path.file_name().and_then(|n| n.to_str()).unwrap_or(\"\");\n if name.starts_with('.') {\n return false;\n }\n if name.ends_with('~') {\n return false;\n }\n true\n}\n\nfn should_ignore_event_path(dir: &Path, path: &Path) -> bool {\n // Ignore non-files and non-md updates.\n if path == dir.join(STATUS_FILENAME) {\n return true;\n }\n let name = path.file_name().and_then(|n| n.to_str()).unwrap_or(\"\");\n if name == STATUS_FILENAME {\n return true;\n }\n if name.starts_with(\".\")\n || name.ends_with(\"~\")\n || name.ends_with(\".swp\")\n || name.ends_with(\".tmp\")\n {\n return true;\n }\n if !name.ends_with(\".md\") {\n return true;\n }\n false\n}\n\nfn spawn_watcher_thread(dir: PathBuf, tx: mpsc::Sender<PathBuf>) -> Result<()> {\n std::thread::spawn(move || {\n let (event_tx, event_rx) = std::sync::mpsc::channel();\n let mut debouncer = match new_debouncer(Duration::from_millis(250), event_tx) {\n Ok(d) => d,\n Err(err) => {\n tracing::warn!(?err, \"failed to init pr-edit watcher\");\n return;\n }\n };\n if let Err(err) = debouncer.watcher().watch(&dir, RecursiveMode::NonRecursive) {\n tracing::warn!(?err, dir=%dir.display(), \"failed to watch pr-edit directory\");\n return;\n }\n\n loop {\n match event_rx.recv_timeout(Duration::from_millis(500)) {\n Ok(Ok(events)) => {\n for e in events {\n let p = e.path;\n let is_md = p.extension().and_then(|x| x.to_str()) == Some(\"md\");\n let is_index =\n p.file_name().and_then(|n| n.to_str()) == Some(INDEX_FILENAME);\n // Only enqueue md files + index updates; manager will do more filtering.\n if is_md || is_index {\n let _ = tx.blocking_send(p);\n }\n }\n }\n Ok(Err(err)) => {\n tracing::debug!(?err, \"pr-edit watcher error\");\n }\n Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {}\n Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => break,\n }\n }\n });\n Ok(())\n}\n\nfn parse_frontmatter(text: &str) -> Option<PrMeta> {\n let mut lines = text.lines();\n let first = lines.next()?.trim();\n if first != \"---\" {\n return None;\n }\n\n let mut repo: Option<String> = None;\n let mut pr: Option<u64> = None;\n for line in lines {\n let l = line.trim();\n if l == \"---\" {\n break;\n }\n if let Some(v) = l.strip_prefix(\"repo:\") {\n let v = v.trim().trim_matches('\"').trim_matches('\\'');\n if !v.is_empty() {\n repo = Some(v.to_string());\n }\n }\n if let Some(v) = l.strip_prefix(\"pr:\") {\n let v = v.trim();\n if let Ok(n) = v.parse::<u64>() {\n pr = Some(n);\n }\n }\n }\n\n match (repo, pr) {\n (Some(repo), Some(pr)) => Some(PrMeta { repo, pr }),\n _ => None,\n }\n}\n\nfn parse_title_body(text: &str) -> Result<(String, String)> {\n let mut title: Option<String> = None;\n let mut body_lines: Vec<String> = Vec::new();\n\n let mut lines = text.lines().peekable();\n while let Some(line) = lines.next() {\n let l = line.trim_end();\n if l.trim() == \"# Title\" {\n while let Some(nl) = lines.peek() {\n if nl.trim().is_empty() {\n lines.next();\n } else {\n break;\n }\n }\n if let Some(nl) = lines.peek() {\n let t = nl.trim();\n if !t.is_empty() {\n title = Some(t.to_string());\n }\n }\n continue;\n }\n if l.trim() == \"# Description\" {\n while let Some(nl) = lines.peek() {\n if nl.trim().is_empty() {\n lines.next();\n } else {\n break;\n }\n }\n for rest in lines {\n body_lines.push(rest.to_string());\n }\n break;\n }\n }\n\n let title = title.unwrap_or_default().trim().to_string();\n if title.is_empty() {\n bail!(\"missing PR title (expected a non-empty line under `# Title`)\");\n }\n let body = body_lines.join(\"\\n\").trim_end().to_string();\n Ok((title, body))\n}\n\nfn write_index(dir: &Path, idx: &IndexFile) -> Result<()> {\n let path = dir.join(INDEX_FILENAME);\n let json = serde_json::to_string_pretty(idx)?;\n std::fs::write(path, json)?;\n Ok(())\n}\n\n/// Best-effort helper for other codepaths (e.g. `f pr open edit`) to register mappings for files\n/// that don't (yet) have frontmatter.\npub fn index_upsert_file(path: &Path, repo: &str, pr: u64) -> Result<()> {\n let dir = pr_edit_dir()?;\n std::fs::create_dir_all(&dir)?;\n let mut idx = load_index(&dir).unwrap_or_default();\n idx.files.insert(\n path.to_string_lossy().to_string(),\n PrMeta {\n repo: repo.to_string(),\n pr,\n },\n );\n write_index(&dir, &idx)\n}\n\nfn compute_digest_hex(title: &str, body: &str) -> String {\n let mut hasher = Sha256::new();\n hasher.update(title.as_bytes());\n hasher.update(b\"\\n\");\n hasher.update(body.as_bytes());\n hex::encode(hasher.finalize())\n}\n\nfn now_ms() -> i64 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .unwrap_or_else(|_| Duration::from_secs(0))\n .as_millis() as i64\n}\n\nfn load_index(dir: &Path) -> Result<IndexFile> {\n let path = dir.join(INDEX_FILENAME);\n if !path.exists() {\n return Ok(IndexFile {\n version: 1,\n files: HashMap::new(),\n });\n }\n let text = std::fs::read_to_string(&path)?;\n let mut parsed: IndexFile = serde_json::from_str(&text)?;\n if parsed.version == 0 {\n parsed.version = 1;\n }\n Ok(parsed)\n}\n" }, { "path": "src/processes.rs", "content": "use std::collections::hash_map::DefaultHasher;\nuse std::fs::{self, File};\nuse std::hash::{Hash, Hasher};\nuse std::io::{BufRead, BufReader, Read, Seek, SeekFrom};\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\nuse std::thread;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::{KillOpts, ProcessOpts, TaskLogsOpts};\nuse crate::projects;\nuse crate::running;\nuse crate::tasks;\n\n/// Show running processes for a project (or all projects)\npub fn show_project_processes(opts: ProcessOpts) -> Result<()> {\n if opts.all {\n show_all_processes()\n } else {\n let (config_path, cfg) = tasks::load_project_config(opts.config)?;\n let canonical = config_path.canonicalize()?;\n show_processes_for_project(&canonical, cfg.project_name.as_deref())\n }\n}\n\nfn show_processes_for_project(config_path: &Path, project_name: Option<&str>) -> Result<()> {\n let processes = running::get_project_processes(config_path)?;\n let project_root = config_path.parent().unwrap_or(Path::new(\".\"));\n\n match project_name {\n Some(name) => println!(\"Project: {} ({})\", name, project_root.display()),\n None => println!(\"Project: {}\", project_root.display()),\n }\n\n if processes.is_empty() {\n println!(\"No running flow processes.\");\n return Ok(());\n }\n\n println!(\"Running processes:\");\n for proc in &processes {\n let runtime = format_runtime(proc.started_at);\n println!(\n \" {} [pid: {}, pgid: {}] - {}\",\n proc.task_name, proc.pid, proc.pgid, runtime\n );\n println!(\" {}\", proc.command);\n if proc.used_flox {\n println!(\" (flox environment)\");\n }\n }\n\n Ok(())\n}\n\nfn show_all_processes() -> Result<()> {\n let all = running::load_running_processes()?;\n\n if all.projects.is_empty() {\n println!(\"No running flow processes.\");\n return Ok(());\n }\n\n for (config_path, processes) in &all.projects {\n let project_name = processes\n .first()\n .and_then(|p| p.project_name.as_deref())\n .unwrap_or(\"unknown\");\n let project_root = Path::new(config_path)\n .parent()\n .map(|p| p.display().to_string())\n .unwrap_or_else(|| config_path.clone());\n\n println!(\"\\n{} ({}):\", project_name, project_root);\n for proc in processes {\n let runtime = format_runtime(proc.started_at);\n println!(\" {} [pid: {}] - {}\", proc.task_name, proc.pid, runtime);\n }\n }\n\n Ok(())\n}\n\nfn format_runtime(started_at: u128) -> String {\n let now = std::time::SystemTime::now()\n .duration_since(std::time::UNIX_EPOCH)\n .map(|d| d.as_millis())\n .unwrap_or(0);\n\n let elapsed_secs = ((now.saturating_sub(started_at)) / 1000) as u64;\n\n if elapsed_secs < 60 {\n format!(\"{}s\", elapsed_secs)\n } else if elapsed_secs < 3600 {\n format!(\"{}m {}s\", elapsed_secs / 60, elapsed_secs % 60)\n } else {\n format!(\"{}h {}m\", elapsed_secs / 3600, (elapsed_secs % 3600) / 60)\n }\n}\n\n/// Kill processes based on options\npub fn kill_processes(opts: KillOpts) -> Result<()> {\n let (config_path, _cfg) = tasks::load_project_config(opts.config)?;\n let canonical = config_path.canonicalize()?;\n\n if let Some(pid) = opts.pid {\n kill_by_pid(pid, opts.force, opts.timeout)\n } else if let Some(task) = &opts.task {\n kill_by_task(&canonical, task, opts.force, opts.timeout)\n } else if opts.all {\n kill_all_for_project(&canonical, opts.force, opts.timeout)\n } else {\n bail!(\"Specify a task name, --pid <pid>, or --all\")\n }\n}\n\nfn kill_by_pid(pid: u32, force: bool, timeout: u64) -> Result<()> {\n let processes = running::load_running_processes()?;\n\n // Find the process entry to get its PGID\n let entry = processes.projects.values().flatten().find(|p| p.pid == pid);\n\n let pgid = entry.map(|e| e.pgid).unwrap_or(pid);\n let task_name = entry.map(|e| e.task_name.as_str()).unwrap_or(\"unknown\");\n\n terminate_process_group(pgid, force, timeout)?;\n running::unregister_process(pid)?;\n\n println!(\"Killed {} (pid: {}, pgid: {})\", task_name, pid, pgid);\n Ok(())\n}\n\nfn kill_by_task(config_path: &Path, task: &str, force: bool, timeout: u64) -> Result<()> {\n let processes = running::get_project_processes(config_path)?;\n let matching: Vec<_> = processes.iter().filter(|p| p.task_name == task).collect();\n\n if matching.is_empty() {\n bail!(\"No running process found for task '{}'\", task);\n }\n\n for proc in matching {\n terminate_process_group(proc.pgid, force, timeout)?;\n running::unregister_process(proc.pid)?;\n println!(\"Killed {} (pid: {})\", proc.task_name, proc.pid);\n }\n\n Ok(())\n}\n\nfn kill_all_for_project(config_path: &Path, force: bool, timeout: u64) -> Result<()> {\n let processes = running::get_project_processes(config_path)?;\n\n if processes.is_empty() {\n println!(\"No running processes to kill.\");\n return Ok(());\n }\n\n for proc in &processes {\n terminate_process_group(proc.pgid, force, timeout)?;\n running::unregister_process(proc.pid)?;\n println!(\"Killed {} (pid: {})\", proc.task_name, proc.pid);\n }\n\n Ok(())\n}\n\nfn terminate_process_group(pgid: u32, force: bool, timeout: u64) -> Result<()> {\n #[cfg(unix)]\n {\n if force {\n // Immediate SIGKILL to process group\n Command::new(\"kill\")\n .arg(\"-KILL\")\n .arg(format!(\"-{}\", pgid))\n .status()\n .context(\"failed to send SIGKILL\")?;\n } else {\n // Graceful SIGTERM to process group\n let _ = Command::new(\"kill\")\n .arg(\"-TERM\")\n .arg(format!(\"-{}\", pgid))\n .status();\n\n // Wait for process to exit\n for _ in 0..timeout {\n thread::sleep(Duration::from_secs(1));\n if !running::process_alive(pgid) {\n return Ok(());\n }\n }\n\n // Force kill if still alive\n if running::process_alive(pgid) {\n Command::new(\"kill\")\n .arg(\"-KILL\")\n .arg(format!(\"-{}\", pgid))\n .status()\n .context(\"failed to send SIGKILL after timeout\")?;\n }\n }\n }\n\n #[cfg(windows)]\n {\n Command::new(\"taskkill\")\n .args([\"/PID\", &pgid.to_string(), \"/T\", \"/F\"])\n .status()\n .context(\"failed to kill process tree\")?;\n }\n\n Ok(())\n}\n\n// ============================================================================\n// Task Logs\n// ============================================================================\n\nfn log_dir() -> PathBuf {\n std::env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".config/flow/logs\")\n}\n\nfn sanitize_component(raw: &str) -> String {\n let mut s = String::with_capacity(raw.len());\n for ch in raw.chars() {\n if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' {\n s.push(ch);\n } else {\n s.push('-');\n }\n }\n s.trim_matches('-').to_lowercase()\n}\n\nfn short_hash(input: &str) -> String {\n let mut hasher = DefaultHasher::new();\n input.hash(&mut hasher);\n format!(\"{:x}\", hasher.finish())\n}\n\nfn project_slug(project_root: &Path, project_name: Option<&str>) -> String {\n let project_root_key = project_root.display().to_string();\n let project_root_hash = short_hash(&project_root_key);\n match project_name {\n Some(name) => {\n let clean = sanitize_component(name);\n if clean.is_empty() {\n format!(\"proj-{project_root_hash}\")\n } else {\n format!(\"{clean}-{project_root_hash}\")\n }\n }\n None => format!(\"proj-{project_root_hash}\"),\n }\n}\n\n/// Get the log path for a project/task\nfn get_log_path(project_root: &Path, project_name: Option<&str>, task_name: &str) -> PathBuf {\n let base = log_dir();\n let slug = project_slug(project_root, project_name);\n\n let task = {\n let clean = sanitize_component(task_name);\n if clean.is_empty() {\n \"task\".to_string()\n } else {\n clean\n }\n };\n\n base.join(slug).join(format!(\"{task}.log\"))\n}\n\n/// Show task logs\npub fn show_task_logs(opts: TaskLogsOpts) -> Result<()> {\n // If task_id is provided, fetch from hub\n if let Some(ref task_id) = opts.task_id {\n return show_hub_task_logs(task_id, opts.follow);\n }\n\n if opts.list {\n return list_available_logs(opts.all);\n }\n\n if opts.all {\n return show_all_logs(opts.lines);\n }\n\n // Resolve project: --project flag > flow.toml in cwd > active project\n let (project_root, config_path, project_name) = if let Some(ref name) = opts.project {\n // Explicit project name\n match projects::resolve_project(name)? {\n Some(entry) => (entry.project_root, entry.config_path, Some(entry.name)),\n None => {\n bail!(\n \"Project '{}' not found. Use `f projects` to see registered projects.\",\n name\n );\n }\n }\n } else if opts.config.exists() {\n // flow.toml in current directory\n let (cfg_path, cfg) = tasks::load_project_config(opts.config.clone())?;\n let canonical = cfg_path.canonicalize().unwrap_or_else(|_| cfg_path.clone());\n let root = cfg_path\n .parent()\n .unwrap_or(Path::new(\".\"))\n .canonicalize()\n .unwrap_or_else(|_| cfg_path.parent().unwrap_or(Path::new(\".\")).to_path_buf());\n (root, canonical, cfg.project_name)\n } else if let Some(active) = projects::get_active_project() {\n // Fall back to active project\n match projects::resolve_project(&active)? {\n Some(entry) => (entry.project_root, entry.config_path, Some(entry.name)),\n None => {\n bail!(\n \"Active project '{}' not found. Use `f projects` to see registered projects.\",\n active\n );\n }\n }\n } else {\n bail!(\n \"No flow.toml in current directory and no active project set.\\nRun a task in a project first, or use: f logs -p <project>\"\n );\n };\n\n // If no task specified, try to find available logs - prefer running tasks\n let task_name = match opts.task {\n Some(name) => name,\n None => {\n let logs = get_project_log_files(&project_root, project_name.as_deref());\n\n if logs.is_empty() {\n println!(\"No logs found for this project.\");\n return Ok(());\n }\n\n // Check for running tasks\n let running = running::get_project_processes(&config_path).unwrap_or_default();\n let running_tasks: Vec<_> = running.iter().map(|p| p.task_name.clone()).collect();\n let running_logs: Vec<_> = logs\n .iter()\n .filter(|log| running_tasks.contains(log))\n .cloned()\n .collect();\n\n if running_logs.len() == 1 {\n // Single running task - use it\n running_logs[0].clone()\n } else if running_logs.len() > 1 {\n // Multiple running tasks\n println!(\"Multiple running tasks. Specify which to view:\");\n for log in &running_logs {\n println!(\" f logs {}\", log);\n }\n return Ok(());\n } else if logs.len() == 1 {\n // No running tasks, but only one log file\n logs[0].clone()\n } else {\n // No running tasks, multiple log files\n println!(\"No running tasks. Available logs:\");\n for log in &logs {\n println!(\" f logs {}\", log);\n }\n return Ok(());\n }\n }\n };\n\n let log_path = get_log_path(&project_root, project_name.as_deref(), &task_name);\n\n if !log_path.exists() {\n bail!(\n \"No log file found for task '{}' at {}\",\n task_name,\n log_path.display()\n );\n }\n\n if opts.follow {\n tail_follow(&log_path, opts.lines, opts.quiet)?;\n } else {\n tail_lines(&log_path, opts.lines)?;\n }\n\n Ok(())\n}\n\nfn show_all_logs(lines: usize) -> Result<()> {\n let base = log_dir();\n if !base.exists() {\n println!(\"No logs found at {}\", base.display());\n return Ok(());\n }\n\n // Find the most recently modified log file\n let mut newest: Option<(PathBuf, u64)> = None;\n\n for entry in fs::read_dir(&base)? {\n let entry = entry?;\n let path = entry.path();\n if path.is_dir() {\n for log_entry in fs::read_dir(&path)? {\n let log_entry = log_entry?;\n let log_path = log_entry.path();\n if log_path.extension().map(|e| e == \"log\").unwrap_or(false) {\n if let Ok(meta) = fs::metadata(&log_path) {\n let modified = meta\n .modified()\n .ok()\n .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())\n .map(|d| d.as_secs())\n .unwrap_or(0);\n\n if newest.as_ref().map(|(_, t)| modified > *t).unwrap_or(true) {\n newest = Some((log_path, modified));\n }\n }\n }\n }\n }\n }\n\n match newest {\n Some((path, _)) => {\n println!(\"Showing most recent log: {}\\n\", path.display());\n tail_lines(&path, lines)\n }\n None => {\n println!(\"No log files found.\");\n Ok(())\n }\n }\n}\n\nfn list_available_logs(_all: bool) -> Result<()> {\n let base = log_dir();\n if !base.exists() {\n println!(\"No logs found at {}\", base.display());\n return Ok(());\n }\n\n println!(\"Available logs in {}:\", base.display());\n\n for entry in fs::read_dir(&base)? {\n let entry = entry?;\n let path = entry.path();\n if path.is_dir() {\n let project_name = path\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(\"unknown\");\n println!(\"\\n{}:\", project_name);\n\n for log_entry in fs::read_dir(&path)? {\n let log_entry = log_entry?;\n let log_path = log_entry.path();\n if log_path.extension().map(|e| e == \"log\").unwrap_or(false) {\n let task_name = log_path\n .file_stem()\n .and_then(|n| n.to_str())\n .unwrap_or(\"unknown\");\n let metadata = fs::metadata(&log_path)?;\n let size = metadata.len();\n let modified = metadata\n .modified()\n .ok()\n .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())\n .map(|d| d.as_secs())\n .unwrap_or(0);\n\n let now = std::time::SystemTime::now()\n .duration_since(std::time::UNIX_EPOCH)\n .map(|d| d.as_secs())\n .unwrap_or(0);\n let age = format_relative_time(now.saturating_sub(modified));\n\n println!(\" {} ({} bytes, modified {})\", task_name, size, age);\n }\n }\n }\n }\n\n Ok(())\n}\n\nfn format_relative_time(seconds: u64) -> String {\n if seconds < 60 {\n format!(\"{}s ago\", seconds)\n } else if seconds < 3600 {\n format!(\"{}m ago\", seconds / 60)\n } else if seconds < 86400 {\n format!(\"{}h ago\", seconds / 3600)\n } else {\n format!(\"{}d ago\", seconds / 86400)\n }\n}\n\n/// Get list of task names that have log files for a project\nfn get_project_log_files(project_root: &Path, project_name: Option<&str>) -> Vec<String> {\n let base = log_dir();\n let slug = project_slug(project_root, project_name);\n\n let project_log_dir = base.join(&slug);\n if !project_log_dir.exists() {\n return Vec::new();\n }\n\n let mut tasks = Vec::new();\n if let Ok(entries) = fs::read_dir(&project_log_dir) {\n for entry in entries.flatten() {\n let path = entry.path();\n if path.extension().map(|e| e == \"log\").unwrap_or(false) {\n if let Some(task_name) = path.file_stem().and_then(|n| n.to_str()) {\n tasks.push(task_name.to_string());\n }\n }\n }\n }\n tasks\n}\n\nfn tail_lines(path: &Path, n: usize) -> Result<()> {\n let file = File::open(path).context(\"failed to open log file\")?;\n let reader = BufReader::new(file);\n let lines: Vec<String> = reader.lines().filter_map(|l| l.ok()).collect();\n\n let start = lines.len().saturating_sub(n);\n for line in &lines[start..] {\n println!(\"{}\", line);\n }\n\n Ok(())\n}\n\nfn tail_follow(path: &Path, initial_lines: usize, quiet: bool) -> Result<()> {\n // First show the last N lines\n tail_lines(path, initial_lines)?;\n\n // Then follow\n let mut file = File::open(path).context(\"failed to open log file\")?;\n file.seek(SeekFrom::End(0))?;\n\n if !quiet {\n println!(\"\\n--- Following {} (Ctrl+C to stop) ---\", path.display());\n }\n\n let mut buf = vec![0u8; 4096];\n loop {\n match file.read(&mut buf) {\n Ok(0) => {\n // No new data, sleep and retry\n thread::sleep(Duration::from_millis(100));\n }\n Ok(n) => {\n print!(\"{}\", String::from_utf8_lossy(&buf[..n]));\n }\n Err(e) => {\n bail!(\"Error reading log file: {}\", e);\n }\n }\n }\n}\n\n/// Fetch and display logs for a hub task by ID\nfn show_hub_task_logs(task_id: &str, follow: bool) -> Result<()> {\n use reqwest::blocking::Client;\n use serde::Deserialize;\n\n const HUB_HOST: &str = \"127.0.0.1\";\n const HUB_PORT: u16 = 9050;\n\n #[derive(Debug, Deserialize)]\n struct TaskLog {\n id: String,\n name: String,\n command: String,\n cwd: Option<String>,\n #[allow(dead_code)]\n started_at: u64,\n finished_at: Option<u64>,\n exit_code: Option<i32>,\n output: Vec<OutputLine>,\n }\n\n #[derive(Debug, Deserialize)]\n struct OutputLine {\n #[allow(dead_code)]\n timestamp_ms: u64,\n stream: String,\n line: String,\n }\n\n let url = format!(\"http://{}:{}/tasks/logs/{}\", HUB_HOST, HUB_PORT, task_id);\n\n let client = Client::builder()\n .timeout(Duration::from_secs(5))\n .build()\n .context(\"failed to create HTTP client\")?;\n\n if follow {\n // Poll for updates\n let mut last_output_count = 0;\n\n loop {\n let resp = client.get(&url).send();\n\n match resp {\n Ok(r) if r.status().is_success() => {\n let log: TaskLog = r.json().context(\"failed to parse task log\")?;\n\n // Print new output lines\n for line in log.output.iter().skip(last_output_count) {\n let prefix = if line.stream == \"stderr\" { \"!\" } else { \" \" };\n println!(\"{} {}\", prefix, line.line);\n }\n last_output_count = log.output.len();\n\n // Check if task is done\n if log.finished_at.is_some() {\n if let Some(code) = log.exit_code {\n if code == 0 {\n println!(\"\\n✓ Task completed successfully\");\n } else {\n println!(\"\\n✗ Task failed with exit code {}\", code);\n }\n }\n break;\n }\n }\n Ok(r) if r.status().as_u16() == 404 => {\n // Task not found yet, wait\n thread::sleep(Duration::from_millis(200));\n continue;\n }\n Ok(r) => {\n bail!(\"Hub returned error: {}\", r.status());\n }\n Err(e) => {\n bail!(\"Failed to fetch task logs: {}\", e);\n }\n }\n\n thread::sleep(Duration::from_millis(500));\n }\n } else {\n // One-shot fetch\n let resp = client\n .get(&url)\n .send()\n .context(\"failed to fetch task logs\")?;\n\n if resp.status().as_u16() == 404 {\n println!(\n \"Task '{}' not found yet (queued). Streaming logs...\",\n task_id\n );\n return show_hub_task_logs(task_id, true);\n }\n\n if !resp.status().is_success() {\n bail!(\"Hub returned error: {}\", resp.status());\n }\n\n let log: TaskLog = resp.json().context(\"failed to parse task log\")?;\n\n println!(\"Task: {} ({})\", log.name, log.id);\n println!(\"Command: {}\", log.command);\n if let Some(cwd) = &log.cwd {\n println!(\"Working dir: {}\", cwd);\n }\n println!();\n\n for line in &log.output {\n let prefix = if line.stream == \"stderr\" { \"!\" } else { \" \" };\n println!(\"{} {}\", prefix, line.line);\n }\n\n if let Some(code) = log.exit_code {\n println!();\n if code == 0 {\n println!(\"✓ Exit code: {}\", code);\n } else {\n println!(\"✗ Exit code: {}\", code);\n }\n } else {\n println!(\"\\n⋯ Task still running...\");\n }\n }\n\n Ok(())\n}\n" }, { "path": "src/project_snapshot.rs", "content": "use std::{\n fs,\n path::{Path, PathBuf},\n time::UNIX_EPOCH,\n};\n\nuse anyhow::{Context, Result};\nuse serde::{Deserialize, Serialize};\n\nuse crate::{ai_tasks, discover};\n\nconst SNAPSHOT_CACHE_VERSION: u32 = 1;\nconst SNAPSHOT_CACHE_ENV_DISABLE: &str = \"FLOW_DISABLE_DISCOVERY_CACHE\";\n\n#[derive(Debug, Clone)]\npub struct ProjectSnapshot {\n pub root: PathBuf,\n pub discovery: discover::DiscoveryResult,\n pub ai_tasks: Vec<ai_tasks::DiscoveredAiTask>,\n}\n\nimpl ProjectSnapshot {\n pub fn from_root_tasks_only(root: &Path) -> Result<Self> {\n let root = canonicalize_root(root)?;\n Self::from_canonical_root_tasks_only(root)\n }\n\n pub fn from_task_config(config: &Path, climb_to_default_flow_toml: bool) -> Result<Self> {\n let root = resolve_project_root_from_config(config, climb_to_default_flow_toml)?;\n Self::from_canonical_root(root)\n }\n\n pub fn from_task_config_tasks_only(\n config: &Path,\n climb_to_default_flow_toml: bool,\n ) -> Result<Self> {\n let root = resolve_project_root_from_config(config, climb_to_default_flow_toml)?;\n Self::from_canonical_root_tasks_only(root)\n }\n\n pub fn from_current_dir(climb_to_flow_toml: bool) -> Result<Self> {\n let root = resolve_project_root_from_current_dir(climb_to_flow_toml)?;\n Self::from_canonical_root(root)\n }\n\n pub fn has_any_tasks(&self) -> bool {\n !self.discovery.tasks.is_empty() || !self.ai_tasks.is_empty()\n }\n\n pub(crate) fn from_canonical_root(root: PathBuf) -> Result<Self> {\n let (discovery, ai_tasks) = load_or_build_project_sections(&root, true)?;\n Ok(Self {\n root,\n discovery,\n ai_tasks,\n })\n }\n\n pub(crate) fn from_canonical_root_tasks_only(root: PathBuf) -> Result<Self> {\n let (discovery, _) = load_or_build_project_sections(&root, false)?;\n Ok(Self {\n root,\n discovery,\n ai_tasks: Vec::new(),\n })\n }\n}\n\n#[derive(Debug, Clone)]\npub struct AiTaskSnapshot {\n pub root: PathBuf,\n pub tasks: Vec<ai_tasks::DiscoveredAiTask>,\n}\n\nimpl AiTaskSnapshot {\n pub fn from_root(root: &Path) -> Result<Self> {\n let root = canonicalize_root(root)?;\n Self::from_canonical_root(root)\n }\n\n pub(crate) fn from_canonical_root(root: PathBuf) -> Result<Self> {\n let tasks = load_or_build_ai_tasks(&root)?;\n Ok(Self { root, tasks })\n }\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, Default)]\nstruct SnapshotCacheEntry {\n version: u32,\n discovery: Option<CachedDiscoverySection>,\n ai_tasks: Option<CachedAiTasksSection>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct CachedDiscoverySection {\n result: discover::DiscoveryResult,\n watched: Vec<PathStamp>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct CachedAiTasksSection {\n tasks: Vec<ai_tasks::DiscoveredAiTask>,\n watched: Vec<PathStamp>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct PathStamp {\n path: PathBuf,\n is_dir: bool,\n len: u64,\n modified_sec: u64,\n modified_nsec: u32,\n}\n\nfn load_or_build_project_sections(\n root: &Path,\n include_ai_tasks: bool,\n) -> Result<(discover::DiscoveryResult, Vec<ai_tasks::DiscoveredAiTask>)> {\n if cache_disabled() {\n let discovery = discover::discover_tasks_from_root(root.to_path_buf())?;\n let ai_tasks = if include_ai_tasks {\n ai_tasks::discover_tasks_from_root(root.to_path_buf())?\n } else {\n Vec::new()\n };\n return Ok((discovery, ai_tasks));\n }\n\n let cache_path = snapshot_cache_path(root);\n let mut cache = read_cache_entry(&cache_path).unwrap_or_default();\n let mut cache_dirty = false;\n\n let discovery = match cache.discovery.as_ref() {\n Some(section) if stamps_match(§ion.watched) => section.result.clone(),\n _ => {\n let artifacts = discover::discover_tasks_from_root_artifacts(root.to_path_buf())?;\n let result = artifacts.result.clone();\n cache.discovery = Some(CachedDiscoverySection {\n result: artifacts.result,\n watched: stamps_for_paths(&artifacts.watched_paths),\n });\n cache_dirty = true;\n result\n }\n };\n\n let ai_tasks = if include_ai_tasks {\n match cache.ai_tasks.as_ref() {\n Some(section) if stamps_match(§ion.watched) => section.tasks.clone(),\n _ => {\n let artifacts = ai_tasks::discover_tasks_from_root_artifacts(root.to_path_buf())?;\n let tasks = artifacts.tasks.clone();\n cache.ai_tasks = Some(CachedAiTasksSection {\n tasks: artifacts.tasks,\n watched: stamps_for_paths(&artifacts.watched_paths),\n });\n cache_dirty = true;\n tasks\n }\n }\n } else {\n Vec::new()\n };\n\n if cache_dirty && let Err(err) = write_cache_entry(&cache_path, &cache) {\n tracing::debug!(path = %cache_path.display(), error = %err, \"failed to write project snapshot cache\");\n }\n\n Ok((discovery, ai_tasks))\n}\n\nfn load_or_build_ai_tasks(root: &Path) -> Result<Vec<ai_tasks::DiscoveredAiTask>> {\n if cache_disabled() {\n return ai_tasks::discover_tasks_from_root(root.to_path_buf());\n }\n\n let cache_path = snapshot_cache_path(root);\n let mut cache = read_cache_entry(&cache_path).unwrap_or_default();\n if let Some(section) = cache.ai_tasks.as_ref()\n && stamps_match(§ion.watched)\n {\n return Ok(section.tasks.clone());\n }\n\n let artifacts = ai_tasks::discover_tasks_from_root_artifacts(root.to_path_buf())?;\n let tasks = artifacts.tasks.clone();\n cache.ai_tasks = Some(CachedAiTasksSection {\n tasks: artifacts.tasks,\n watched: stamps_for_paths(&artifacts.watched_paths),\n });\n if let Err(err) = write_cache_entry(&cache_path, &cache) {\n tracing::debug!(path = %cache_path.display(), error = %err, \"failed to write AI task snapshot cache\");\n }\n Ok(tasks)\n}\n\nfn cache_disabled() -> bool {\n matches!(\n std::env::var(SNAPSHOT_CACHE_ENV_DISABLE)\n .ok()\n .as_deref()\n .map(str::trim)\n .map(str::to_ascii_lowercase)\n .as_deref(),\n Some(\"1\" | \"true\" | \"yes\" | \"on\")\n )\n}\n\nfn snapshot_cache_path(root: &Path) -> PathBuf {\n let hash = blake3::hash(root.to_string_lossy().as_bytes()).to_hex();\n crate::config::global_state_dir()\n .join(\"project-snapshot-cache\")\n .join(format!(\"{hash}.msgpack\"))\n}\n\nfn read_cache_entry(path: &Path) -> Option<SnapshotCacheEntry> {\n let bytes = fs::read(path).ok()?;\n let cache = rmp_serde::from_slice::<SnapshotCacheEntry>(&bytes).ok()?;\n if cache.version != SNAPSHOT_CACHE_VERSION {\n return None;\n }\n Some(cache)\n}\n\nfn write_cache_entry(path: &Path, cache: &SnapshotCacheEntry) -> Result<()> {\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create snapshot cache dir {}\", parent.display()))?;\n }\n\n let mut cache = cache.clone();\n cache.version = SNAPSHOT_CACHE_VERSION;\n let bytes = rmp_serde::to_vec(&cache).context(\"failed to encode snapshot cache\")?;\n let tmp_path = path.with_extension(format!(\"msgpack.tmp.{}\", std::process::id()));\n fs::write(&tmp_path, bytes)\n .with_context(|| format!(\"failed to write snapshot cache {}\", tmp_path.display()))?;\n if let Err(err) = fs::rename(&tmp_path, path) {\n if path.exists() {\n let _ = fs::remove_file(path);\n fs::rename(&tmp_path, path)\n .with_context(|| format!(\"failed to finalize snapshot cache {}\", path.display()))?;\n } else {\n return Err(err)\n .with_context(|| format!(\"failed to finalize snapshot cache {}\", path.display()));\n }\n }\n Ok(())\n}\n\nfn stamps_for_paths(paths: &[PathBuf]) -> Vec<PathStamp> {\n let mut stamps: Vec<PathStamp> = paths\n .iter()\n .filter_map(|path| PathStamp::capture(path))\n .collect();\n stamps.sort_by(|a, b| a.path.cmp(&b.path));\n stamps.dedup_by(|a, b| a.path == b.path);\n stamps\n}\n\nfn stamps_match(stamps: &[PathStamp]) -> bool {\n stamps.iter().all(PathStamp::matches_current)\n}\n\nimpl PathStamp {\n fn capture(path: &Path) -> Option<Self> {\n let metadata = fs::metadata(path).ok()?;\n let modified = metadata.modified().ok()?.duration_since(UNIX_EPOCH).ok()?;\n Some(Self {\n path: path.to_path_buf(),\n is_dir: metadata.is_dir(),\n len: if metadata.is_file() {\n metadata.len()\n } else {\n 0\n },\n modified_sec: modified.as_secs(),\n modified_nsec: modified.subsec_nanos(),\n })\n }\n\n fn matches_current(&self) -> bool {\n let Some(current) = Self::capture(&self.path) else {\n return false;\n };\n current.is_dir == self.is_dir\n && current.len == self.len\n && current.modified_sec == self.modified_sec\n && current.modified_nsec == self.modified_nsec\n }\n}\n\npub fn canonicalize_root(root: &Path) -> Result<PathBuf> {\n let root = if root.is_absolute() {\n root.to_path_buf()\n } else {\n std::env::current_dir()?.join(root)\n };\n Ok(root.canonicalize().unwrap_or(root))\n}\n\npub fn resolve_project_root_from_current_dir(climb_to_flow_toml: bool) -> Result<PathBuf> {\n let root = std::env::current_dir()?;\n resolve_project_root_from_start(root, climb_to_flow_toml)\n}\n\npub fn resolve_project_root_from_config(\n config: &Path,\n climb_to_default_flow_toml: bool,\n) -> Result<PathBuf> {\n let resolved_config = if config.is_absolute() {\n config.to_path_buf()\n } else {\n std::env::current_dir()?.join(config)\n };\n let root = resolved_config\n .parent()\n .map(|p| p.to_path_buf())\n .unwrap_or_else(|| PathBuf::from(\".\"));\n let climb = climb_to_default_flow_toml && is_default_flow_config(config);\n resolve_project_root_from_start(root, climb)\n}\n\npub fn is_default_flow_config(path: &Path) -> bool {\n path.file_name().and_then(|name| name.to_str()) == Some(\"flow.toml\")\n}\n\npub fn find_flow_toml_upwards(start: &Path) -> Option<PathBuf> {\n let mut current = start.to_path_buf();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\nfn resolve_project_root_from_start(start: PathBuf, climb_to_flow_toml: bool) -> Result<PathBuf> {\n let root = if climb_to_flow_toml && !start.join(\"flow.toml\").exists() {\n find_flow_toml_upwards(&start)\n .and_then(|found| found.parent().map(|p| p.to_path_buf()))\n .unwrap_or(start)\n } else {\n start\n };\n Ok(root.canonicalize().unwrap_or(root))\n}\n\n#[cfg(test)]\nmod tests {\n use std::{fs, path::Path, thread, time::Duration};\n\n use tempfile::tempdir;\n\n use super::{PathStamp, find_flow_toml_upwards, resolve_project_root_from_config};\n\n struct CurrentDirGuard(std::path::PathBuf);\n\n impl Drop for CurrentDirGuard {\n fn drop(&mut self) {\n let _ = std::env::set_current_dir(&self.0);\n }\n }\n\n #[test]\n fn find_flow_toml_upwards_finds_nearest_ancestor() {\n let dir = tempdir().expect(\"tempdir\");\n let root = dir.path().join(\"repo\");\n let nested = root.join(\"a/b/c\");\n fs::create_dir_all(&nested).expect(\"nested dir\");\n fs::write(root.join(\"flow.toml\"), \"version = 1\\nname = \\\"t\\\"\\n\").expect(\"flow.toml\");\n\n let found = find_flow_toml_upwards(&nested).expect(\"should find ancestor flow.toml\");\n assert_eq!(found, root.join(\"flow.toml\"));\n }\n\n #[test]\n fn resolve_project_root_from_absolute_config_uses_parent() {\n let dir = tempdir().expect(\"tempdir\");\n let root = dir.path().join(\"repo\");\n fs::create_dir_all(&root).expect(\"repo dir\");\n let config = root.join(\"flow.toml\");\n fs::write(&config, \"version = 1\\nname = \\\"t\\\"\\n\").expect(\"flow.toml\");\n\n let resolved =\n resolve_project_root_from_config(&config, true).expect(\"absolute config resolves\");\n assert_eq!(\n resolved,\n root.canonicalize().unwrap_or(root.clone()),\n \"absolute config should resolve to its parent\"\n );\n }\n\n #[test]\n fn resolve_project_root_from_relative_config_uses_relative_parent() {\n let dir = tempdir().expect(\"tempdir\");\n let root = dir.path().join(\"repo\");\n let nested = root.join(\"nested\");\n fs::create_dir_all(&nested).expect(\"nested dir\");\n fs::write(nested.join(\"flow.toml\"), \"version = 1\\nname = \\\"t\\\"\\n\").expect(\"flow.toml\");\n\n let previous = std::env::current_dir().expect(\"current dir\");\n let _guard = CurrentDirGuard(previous);\n std::env::set_current_dir(&root).expect(\"set current dir\");\n let resolved = resolve_project_root_from_config(Path::new(\"nested/flow.toml\"), false)\n .expect(\"relative config resolves\");\n\n assert_eq!(\n resolved,\n nested.canonicalize().unwrap_or(nested.clone()),\n \"relative config should resolve to its file parent\"\n );\n }\n\n #[test]\n fn path_stamp_detects_file_changes() {\n let dir = tempdir().expect(\"tempdir\");\n let path = dir.path().join(\"flow.toml\");\n fs::write(&path, \"a = 1\\n\").expect(\"write file\");\n let stamp = PathStamp::capture(&path).expect(\"capture stamp\");\n\n thread::sleep(Duration::from_millis(5));\n fs::write(&path, \"a = 11\\n\").expect(\"rewrite file\");\n\n assert!(\n !stamp.matches_current(),\n \"file content changes should invalidate the cache stamp\"\n );\n }\n}\n" }, { "path": "src/projects.rs", "content": "use std::fs;\nuse std::path::{Path, PathBuf};\n\nuse anyhow::{Context, Result};\nuse rusqlite::{Connection, params};\nuse serde::{Deserialize, Serialize};\n\nuse crate::cli::ActiveOpts;\nuse crate::{db, running};\n\n/// Single project record.\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ProjectEntry {\n pub name: String,\n pub project_root: PathBuf,\n pub config_path: PathBuf,\n pub updated_ms: u128,\n}\n\n/// Persist the project name -> path mapping. Idempotent.\npub fn register_project(name: &str, config_path: &Path) -> Result<()> {\n let canonical_config = config_path\n .canonicalize()\n .unwrap_or_else(|_| config_path.to_path_buf());\n let project_root = config_path\n .parent()\n .unwrap_or(Path::new(\".\"))\n .canonicalize()\n .unwrap_or_else(|_| config_path.parent().unwrap_or(Path::new(\".\")).to_path_buf());\n\n let conn = open_db()?;\n create_schema(&conn)?;\n conn.execute(\n r#\"\n INSERT INTO projects (name, project_root, config_path, updated_ms)\n VALUES (?1, ?2, ?3, ?4)\n ON CONFLICT(name) DO UPDATE SET\n project_root=excluded.project_root,\n config_path=excluded.config_path,\n updated_ms=excluded.updated_ms\n \"#,\n params![\n name,\n project_root.to_string_lossy(),\n canonical_config.to_string_lossy(),\n running::now_ms() as i64\n ],\n )\n .context(\"failed to upsert project\")?;\n\n Ok(())\n}\n\n/// Return the most recent entry for a given project name, if present.\npub fn resolve_project(name: &str) -> Result<Option<ProjectEntry>> {\n let conn = open_db()?;\n create_schema(&conn)?;\n\n let mut stmt = conn.prepare(\n \"SELECT name, project_root, config_path, updated_ms FROM projects WHERE name = ?1\",\n )?;\n let mut rows = stmt.query([name])?;\n if let Some(row) = rows.next()? {\n let entry = ProjectEntry {\n name: row.get(0)?,\n project_root: PathBuf::from(row.get::<_, String>(1)?),\n config_path: PathBuf::from(row.get::<_, String>(2)?),\n updated_ms: row.get::<_, i64>(3)? as u128,\n };\n Ok(Some(entry))\n } else {\n Ok(None)\n }\n}\n\n/// List all registered projects, ordered by most recently updated.\npub fn list_projects() -> Result<Vec<ProjectEntry>> {\n let conn = open_db()?;\n create_schema(&conn)?;\n\n let mut stmt = conn.prepare(\n \"SELECT name, project_root, config_path, updated_ms FROM projects ORDER BY updated_ms DESC\",\n )?;\n let mut rows = stmt.query([])?;\n let mut entries = Vec::new();\n while let Some(row) = rows.next()? {\n entries.push(ProjectEntry {\n name: row.get(0)?,\n project_root: PathBuf::from(row.get::<_, String>(1)?),\n config_path: PathBuf::from(row.get::<_, String>(2)?),\n updated_ms: row.get::<_, i64>(3)? as u128,\n });\n }\n Ok(entries)\n}\n\n/// Print all registered projects.\npub fn show_projects() -> Result<()> {\n let projects = list_projects()?;\n if projects.is_empty() {\n println!(\"No registered projects.\");\n println!(\"Projects are registered when you run a task in a flow.toml with a 'name' field.\");\n return Ok(());\n }\n\n println!(\"Registered projects:\\n\");\n for entry in &projects {\n let age = format_age(entry.updated_ms);\n println!(\" {} ({})\", entry.name, age);\n println!(\" {}\", entry.project_root.display());\n }\n Ok(())\n}\n\nfn format_age(timestamp_ms: u128) -> String {\n let now = running::now_ms();\n let elapsed_secs = ((now.saturating_sub(timestamp_ms)) / 1000) as u64;\n\n if elapsed_secs < 60 {\n format!(\"{}s ago\", elapsed_secs)\n } else if elapsed_secs < 3600 {\n format!(\"{}m ago\", elapsed_secs / 60)\n } else if elapsed_secs < 86400 {\n format!(\"{}h ago\", elapsed_secs / 3600)\n } else {\n format!(\"{}d ago\", elapsed_secs / 86400)\n }\n}\n\nfn open_db() -> Result<Connection> {\n db::open_db()\n}\n\nfn create_schema(conn: &Connection) -> Result<()> {\n conn.execute_batch(\n r#\"\n CREATE TABLE IF NOT EXISTS projects (\n name TEXT PRIMARY KEY,\n project_root TEXT NOT NULL,\n config_path TEXT NOT NULL,\n updated_ms INTEGER NOT NULL\n );\n \"#,\n )\n .context(\"failed to create schema\")?;\n Ok(())\n}\n\n// ============================================================================\n// Active Project\n// ============================================================================\n\nfn active_project_path() -> PathBuf {\n std::env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".config/flow/active_project\")\n}\n\n/// Set the active project name.\npub fn set_active_project(name: &str) -> Result<()> {\n let path = active_project_path();\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent).context(\"failed to create config dir\")?;\n }\n fs::write(&path, name).context(\"failed to write active project\")?;\n Ok(())\n}\n\n/// Get the current active project name, if set.\npub fn get_active_project() -> Option<String> {\n let path = active_project_path();\n fs::read_to_string(&path)\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n}\n\n/// Clear the active project.\npub fn clear_active_project() -> Result<()> {\n let path = active_project_path();\n if path.exists() {\n fs::remove_file(&path).context(\"failed to remove active project\")?;\n }\n Ok(())\n}\n\n/// Handle the `f active` command.\npub fn handle_active(opts: ActiveOpts) -> Result<()> {\n if opts.clear {\n clear_active_project()?;\n println!(\"Active project cleared.\");\n return Ok(());\n }\n\n if let Some(name) = opts.project {\n // Verify project exists\n if resolve_project(&name)?.is_none() {\n anyhow::bail!(\n \"Project '{}' not found. Use `f projects` to see registered projects.\",\n name\n );\n }\n set_active_project(&name)?;\n println!(\"Active project set to: {}\", name);\n return Ok(());\n }\n\n // Show current active project\n match get_active_project() {\n Some(name) => println!(\"{}\", name),\n None => println!(\"No active project set.\"),\n }\n Ok(())\n}\n" }, { "path": "src/proxy/mod.rs", "content": "//! proxyx - Zero-cost traced reverse proxy for Flow.\n//!\n//! This module provides a lightweight reverse proxy with always-on observability\n//! designed for macOS development. Key features:\n//!\n//! - **Zero-cost tracing** via mmap ring buffer (no allocations per request)\n//! - **Agent-readable summary** JSON file for AI assistants\n//! - **Trace ID propagation** across services\n//! - **Flow integration** via flow.toml configuration\n\npub mod server;\npub mod summary;\npub mod trace;\n\nuse std::net::SocketAddr;\nuse std::path::PathBuf;\nuse std::sync::Arc;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result};\nuse serde::{Deserialize, Serialize};\n\nuse server::{Backend, ProxyRouter, ProxyServer};\nuse summary::{SummaryState, SummaryWriter};\nuse trace::TraceBuffer;\n\n/// Proxy configuration from flow.toml\n#[derive(Debug, Clone, Deserialize, Serialize, Default)]\npub struct ProxyConfig {\n /// Listen address (e.g., \":8080\" or \"127.0.0.1:8080\")\n #[serde(default = \"default_listen\")]\n pub listen: String,\n\n /// Trace ring buffer size (e.g., \"16MB\")\n #[serde(default = \"default_trace_size\")]\n pub trace_size: String,\n\n /// Trace directory\n #[serde(default)]\n pub trace_dir: Option<String>,\n\n /// Write agent-readable summary JSON\n #[serde(default = \"default_true\")]\n pub trace_summary: bool,\n\n /// Summary update interval (e.g., \"1s\")\n #[serde(default = \"default_summary_interval\")]\n pub summary_interval: String,\n\n /// Slow request threshold in milliseconds\n #[serde(default = \"default_slow_threshold\")]\n pub slow_threshold_ms: u32,\n}\n\nfn default_listen() -> String {\n \"127.0.0.1:8080\".to_string()\n}\n\nfn default_trace_size() -> String {\n \"16MB\".to_string()\n}\n\nfn default_true() -> bool {\n true\n}\n\nfn default_summary_interval() -> String {\n \"1s\".to_string()\n}\n\nfn default_slow_threshold() -> u32 {\n 500\n}\n\n/// Individual proxy target configuration\n#[derive(Debug, Clone, Deserialize, Serialize)]\npub struct ProxyTargetConfig {\n /// Unique name for this proxy\n pub name: String,\n\n /// Target address (e.g., \"localhost:3000\")\n pub target: String,\n\n /// Optional host-based routing\n #[serde(default)]\n pub host: Option<String>,\n\n /// Optional path prefix routing\n #[serde(default)]\n pub path: Option<String>,\n\n /// Capture request/response bodies\n #[serde(default)]\n pub capture_body: bool,\n\n /// Max body size to capture\n #[serde(default = \"default_capture_max\")]\n pub capture_body_max: String,\n\n /// Health check path\n #[serde(default)]\n pub health: Option<String>,\n\n /// Paths to exclude from tracing\n #[serde(default)]\n pub exclude_paths: Vec<String>,\n}\n\nfn default_capture_max() -> String {\n \"64KB\".to_string()\n}\n\n/// Parse size string (e.g., \"16MB\") to bytes\npub fn parse_size(s: &str) -> usize {\n let s = s.trim().to_uppercase();\n if let Some(num) = s.strip_suffix(\"GB\") {\n num.trim().parse::<usize>().unwrap_or(0) * 1024 * 1024 * 1024\n } else if let Some(num) = s.strip_suffix(\"MB\") {\n num.trim().parse::<usize>().unwrap_or(0) * 1024 * 1024\n } else if let Some(num) = s.strip_suffix(\"KB\") {\n num.trim().parse::<usize>().unwrap_or(0) * 1024\n } else if let Some(num) = s.strip_suffix(\"B\") {\n num.trim().parse::<usize>().unwrap_or(0)\n } else {\n s.parse::<usize>().unwrap_or(16 * 1024 * 1024)\n }\n}\n\n/// Parse duration string (e.g., \"1s\", \"500ms\") to Duration\npub fn parse_duration(s: &str) -> Duration {\n let s = s.trim().to_lowercase();\n if let Some(num) = s.strip_suffix(\"ms\") {\n Duration::from_millis(num.trim().parse().unwrap_or(1000))\n } else if let Some(num) = s.strip_suffix('s') {\n Duration::from_secs(num.trim().parse().unwrap_or(1))\n } else if let Some(num) = s.strip_suffix('m') {\n Duration::from_secs(num.trim().parse::<u64>().unwrap_or(1) * 60)\n } else {\n Duration::from_secs(s.parse().unwrap_or(1))\n }\n}\n\n/// Start the proxy server with the given configuration\npub async fn start(config: ProxyConfig, targets: Vec<ProxyTargetConfig>) -> Result<()> {\n // Parse listen address\n let listen_addr: SocketAddr = if config.listen.starts_with(':') {\n format!(\"127.0.0.1{}\", config.listen).parse()\n } else {\n config.listen.parse()\n }\n .context(\"Invalid listen address\")?;\n\n // Initialize trace buffer\n let trace_dir = config\n .trace_dir\n .as_ref()\n .map(|s| PathBuf::from(shellexpand::tilde(s).to_string()))\n .unwrap_or_else(trace::default_trace_dir);\n\n let trace_size = parse_size(&config.trace_size);\n\n let trace_buffer =\n TraceBuffer::init(&trace_dir, trace_size).context(\"Failed to initialize trace buffer\")?;\n let trace_buffer = Arc::new(trace_buffer);\n\n // Build backends\n let mut backends = Vec::new();\n for (idx, target) in targets.iter().enumerate() {\n let addr: SocketAddr = if target.target.contains(':') {\n target.target.parse()\n } else {\n format!(\"127.0.0.1:{}\", target.target).parse()\n }\n .context(format!(\"Invalid target address: {}\", target.target))?;\n\n backends.push(Backend {\n name: target.name.clone(),\n addr,\n index: idx as u8,\n });\n }\n\n // Build router\n let mut router = ProxyRouter::new(backends);\n\n for (idx, target) in targets.iter().enumerate() {\n if let Some(host) = &target.host {\n router.add_host_route(host.clone(), idx);\n }\n if let Some(path) = &target.path {\n router.add_path_route(path.clone(), idx);\n }\n }\n\n // Create summary state\n let target_names = router.backend_names();\n let summary_state = Arc::new(SummaryState::new(target_names, config.slow_threshold_ms));\n\n // Create server\n let server = Arc::new(ProxyServer::new(\n router,\n trace_buffer.clone(),\n summary_state.clone(),\n ));\n\n // Start summary writer if enabled\n if config.trace_summary {\n let summary_path = trace_dir.join(\"trace-summary.json\");\n let interval = parse_duration(&config.summary_interval);\n let writer = SummaryWriter::new(\n trace_buffer.clone(),\n summary_state.clone(),\n summary_path.clone(),\n interval,\n );\n writer.spawn();\n tracing::info!(\"Summary writer started: {:?}\", summary_path);\n }\n\n // Print startup info\n println!(\"proxyx listening on {}\", listen_addr);\n println!(\"Trace buffer: {:?} ({} bytes)\", trace_dir, trace_size);\n println!(\"Targets:\");\n for target in &targets {\n println!(\" {} -> {}\", target.name, target.target);\n }\n\n // Run server\n server::run_server(listen_addr, server).await\n}\n\n/// CLI command to view recent traces\npub fn trace_last(count: usize) -> Result<()> {\n let trace_dir = trace::default_trace_dir();\n\n // Find the trace file\n let entries = std::fs::read_dir(&trace_dir)?;\n let trace_file = entries\n .filter_map(|e| e.ok())\n .find(|e| {\n e.file_name()\n .to_str()\n .map(|s| s.starts_with(\"trace.\") && s.ends_with(\".bin\"))\n .unwrap_or(false)\n })\n .context(\"No trace file found\")?;\n\n // Memory-map and read\n let file = std::fs::File::open(trace_file.path())?;\n let size = file.metadata()?.len() as usize;\n\n let buffer = TraceBuffer::init(&trace_dir, size).context(\"Failed to open trace buffer\")?;\n\n let records = buffer.recent(count);\n\n println!(\n \"{:<12} {:<8} {:<6} {:<40} {:<6} {:<10} {:<10}\",\n \"TIME\", \"REQ_ID\", \"METHOD\", \"PATH\", \"STATUS\", \"LATENCY\", \"TARGET\"\n );\n println!(\"{}\", \"-\".repeat(100));\n\n for record in records {\n if record.timestamp() == 0 {\n continue;\n }\n println!(\n \"{:<12} {:<8x} {:<6} {:<40} {:<6} {:<10} {:<10}\",\n format!(\"{}ms ago\", record.timestamp() / 1_000_000),\n record.req_id(),\n format!(\"{:?}\", record.method()),\n truncate_path(record.path(), 40),\n record.status(),\n format!(\"{}ms\", record.latency_us() / 1000),\n record.target_idx(),\n );\n }\n\n Ok(())\n}\n\nfn truncate_path(path: &str, max_len: usize) -> String {\n if path.len() <= max_len {\n path.to_string()\n } else {\n format!(\"{}...\", &path[..max_len - 3])\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn test_parse_size() {\n assert_eq!(parse_size(\"16MB\"), 16 * 1024 * 1024);\n assert_eq!(parse_size(\"1GB\"), 1024 * 1024 * 1024);\n assert_eq!(parse_size(\"64KB\"), 64 * 1024);\n assert_eq!(parse_size(\"1024\"), 1024);\n }\n\n #[test]\n fn test_parse_duration() {\n assert_eq!(parse_duration(\"1s\"), Duration::from_secs(1));\n assert_eq!(parse_duration(\"500ms\"), Duration::from_millis(500));\n assert_eq!(parse_duration(\"5m\"), Duration::from_secs(300));\n }\n}\n" }, { "path": "src/proxy/server.rs", "content": "//! HTTP reverse proxy server.\n//!\n//! A lightweight proxy that forwards requests to backends and records traces.\n\nuse std::collections::HashMap;\nuse std::net::SocketAddr;\nuse std::sync::Arc;\nuse std::sync::atomic::{AtomicU64, Ordering};\nuse std::time::Instant;\n\nuse anyhow::{Context, Result};\nuse axum::Router;\nuse axum::body::Body;\nuse axum::extract::State;\nuse axum::http::{Request, Response, StatusCode};\nuse axum::routing::any;\nuse tokio::sync::RwLock;\n\nuse super::summary::SummaryState;\nuse super::trace::{TraceBuffer, TraceRecord, hash_path, now_ns};\n\n/// A backend target\n#[derive(Debug, Clone)]\npub struct Backend {\n pub name: String,\n pub addr: SocketAddr,\n pub index: u8,\n}\n\n/// Routing configuration\npub struct ProxyRouter {\n /// Host header -> backend index\n pub host_routes: HashMap<String, usize>,\n /// Path prefix -> backend index (checked in order)\n pub path_routes: Vec<(String, usize)>,\n /// Default backend (if no route matches)\n pub default: Option<usize>,\n /// All backends\n pub backends: Vec<Backend>,\n}\n\nimpl ProxyRouter {\n pub fn new(backends: Vec<Backend>) -> Self {\n Self {\n host_routes: HashMap::new(),\n path_routes: Vec::new(),\n default: if backends.is_empty() { None } else { Some(0) },\n backends,\n }\n }\n\n pub fn add_host_route(&mut self, host: String, backend_idx: usize) {\n self.host_routes.insert(host, backend_idx);\n }\n\n pub fn add_path_route(&mut self, prefix: String, backend_idx: usize) {\n self.path_routes.push((prefix, backend_idx));\n }\n\n pub fn route(&self, host: Option<&str>, path: &str) -> Option<&Backend> {\n // 1. Check host header\n if let Some(host_str) = host {\n // Strip port if present\n let host_name = host_str.split(':').next().unwrap_or(host_str);\n if let Some(&idx) = self.host_routes.get(host_name) {\n return self.backends.get(idx);\n }\n }\n\n // 2. Check path prefix\n for (prefix, idx) in &self.path_routes {\n if path.starts_with(prefix) {\n return self.backends.get(*idx);\n }\n }\n\n // 3. Default\n self.default.and_then(|idx| self.backends.get(idx))\n }\n\n pub fn backend_names(&self) -> Vec<String> {\n self.backends.iter().map(|b| b.name.clone()).collect()\n }\n}\n\n/// Proxy server state\npub struct ProxyServer {\n pub router: RwLock<ProxyRouter>,\n pub trace_buffer: Arc<TraceBuffer>,\n pub summary_state: Arc<SummaryState>,\n pub client: reqwest::Client,\n pub trace_id_counter: AtomicU64,\n}\n\nimpl ProxyServer {\n pub fn new(\n router: ProxyRouter,\n trace_buffer: Arc<TraceBuffer>,\n summary_state: Arc<SummaryState>,\n ) -> Self {\n let client = reqwest::Client::builder()\n .pool_max_idle_per_host(10)\n .build()\n .expect(\"Failed to create HTTP client\");\n\n Self {\n router: RwLock::new(router),\n trace_buffer,\n summary_state,\n client,\n trace_id_counter: AtomicU64::new(1),\n }\n }\n\n /// Generate a new trace ID\n pub fn next_trace_id(&self) -> u128 {\n self.trace_id_counter.fetch_add(1, Ordering::Relaxed) as u128\n }\n}\n\n/// Handle proxied requests\nasync fn proxy_handler(\n State(server): State<Arc<ProxyServer>>,\n req: Request<Body>,\n) -> Response<Body> {\n let start = Instant::now();\n let start_ns = now_ns();\n let req_id = server.trace_buffer.next_req_id();\n\n // Get or generate trace ID\n let trace_id = req\n .headers()\n .get(\"x-trace-id\")\n .and_then(|v| v.to_str().ok())\n .and_then(|s| s.parse::<u128>().ok())\n .unwrap_or_else(|| server.next_trace_id());\n\n let method = req.method().clone();\n let uri = req.uri().clone();\n let path = uri.path().to_string();\n let method_str = method.as_str();\n let host = req\n .headers()\n .get(\"host\")\n .and_then(|v| v.to_str().ok())\n .map(|s| s.to_string());\n\n // Route to backend\n let router = server.router.read().await;\n let backend = match router.route(host.as_deref(), &path) {\n Some(b) => b.clone(),\n None => {\n drop(router);\n // No route found\n let mut record = TraceRecord::new();\n record.set_timestamp(start_ns);\n record.set_req_id(req_id);\n record.set_latency_status(\n start.elapsed().as_micros() as u32,\n 502,\n method_str.into(),\n 0,\n );\n record.set_path(&path);\n record.set_path_hash(hash_path(&path));\n server.trace_buffer.record(&record);\n\n return Response::builder()\n .status(StatusCode::BAD_GATEWAY)\n .body(Body::from(\"No backend configured\"))\n .unwrap();\n }\n };\n drop(router);\n\n // Build upstream URL\n let upstream_url = format!(\n \"http://{}{}{}\",\n backend.addr,\n path,\n uri.query().map(|q| format!(\"?{}\", q)).unwrap_or_default()\n );\n\n // Forward request headers\n let upstream_start = Instant::now();\n let mut upstream_req = server.client.request(method.clone(), &upstream_url);\n\n // Copy headers (except host)\n for (name, value) in req.headers() {\n if name != \"host\" {\n if let Ok(v) = value.to_str() {\n upstream_req = upstream_req.header(name.as_str(), v);\n }\n }\n }\n\n // Add trace ID header\n upstream_req = upstream_req.header(\"x-trace-id\", trace_id.to_string());\n\n // Get request body\n let body_bytes = axum::body::to_bytes(req.into_body(), 10 * 1024 * 1024)\n .await\n .ok();\n let bytes_in = body_bytes.as_ref().map(|b| b.len()).unwrap_or(0) as u32;\n\n // Send body if present\n if let Some(body) = body_bytes {\n if !body.is_empty() {\n upstream_req = upstream_req.body(body.to_vec());\n }\n }\n\n // Execute request\n let result = upstream_req.send().await;\n let upstream_latency_us = upstream_start.elapsed().as_micros() as u32;\n\n let (status, body, bytes_out) = match result {\n Ok(resp) => {\n let status = resp.status().as_u16();\n let body = resp.text().await.unwrap_or_default();\n let bytes_out = body.len() as u32;\n\n // Store error body for AI analysis\n if status >= 400 {\n server.summary_state.store_error_body(req_id, body.clone());\n }\n\n (status, body, bytes_out)\n }\n Err(e) => {\n let error_body = format!(\"{{\\\"error\\\": \\\"{}\\\"}}\", e);\n server\n .summary_state\n .store_error_body(req_id, error_body.clone());\n (502, error_body, 0)\n }\n };\n\n let total_latency_us = start.elapsed().as_micros() as u32;\n\n // Record trace\n let mut record = TraceRecord::new();\n record.set_timestamp(start_ns);\n record.set_req_id(req_id);\n record.set_latency_status(total_latency_us, status, method_str.into(), 0);\n record.set_bytes(bytes_in, bytes_out);\n record.set_target_and_trace_id(backend.index, path.len().min(255) as u8, trace_id);\n record.set_path_hash(hash_path(&path));\n record.set_upstream_latency(upstream_latency_us);\n record.set_path(&path);\n server.trace_buffer.record(&record);\n\n // Build response\n Response::builder()\n .status(StatusCode::from_u16(status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR))\n .header(\"x-trace-id\", trace_id.to_string())\n .header(\"x-proxy-latency-ms\", (total_latency_us / 1000).to_string())\n .header(\"content-type\", \"application/json\")\n .body(Body::from(body))\n .unwrap()\n}\n\n/// Health check endpoint\nasync fn health_handler(State(server): State<Arc<ProxyServer>>) -> Response<Body> {\n let router = server.router.read().await;\n let backends: Vec<_> = router\n .backends\n .iter()\n .map(|b| {\n serde_json::json!({\n \"name\": b.name,\n \"addr\": b.addr.to_string(),\n })\n })\n .collect();\n\n let stats = serde_json::json!({\n \"status\": \"ok\",\n \"total_requests\": server.trace_buffer.write_index(),\n \"backends\": backends,\n });\n\n Response::builder()\n .status(StatusCode::OK)\n .header(\"content-type\", \"application/json\")\n .body(Body::from(serde_json::to_string_pretty(&stats).unwrap()))\n .unwrap()\n}\n\n/// Create the axum router\npub fn create_router(server: Arc<ProxyServer>) -> Router {\n Router::new()\n .route(\"/_proxy/health\", axum::routing::get(health_handler))\n .fallback(any(proxy_handler))\n .with_state(server)\n}\n\n/// Run the proxy server\npub async fn run_server(addr: SocketAddr, server: Arc<ProxyServer>) -> Result<()> {\n let app = create_router(server);\n\n let listener = tokio::net::TcpListener::bind(addr)\n .await\n .context(\"Failed to bind proxy server\")?;\n\n tracing::info!(\"Proxy server listening on {}\", addr);\n\n axum::serve(listener, app)\n .await\n .context(\"Proxy server error\")?;\n\n Ok(())\n}\n" }, { "path": "src/proxy/summary.rs", "content": "//! Agent-readable trace summary.\n//!\n//! Writes a JSON file that AI agents (like Claude Code) can read to understand\n//! the current state of the application during development.\n\nuse std::collections::HashMap;\nuse std::fs;\nuse std::path::PathBuf;\nuse std::sync::{Arc, RwLock};\nuse std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};\n\nuse serde::Serialize;\n\nuse super::trace::{TraceBuffer, TraceRecord};\n\n/// Summary of a single error for AI consumption\n#[derive(Debug, Clone, Serialize)]\npub struct ErrorSummary {\n pub time: String,\n pub req_id: String,\n pub method: String,\n pub path: String,\n pub status: u16,\n pub latency_ms: u32,\n pub target: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub error_body: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub suggestion: Option<String>,\n}\n\n/// Summary of a slow request for AI consumption\n#[derive(Debug, Clone, Serialize)]\npub struct SlowRequestSummary {\n pub time: String,\n pub req_id: String,\n pub method: String,\n pub path: String,\n pub status: u16,\n pub latency_ms: u32,\n pub upstream_latency_ms: u32,\n pub target: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub reason: Option<String>,\n}\n\n/// Health status for a target/provider\n#[derive(Debug, Clone, Serialize)]\npub struct TargetHealth {\n pub healthy: bool,\n pub total_requests: u64,\n pub error_count: u64,\n pub error_rate: String,\n pub avg_latency_ms: u32,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub last_error: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub last_error_time: Option<String>,\n}\n\n/// Session statistics\n#[derive(Debug, Clone, Serialize)]\npub struct SessionStats {\n pub started: u64,\n pub started_human: String,\n pub uptime_seconds: u64,\n pub total_requests: u64,\n pub total_errors: u64,\n pub error_rate: String,\n pub avg_latency_ms: u32,\n pub p99_latency_ms: u32,\n pub bytes_in: u64,\n pub bytes_out: u64,\n}\n\n/// The complete trace summary (written to JSON)\n#[derive(Debug, Clone, Serialize)]\npub struct TraceSummary {\n pub last_updated: u64,\n pub last_updated_human: String,\n pub session: SessionStats,\n pub recent_errors: Vec<ErrorSummary>,\n pub slow_requests: Vec<SlowRequestSummary>,\n pub target_health: HashMap<String, TargetHealth>,\n pub request_patterns: HashMap<String, u64>,\n}\n\n/// State for computing summaries\npub struct SummaryState {\n pub targets: Vec<String>,\n pub error_bodies: RwLock<HashMap<u64, String>>,\n pub slow_threshold_ms: u32,\n pub session_start: Instant,\n pub session_start_unix: u64,\n}\n\nimpl SummaryState {\n pub fn new(targets: Vec<String>, slow_threshold_ms: u32) -> Self {\n let now = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .unwrap_or_default()\n .as_secs();\n\n Self {\n targets,\n error_bodies: RwLock::new(HashMap::new()),\n slow_threshold_ms,\n session_start: Instant::now(),\n session_start_unix: now,\n }\n }\n\n /// Store an error response body for a request ID\n pub fn store_error_body(&self, req_id: u64, body: String) {\n if let Ok(mut bodies) = self.error_bodies.write() {\n // Keep only last 100 error bodies\n if bodies.len() > 100 {\n // Remove oldest entries (this is O(n) but rare)\n let to_remove: Vec<_> = bodies.keys().take(50).copied().collect();\n for k in to_remove {\n bodies.remove(&k);\n }\n }\n bodies.insert(req_id, body);\n }\n }\n\n /// Get error body for a request ID\n pub fn get_error_body(&self, req_id: u64) -> Option<String> {\n self.error_bodies\n .read()\n .ok()\n .and_then(|b| b.get(&req_id).cloned())\n }\n\n /// Get target name by index\n pub fn target_name(&self, idx: u8) -> &str {\n self.targets\n .get(idx as usize)\n .map(|s| s.as_str())\n .unwrap_or(\"unknown\")\n }\n}\n\n/// Compute a summary from the trace buffer\npub fn compute_summary(buffer: &TraceBuffer, state: &SummaryState) -> TraceSummary {\n let now = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .unwrap_or_default()\n .as_secs();\n\n let records = buffer.recent(1000);\n\n // Compute session stats\n let total_requests = buffer.write_index();\n let total_errors = records.iter().filter(|r| r.is_error()).count() as u64;\n let error_rate = if total_requests > 0 {\n format!(\n \"{:.1}%\",\n (total_errors as f64 / records.len() as f64) * 100.0\n )\n } else {\n \"0%\".to_string()\n };\n\n let latencies: Vec<u32> = records.iter().map(|r| r.latency_us() / 1000).collect();\n let avg_latency_ms = if !latencies.is_empty() {\n (latencies.iter().map(|&l| l as u64).sum::<u64>() / latencies.len() as u64) as u32\n } else {\n 0\n };\n\n let p99_latency_ms = if !latencies.is_empty() {\n let mut sorted = latencies.clone();\n sorted.sort();\n let p99_idx = (sorted.len() as f64 * 0.99) as usize;\n sorted\n .get(p99_idx.min(sorted.len() - 1))\n .copied()\n .unwrap_or(0)\n } else {\n 0\n };\n\n let bytes_in: u64 = records.iter().map(|r| r.bytes_in() as u64).sum();\n let bytes_out: u64 = records.iter().map(|r| r.bytes_out() as u64).sum();\n\n let uptime = state.session_start.elapsed().as_secs();\n\n let session = SessionStats {\n started: state.session_start_unix,\n started_human: format_timestamp(state.session_start_unix),\n uptime_seconds: uptime,\n total_requests,\n total_errors,\n error_rate,\n avg_latency_ms,\n p99_latency_ms,\n bytes_in,\n bytes_out,\n };\n\n // Recent errors (last 10)\n let recent_errors: Vec<ErrorSummary> = records\n .iter()\n .filter(|r| r.is_error())\n .take(10)\n .map(|r| {\n let error_body = state.get_error_body(r.req_id());\n let suggestion = suggest_fix(r, error_body.as_deref());\n\n ErrorSummary {\n time: format_relative_time(r.timestamp(), buffer.start_time()),\n req_id: format!(\"{:x}\", r.req_id()),\n method: format!(\"{:?}\", r.method()),\n path: r.path().to_string(),\n status: r.status(),\n latency_ms: r.latency_us() / 1000,\n target: state.target_name(r.target_idx()).to_string(),\n error_body,\n suggestion,\n }\n })\n .collect();\n\n // Slow requests (last 10, > threshold)\n let slow_requests: Vec<SlowRequestSummary> = records\n .iter()\n .filter(|r| r.is_slow(state.slow_threshold_ms))\n .take(10)\n .map(|r| {\n let reason = if r.upstream_latency_us() > state.slow_threshold_ms * 1000 * 80 / 100 {\n Some(\"Upstream response slow\".to_string())\n } else {\n None\n };\n\n SlowRequestSummary {\n time: format_relative_time(r.timestamp(), buffer.start_time()),\n req_id: format!(\"{:x}\", r.req_id()),\n method: format!(\"{:?}\", r.method()),\n path: r.path().to_string(),\n status: r.status(),\n latency_ms: r.latency_us() / 1000,\n upstream_latency_ms: r.upstream_latency_us() / 1000,\n target: state.target_name(r.target_idx()).to_string(),\n reason,\n }\n })\n .collect();\n\n // Target health\n let mut target_health: HashMap<String, TargetHealth> = HashMap::new();\n for target in &state.targets {\n target_health.insert(\n target.clone(),\n TargetHealth {\n healthy: true,\n total_requests: 0,\n error_count: 0,\n error_rate: \"0%\".to_string(),\n avg_latency_ms: 0,\n last_error: None,\n last_error_time: None,\n },\n );\n }\n\n // Compute per-target stats\n let mut target_latencies: HashMap<u8, Vec<u32>> = HashMap::new();\n let mut target_errors: HashMap<u8, (u64, Option<(String, u64)>)> = HashMap::new();\n let mut target_counts: HashMap<u8, u64> = HashMap::new();\n\n for r in &records {\n let idx = r.target_idx();\n *target_counts.entry(idx).or_insert(0) += 1;\n target_latencies\n .entry(idx)\n .or_insert_with(Vec::new)\n .push(r.latency_us() / 1000);\n\n if r.is_error() {\n let entry = target_errors.entry(idx).or_insert((0, None));\n entry.0 += 1;\n if entry.1.is_none() {\n entry.1 = Some((format!(\"{} {}\", r.status(), r.path()), r.timestamp()));\n }\n }\n }\n\n for (idx, count) in target_counts {\n let target_name = state.target_name(idx);\n if let Some(health) = target_health.get_mut(target_name) {\n health.total_requests = count;\n\n if let Some(latencies) = target_latencies.get(&idx) {\n if !latencies.is_empty() {\n health.avg_latency_ms = (latencies.iter().map(|&l| l as u64).sum::<u64>()\n / latencies.len() as u64)\n as u32;\n }\n }\n\n if let Some((error_count, last_error)) = target_errors.get(&idx) {\n health.error_count = *error_count;\n health.error_rate = format!(\"{:.1}%\", (*error_count as f64 / count as f64) * 100.0);\n health.healthy = (*error_count as f64 / count as f64) < 0.1; // < 10% errors\n\n if let Some((err, ts)) = last_error {\n health.last_error = Some(err.clone());\n health.last_error_time = Some(format_relative_time(*ts, buffer.start_time()));\n }\n }\n }\n }\n\n // Request patterns (path -> count)\n let mut request_patterns: HashMap<String, u64> = HashMap::new();\n for r in &records {\n // Normalize path (remove query params, truncate)\n let path = r.path().split('?').next().unwrap_or(\"\").to_string();\n *request_patterns.entry(path).or_insert(0) += 1;\n }\n\n // Keep only top 20 patterns\n let mut patterns: Vec<_> = request_patterns.into_iter().collect();\n patterns.sort_by(|a, b| b.1.cmp(&a.1));\n let request_patterns: HashMap<String, u64> = patterns.into_iter().take(20).collect();\n\n TraceSummary {\n last_updated: now,\n last_updated_human: format_timestamp(now),\n session,\n recent_errors,\n slow_requests,\n target_health,\n request_patterns,\n }\n}\n\n/// Write summary to a JSON file\npub fn write_summary(summary: &TraceSummary, path: &PathBuf) -> std::io::Result<()> {\n let json = serde_json::to_string_pretty(summary)?;\n fs::write(path, json)\n}\n\n/// Get the default summary file path\npub fn default_summary_path() -> PathBuf {\n dirs::config_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"flow\")\n .join(\"proxy\")\n .join(\"trace-summary.json\")\n}\n\n// Helper: format Unix timestamp as human-readable\nfn format_timestamp(ts: u64) -> String {\n use std::time::{Duration, UNIX_EPOCH};\n let dt = UNIX_EPOCH + Duration::from_secs(ts);\n // Simple format without chrono dependency\n format!(\"{:?}\", dt)\n}\n\n// Helper: format nanosecond timestamp relative to start\nfn format_relative_time(ts_ns: u64, start: Instant) -> String {\n // Convert to wall clock time (approximate)\n let elapsed = start.elapsed();\n let now_ns = elapsed.as_nanos() as u64;\n\n if ts_ns > now_ns {\n return \"now\".to_string();\n }\n\n let diff_ns = now_ns - ts_ns;\n let diff_secs = diff_ns / 1_000_000_000;\n\n if diff_secs < 60 {\n format!(\"{}s ago\", diff_secs)\n } else if diff_secs < 3600 {\n format!(\"{}m ago\", diff_secs / 60)\n } else {\n format!(\"{}h ago\", diff_secs / 3600)\n }\n}\n\n// Helper: suggest a fix based on error\nfn suggest_fix(record: &TraceRecord, error_body: Option<&str>) -> Option<String> {\n let status = record.status();\n let path = record.path();\n\n // Parse error body for common patterns\n if let Some(body) = error_body {\n if body.contains(\"ParseError\") || body.contains(\"validation\") {\n return Some(\"Check request body schema matches expected format\".to_string());\n }\n if body.contains(\"timeout\") {\n return Some(\"Upstream service timed out - check service health\".to_string());\n }\n if body.contains(\"ECONNREFUSED\") {\n return Some(\"Upstream service not running - start the service\".to_string());\n }\n if body.contains(\"token\") || body.contains(\"auth\") || body.contains(\"unauthorized\") {\n return Some(\"Authentication failed - check credentials/token\".to_string());\n }\n }\n\n // Fallback suggestions based on status code\n match status {\n 400 => Some(\"Bad request - check request parameters\".to_string()),\n 401 => Some(\"Unauthorized - check authentication\".to_string()),\n 403 => Some(\"Forbidden - check permissions\".to_string()),\n 404 => Some(format!(\"Not found - verify endpoint '{}' exists\", path)),\n 500 => Some(\"Internal server error - check server logs\".to_string()),\n 502 => Some(\"Bad gateway - upstream service may be down\".to_string()),\n 503 => Some(\"Service unavailable - service may be overloaded\".to_string()),\n 504 => Some(\"Gateway timeout - upstream service too slow\".to_string()),\n _ => None,\n }\n}\n\n/// Background task that periodically updates the summary file\npub struct SummaryWriter {\n buffer: Arc<TraceBuffer>,\n state: Arc<SummaryState>,\n path: PathBuf,\n interval: Duration,\n}\n\nimpl SummaryWriter {\n pub fn new(\n buffer: Arc<TraceBuffer>,\n state: Arc<SummaryState>,\n path: PathBuf,\n interval: Duration,\n ) -> Self {\n Self {\n buffer,\n state,\n path,\n interval,\n }\n }\n\n /// Run the summary writer (blocking)\n pub fn run(&self) {\n loop {\n let summary = compute_summary(&self.buffer, &self.state);\n if let Err(e) = write_summary(&summary, &self.path) {\n eprintln!(\"Failed to write trace summary: {}\", e);\n }\n std::thread::sleep(self.interval);\n }\n }\n\n /// Spawn as a background thread\n pub fn spawn(self) -> std::thread::JoinHandle<()> {\n std::thread::spawn(move || self.run())\n }\n}\n" }, { "path": "src/proxy/trace.rs", "content": "//! Zero-cost request tracing via mmap ring buffer.\n//!\n//! Inspired by fishx's observe.rs - uses mmap + atomic index for lock-free,\n//! allocation-free request recording.\n\nuse std::fs::OpenOptions;\nuse std::os::fd::AsRawFd;\nuse std::os::unix::fs::OpenOptionsExt;\nuse std::path::PathBuf;\nuse std::ptr::{null_mut, write_unaligned};\nuse std::sync::OnceLock;\nuse std::sync::atomic::{AtomicU64, Ordering};\nuse std::time::Instant;\n\nuse libc::{CLOCK_MONOTONIC, MAP_SHARED, PROT_READ, PROT_WRITE};\n\n// Magic bytes to identify trace files\nconst TRACE_MAGIC: &[u8; 8] = b\"PROXYTRC\";\nconst TRACE_VERSION: u32 = 1;\n\n// Record layout - 128 bytes per request\nconst TRACE_PATH_BYTES: usize = 64;\nconst TRACE_RECORD_SIZE: usize = 128;\nconst TRACE_HEADER_SIZE: usize = 64;\nconst TRACE_DEFAULT_SIZE: usize = 16 * 1024 * 1024; // 16MB default\n\n// Field indices in the record (as u64 words)\nconst IDX_TS_NS: usize = 0;\nconst IDX_REQ_ID: usize = 1;\nconst IDX_LATENCY_STATUS: usize = 2; // latency_us (32) | status (16) | method (8) | flags (8)\nconst IDX_BYTES: usize = 3; // bytes_in (32) | bytes_out (32)\nconst IDX_TARGET_PATH_LEN: usize = 4; // target_idx (8) | path_len (8) | trace_id_high (48)\nconst IDX_TRACE_ID_LOW: usize = 5;\nconst IDX_PATH_HASH: usize = 6;\nconst IDX_UPSTREAM_LATENCY: usize = 7; // upstream_latency_us (32) | reserved (32)\n// Remaining 64 bytes = path prefix\n\n/// HTTP methods encoded as u8\n#[repr(u8)]\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\npub enum Method {\n Unknown = 0,\n Get = 1,\n Post = 2,\n Put = 3,\n Delete = 4,\n Patch = 5,\n Head = 6,\n Options = 7,\n Connect = 8,\n Trace = 9,\n}\n\nimpl From<&str> for Method {\n fn from(s: &str) -> Self {\n match s {\n \"GET\" => Method::Get,\n \"POST\" => Method::Post,\n \"PUT\" => Method::Put,\n \"DELETE\" => Method::Delete,\n \"PATCH\" => Method::Patch,\n \"HEAD\" => Method::Head,\n \"OPTIONS\" => Method::Options,\n \"CONNECT\" => Method::Connect,\n \"TRACE\" => Method::Trace,\n _ if s.eq_ignore_ascii_case(\"GET\") => Method::Get,\n _ if s.eq_ignore_ascii_case(\"POST\") => Method::Post,\n _ if s.eq_ignore_ascii_case(\"PUT\") => Method::Put,\n _ if s.eq_ignore_ascii_case(\"DELETE\") => Method::Delete,\n _ if s.eq_ignore_ascii_case(\"PATCH\") => Method::Patch,\n _ if s.eq_ignore_ascii_case(\"HEAD\") => Method::Head,\n _ if s.eq_ignore_ascii_case(\"OPTIONS\") => Method::Options,\n _ if s.eq_ignore_ascii_case(\"CONNECT\") => Method::Connect,\n _ if s.eq_ignore_ascii_case(\"TRACE\") => Method::Trace,\n _ => Method::Unknown,\n }\n }\n}\n\n/// Trace record header (64 bytes, at start of mmap file)\n#[repr(C)]\nstruct TraceHeader {\n magic: [u8; 8],\n version: u32,\n record_size: u32,\n capacity: u64,\n write_index: AtomicU64,\n req_counter: AtomicU64,\n // Target names stored after header, before records\n target_count: u32,\n _reserved: [u8; 20],\n}\n\n/// A single trace record (128 bytes)\n#[repr(C)]\n#[derive(Clone, Copy)]\npub struct TraceRecord {\n words: [u64; 8],\n path: [u8; TRACE_PATH_BYTES],\n}\n\nimpl TraceRecord {\n pub fn new() -> Self {\n Self {\n words: [0; 8],\n path: [0; TRACE_PATH_BYTES],\n }\n }\n\n #[inline]\n pub fn set_timestamp(&mut self, ts_ns: u64) {\n self.words[IDX_TS_NS] = ts_ns;\n }\n\n #[inline]\n pub fn set_req_id(&mut self, req_id: u64) {\n self.words[IDX_REQ_ID] = req_id;\n }\n\n #[inline]\n pub fn set_latency_status(&mut self, latency_us: u32, status: u16, method: Method, flags: u8) {\n self.words[IDX_LATENCY_STATUS] =\n (latency_us as u64) << 32 | (status as u64) << 16 | (method as u64) << 8 | flags as u64;\n }\n\n #[inline]\n pub fn set_bytes(&mut self, bytes_in: u32, bytes_out: u32) {\n self.words[IDX_BYTES] = (bytes_in as u64) << 32 | bytes_out as u64;\n }\n\n #[inline]\n pub fn set_target_and_trace_id(&mut self, target_idx: u8, path_len: u8, trace_id: u128) {\n let trace_id_high = (trace_id >> 64) as u64;\n let trace_id_low = trace_id as u64;\n self.words[IDX_TARGET_PATH_LEN] = (target_idx as u64) << 56\n | (path_len as u64) << 48\n | (trace_id_high & 0xFFFF_FFFF_FFFF);\n self.words[IDX_TRACE_ID_LOW] = trace_id_low;\n }\n\n #[inline]\n pub fn set_path_hash(&mut self, hash: u64) {\n self.words[IDX_PATH_HASH] = hash;\n }\n\n #[inline]\n pub fn set_upstream_latency(&mut self, upstream_latency_us: u32) {\n self.words[IDX_UPSTREAM_LATENCY] = (upstream_latency_us as u64) << 32;\n }\n\n #[inline]\n pub fn set_path(&mut self, path: &str) {\n let bytes = path.as_bytes();\n let len = bytes.len().min(TRACE_PATH_BYTES);\n self.path[..len].copy_from_slice(&bytes[..len]);\n }\n\n // Getters for reading records\n #[inline]\n pub fn timestamp(&self) -> u64 {\n self.words[IDX_TS_NS]\n }\n\n #[inline]\n pub fn req_id(&self) -> u64 {\n self.words[IDX_REQ_ID]\n }\n\n #[inline]\n pub fn latency_us(&self) -> u32 {\n (self.words[IDX_LATENCY_STATUS] >> 32) as u32\n }\n\n #[inline]\n pub fn status(&self) -> u16 {\n ((self.words[IDX_LATENCY_STATUS] >> 16) & 0xFFFF) as u16\n }\n\n #[inline]\n pub fn method(&self) -> Method {\n match ((self.words[IDX_LATENCY_STATUS] >> 8) & 0xFF) as u8 {\n 1 => Method::Get,\n 2 => Method::Post,\n 3 => Method::Put,\n 4 => Method::Delete,\n 5 => Method::Patch,\n 6 => Method::Head,\n 7 => Method::Options,\n 8 => Method::Connect,\n 9 => Method::Trace,\n _ => Method::Unknown,\n }\n }\n\n #[inline]\n pub fn flags(&self) -> u8 {\n (self.words[IDX_LATENCY_STATUS] & 0xFF) as u8\n }\n\n #[inline]\n pub fn bytes_in(&self) -> u32 {\n (self.words[IDX_BYTES] >> 32) as u32\n }\n\n #[inline]\n pub fn bytes_out(&self) -> u32 {\n (self.words[IDX_BYTES] & 0xFFFF_FFFF) as u32\n }\n\n #[inline]\n pub fn target_idx(&self) -> u8 {\n (self.words[IDX_TARGET_PATH_LEN] >> 56) as u8\n }\n\n #[inline]\n pub fn path_len(&self) -> u8 {\n ((self.words[IDX_TARGET_PATH_LEN] >> 48) & 0xFF) as u8\n }\n\n #[inline]\n pub fn trace_id(&self) -> u128 {\n let high = (self.words[IDX_TARGET_PATH_LEN] & 0xFFFF_FFFF_FFFF) as u128;\n let low = self.words[IDX_TRACE_ID_LOW] as u128;\n (high << 64) | low\n }\n\n #[inline]\n pub fn path_hash(&self) -> u64 {\n self.words[IDX_PATH_HASH]\n }\n\n #[inline]\n pub fn upstream_latency_us(&self) -> u32 {\n (self.words[IDX_UPSTREAM_LATENCY] >> 32) as u32\n }\n\n #[inline]\n pub fn path(&self) -> &str {\n let len = self.path_len() as usize;\n std::str::from_utf8(&self.path[..len.min(TRACE_PATH_BYTES)]).unwrap_or(\"\")\n }\n\n /// Check if this is an error response\n #[inline]\n pub fn is_error(&self) -> bool {\n self.status() >= 400\n }\n\n /// Check if this is a slow request (> threshold_ms)\n #[inline]\n pub fn is_slow(&self, threshold_ms: u32) -> bool {\n self.latency_us() > threshold_ms * 1000\n }\n}\n\nimpl Default for TraceRecord {\n fn default() -> Self {\n Self::new()\n }\n}\n\n/// The trace buffer state (mmap handle)\npub struct TraceBuffer {\n _map: *mut u8,\n _map_len: usize,\n header: *mut TraceHeader,\n records: *mut u8,\n capacity: u64,\n start_time: Instant,\n}\n\n// Safety: The mmap is process-local and we use atomic operations\nunsafe impl Send for TraceBuffer {}\nunsafe impl Sync for TraceBuffer {}\n\nimpl TraceBuffer {\n /// Initialize a new trace buffer at the given path\n pub fn init(dir: &PathBuf, size: usize) -> Option<Self> {\n if std::fs::create_dir_all(dir).is_err() {\n return None;\n }\n\n let pid = unsafe { libc::getpid() };\n let filename = format!(\"trace.{}.bin\", pid);\n let path = dir.join(filename);\n\n let file = OpenOptions::new()\n .create(true)\n .read(true)\n .write(true)\n .mode(0o600)\n .open(&path)\n .ok()?;\n\n // Ensure file is the right size\n if set_file_len(&file, size).is_err() {\n return None;\n }\n\n let map = unsafe {\n libc::mmap(\n null_mut(),\n size,\n PROT_READ | PROT_WRITE,\n MAP_SHARED,\n file.as_raw_fd(),\n 0,\n )\n };\n if map == libc::MAP_FAILED {\n return None;\n }\n\n let header = map as *mut TraceHeader;\n let records = unsafe { (map as *mut u8).add(TRACE_HEADER_SIZE) };\n let capacity = ((size - TRACE_HEADER_SIZE) / TRACE_RECORD_SIZE) as u64;\n\n if capacity == 0 {\n unsafe {\n libc::munmap(map, size);\n }\n return None;\n }\n\n // Initialize or validate header\n unsafe {\n if (*header).magic != *TRACE_MAGIC\n || (*header).version != TRACE_VERSION\n || (*header).record_size != TRACE_RECORD_SIZE as u32\n || (*header).capacity != capacity\n {\n write_unaligned(\n header,\n TraceHeader {\n magic: *TRACE_MAGIC,\n version: TRACE_VERSION,\n record_size: TRACE_RECORD_SIZE as u32,\n capacity,\n write_index: AtomicU64::new(0),\n req_counter: AtomicU64::new(0),\n target_count: 0,\n _reserved: [0; 20],\n },\n );\n }\n }\n\n Some(TraceBuffer {\n _map: map as *mut u8,\n _map_len: size,\n header,\n records,\n capacity,\n start_time: Instant::now(),\n })\n }\n\n /// Record a completed request (zero allocations)\n #[inline]\n pub fn record(&self, record: &TraceRecord) {\n let idx = unsafe { (*self.header).write_index.fetch_add(1, Ordering::Relaxed) };\n let slot = (idx % self.capacity) as usize;\n let dst = unsafe { self.records.add(slot * TRACE_RECORD_SIZE) as *mut TraceRecord };\n unsafe { write_unaligned(dst, *record) };\n }\n\n /// Get the next request ID (monotonically increasing)\n #[inline]\n pub fn next_req_id(&self) -> u64 {\n unsafe { (*self.header).req_counter.fetch_add(1, Ordering::Relaxed) }\n }\n\n /// Get current write index\n #[inline]\n pub fn write_index(&self) -> u64 {\n unsafe { (*self.header).write_index.load(Ordering::Relaxed) }\n }\n\n /// Get capacity (number of records)\n #[inline]\n pub fn capacity(&self) -> u64 {\n self.capacity\n }\n\n /// Read a record at a given index (wraps around)\n #[inline]\n pub fn read(&self, idx: u64) -> TraceRecord {\n let slot = (idx % self.capacity) as usize;\n let src = unsafe { self.records.add(slot * TRACE_RECORD_SIZE) as *const TraceRecord };\n unsafe { std::ptr::read_unaligned(src) }\n }\n\n /// Iterate over recent records (most recent first)\n pub fn recent(&self, count: usize) -> Vec<TraceRecord> {\n let write_idx = self.write_index();\n let count = count.min(write_idx as usize).min(self.capacity as usize);\n let mut records = Vec::with_capacity(count);\n\n for i in 0..count {\n let idx = write_idx.saturating_sub(1 + i as u64);\n records.push(self.read(idx));\n }\n\n records\n }\n\n /// Iterate over records matching a predicate\n pub fn filter<F>(&self, count: usize, predicate: F) -> Vec<TraceRecord>\n where\n F: Fn(&TraceRecord) -> bool,\n {\n let write_idx = self.write_index();\n let max_scan = (self.capacity as usize).min(write_idx as usize);\n let mut records = Vec::new();\n\n for i in 0..max_scan {\n if records.len() >= count {\n break;\n }\n let idx = write_idx.saturating_sub(1 + i as u64);\n let record = self.read(idx);\n if predicate(&record) {\n records.push(record);\n }\n }\n\n records\n }\n\n /// Get timestamp of buffer creation\n pub fn start_time(&self) -> Instant {\n self.start_time\n }\n}\n\nimpl Drop for TraceBuffer {\n fn drop(&mut self) {\n unsafe {\n libc::munmap(self._map as *mut libc::c_void, self._map_len);\n }\n }\n}\n\n/// Global trace buffer (lazily initialized)\nstatic TRACE_BUFFER: OnceLock<Option<TraceBuffer>> = OnceLock::new();\n\n/// Initialize the global trace buffer\npub fn init_global(dir: PathBuf, size: usize) -> bool {\n TRACE_BUFFER\n .get_or_init(|| TraceBuffer::init(&dir, size))\n .is_some()\n}\n\n/// Get the global trace buffer\npub fn global() -> Option<&'static TraceBuffer> {\n TRACE_BUFFER.get().and_then(|b| b.as_ref())\n}\n\n/// Record a request to the global buffer\n#[inline]\npub fn record(record: &TraceRecord) {\n if let Some(buf) = global() {\n buf.record(record);\n }\n}\n\n/// Get next request ID from global buffer\n#[inline]\npub fn next_req_id() -> u64 {\n global().map(|b| b.next_req_id()).unwrap_or(0)\n}\n\n// Helper: get monotonic time in nanoseconds\npub fn now_ns() -> u64 {\n unsafe {\n let mut ts = std::mem::MaybeUninit::<libc::timespec>::uninit();\n if libc::clock_gettime(CLOCK_MONOTONIC, ts.as_mut_ptr()) == 0 {\n let ts = ts.assume_init();\n return (ts.tv_sec as u64)\n .saturating_mul(1_000_000_000)\n .saturating_add(ts.tv_nsec as u64);\n }\n }\n 0\n}\n\n// Helper: FNV-1a hash for path strings\npub fn hash_path(path: &str) -> u64 {\n let mut hash: u64 = 0xcbf29ce484222325;\n for b in path.bytes() {\n hash ^= b as u64;\n hash = hash.wrapping_mul(0x100000001b3);\n }\n hash\n}\n\n// Helper: set file length\nfn set_file_len(file: &std::fs::File, size: usize) -> std::io::Result<()> {\n let fd = file.as_raw_fd();\n let res = unsafe { libc::ftruncate(fd, size as libc::off_t) };\n if res == 0 {\n Ok(())\n } else {\n Err(std::io::Error::last_os_error())\n }\n}\n\n/// Get the default trace directory\npub fn default_trace_dir() -> PathBuf {\n dirs::config_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"flow\")\n .join(\"proxy\")\n}\n\n/// Get the default trace size\npub fn default_trace_size() -> usize {\n TRACE_DEFAULT_SIZE\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn test_record_roundtrip() {\n let mut record = TraceRecord::new();\n record.set_timestamp(12345678);\n record.set_req_id(42);\n record.set_latency_status(1500, 200, Method::Get, 0);\n record.set_bytes(100, 2048);\n record.set_target_and_trace_id(1, 10, 0xDEADBEEF);\n record.set_path_hash(hash_path(\"/api/users\"));\n record.set_upstream_latency(1200);\n record.set_path(\"/api/users\");\n\n assert_eq!(record.timestamp(), 12345678);\n assert_eq!(record.req_id(), 42);\n assert_eq!(record.latency_us(), 1500);\n assert_eq!(record.status(), 200);\n assert_eq!(record.method(), Method::Get);\n assert_eq!(record.bytes_in(), 100);\n assert_eq!(record.bytes_out(), 2048);\n assert_eq!(record.target_idx(), 1);\n assert_eq!(record.upstream_latency_us(), 1200);\n assert_eq!(record.path(), \"/api/users\");\n }\n}\n" }, { "path": "src/publish.rs", "content": "//! Publish projects to gitedit.dev or GitHub.\n\nuse std::collections::HashSet;\nuse std::io::{self, IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result, bail};\nuse crossterm::event::{self, Event as CEvent, KeyCode};\nuse crossterm::terminal::{disable_raw_mode, enable_raw_mode};\nuse reqwest::blocking::Client;\nuse serde::Serialize;\n\nuse crate::cli::{PublishAction, PublishCommand, PublishOpts};\nuse crate::config;\nuse crate::vcs;\n\nfn parse_github_repo(url: &str) -> Result<(String, String, String)> {\n let trimmed = url.trim().trim_end_matches('/');\n if trimmed.is_empty() {\n bail!(\"GitHub URL is empty\");\n }\n\n if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n let rest = rest.trim_end_matches(\".git\");\n let Some((owner, repo)) = rest.split_once('/') else {\n bail!(\"Invalid GitHub SSH URL: {}\", url);\n };\n return Ok((\n owner.to_string(),\n repo.to_string(),\n format!(\"git@github.com:{}/{}.git\", owner, repo),\n ));\n }\n\n if let Some(rest) = trimmed.strip_prefix(\"https://github.com/\") {\n let rest = rest.trim_end_matches(\".git\");\n let Some((owner, repo)) = rest.split_once('/') else {\n bail!(\"Invalid GitHub HTTPS URL: {}\", url);\n };\n return Ok((\n owner.to_string(),\n repo.to_string(),\n format!(\"git@github.com:{}/{}.git\", owner, repo),\n ));\n }\n\n bail!(\n \"Unsupported GitHub URL (expected https://github.com/... or git@github.com:...): {}\",\n url\n );\n}\n\n/// Run the publish command.\npub fn run(cmd: PublishCommand) -> Result<()> {\n match cmd.action {\n Some(PublishAction::Gitedit(opts)) => run_gitedit(opts),\n Some(PublishAction::Github(opts)) => run_github(opts),\n None => run_fuzzy_select(),\n }\n}\n\n/// Show fuzzy picker for publish targets.\nfn run_fuzzy_select() -> Result<()> {\n let options = vec![\n (\"gitedit\", \"Publish to gitedit.dev\"),\n (\"github\", \"Publish to GitHub\"),\n ];\n\n let input = options\n .iter()\n .map(|(cmd, desc)| format!(\"{}\\t{}\", cmd, desc))\n .collect::<Vec<_>>()\n .join(\"\\n\");\n\n let output = Command::new(\"fzf\")\n .args([\n \"--height=10\",\n \"--reverse\",\n \"--delimiter=\\t\",\n \"--with-nth=1,2\",\n ])\n .stdin(std::process::Stdio::piped())\n .stdout(std::process::Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n output.stdin.as_ref().unwrap().write_all(input.as_bytes())?;\n\n let result = output.wait_with_output()?;\n if !result.status.success() {\n return Ok(()); // User cancelled\n }\n\n let selected = String::from_utf8_lossy(&result.stdout)\n .trim()\n .split('\\t')\n .next()\n .unwrap_or(\"\")\n .to_string();\n\n match selected.as_str() {\n \"gitedit\" => run_gitedit(PublishOpts::default()),\n \"github\" => run_github(PublishOpts::default()),\n _ => Ok(()),\n }\n}\n\n/// Run the GitHub publish flow.\npub fn run_github(opts: PublishOpts) -> Result<()> {\n // Check if gh CLI is available\n if Command::new(\"gh\").arg(\"--version\").output().is_err() {\n bail!(\"GitHub CLI (gh) is not installed. Install from: https://cli.github.com\");\n }\n\n // Check if authenticated\n let auth_status = Command::new(\"gh\")\n .args([\"auth\", \"status\"])\n .output()\n .context(\"failed to check gh auth status\")?;\n\n if !auth_status.status.success() {\n println!(\"Not authenticated with GitHub.\");\n println!(\"Run: gh auth login\");\n bail!(\"GitHub authentication required\");\n }\n\n // Get current directory name as default repo name\n let cwd = std::env::current_dir()?;\n let folder_name = cwd\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(\"repo\")\n .to_string();\n\n // Check if already a git repo\n let is_git_repo = cwd.join(\".git\").exists();\n\n // Get GitHub username (fallback owner)\n let gh_user = Command::new(\"gh\")\n .args([\"api\", \"user\", \"-q\", \".login\"])\n .output()\n .context(\"failed to get GitHub username\")?;\n\n let username = String::from_utf8_lossy(&gh_user.stdout).trim().to_string();\n if username.is_empty() {\n bail!(\"Could not determine GitHub username\");\n }\n let mut owner = opts.owner.clone().unwrap_or_else(|| username.clone());\n let mut repo_name_from_url: Option<String> = None;\n let mut remote_from_url: Option<String> = None;\n if let Some(url) = opts.url.as_ref() {\n let (parsed_owner, parsed_name, parsed_remote) = parse_github_repo(url)?;\n owner = parsed_owner;\n repo_name_from_url = Some(parsed_name);\n remote_from_url = Some(parsed_remote);\n }\n\n // Determine repo name\n let repo_name = if let Some(name) = opts.name {\n name\n } else if let Some(name) = repo_name_from_url.clone() {\n name\n } else if opts.yes {\n folder_name.clone()\n } else {\n print!(\"Repository name [{}]: \", folder_name);\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let input = input.trim();\n if input.is_empty() {\n folder_name.clone()\n } else {\n input.to_string()\n }\n };\n\n // Determine visibility\n let is_public = if opts.public {\n true\n } else if opts.private {\n false\n } else if opts.yes {\n false // Default to private if -y is passed\n } else {\n prompt_public_choice()?\n };\n\n let visibility = if is_public { \"public\" } else { \"private\" };\n let full_name = format!(\"{}/{}\", owner, repo_name);\n let desired_remote =\n remote_from_url.unwrap_or_else(|| format!(\"git@github.com:{}.git\", full_name));\n let set_origin = opts.set_origin || opts.url.is_some();\n\n // Check if repo already exists\n let repo_check = Command::new(\"gh\")\n .args([\n \"repo\",\n \"view\",\n &full_name,\n \"--json\",\n \"visibility\",\n \"-q\",\n \".visibility\",\n ])\n .output();\n\n if let Ok(output) = repo_check {\n if output.status.success() {\n let current_visibility = String::from_utf8_lossy(&output.stdout)\n .trim()\n .to_lowercase();\n println!(\n \"Repository {} already exists ({}).\",\n full_name, current_visibility\n );\n\n // Check if visibility needs to change\n let target_visibility = if is_public { \"public\" } else { \"private\" };\n if current_visibility != target_visibility {\n println!(\"Updating visibility to {}...\", target_visibility);\n let visibility_flag = format!(\"--visibility={}\", target_visibility);\n let update_result = Command::new(\"gh\")\n .args([\n \"repo\",\n \"edit\",\n &full_name,\n &visibility_flag,\n \"--accept-visibility-change-consequences\",\n ])\n .status()\n .context(\"failed to update repository visibility\")?;\n\n if update_result.success() {\n println!(\"✓ Updated to {}\", target_visibility);\n } else {\n println!(\"Warning: Could not update visibility\");\n }\n }\n\n // Check if origin remote exists\n let origin_check = Command::new(\"git\")\n .args([\"remote\", \"get-url\", \"origin\"])\n .output();\n\n if let Ok(output) = origin_check {\n if output.status.success() {\n let current_origin = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if set_origin && current_origin != desired_remote {\n println!(\"Updating origin remote...\");\n Command::new(\"git\")\n .args([\"remote\", \"set-url\", \"origin\", &desired_remote])\n .status()\n .context(\"failed to update origin remote\")?;\n }\n\n let should_push = if opts.yes {\n true\n } else {\n prompt_push_choice()?\n };\n\n if should_push {\n println!(\"Pushing to {}...\", full_name);\n push_to_origin()?;\n }\n\n println!(\"\\n✓ https://github.com/{}\", full_name);\n return Ok(());\n }\n }\n\n // Add origin and push\n println!(\"Adding origin remote...\");\n let remote_url = desired_remote.clone();\n Command::new(\"git\")\n .args([\"remote\", \"add\", \"origin\", &remote_url])\n .status()\n .context(\"failed to add origin remote\")?;\n\n println!(\"Pushing to {}...\", full_name);\n push_to_origin()?;\n\n println!(\"\\n✓ Published to https://github.com/{}\", full_name);\n return Ok(());\n }\n }\n\n // Show confirmation\n if !opts.yes {\n println!();\n println!(\"Create repository:\");\n println!(\" Name: {}\", full_name);\n println!(\" Visibility: {}\", visibility);\n if let Some(ref desc) = opts.description {\n println!(\" Description: {}\", desc);\n }\n println!();\n\n print!(\"Proceed? [Y/n]: \");\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let input = input.trim().to_lowercase();\n if input == \"n\" || input == \"no\" {\n println!(\"Aborted.\");\n return Ok(());\n }\n }\n\n // Initialize git if needed\n if !is_git_repo {\n println!(\"Initializing git repository...\");\n Command::new(\"git\")\n .args([\"init\"])\n .status()\n .context(\"failed to initialize git\")?;\n\n // Create initial commit if no commits exist\n let has_commits = Command::new(\"git\")\n .args([\"rev-parse\", \"HEAD\"])\n .output()\n .map(|o| o.status.success())\n .unwrap_or(false);\n\n if !has_commits {\n // Stage all files\n Command::new(\"git\")\n .args([\"add\", \".\"])\n .status()\n .context(\"failed to stage files\")?;\n\n Command::new(\"git\")\n .args([\"commit\", \"-m\", \"Initial commit\"])\n .status()\n .context(\"failed to create initial commit\")?;\n }\n }\n\n // Create the repository\n println!(\"Creating repository on GitHub...\");\n\n let mut args = vec![\n \"repo\".to_string(),\n \"create\".to_string(),\n repo_name.clone(),\n format!(\"--{}\", visibility),\n \"--source=.\".to_string(),\n \"--push\".to_string(),\n ];\n\n if let Some(desc) = opts.description {\n args.push(\"--description\".to_string());\n args.push(desc);\n }\n\n let create_result = Command::new(\"gh\")\n .args(&args)\n .status()\n .context(\"failed to create repository\")?;\n\n if !create_result.success() {\n bail!(\"Failed to create repository\");\n }\n\n println!();\n println!(\"✓ Published to https://github.com/{}\", full_name);\n\n Ok(())\n}\n\nconst MAX_GITEDIT_FILE_BYTES: u64 = 512 * 1024;\nconst MAX_GITEDIT_TOTAL_BYTES: u64 = 8 * 1024 * 1024;\nconst MAX_GITEDIT_FILES: usize = 4000;\n\n#[derive(Serialize)]\n#[serde(rename_all = \"snake_case\")]\nstruct RepoSnapshot {\n repo: RepoMeta,\n tree: Vec<RepoTreeEntry>,\n files: Vec<RepoFileEntry>,\n readme: Option<RepoReadme>,\n}\n\n#[derive(Serialize)]\n#[serde(rename_all = \"snake_case\")]\nstruct RepoMeta {\n description: Option<String>,\n default_branch: String,\n language: Option<String>,\n}\n\n#[derive(Serialize)]\n#[serde(rename_all = \"snake_case\")]\nstruct RepoTreeEntry {\n path: String,\n #[serde(rename = \"type\")]\n entry_type: String,\n sha: String,\n size: Option<u64>,\n}\n\n#[derive(Serialize)]\n#[serde(rename_all = \"snake_case\")]\nstruct RepoFileEntry {\n path: String,\n content: String,\n size: u64,\n is_binary: bool,\n encoding: String,\n}\n\n#[derive(Serialize)]\n#[serde(rename_all = \"snake_case\")]\nstruct RepoReadme {\n path: String,\n content: String,\n}\n\n#[derive(Serialize)]\n#[serde(rename_all = \"snake_case\")]\nstruct GiteditSyncPayload {\n owner: String,\n repo: String,\n commit_sha: String,\n branch: Option<String>,\n #[serde(rename = \"ref\")]\n ref_name: Option<String>,\n event: String,\n source: String,\n commit_message: Option<String>,\n author_name: Option<String>,\n author_email: Option<String>,\n session_hash: Option<String>,\n repo_snapshot: Option<RepoSnapshot>,\n}\n\nfn run_gitedit(opts: PublishOpts) -> Result<()> {\n let repo_root = git_root()?;\n ensure_git_repo(&repo_root)?;\n\n let folder_name = repo_root\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(\"repo\")\n .to_string();\n\n let repo_name = resolve_repo_name(&opts, &folder_name)?;\n let (owner, repo_override) = gitedit_repo_override(&repo_root);\n let repo_name = repo_override.unwrap_or(repo_name);\n let owner = resolve_gitedit_owner(&opts, owner, &repo_root)?;\n let full_name = format!(\"{}/{}\", owner, repo_name);\n\n if !opts.yes {\n println!();\n println!(\"Publish to gitedit.dev:\");\n println!(\" Repo: {}\", full_name);\n if let Some(ref desc) = opts.description {\n println!(\" Description: {}\", desc);\n }\n println!();\n\n print!(\"Proceed? [Y/n]: \");\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let input = input.trim().to_ascii_lowercase();\n if input == \"n\" || input == \"no\" {\n println!(\"Aborted.\");\n return Ok(());\n }\n }\n\n let commit_sha = git_capture_in(&repo_root, &[\"rev-parse\", \"HEAD\"])\n .context(\"failed to read git HEAD\")?\n .trim()\n .to_string();\n let branch = git_capture_in(&repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .ok()\n .map(|value| value.trim().to_string())\n .filter(|value| value != \"HEAD\");\n let ref_name = branch.as_ref().map(|name| format!(\"refs/heads/{}\", name));\n let default_branch = branch.clone().unwrap_or_else(|| \"main\".to_string());\n\n let commit_message = git_capture_in(&repo_root, &[\"log\", \"-1\", \"--format=%B\"])\n .ok()\n .map(|value| value.trim().to_string())\n .filter(|value| !value.is_empty());\n let author_name = git_capture_in(&repo_root, &[\"log\", \"-1\", \"--format=%an\"])\n .ok()\n .map(|value| value.trim().to_string())\n .filter(|value| !value.is_empty());\n let author_email = git_capture_in(&repo_root, &[\"log\", \"-1\", \"--format=%ae\"])\n .ok()\n .map(|value| value.trim().to_string())\n .filter(|value| !value.is_empty());\n\n let snapshot = build_repo_snapshot(&repo_root, &default_branch, opts.description.clone())?;\n let payload = GiteditSyncPayload {\n owner: owner.clone(),\n repo: repo_name.clone(),\n commit_sha,\n branch,\n ref_name,\n event: \"commit\".to_string(),\n source: \"flow-cli\".to_string(),\n commit_message,\n author_name,\n author_email,\n session_hash: None,\n repo_snapshot: Some(snapshot),\n };\n\n let base_url = gitedit_api_url(&repo_root);\n let api_url = format!(\"{}/api/mirrors/sync\", base_url.trim_end_matches('/'));\n let view_url = format!(\"{}/{}/{}\", base_url.trim_end_matches('/'), owner, repo_name);\n let token = gitedit_token(&repo_root);\n\n let client = Client::builder()\n .timeout(Duration::from_secs(30))\n .build()\n .context(\"failed to build HTTP client\")?;\n let mut request = client.post(&api_url).json(&payload);\n if let Some(token) = token {\n request = request.bearer_auth(token);\n }\n let response = request.send().context(\"failed to publish to gitedit\")?;\n if !response.status().is_success() {\n bail!(\"gitedit publish failed: HTTP {}\", response.status());\n }\n\n println!();\n println!(\"✓ Published to {}\", view_url);\n Ok(())\n}\n\nfn resolve_repo_name(opts: &PublishOpts, fallback: &str) -> Result<String> {\n let name = if let Some(name) = opts.name.clone() {\n name\n } else if opts.yes {\n fallback.to_string()\n } else {\n print!(\"Repository name [{}]: \", fallback);\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let input = input.trim();\n if input.is_empty() {\n fallback.to_string()\n } else {\n input.to_string()\n }\n };\n Ok(name)\n}\n\nfn resolve_gitedit_owner(\n opts: &PublishOpts,\n override_owner: Option<String>,\n _repo_root: &Path,\n) -> Result<String> {\n if let Some(owner) = opts.owner.clone() {\n return Ok(owner);\n }\n if let Some(owner) = override_owner {\n return Ok(owner);\n }\n if let Ok(owner) = std::env::var(\"GITEDIT_OWNER\") {\n let owner = owner.trim();\n if !owner.is_empty() {\n return Ok(owner.to_string());\n }\n }\n if let Ok(owner) = std::env::var(\"USER\") {\n let slug = sanitize_slug(&owner);\n if !slug.is_empty() {\n if opts.yes {\n return Ok(slug);\n }\n print!(\"gitedit owner [{}]: \", slug);\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let input = input.trim();\n if input.is_empty() {\n return Ok(slug);\n }\n return Ok(input.to_string());\n }\n }\n if opts.yes {\n bail!(\"gitedit owner not set (use --owner or GITEDIT_OWNER)\");\n }\n print!(\"gitedit owner: \");\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let input = input.trim();\n if input.is_empty() {\n bail!(\"gitedit owner is required\");\n }\n Ok(input.to_string())\n}\n\nfn gitedit_repo_override(repo_root: &Path) -> (Option<String>, Option<String>) {\n let flow_path = find_flow_toml(repo_root);\n let Some(flow_path) = flow_path else {\n return (None, None);\n };\n let cfg = match config::load(&flow_path) {\n Ok(cfg) => cfg,\n Err(_) => return (None, None),\n };\n let raw = match cfg.options.gitedit_repo_full_name {\n Some(value) => value,\n None => return (None, None),\n };\n let mut parts = raw.split('/');\n let owner = parts.next().map(|value| value.to_string());\n let repo = parts.next().map(|value| value.to_string());\n (owner, repo)\n}\n\nfn gitedit_api_url(repo_root: &Path) -> String {\n let flow_path = find_flow_toml(repo_root);\n if let Some(flow_path) = flow_path {\n if let Ok(cfg) = config::load(&flow_path) {\n if let Some(url) = cfg.options.gitedit_url {\n let trimmed = url.trim().to_string();\n if !trimmed.is_empty() {\n return trimmed;\n }\n }\n }\n }\n \"https://gitedit.dev\".to_string()\n}\n\nfn gitedit_token(repo_root: &Path) -> Option<String> {\n for key in [\n \"GITEDIT_PUBLISH_TOKEN\",\n \"GITEDIT_TOKEN\",\n \"FLOW_GITEDIT_TOKEN\",\n ] {\n if let Ok(value) = std::env::var(key) {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n }\n }\n }\n let flow_path = find_flow_toml(repo_root)?;\n let cfg = config::load(&flow_path).ok()?;\n cfg.options.gitedit_token\n}\n\nfn find_flow_toml(start: &Path) -> Option<PathBuf> {\n let mut current = start.to_path_buf();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\nfn git_root() -> Result<PathBuf> {\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"--show-toplevel\"])\n .output()\n .context(\"failed to locate git root\")?;\n if !output.status.success() {\n bail!(\"not inside a git repository\");\n }\n let path = String::from_utf8_lossy(&output.stdout).trim().to_string();\n Ok(PathBuf::from(path))\n}\n\nfn ensure_git_repo(repo_root: &Path) -> Result<()> {\n let _ = vcs::ensure_jj_repo_in(repo_root)?;\n let git_dir = repo_root.join(\".git\");\n if !git_dir.exists() {\n Command::new(\"git\")\n .args([\"init\"])\n .current_dir(repo_root)\n .status()\n .context(\"failed to initialize git\")?;\n }\n\n let has_commits = Command::new(\"git\")\n .args([\"rev-parse\", \"HEAD\"])\n .current_dir(repo_root)\n .output()\n .map(|o| o.status.success())\n .unwrap_or(false);\n\n if !has_commits {\n Command::new(\"git\")\n .args([\"add\", \".\"])\n .current_dir(repo_root)\n .status()\n .context(\"failed to stage files\")?;\n Command::new(\"git\")\n .args([\"commit\", \"-m\", \"Initial commit\"])\n .current_dir(repo_root)\n .status()\n .context(\"failed to create initial commit\")?;\n }\n\n Ok(())\n}\n\nfn git_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"git\")\n .args(args)\n .current_dir(repo_root)\n .output()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n if !output.status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nfn build_repo_snapshot(\n repo_root: &Path,\n default_branch: &str,\n description: Option<String>,\n) -> Result<RepoSnapshot> {\n let tree_output = git_capture_in(repo_root, &[\"ls-tree\", \"-r\", \"-t\", \"-l\", \"HEAD\"])?;\n let mut tree = Vec::new();\n let mut files = Vec::new();\n let mut seen_paths = HashSet::new();\n let mut total_bytes: u64 = 0;\n let mut skipped_files: usize = 0;\n\n let mut readme_path: Option<String> = None;\n\n for line in tree_output.lines() {\n let Some((left, path)) = line.split_once('\\t') else {\n continue;\n };\n let mut parts = left.split_whitespace();\n let _mode = parts.next();\n let entry_type = match parts.next() {\n Some(value) => value,\n None => continue,\n };\n let sha = match parts.next() {\n Some(value) => value.to_string(),\n None => continue,\n };\n let size = parts.next().and_then(|value| value.parse::<u64>().ok());\n let path = path.trim().to_string();\n if path.is_empty() {\n continue;\n }\n\n if !seen_paths.insert(path.clone()) {\n continue;\n }\n\n tree.push(RepoTreeEntry {\n path: path.clone(),\n entry_type: entry_type.to_string(),\n sha: sha.clone(),\n size,\n });\n\n if entry_type == \"blob\" {\n if files.len() >= MAX_GITEDIT_FILES {\n skipped_files += 1;\n continue;\n }\n\n let size_value = size.unwrap_or(0);\n let (content, is_binary, encoding, included_bytes) =\n read_blob_content(repo_root, &sha, size_value)?;\n if !content.is_empty() {\n total_bytes = total_bytes.saturating_add(included_bytes);\n }\n if total_bytes > MAX_GITEDIT_TOTAL_BYTES {\n files.push(RepoFileEntry {\n path: path.clone(),\n content: String::new(),\n size: size_value,\n is_binary: true,\n encoding: \"binary\".to_string(),\n });\n skipped_files += 1;\n continue;\n }\n\n files.push(RepoFileEntry {\n path: path.clone(),\n content,\n size: size_value,\n is_binary,\n encoding,\n });\n\n if readme_path.is_none() && is_readme_path(&path) {\n readme_path = Some(path);\n }\n }\n }\n\n let readme = readme_path.and_then(|path| {\n files\n .iter()\n .find(|entry| entry.path == path && !entry.is_binary)\n .map(|entry| RepoReadme {\n path: entry.path.clone(),\n content: entry.content.clone(),\n })\n });\n\n if skipped_files > 0 {\n println!(\n \"Warning: skipped {} file(s) (size or limit exceeded) for gitedit snapshot.\",\n skipped_files\n );\n }\n\n Ok(RepoSnapshot {\n repo: RepoMeta {\n description,\n default_branch: default_branch.to_string(),\n language: None,\n },\n tree,\n files,\n readme,\n })\n}\n\nfn read_blob_content(\n repo_root: &Path,\n sha: &str,\n size: u64,\n) -> Result<(String, bool, String, u64)> {\n if size > MAX_GITEDIT_FILE_BYTES {\n return Ok((String::new(), true, \"binary\".to_string(), 0));\n }\n let output = Command::new(\"git\")\n .args([\"cat-file\", \"-p\", sha])\n .current_dir(repo_root)\n .output()\n .context(\"failed to read git blob\")?;\n if !output.status.success() {\n return Ok((String::new(), true, \"binary\".to_string(), 0));\n }\n if output.stdout.iter().any(|byte| *byte == 0) {\n return Ok((String::new(), true, \"binary\".to_string(), 0));\n }\n match String::from_utf8(output.stdout) {\n Ok(text) => Ok((text, false, \"utf-8\".to_string(), size)),\n Err(_) => Ok((String::new(), true, \"binary\".to_string(), 0)),\n }\n}\n\nfn is_readme_path(path: &str) -> bool {\n let lower = path.to_ascii_lowercase();\n lower.ends_with(\"readme.md\")\n || lower.ends_with(\"readme.markdown\")\n || lower.ends_with(\"readme.mdx\")\n}\n\nfn sanitize_slug(value: &str) -> String {\n let mut out = String::new();\n let mut prev_dash = false;\n for ch in value.chars() {\n if ch.is_ascii_alphanumeric() {\n out.push(ch.to_ascii_lowercase());\n prev_dash = false;\n } else if ch == '-' || ch == '_' {\n out.push(ch);\n prev_dash = ch == '-';\n } else if ch.is_whitespace() || ch == '.' || ch == '/' {\n if !prev_dash && !out.is_empty() {\n out.push('-');\n prev_dash = true;\n }\n }\n }\n while out.ends_with('-') {\n out.pop();\n }\n out\n}\n\nfn prompt_public_choice() -> Result<bool> {\n let default_public = false;\n print!(\"Public? [y/N]: \");\n io::stdout().flush()?;\n\n if io::stdin().is_terminal() {\n return read_yes_no_key(default_public);\n }\n\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n if answer.is_empty() {\n return Ok(default_public);\n }\n Ok(matches!(\n answer.as_str(),\n \"y\" | \"yes\" | \"public\" | \"pub\" | \"p\"\n ))\n}\n\nfn prompt_push_choice() -> Result<bool> {\n let default_push = true;\n print!(\"Push current branch to origin? [Y/n]: \");\n io::stdout().flush()?;\n\n if io::stdin().is_terminal() {\n return read_yes_no_key(default_push);\n }\n\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n if answer.is_empty() {\n return Ok(default_push);\n }\n Ok(matches!(answer.as_str(), \"y\" | \"yes\"))\n}\n\nfn read_yes_no_key(default_yes: bool) -> Result<bool> {\n enable_raw_mode().context(\"failed to enable raw mode\")?;\n let mut selection = default_yes;\n let mut echo_char: Option<char> = None;\n loop {\n if let CEvent::Key(key) = event::read()? {\n match key.code {\n KeyCode::Char('y') | KeyCode::Char('Y') => {\n selection = true;\n echo_char = Some('y');\n break;\n }\n KeyCode::Char('n') | KeyCode::Char('N') => {\n selection = false;\n echo_char = Some('n');\n break;\n }\n KeyCode::Enter => {\n break;\n }\n KeyCode::Esc => {\n selection = false;\n break;\n }\n _ => {}\n }\n }\n }\n\n disable_raw_mode().context(\"failed to disable raw mode\")?;\n if let Some(ch) = echo_char {\n println!(\"{ch}\");\n } else {\n println!();\n }\n Ok(selection)\n}\n\nfn push_to_origin() -> Result<()> {\n // Get current branch\n let branch = Command::new(\"git\")\n .args([\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .output()\n .context(\"failed to get current branch\")?;\n\n let branch = String::from_utf8_lossy(&branch.stdout).trim().to_string();\n let branch = if branch.is_empty() || branch == \"HEAD\" {\n \"main\".to_string()\n } else {\n branch\n };\n\n let status = Command::new(\"git\")\n .args([\"push\", \"-u\", \"origin\", &branch])\n .status()\n .context(\"failed to push to origin\")?;\n\n if !status.success() {\n bail!(\"git push failed\");\n }\n\n Ok(())\n}\n" }, { "path": "src/push.rs", "content": "use std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::PushCommand;\nuse crate::{env, ssh, ssh_keys};\n\npub fn run(cmd: PushCommand) -> Result<()> {\n let repo_root = git_root()?;\n let current_branch = current_branch(&repo_root)?;\n\n let upstream_url = git_capture_in(&repo_root, &[\"remote\", \"get-url\", \"upstream\"])\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty());\n let origin_url = git_capture_in(&repo_root, &[\"remote\", \"get-url\", \"origin\"])\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty());\n\n let owner = resolve_push_owner(cmd.owner.as_deref())?;\n let repo_name = if let Some(repo) = cmd.repo.as_deref() {\n repo.trim().to_string()\n } else {\n derive_repo_name(&repo_root, upstream_url.as_deref(), origin_url.as_deref())?\n };\n if repo_name.is_empty() {\n bail!(\"could not determine repo name (use --repo)\");\n }\n\n let target_url = choose_github_remote_url(&owner, &repo_name, &cmd)?;\n\n if cmd.dry_run {\n println!(\"Repo: {}\", repo_root.display());\n println!(\"Branch: {}\", current_branch);\n println!(\"Remote: {}\", cmd.remote);\n println!(\"Target: {}\", target_url);\n return Ok(());\n }\n\n ensure_remote_points_to_target(\n &repo_root,\n &cmd.remote,\n &target_url,\n upstream_url.as_deref(),\n cmd.force,\n )?;\n\n if cmd.create_repo {\n ensure_github_repo_exists(&owner, &repo_name)?;\n }\n\n println!(\"==> Pushing {} to {}...\", current_branch, cmd.remote);\n git_run_in(&repo_root, &[\"push\", \"-u\", &cmd.remote, ¤t_branch])?;\n println!(\"✓ Pushed to {}/{}\", owner, repo_name);\n Ok(())\n}\n\nfn resolve_push_owner(cli: Option<&str>) -> Result<String> {\n if let Some(value) = cli {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(trimmed.to_string());\n }\n }\n\n resolve_fork_owner(None)\n}\n\n/// Resolve the GitHub owner for fork push operations.\n///\n/// Priority: explicit config → FLOW_PUSH_OWNER env → personal env → `gh api user` → `git config github.user`.\npub(crate) fn resolve_fork_owner(config_owner: Option<&str>) -> Result<String> {\n if let Some(value) = config_owner {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(trimmed.to_string());\n }\n }\n\n if let Ok(value) = std::env::var(\"FLOW_PUSH_OWNER\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(trimmed.to_string());\n }\n }\n\n if let Ok(Some(value)) = env::get_personal_env_var(\"FLOW_PUSH_OWNER\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(trimmed.to_string());\n }\n }\n\n // Try `gh api user`\n if let Ok(output) = Command::new(\"gh\")\n .args([\"api\", \"user\", \"-q\", \".login\"])\n .stdin(Stdio::null())\n .stderr(Stdio::null())\n .output()\n {\n if output.status.success() {\n let login = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if !login.is_empty() {\n return Ok(login);\n }\n }\n }\n\n // Try `git config github.user`\n if let Ok(output) = Command::new(\"git\")\n .args([\"config\", \"github.user\"])\n .stdin(Stdio::null())\n .stderr(Stdio::null())\n .output()\n {\n if output.status.success() {\n let user = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if !user.is_empty() {\n return Ok(user);\n }\n }\n }\n\n bail!(\n \"Could not determine GitHub owner. Configure it via:\\n \\\n [git] fork-push-owner in flow.toml, or\\n \\\n f env set FLOW_PUSH_OWNER=<owner> --personal, or\\n \\\n gh auth login, or\\n \\\n git config --global github.user <owner>\"\n );\n}\n\npub(crate) fn derive_repo_name(\n repo_root: &Path,\n upstream_url: Option<&str>,\n origin_url: Option<&str>,\n) -> Result<String> {\n if let Some(url) = upstream_url {\n if let Some((_owner, repo)) = parse_github_owner_repo(url) {\n return Ok(repo);\n }\n }\n if let Some(url) = origin_url {\n if let Some((_owner, repo)) = parse_github_owner_repo(url) {\n return Ok(repo);\n }\n }\n Ok(repo_root\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(\"repo\")\n .to_string())\n}\n\npub(crate) fn build_github_ssh_url(owner: &str, repo: &str) -> String {\n let owner = owner.trim();\n let repo = repo.trim();\n format!(\"git@github.com:{}/{}.git\", owner, repo)\n}\n\nfn build_github_https_url(owner: &str, repo: &str) -> String {\n let owner = owner.trim();\n let repo = repo.trim();\n format!(\"https://github.com/{}/{}.git\", owner, repo)\n}\n\nfn choose_github_remote_url(owner: &str, repo: &str, cmd: &PushCommand) -> Result<String> {\n let ssh_url = build_github_ssh_url(owner, repo);\n let https_url = build_github_https_url(owner, repo);\n\n match ssh::ssh_mode() {\n ssh::SshMode::Https => Ok(https_url),\n ssh::SshMode::Force => {\n if !cmd.no_ssh {\n if let Err(err) = ssh_keys::ensure_default_identity(cmd.ttl_hours) {\n eprintln!(\n \"Warning: could not unlock Flow SSH key (continuing): {}\",\n err\n );\n }\n }\n Ok(ssh_url)\n }\n ssh::SshMode::Auto => {\n if !cmd.no_ssh {\n if let Err(err) = ssh_keys::ensure_default_identity(cmd.ttl_hours) {\n eprintln!(\n \"Warning: could not unlock Flow SSH key (continuing): {}\",\n err\n );\n }\n }\n if ssh::has_identities() {\n Ok(ssh_url)\n } else {\n Ok(https_url)\n }\n }\n }\n}\n\npub(crate) fn parse_github_owner_repo(url: &str) -> Option<(String, String)> {\n let trimmed = url.trim().trim_end_matches('/');\n if trimmed.is_empty() {\n return None;\n }\n\n if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n let rest = rest.trim_end_matches(\".git\");\n let (owner, repo) = rest.split_once('/')?;\n return Some((owner.to_string(), repo.to_string()));\n }\n\n if let Some(rest) = trimmed.strip_prefix(\"https://github.com/\") {\n let rest = rest.trim_end_matches(\".git\");\n let (owner, repo) = rest.split_once('/')?;\n return Some((owner.to_string(), repo.to_string()));\n }\n\n None\n}\n\npub(crate) fn ensure_remote_points_to_target(\n repo_root: &Path,\n remote: &str,\n target_url: &str,\n upstream_url: Option<&str>,\n force: bool,\n) -> Result<()> {\n let existing = git_capture_in(repo_root, &[\"remote\", \"get-url\", remote])\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty());\n\n if let Some(existing) = existing {\n if normalize_git_url(&existing) == normalize_git_url(target_url) {\n return Ok(());\n }\n\n // Safe override when the remote points at upstream (read-only clone).\n let is_upstream = upstream_url\n .map(|u| normalize_git_url(u) == normalize_git_url(&existing))\n .unwrap_or(false);\n if is_upstream || force {\n println!(\"==> Updating remote {} url...\", remote);\n git_run_in(repo_root, &[\"remote\", \"set-url\", remote, target_url])?;\n return Ok(());\n }\n\n bail!(\n \"remote '{}' already points to {}\\nrefusing to overwrite without --force\\n(target would be {})\",\n remote,\n existing,\n target_url\n );\n }\n\n println!(\"==> Adding remote {}...\", remote);\n git_run_in(repo_root, &[\"remote\", \"add\", remote, target_url])?;\n Ok(())\n}\n\npub(crate) fn ensure_github_repo_exists(owner: &str, repo: &str) -> Result<()> {\n let full_name = format!(\"{}/{}\", owner.trim(), repo.trim());\n\n let view = Command::new(\"gh\")\n .args([\"repo\", \"view\", &full_name])\n .stdin(Stdio::null())\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status();\n\n if matches!(view, Ok(s) if s.success()) {\n return Ok(());\n }\n\n println!(\"==> Creating GitHub repo {} (private)...\", full_name);\n let status = Command::new(\"gh\")\n .args([\"repo\", \"create\", &full_name, \"--private\", \"--confirm\"])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status();\n\n match status {\n Ok(s) if s.success() => Ok(()),\n Ok(_) => bail!(\"failed to create repo via gh (is it installed/authenticated?)\"),\n Err(err) => Err(err).context(\"failed to run gh\"),\n }\n}\n\npub(crate) fn normalize_git_url(url: &str) -> String {\n let url = url.trim();\n let url = if url.starts_with(\"git@github.com:\") {\n url.replace(\"git@github.com:\", \"github.com/\")\n } else if url.starts_with(\"https://github.com/\") {\n url.replace(\"https://github.com/\", \"github.com/\")\n } else {\n url.to_string()\n };\n url.trim_end_matches(\".git\").to_lowercase()\n}\n\nfn git_root() -> Result<PathBuf> {\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"--show-toplevel\"])\n .output()\n .context(\"failed to locate git root\")?;\n if !output.status.success() {\n bail!(\"not inside a git repository\");\n }\n let path = String::from_utf8_lossy(&output.stdout).trim().to_string();\n Ok(PathBuf::from(path))\n}\n\nfn current_branch(repo_root: &Path) -> Result<String> {\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .current_dir(repo_root)\n .output()\n .context(\"failed to read current branch\")?;\n if !output.status.success() {\n bail!(\"git rev-parse --abbrev-ref HEAD failed\");\n }\n let name = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if name.is_empty() || name == \"HEAD\" {\n bail!(\"detached HEAD (checkout a branch first)\");\n }\n Ok(name)\n}\n\npub(crate) fn git_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"git\")\n .args(args)\n .current_dir(repo_root)\n .output()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n if !output.status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\npub(crate) fn git_run_in(repo_root: &Path, args: &[&str]) -> Result<()> {\n let status = Command::new(\"git\")\n .args(args)\n .current_dir(repo_root)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .with_context(|| format!(\"failed to run git {}\", args.join(\" \")))?;\n if !status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n Ok(())\n}\n" }, { "path": "src/recipe.rs", "content": "use std::collections::BTreeSet;\nuse std::env;\nuse std::fs;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\nuse shellexpand::tilde;\n\nuse crate::cli::{\n RecipeAction, RecipeCommand, RecipeInitOpts, RecipeListOpts, RecipeRunOpts, RecipeScopeArg,\n RecipeSearchOpts,\n};\nuse crate::config;\n\nconst ENV_GLOBAL_RECIPE_DIR: &str = \"FLOW_RECIPES_GLOBAL_DIR\";\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]\nenum Scope {\n Project,\n Global,\n}\n\nimpl Scope {\n fn as_str(self) -> &'static str {\n match self {\n Scope::Project => \"project\",\n Scope::Global => \"global\",\n }\n }\n}\n\n#[derive(Debug, Clone)]\nstruct Recipe {\n id: String,\n name: String,\n description: String,\n path: PathBuf,\n scope: Scope,\n runner: RecipeRunner,\n tags: Vec<String>,\n}\n\n#[derive(Debug, Clone)]\nenum RecipeRunner {\n Shell { shell: String, command: String },\n MoonbitFile,\n}\n\n#[derive(Debug, Clone, Default)]\nstruct Frontmatter {\n title: Option<String>,\n description: Option<String>,\n tags: Vec<String>,\n}\n\npub fn run(cmd: RecipeCommand) -> Result<()> {\n eprintln!(\n \"warning: `f recipe` is legacy compatibility. Prefer task-centric workflows with flow.toml tasks + .ai/tasks/*.mbt.\"\n );\n match cmd.action.unwrap_or(RecipeAction::List(RecipeListOpts {\n scope: RecipeScopeArg::All,\n query: None,\n global_dir: None,\n })) {\n RecipeAction::List(opts) => list_recipes(opts),\n RecipeAction::Search(opts) => search_recipes(opts),\n RecipeAction::Run(opts) => run_recipe(opts),\n RecipeAction::Init(opts) => init_recipes(opts),\n }\n}\n\nfn list_recipes(opts: RecipeListOpts) -> Result<()> {\n let recipes = load_recipes(opts.scope, opts.global_dir.as_deref())?;\n let filtered = filter_recipes(recipes, opts.query.as_deref());\n if filtered.is_empty() {\n println!(\"No recipes found.\");\n return Ok(());\n }\n\n for recipe in filtered {\n let tags = if recipe.tags.is_empty() {\n String::new()\n } else {\n format!(\" [{}]\", recipe.tags.join(\",\"))\n };\n println!(\n \"{:<7} {:<36} {}{}\",\n recipe.scope.as_str(),\n recipe.id,\n recipe.name,\n tags\n );\n if !recipe.description.is_empty() {\n println!(\" {}\", recipe.description);\n }\n }\n Ok(())\n}\n\nfn search_recipes(opts: RecipeSearchOpts) -> Result<()> {\n let recipes = load_recipes(opts.scope, opts.global_dir.as_deref())?;\n let filtered = filter_recipes(recipes, Some(opts.query.as_str()));\n if filtered.is_empty() {\n println!(\"No recipes matched '{}'.\", opts.query);\n return Ok(());\n }\n for recipe in filtered {\n println!(\n \"{:<7} {:<36} {}\",\n recipe.scope.as_str(),\n recipe.id,\n recipe.name\n );\n }\n Ok(())\n}\n\nfn run_recipe(opts: RecipeRunOpts) -> Result<()> {\n let recipes = load_recipes(opts.scope, opts.global_dir.as_deref())?;\n let recipe = match select_recipe(&recipes, &opts.selector) {\n Ok(recipe) => recipe,\n Err(err) => {\n eprintln!(\"{err}\");\n bail!(\"failed to select recipe\")\n }\n };\n\n let cwd = resolve_cwd(opts.cwd.as_deref())?;\n\n println!(\n \"Running recipe {} ({}) from {}\",\n recipe.id,\n recipe.scope.as_str(),\n recipe.path.display()\n );\n println!(\"cwd: {}\", cwd.display());\n match &recipe.runner {\n RecipeRunner::Shell { shell, command } => {\n let shell_bin = resolve_shell_bin(shell);\n let shell_cmd = command.trim();\n println!(\"engine: shell\");\n println!(\"shell: {}\", shell_bin);\n println!(\"cmd: {}\", shell_cmd);\n\n if opts.dry_run {\n return Ok(());\n }\n\n let status = Command::new(&shell_bin)\n .arg(\"-lc\")\n .arg(shell_cmd)\n .current_dir(&cwd)\n .status()\n .with_context(|| format!(\"failed to run recipe command via {}\", shell_bin))?;\n\n if !status.success() {\n bail!(\"recipe '{}' failed with status {}\", recipe.id, status);\n }\n }\n RecipeRunner::MoonbitFile => {\n println!(\"engine: moonbit\");\n println!(\"cmd: moon run {}\", recipe.path.display());\n\n if opts.dry_run {\n return Ok(());\n }\n\n let status = Command::new(\"moon\")\n .arg(\"run\")\n .arg(&recipe.path)\n .current_dir(&cwd)\n .status()\n .with_context(|| format!(\"failed to run moon recipe {}\", recipe.path.display()))?;\n\n if !status.success() {\n bail!(\"recipe '{}' failed with status {}\", recipe.id, status);\n }\n }\n }\n Ok(())\n}\n\nfn init_recipes(opts: RecipeInitOpts) -> Result<()> {\n let project_root = detect_project_root()?;\n let global_dir = resolve_global_dir(&project_root, opts.global_dir.as_deref());\n\n let mut created: Vec<PathBuf> = Vec::new();\n let mut created_files: Vec<PathBuf> = Vec::new();\n\n if matches!(opts.scope, RecipeScopeArg::Project | RecipeScopeArg::All) {\n let project_dir = project_root.join(\".ai/recipes/project\");\n ensure_dir(&project_dir, &mut created)?;\n write_starter_recipe(\n &project_dir.join(\"open-safari-new-tab.md\"),\n STARTER_PROJECT_RECIPE,\n &mut created_files,\n )?;\n write_starter_recipe(\n &project_dir.join(\"bridge-latency-bench.md\"),\n STARTER_PROJECT_BENCH_RECIPE,\n &mut created_files,\n )?;\n write_starter_recipe(\n &project_dir.join(\"moonbit-starter.mbt\"),\n STARTER_PROJECT_MOONBIT_RECIPE,\n &mut created_files,\n )?;\n }\n\n if matches!(opts.scope, RecipeScopeArg::Global | RecipeScopeArg::All) {\n ensure_dir(&global_dir, &mut created)?;\n write_starter_recipe(\n &global_dir.join(\"system-ready-check.md\"),\n STARTER_GLOBAL_RECIPE,\n &mut created_files,\n )?;\n }\n\n if created.is_empty() && created_files.is_empty() {\n println!(\"Recipe directories already initialized.\");\n } else {\n for dir in created {\n println!(\"created dir: {}\", dir.display());\n }\n for file in created_files {\n println!(\"created recipe: {}\", file.display());\n }\n }\n\n Ok(())\n}\n\nfn load_recipes(scope: RecipeScopeArg, global_dir_override: Option<&str>) -> Result<Vec<Recipe>> {\n let project_root = detect_project_root()?;\n let mut roots: Vec<(Scope, PathBuf)> = Vec::new();\n\n if matches!(scope, RecipeScopeArg::Project | RecipeScopeArg::All) {\n let preferred = project_root.join(\".ai/recipes/project\");\n if preferred.exists() {\n roots.push((Scope::Project, preferred));\n } else {\n roots.push((Scope::Project, project_root.join(\".ai/recipes\")));\n }\n }\n if matches!(scope, RecipeScopeArg::Global | RecipeScopeArg::All) {\n roots.push((\n Scope::Global,\n resolve_global_dir(&project_root, global_dir_override),\n ));\n }\n\n let mut seen = BTreeSet::new();\n roots.retain(|(_, root)| seen.insert(root.clone()));\n\n let mut recipes = Vec::new();\n let mut seen_recipe_paths = BTreeSet::new();\n for (scope, root) in roots {\n if !root.exists() {\n continue;\n }\n let files = collect_recipe_files(&root)?;\n for file in files {\n let key = (scope, file.clone());\n if !seen_recipe_paths.insert(key) {\n continue;\n }\n if let Some(recipe) = parse_recipe(scope, &root, &file)? {\n recipes.push(recipe);\n }\n }\n }\n\n recipes.sort_by(|a, b| (a.scope, a.id.as_str()).cmp(&(b.scope, b.id.as_str())));\n Ok(recipes)\n}\n\nfn collect_recipe_files(root: &Path) -> Result<Vec<PathBuf>> {\n let mut out = Vec::new();\n collect_recipe_files_recursive(root, &mut out)?;\n out.sort();\n Ok(out)\n}\n\nfn collect_recipe_files_recursive(dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {\n for entry in fs::read_dir(dir).with_context(|| format!(\"failed to read {}\", dir.display()))? {\n let entry = entry.with_context(|| format!(\"failed to read entry in {}\", dir.display()))?;\n let path = entry.path();\n let ty = entry\n .file_type()\n .with_context(|| format!(\"failed to get type for {}\", path.display()))?;\n if ty.is_dir() {\n collect_recipe_files_recursive(&path, out)?;\n continue;\n }\n if !ty.is_file() {\n continue;\n }\n let ext = path\n .extension()\n .and_then(|e| e.to_str())\n .unwrap_or_default()\n .to_ascii_lowercase();\n if ext == \"md\" || ext == \"markdown\" || ext == \"mbt\" {\n out.push(path);\n }\n }\n Ok(())\n}\n\nfn parse_recipe(scope: Scope, root: &Path, path: &Path) -> Result<Option<Recipe>> {\n let ext = path\n .extension()\n .and_then(|e| e.to_str())\n .unwrap_or_default()\n .to_ascii_lowercase();\n if ext == \"mbt\" {\n return parse_moonbit_recipe(scope, root, path);\n }\n parse_markdown_recipe(scope, root, path)\n}\n\nfn parse_markdown_recipe(scope: Scope, root: &Path, path: &Path) -> Result<Option<Recipe>> {\n let content =\n fs::read_to_string(path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let (frontmatter, body) = parse_frontmatter(&content);\n let (shell, command) = match extract_first_shell_block(body) {\n Some(found) => found,\n None => return Ok(None),\n };\n\n let relative = path.strip_prefix(root).unwrap_or(path);\n let id = format!(\n \"{}:{}\",\n scope.as_str(),\n relative\n .with_extension(\"\")\n .to_string_lossy()\n .replace('\\\\', \"/\")\n );\n\n let title = frontmatter\n .title\n .or_else(|| extract_first_heading(body))\n .unwrap_or_else(|| {\n path.file_stem()\n .and_then(|s| s.to_str())\n .unwrap_or(\"recipe\")\n .replace('-', \" \")\n });\n let description = frontmatter\n .description\n .or_else(|| extract_description(body))\n .unwrap_or_default();\n\n Ok(Some(Recipe {\n id,\n name: title,\n description,\n path: path.to_path_buf(),\n scope,\n runner: RecipeRunner::Shell { shell, command },\n tags: frontmatter.tags,\n }))\n}\n\nfn parse_moonbit_recipe(scope: Scope, root: &Path, path: &Path) -> Result<Option<Recipe>> {\n let content =\n fs::read_to_string(path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let frontmatter = parse_moonbit_metadata(&content);\n\n let relative = path.strip_prefix(root).unwrap_or(path);\n let id = format!(\n \"{}:{}\",\n scope.as_str(),\n relative\n .with_extension(\"\")\n .to_string_lossy()\n .replace('\\\\', \"/\")\n );\n\n let title = frontmatter.title.unwrap_or_else(|| {\n path.file_stem()\n .and_then(|s| s.to_str())\n .unwrap_or(\"recipe\")\n .replace(['-', '_'], \" \")\n });\n let description = frontmatter.description.unwrap_or_default();\n\n Ok(Some(Recipe {\n id,\n name: title,\n description,\n path: path.to_path_buf(),\n scope,\n runner: RecipeRunner::MoonbitFile,\n tags: frontmatter.tags,\n }))\n}\n\nfn parse_moonbit_metadata(content: &str) -> Frontmatter {\n let mut fm = Frontmatter::default();\n for raw in content.lines() {\n let line = raw.trim();\n if line.is_empty() {\n continue;\n }\n let Some(comment) = line.strip_prefix(\"//\") else {\n break;\n };\n let comment = comment.trim();\n let Some((key, value)) = comment.split_once(':') else {\n continue;\n };\n let key = key.trim().to_ascii_lowercase();\n let value = value.trim();\n if key == \"title\" {\n fm.title = Some(strip_quotes(value));\n } else if key == \"description\" {\n fm.description = Some(strip_quotes(value));\n } else if key == \"tags\" {\n fm.tags = parse_tags(value);\n }\n }\n fm\n}\n\nfn parse_frontmatter(content: &str) -> (Frontmatter, &str) {\n let mut fm = Frontmatter::default();\n if !content.starts_with(\"---\\n\") {\n return (fm, content);\n }\n let rest = &content[4..];\n let Some(end_idx) = rest.find(\"\\n---\\n\") else {\n return (fm, content);\n };\n let block = &rest[..end_idx];\n let body = &rest[end_idx + 5..];\n for raw in block.lines() {\n let line = raw.trim();\n if line.is_empty() || line.starts_with('#') {\n continue;\n }\n let Some((key, value)) = line.split_once(':') else {\n continue;\n };\n let key = key.trim().to_ascii_lowercase();\n let value = value.trim();\n if key == \"title\" {\n fm.title = Some(strip_quotes(value));\n } else if key == \"description\" {\n fm.description = Some(strip_quotes(value));\n } else if key == \"tags\" {\n fm.tags = parse_tags(value);\n }\n }\n (fm, body)\n}\n\nfn parse_tags(value: &str) -> Vec<String> {\n let v = strip_quotes(value);\n let trimmed = v.trim();\n let inner = if trimmed.starts_with('[') && trimmed.ends_with(']') && trimmed.len() >= 2 {\n &trimmed[1..trimmed.len() - 1]\n } else {\n trimmed\n };\n inner\n .split(',')\n .map(strip_quotes)\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty())\n .collect()\n}\n\nfn strip_quotes(value: &str) -> String {\n let trimmed = value.trim();\n if trimmed.len() >= 2 {\n let bytes = trimmed.as_bytes();\n if (bytes[0] == b'\"' && bytes[trimmed.len() - 1] == b'\"')\n || (bytes[0] == b'\\'' && bytes[trimmed.len() - 1] == b'\\'')\n {\n return trimmed[1..trimmed.len() - 1].to_string();\n }\n }\n trimmed.to_string()\n}\n\nfn extract_first_heading(body: &str) -> Option<String> {\n for raw in body.lines() {\n let line = raw.trim();\n if let Some(title) = line.strip_prefix(\"# \") {\n let title = title.trim();\n if !title.is_empty() {\n return Some(title.to_string());\n }\n }\n }\n None\n}\n\nfn extract_description(body: &str) -> Option<String> {\n let mut in_fence = false;\n for raw in body.lines() {\n let line = raw.trim();\n if line.starts_with(\"```\") {\n in_fence = !in_fence;\n continue;\n }\n if in_fence || line.is_empty() || line.starts_with('#') {\n continue;\n }\n return Some(line.to_string());\n }\n None\n}\n\nfn extract_first_shell_block(body: &str) -> Option<(String, String)> {\n let mut in_block = false;\n let mut capture = false;\n let mut shell = String::from(\"sh\");\n let mut lines: Vec<String> = Vec::new();\n\n for raw in body.lines() {\n let line = raw.trim_end_matches('\\r');\n let trimmed = line.trim_start();\n if trimmed.starts_with(\"```\") {\n if in_block {\n if capture {\n let command = lines.join(\"\\n\").trim().to_string();\n if !command.is_empty() {\n return Some((shell, command));\n }\n }\n in_block = false;\n capture = false;\n lines.clear();\n continue;\n }\n\n in_block = true;\n let fence_info = trimmed.trim_start_matches(\"```\").trim();\n let lang = fence_info\n .split_whitespace()\n .next()\n .unwrap_or_default()\n .to_ascii_lowercase();\n if is_shell_lang(&lang) {\n capture = true;\n shell = normalize_shell_lang(&lang);\n } else {\n capture = false;\n }\n continue;\n }\n\n if in_block && capture {\n lines.push(line.to_string());\n }\n }\n None\n}\n\nfn is_shell_lang(lang: &str) -> bool {\n matches!(lang, \"\" | \"sh\" | \"bash\" | \"zsh\" | \"shell\" | \"fish\")\n}\n\nfn normalize_shell_lang(lang: &str) -> String {\n let normalized = lang.trim().to_ascii_lowercase();\n if normalized.is_empty() || normalized == \"shell\" {\n \"sh\".to_string()\n } else {\n normalized\n }\n}\n\nfn resolve_shell_bin(shell: &str) -> String {\n let token = shell.split_whitespace().next().unwrap_or(\"\").trim();\n match token.to_ascii_lowercase().as_str() {\n \"\" | \"sh\" | \"shell\" => \"/bin/sh\".to_string(),\n \"bash\" => \"bash\".to_string(),\n \"zsh\" => \"zsh\".to_string(),\n \"fish\" => \"fish\".to_string(),\n other => {\n if other.is_empty() {\n \"/bin/sh\".to_string()\n } else {\n token.to_string()\n }\n }\n }\n}\n\nfn filter_recipes(recipes: Vec<Recipe>, query: Option<&str>) -> Vec<Recipe> {\n let Some(query) = query.map(|q| q.trim()).filter(|q| !q.is_empty()) else {\n return recipes;\n };\n let needle = query.to_ascii_lowercase();\n recipes\n .into_iter()\n .filter(|r| {\n let mut hay = String::new();\n hay.push_str(&r.id);\n hay.push(' ');\n hay.push_str(&r.name);\n hay.push(' ');\n hay.push_str(&r.description);\n if !r.tags.is_empty() {\n hay.push(' ');\n hay.push_str(&r.tags.join(\" \"));\n }\n hay.to_ascii_lowercase().contains(&needle)\n })\n .collect()\n}\n\nfn select_recipe<'a>(recipes: &'a [Recipe], selector: &str) -> Result<&'a Recipe> {\n let normalized = selector.trim();\n if normalized.is_empty() {\n bail!(\"empty recipe selector\")\n }\n\n if let Some(recipe) = recipes.iter().find(|r| r.id == normalized) {\n return Ok(recipe);\n }\n\n let lowered = normalized.to_ascii_lowercase();\n let exact_name: Vec<&Recipe> = recipes\n .iter()\n .filter(|r| r.name.to_ascii_lowercase() == lowered)\n .collect();\n if exact_name.len() == 1 {\n return Ok(exact_name[0]);\n }\n if exact_name.len() > 1 {\n ambiguous_selector_error(selector, &exact_name)?;\n bail!(\"ambiguous recipe selector\")\n }\n\n let contains: Vec<&Recipe> = recipes\n .iter()\n .filter(|r| {\n r.id.to_ascii_lowercase().contains(&lowered)\n || r.name.to_ascii_lowercase().contains(&lowered)\n })\n .collect();\n if contains.len() == 1 {\n return Ok(contains[0]);\n }\n if contains.is_empty() {\n bail!(\"no recipe matched '{}'\", selector);\n }\n ambiguous_selector_error(selector, &contains)?;\n bail!(\"ambiguous recipe selector\")\n}\n\nfn ambiguous_selector_error(selector: &str, matches: &[&Recipe]) -> Result<()> {\n eprintln!(\"recipe selector '{}' matched multiple recipes:\", selector);\n for recipe in matches {\n eprintln!(\" - {} ({})\", recipe.id, recipe.name);\n }\n Ok(())\n}\n\nfn resolve_cwd(cwd: Option<&str>) -> Result<PathBuf> {\n if let Some(cwd) = cwd {\n return Ok(expand_tilde(cwd));\n }\n detect_project_root()\n}\n\nfn detect_project_root() -> Result<PathBuf> {\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"--show-toplevel\"])\n .output();\n if let Ok(out) = output\n && out.status.success()\n {\n let root = String::from_utf8_lossy(&out.stdout).trim().to_string();\n if !root.is_empty() {\n return Ok(PathBuf::from(root));\n }\n }\n env::current_dir().context(\"failed to resolve current directory\")\n}\n\nfn resolve_global_dir(project_root: &Path, override_dir: Option<&str>) -> PathBuf {\n let env_override = env::var(ENV_GLOBAL_RECIPE_DIR).ok();\n resolve_global_dir_with_env(project_root, override_dir, env_override.as_deref())\n}\n\nfn resolve_global_dir_with_env(\n _project_root: &Path,\n override_dir: Option<&str>,\n env_override: Option<&str>,\n) -> PathBuf {\n if let Some(dir) = override_dir {\n return expand_tilde(dir);\n }\n if let Some(dir) = env_override\n && !dir.trim().is_empty()\n {\n return expand_tilde(dir);\n }\n config::global_config_dir().join(\"recipes\")\n}\n\nfn expand_tilde(path: &str) -> PathBuf {\n PathBuf::from(tilde(path).to_string())\n}\n\nfn ensure_dir(dir: &Path, created: &mut Vec<PathBuf>) -> Result<()> {\n if dir.exists() {\n return Ok(());\n }\n fs::create_dir_all(dir).with_context(|| format!(\"failed to create {}\", dir.display()))?;\n created.push(dir.to_path_buf());\n Ok(())\n}\n\nfn write_starter_recipe(path: &Path, content: &str, created: &mut Vec<PathBuf>) -> Result<()> {\n if path.exists() {\n return Ok(());\n }\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n fs::write(path, content).with_context(|| format!(\"failed to write {}\", path.display()))?;\n created.push(path.to_path_buf());\n Ok(())\n}\n\nconst STARTER_PROJECT_RECIPE: &str = r#\"---\ntitle: Open Safari New Tab\ndescription: Fast local smoke command for seq integration.\ntags: [seq, app]\n---\n\nOpen Safari via seq and create a new tab.\n\n```sh\n~/code/seq/cli/cpp/out/bin/seq run \"open Safari new tab\"\n```\n\"#;\n\nconst STARTER_PROJECT_BENCH_RECIPE: &str = r#\"---\ntitle: Kar User Command Bench\ndescription: Run transport-focused bridge latency benchmark.\ntags: [benchmark, latency, karabiner]\n---\n\n```sh\npython3 tools/bridge_latency_bench.py --build-if-missing --iterations 300 --warmup 40\n```\n\"#;\n\nconst STARTER_PROJECT_MOONBIT_RECIPE: &str = r#\"// title: MoonBit Recipe Starter\n// description: Minimal runnable MoonBit recipe entry.\n// tags: [moonbit, recipe]\n\nfn main {\n println(\"hello from moonbit recipe\")\n}\n\"#;\n\nconst STARTER_GLOBAL_RECIPE: &str = r#\"---\ntitle: System Ready Check\ndescription: Verify machine is in clean state before latency benchmarks.\ntags: [system, benchmark]\n---\n\n```sh\nf kar-uc-system-check-report || true\n```\n\"#;\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn frontmatter_parses_basic_fields() {\n let text = \"---\\n\\\ntitle: Hello\\n\\\ndescription: World\\n\\\ntags: [a, b]\\n\\\n---\\n\\\n# Heading\\n\";\n let (fm, body) = parse_frontmatter(text);\n assert_eq!(fm.title.as_deref(), Some(\"Hello\"));\n assert_eq!(fm.description.as_deref(), Some(\"World\"));\n assert_eq!(fm.tags, vec![\"a\".to_string(), \"b\".to_string()]);\n assert!(body.starts_with(\"# Heading\"));\n }\n\n #[test]\n fn extracts_shell_block() {\n let body = \"# T\\n\\n```bash\\necho hi\\n```\\n\";\n let (shell, command) = extract_first_shell_block(body).expect(\"shell block\");\n assert_eq!(shell, \"bash\");\n assert_eq!(command, \"echo hi\");\n }\n\n #[test]\n fn extracts_shell_block_with_fence_metadata() {\n let body = \"# T\\n\\n```zsh title=\\\"run\\\"\\necho hi\\n```\\n\";\n let (shell, command) = extract_first_shell_block(body).expect(\"shell block\");\n assert_eq!(shell, \"zsh\");\n assert_eq!(command, \"echo hi\");\n }\n\n #[test]\n fn normalize_shell_lang_handles_shell_alias() {\n assert_eq!(normalize_shell_lang(\"shell\"), \"sh\");\n assert_eq!(normalize_shell_lang(\"\"), \"sh\");\n }\n\n #[test]\n fn resolve_shell_bin_honors_declared_shell() {\n assert_eq!(resolve_shell_bin(\"bash\"), \"bash\");\n assert_eq!(resolve_shell_bin(\"zsh\"), \"zsh\");\n assert_eq!(resolve_shell_bin(\"fish\"), \"fish\");\n assert_eq!(resolve_shell_bin(\"sh\"), \"/bin/sh\");\n assert_eq!(resolve_shell_bin(\"shell\"), \"/bin/sh\");\n }\n\n #[test]\n fn resolve_global_dir_prefers_override_then_env_then_config() {\n let root = PathBuf::from(\"/tmp/project\");\n let override_dir = resolve_global_dir_with_env(&root, Some(\"~/recipes-x\"), None);\n assert!(\n override_dir.to_string_lossy().contains(\"recipes-x\"),\n \"override dir should be used\"\n );\n\n let env_dir = resolve_global_dir_with_env(&root, None, Some(\"~/recipes-y\"));\n assert!(\n env_dir.to_string_lossy().contains(\"recipes-y\"),\n \"env dir should be used\"\n );\n\n let cfg_dir = resolve_global_dir_with_env(&root, None, None);\n assert_eq!(cfg_dir, config::global_config_dir().join(\"recipes\"));\n }\n\n #[test]\n fn filter_matches_name_and_tags() {\n let recipes = vec![Recipe {\n id: \"project:a\".to_string(),\n name: \"Open Safari\".to_string(),\n description: \"fast\".to_string(),\n path: PathBuf::from(\"a.md\"),\n scope: Scope::Project,\n runner: RecipeRunner::Shell {\n shell: \"sh\".to_string(),\n command: \"echo\".to_string(),\n },\n tags: vec![\"browser\".to_string()],\n }];\n let out = filter_recipes(recipes, Some(\"browser\"));\n assert_eq!(out.len(), 1);\n }\n\n #[test]\n fn parses_moonbit_metadata_header() {\n let text = \"// title: Fast App Open\\n\\\n// description: open app with moonbit\\n\\\n// tags: [moonbit, fast]\\n\\\n\\n\\\nfn main {\\n\\\n println(\\\"ok\\\")\\n\\\n}\\n\";\n let fm = parse_moonbit_metadata(text);\n assert_eq!(fm.title.as_deref(), Some(\"Fast App Open\"));\n assert_eq!(fm.description.as_deref(), Some(\"open app with moonbit\"));\n assert_eq!(fm.tags, vec![\"moonbit\".to_string(), \"fast\".to_string()]);\n }\n}\n" }, { "path": "src/registry.rs", "content": "use std::collections::BTreeMap;\nuse std::env;\nuse std::fs;\nuse std::io::Write;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result, bail};\nuse chrono::{Datelike, Local, Utc};\nuse reqwest::blocking::Client;\nuse serde::{Deserialize, Serialize};\nuse sha2::{Digest, Sha256};\nuse tempfile::NamedTempFile;\n\nuse crate::cli::{\n InstallOpts, RegistryAction, RegistryCommand, RegistryInitOpts, RegistryReleaseOpts,\n};\nuse crate::config::{self, Config, RegistryReleaseConfig};\nuse crate::env as flow_env;\n\nconst DEFAULT_TOKEN_ENV: &str = \"FLOW_REGISTRY_TOKEN\";\nconst WORKER_TOKEN_SECRET: &str = \"REGISTRY_TOKEN\";\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct RegistryManifest {\n pub name: String,\n pub version: String,\n pub published_at: String,\n #[serde(default)]\n pub bins: Vec<String>,\n #[serde(default)]\n pub default_bin: Option<String>,\n pub targets: BTreeMap<String, RegistryTarget>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct RegistryTarget {\n pub binaries: BTreeMap<String, String>,\n #[serde(default)]\n pub sha256: BTreeMap<String, String>,\n}\n\npub fn run(cmd: RegistryCommand) -> Result<()> {\n match cmd.action {\n Some(RegistryAction::Init(opts)) => init(opts),\n None => {\n println!(\"Registry commands:\");\n println!(\" init Create a registry token and configure worker secrets\");\n Ok(())\n }\n }\n}\n\npub fn init(opts: RegistryInitOpts) -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to read current directory\")?;\n let flow_path = find_flow_toml(&cwd);\n let (project_root, flow_cfg) = if let Some(flow_path) = flow_path.as_ref() {\n let cfg = config::load(flow_path)?;\n let root = flow_path\n .parent()\n .map(Path::to_path_buf)\n .unwrap_or_else(|| cwd.clone());\n (root, Some(cfg))\n } else {\n (cwd.clone(), None)\n };\n\n let registry_cfg = flow_cfg\n .as_ref()\n .and_then(|cfg| cfg.release.as_ref())\n .and_then(|release| release.registry.as_ref());\n\n let token_env = opts\n .token_env\n .clone()\n .or_else(|| registry_cfg.and_then(|cfg| cfg.token_env.clone()))\n .unwrap_or_else(|| DEFAULT_TOKEN_ENV.to_string());\n\n let registry_url = resolve_registry_url(opts.registry.as_deref(), registry_cfg).ok();\n\n let token = opts.token.unwrap_or_else(generate_registry_token);\n flow_env::set_personal_env_var(&token_env, &token)?;\n\n if opts.no_worker {\n println!(\"Skipped worker secret setup (--no-worker).\");\n } else {\n let worker_path = resolve_worker_path(opts.worker.as_ref(), &project_root)?\n .context(\"worker path not found; pass --worker to set secrets\")?;\n set_worker_secret(&worker_path, &token)?;\n }\n\n if let Some(registry_url) = registry_url {\n println!(\"Registry URL: {}\", registry_url);\n }\n\n if opts.show_token {\n println!(\"Registry token: {}\", token);\n } else {\n let preview = token.chars().take(6).collect::<String>();\n println!(\"Registry token: {}… (use --show-token to print)\", preview);\n }\n\n println!(\"Ready to release with `f release`.\");\n Ok(())\n}\n\npub fn publish(config_path: &Path, cfg: &Config, opts: RegistryReleaseOpts) -> Result<()> {\n let project_root = config_path\n .parent()\n .map(Path::to_path_buf)\n .unwrap_or_else(|| PathBuf::from(\".\"));\n\n let registry_cfg = cfg\n .release\n .as_ref()\n .and_then(|release| release.registry.as_ref());\n\n let registry_url = resolve_registry_url(opts.registry.as_deref(), registry_cfg)?;\n let package = resolve_package_name(opts.package.clone(), cfg, registry_cfg, &project_root)?;\n let bins = resolve_bins(&package, opts.bin.clone(), registry_cfg);\n let default_bin = resolve_default_bin(&package, &bins, registry_cfg);\n let version = resolve_registry_version(cfg, opts.version.clone(), ®istry_url, &package)?;\n let latest = resolve_latest_flag(opts.latest, opts.no_latest, registry_cfg);\n\n if !opts.no_build {\n build_binaries(&project_root, &bins)?;\n }\n\n let target = detect_target_triple()?;\n let mut binaries = BTreeMap::new();\n let mut sha256_map = BTreeMap::new();\n for bin in &bins {\n let path = project_root.join(\"target\").join(\"release\").join(bin);\n if !path.exists() {\n bail!(\"binary not found: {}\", path.display());\n }\n let sha = sha256_file(&path)?;\n let key = format!(\"packages/{}/{}/{}/{}\", package, version, target, bin);\n binaries.insert(bin.clone(), key);\n sha256_map.insert(bin.clone(), sha);\n }\n\n let mut targets = BTreeMap::new();\n targets.insert(\n target.clone(),\n RegistryTarget {\n binaries,\n sha256: sha256_map,\n },\n );\n\n let manifest = RegistryManifest {\n name: package.clone(),\n version: version.clone(),\n published_at: Utc::now().to_rfc3339(),\n bins: bins.clone(),\n default_bin,\n targets,\n };\n\n if opts.dry_run {\n println!(\n \"Dry run: would publish {} {} to {} (target {})\",\n package, version, registry_url, target\n );\n return Ok(());\n }\n\n let token_env = registry_cfg\n .and_then(|cfg| cfg.token_env.as_ref())\n .map(|s| s.as_str())\n .unwrap_or(DEFAULT_TOKEN_ENV);\n let token = resolve_registry_token(token_env)?;\n let client = Client::builder().timeout(Duration::from_secs(60)).build()?;\n\n for bin in &bins {\n let path = project_root.join(\"target\").join(\"release\").join(bin);\n let key = format!(\"packages/{}/{}/{}/{}\", package, version, target, bin);\n let url = format!(\"{}/{}\", registry_url, key);\n let body = fs::read(&path)?;\n let sha = sha256_file(&path)?;\n let response = client\n .put(url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .header(\"X-Sha256\", sha)\n .body(body)\n .send()\n .context(\"failed to upload binary\")?;\n if !response.status().is_success() {\n bail!(\"registry upload failed for {} ({})\", bin, response.status());\n }\n }\n\n let manifest_url = format!(\n \"{}/packages/{}/{}/manifest.json\",\n registry_url, package, version\n );\n let mut request = client\n .put(manifest_url)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .body(serde_json::to_string_pretty(&manifest)?);\n if latest {\n request = request.query(&[(\"latest\", \"1\")]);\n }\n let response = request.send().context(\"failed to upload manifest\")?;\n if !response.status().is_success() {\n bail!(\"registry manifest upload failed ({})\", response.status());\n }\n\n println!(\"Published {} {} to {}\", package, version, registry_url);\n Ok(())\n}\n\npub fn install(opts: InstallOpts) -> Result<()> {\n let name = opts.name.as_deref().unwrap_or(\"\").trim().to_string();\n if name.is_empty() {\n bail!(\"package name is required for registry install\");\n }\n let global_registry = load_global_registry_config();\n let registry_url = resolve_registry_url(opts.registry.as_deref(), global_registry.as_ref())?;\n let client = Client::builder().timeout(Duration::from_secs(60)).build()?;\n let version = opts.version.clone();\n let manifest = fetch_manifest(&client, ®istry_url, &name, version.as_deref())?;\n let target = detect_target_triple()?;\n let target_entry = manifest\n .targets\n .get(&target)\n .with_context(|| format!(\"No binaries for target {}\", target))?;\n let bin = resolve_install_bin(&name, &opts.bin, &manifest, target_entry)?;\n let path = target_entry\n .binaries\n .get(&bin)\n .with_context(|| format!(\"No binary '{}' in manifest\", bin))?;\n let download_url = resolve_download_url(®istry_url, path);\n let response = client\n .get(download_url)\n .send()\n .context(\"failed to download binary\")?;\n if !response.status().is_success() {\n bail!(\"download failed ({})\", response.status());\n }\n let bytes = response.bytes().context(\"failed to read download\")?;\n\n if !opts.no_verify {\n if let Some(expected) = target_entry.sha256.get(&bin) {\n let actual = sha256_bytes(&bytes);\n if expected != &actual {\n bail!(\"checksum mismatch for {}\", bin);\n }\n }\n }\n\n let bin_dir = opts.bin_dir.clone().unwrap_or_else(default_bin_dir);\n fs::create_dir_all(&bin_dir)\n .with_context(|| format!(\"failed to create {}\", bin_dir.display()))?;\n let dest = bin_dir.join(&bin);\n if dest.exists() && !opts.force {\n bail!(\n \"{} already exists (use --force to overwrite)\",\n dest.display()\n );\n }\n\n let mut temp = NamedTempFile::new_in(&bin_dir)\n .with_context(|| format!(\"failed to create temp file in {}\", bin_dir.display()))?;\n temp.write_all(&bytes)?;\n temp.flush()?;\n persist_with_permissions(temp, &dest)?;\n\n println!(\"Installed {} to {}\", bin, dest.display());\n if !path_in_env(&bin_dir) {\n println!(\"Add {} to PATH to use it everywhere.\", bin_dir.display());\n }\n Ok(())\n}\n\nfn resolve_registry_url(\n override_url: Option<&str>,\n cfg: Option<&RegistryReleaseConfig>,\n) -> Result<String> {\n let url = override_url\n .map(|s| s.to_string())\n .or_else(|| cfg.and_then(|cfg| cfg.url.clone()))\n .or_else(|| env::var(\"FLOW_REGISTRY_URL\").ok())\n .unwrap_or_else(|| \"https://myflow.sh\".to_string());\n Ok(url.trim_end_matches('/').to_string())\n}\n\nfn load_global_registry_config() -> Option<RegistryReleaseConfig> {\n let path = config::default_config_path();\n if !path.exists() {\n return None;\n }\n let cfg = config::load(&path).ok()?;\n cfg.release.and_then(|release| release.registry)\n}\n\nfn resolve_package_name(\n override_package: Option<String>,\n cfg: &Config,\n registry_cfg: Option<&RegistryReleaseConfig>,\n project_root: &Path,\n) -> Result<String> {\n if let Some(value) = override_package {\n return Ok(value);\n }\n if let Some(cfg) = registry_cfg.and_then(|cfg| cfg.package.clone()) {\n return Ok(cfg);\n }\n if let Some(name) = cfg.project_name.clone() {\n return Ok(name);\n }\n let fallback = project_root\n .file_name()\n .and_then(|name| name.to_str())\n .unwrap_or(\"package\");\n Ok(fallback.to_string())\n}\n\nfn resolve_bins(\n package: &str,\n override_bins: Vec<String>,\n registry_cfg: Option<&RegistryReleaseConfig>,\n) -> Vec<String> {\n if !override_bins.is_empty() {\n return override_bins;\n }\n if let Some(bins) = registry_cfg.and_then(|cfg| cfg.bins.clone()) {\n return bins;\n }\n vec![package.to_string()]\n}\n\nfn resolve_default_bin(\n package: &str,\n bins: &[String],\n registry_cfg: Option<&RegistryReleaseConfig>,\n) -> Option<String> {\n if let Some(default_bin) = registry_cfg.and_then(|cfg| cfg.default_bin.clone()) {\n return Some(default_bin);\n }\n if bins.iter().any(|bin| bin == package) {\n return Some(package.to_string());\n }\n bins.first().cloned()\n}\n\nfn resolve_latest_flag(\n latest: bool,\n no_latest: bool,\n registry_cfg: Option<&RegistryReleaseConfig>,\n) -> bool {\n if latest {\n return true;\n }\n if no_latest {\n return false;\n }\n registry_cfg.and_then(|cfg| cfg.latest).unwrap_or(true)\n}\n\nfn resolve_registry_version(\n cfg: &Config,\n version: Option<String>,\n registry_url: &str,\n package: &str,\n) -> Result<String> {\n if let Some(version) = version {\n return Ok(version);\n }\n let versioning = cfg\n .release\n .as_ref()\n .and_then(|release| release.versioning.as_deref());\n match versioning {\n Some(\"calver\") | Some(\"calendar\") | Some(\"date\") => {\n Ok(calver_version(cfg, registry_url, package))\n }\n _ => bail!(\"Version not provided. Pass --version or set release.versioning.\"),\n }\n}\n\nfn calver_version(cfg: &Config, registry_url: &str, package: &str) -> String {\n let now = Local::now();\n let mut base = format!(\"{}.{}.{}\", now.year(), now.month(), now.day());\n let suffix = cfg\n .release\n .as_ref()\n .and_then(|release| release.calver_suffix.clone())\n .or_else(|| env::var(\"FLOW_CALVER_SUFFIX\").ok());\n if let Some(suffix) = suffix {\n let trimmed = suffix.trim();\n if !trimmed.is_empty() {\n base = format!(\"{}-{}\", base, trimmed);\n }\n return base;\n }\n\n if let Ok(versions) = fetch_registry_versions(registry_url, package) {\n let mut max_suffix: Option<u64> = None;\n for version in versions {\n if version == base {\n max_suffix = Some(max_suffix.unwrap_or(0).max(0));\n continue;\n }\n if let Some(rest) = version.strip_prefix(&format!(\"{}-\", base)) {\n if let Ok(num) = rest.parse::<u64>() {\n max_suffix = Some(max_suffix.unwrap_or(0).max(num));\n }\n }\n }\n if let Some(value) = max_suffix {\n return format!(\"{}-{}\", base, value + 1);\n }\n }\n base\n}\n\nfn fetch_registry_versions(registry_url: &str, package: &str) -> Result<Vec<String>> {\n let client = Client::builder().timeout(Duration::from_secs(10)).build()?;\n let url = format!(\"{}/packages/{}/versions.json\", registry_url, package);\n let resp = client.get(url).send()?;\n if resp.status().as_u16() == 404 {\n return Ok(Vec::new());\n }\n if !resp.status().is_success() {\n bail!(\"registry returned {}\", resp.status());\n }\n #[derive(Deserialize)]\n struct VersionsResponse {\n versions: Vec<String>,\n }\n let parsed: VersionsResponse = resp.json()?;\n Ok(parsed.versions)\n}\n\nfn fetch_manifest(\n client: &Client,\n registry_url: &str,\n name: &str,\n version: Option<&str>,\n) -> Result<RegistryManifest> {\n let url = match version {\n Some(version) => format!(\n \"{}/packages/{}/{}/manifest.json\",\n registry_url, name, version\n ),\n None => format!(\"{}/packages/{}/latest.json\", registry_url, name),\n };\n let resp = client.get(url).send()?;\n if resp.status().as_u16() == 404 {\n bail!(\"Package '{}' not found in registry\", name);\n }\n if !resp.status().is_success() {\n bail!(\"Registry returned {}\", resp.status());\n }\n Ok(resp.json()?)\n}\n\nfn resolve_install_bin(\n package: &str,\n override_bin: &Option<String>,\n manifest: &RegistryManifest,\n target: &RegistryTarget,\n) -> Result<String> {\n if let Some(bin) = override_bin {\n return Ok(bin.to_string());\n }\n if let Some(bin) = manifest.default_bin.as_ref() {\n return Ok(bin.clone());\n }\n if manifest.bins.len() == 1 {\n return Ok(manifest.bins[0].clone());\n }\n if target.binaries.contains_key(package) {\n return Ok(package.to_string());\n }\n if let Some(first) = target.binaries.keys().next() {\n return Ok(first.clone());\n }\n bail!(\"No binaries available for this target\");\n}\n\nfn resolve_download_url(base: &str, path: &str) -> String {\n if path.starts_with(\"http://\") || path.starts_with(\"https://\") {\n return path.to_string();\n }\n format!(\n \"{}/{}\",\n base.trim_end_matches('/'),\n path.trim_start_matches('/')\n )\n}\n\nfn resolve_registry_token(token_env: &str) -> Result<String> {\n if let Ok(token) = env::var(token_env) {\n if !token.trim().is_empty() {\n return Ok(token);\n }\n }\n let vars = flow_env::fetch_personal_env_vars(&[token_env.to_string()])?;\n if let Some(token) = vars.get(token_env) {\n return Ok(token.clone());\n }\n bail!(\n \"{} not set. Add it with `f env new` or export it in your shell.\",\n token_env\n );\n}\n\nfn generate_registry_token() -> String {\n let a = uuid::Uuid::new_v4().simple().to_string();\n let b = uuid::Uuid::new_v4().simple().to_string();\n format!(\"flow_{}{}\", a, b)\n}\n\nfn resolve_worker_path(explicit: Option<&PathBuf>, project_root: &Path) -> Result<Option<PathBuf>> {\n if let Some(path) = explicit {\n return Ok(Some(path.clone()));\n }\n\n let candidates = [\n project_root.join(\"packages\").join(\"worker\"),\n project_root.join(\"worker\"),\n project_root.to_path_buf(),\n ];\n\n for candidate in candidates {\n if has_wrangler_config(&candidate) {\n return Ok(Some(candidate));\n }\n }\n\n Ok(None)\n}\n\nfn has_wrangler_config(path: &Path) -> bool {\n [\"wrangler.toml\", \"wrangler.json\", \"wrangler.jsonc\"]\n .iter()\n .any(|name| path.join(name).exists())\n}\n\nfn set_worker_secret(worker_path: &Path, token: &str) -> Result<()> {\n let mut child = Command::new(\"wrangler\")\n .arg(\"secret\")\n .arg(\"put\")\n .arg(WORKER_TOKEN_SECRET)\n .current_dir(worker_path)\n .stdin(std::process::Stdio::piped())\n .stdout(std::process::Stdio::inherit())\n .stderr(std::process::Stdio::inherit())\n .spawn()\n .context(\"failed to run wrangler secret put\")?;\n\n {\n let stdin = child\n .stdin\n .as_mut()\n .context(\"failed to open wrangler stdin\")?;\n stdin.write_all(token.as_bytes())?;\n stdin.write_all(b\"\\n\")?;\n }\n\n let status = child.wait()?;\n if !status.success() {\n bail!(\"wrangler secret put failed\");\n }\n\n println!(\n \"✓ Set {} in worker config ({})\",\n WORKER_TOKEN_SECRET,\n worker_path.display()\n );\n Ok(())\n}\n\nfn find_flow_toml(start: &Path) -> Option<PathBuf> {\n let mut current = start.to_path_buf();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\nfn build_binaries(project_root: &Path, bins: &[String]) -> Result<()> {\n let mut command = Command::new(\"cargo\");\n command.arg(\"build\").arg(\"--release\");\n for bin in bins {\n command.arg(\"--bin\").arg(bin);\n }\n let status = command\n .current_dir(project_root)\n .status()\n .context(\"failed to run cargo build\")?;\n if !status.success() {\n bail!(\"cargo build failed\");\n }\n Ok(())\n}\n\nfn detect_target_triple() -> Result<String> {\n let os = if cfg!(target_os = \"macos\") {\n \"apple-darwin\"\n } else if cfg!(target_os = \"linux\") {\n \"unknown-linux-gnu\"\n } else if cfg!(target_os = \"windows\") {\n \"pc-windows-msvc\"\n } else {\n bail!(\"Unsupported operating system\");\n };\n\n let arch = if cfg!(target_arch = \"aarch64\") {\n \"aarch64\"\n } else if cfg!(target_arch = \"x86_64\") {\n \"x86_64\"\n } else {\n bail!(\"Unsupported architecture\");\n };\n\n Ok(format!(\"{}-{}\", arch, os))\n}\n\nfn sha256_file(path: &Path) -> Result<String> {\n let data = fs::read(path)?;\n Ok(sha256_bytes(&data))\n}\n\nfn sha256_bytes(bytes: &[u8]) -> String {\n let mut hasher = Sha256::new();\n hasher.update(bytes);\n let digest = hasher.finalize();\n hex::encode(digest)\n}\n\nfn default_bin_dir() -> PathBuf {\n let home = env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"));\n // Prefer ~/.flow/bin (already on PATH from install.sh)\n let flow_bin = home.join(\".flow\").join(\"bin\");\n if flow_bin.exists() {\n return flow_bin;\n }\n home.join(\"bin\")\n}\n\nfn persist_with_permissions(temp: NamedTempFile, dest: &Path) -> Result<()> {\n temp.persist(dest)\n .map_err(|err| err.error)\n .context(\"failed to persist binary\")?;\n #[cfg(unix)]\n {\n use std::os::unix::fs::PermissionsExt;\n let mut perms = fs::metadata(dest)?.permissions();\n perms.set_mode(0o755);\n fs::set_permissions(dest, perms)?;\n }\n Ok(())\n}\n\nfn path_in_env(bin_dir: &Path) -> bool {\n let path = env::var_os(\"PATH\").unwrap_or_default();\n env::split_paths(&path).any(|entry| entry == bin_dir)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn resolves_relative_download_url() {\n let url = resolve_download_url(\"https://example.com\", \"packages/foo/bin\");\n assert_eq!(url, \"https://example.com/packages/foo/bin\");\n }\n\n #[test]\n fn resolves_default_bin_from_manifest() {\n let mut binaries = BTreeMap::new();\n binaries.insert(\"flow\".to_string(), \"path\".to_string());\n let target = RegistryTarget {\n binaries,\n sha256: BTreeMap::new(),\n };\n let manifest = RegistryManifest {\n name: \"flow\".to_string(),\n version: \"1.0.0\".to_string(),\n published_at: \"now\".to_string(),\n bins: vec![\"flow\".to_string()],\n default_bin: Some(\"flow\".to_string()),\n targets: BTreeMap::new(),\n };\n let bin = resolve_install_bin(\"flow\", &None, &manifest, &target).unwrap();\n assert_eq!(bin, \"flow\");\n }\n}\n" }, { "path": "src/release.rs", "content": "use anyhow::{Result, bail};\n\nuse crate::{\n cli::{GhReleaseCommand, ReleaseAction, ReleaseCommand, ReleaseOpts},\n config::Config,\n gh_release, registry, release_signing,\n tasks::{self, find_task},\n};\nuse std::path::Path;\n\nfn available_tasks(cfg: &crate::config::Config) -> String {\n let mut names: Vec<_> = cfg.tasks.iter().map(|task| task.name.clone()).collect();\n names.sort();\n names.join(\", \")\n}\n\nfn resolve_release_task(cfg: &crate::config::Config) -> Result<String> {\n if let Some(name) = cfg.flow.release_task.as_deref() {\n if find_task(cfg, name).is_some() {\n return Ok(name.to_string());\n }\n bail!(\n \"release_task '{}' not found. Available tasks: {}\",\n name,\n available_tasks(cfg)\n );\n }\n\n for fallback in [\"release\", \"release-build\"] {\n if find_task(cfg, fallback).is_some() {\n return Ok(fallback.to_string());\n }\n }\n\n if let Some(name) = cfg.flow.primary_task.as_deref() {\n if find_task(cfg, name).is_some() {\n return Ok(name.to_string());\n }\n }\n\n bail!(\n \"no release task found. Configure flow.release_task or add a 'release' task. Available tasks: {}\",\n available_tasks(cfg)\n );\n}\n\npub fn run(cmd: ReleaseCommand) -> Result<()> {\n if let Some(action) = cmd.action.clone() {\n match action {\n ReleaseAction::Github(cmd) => return gh_release::run(cmd),\n ReleaseAction::Signing(cmd) => return release_signing::run(cmd),\n _ => {}\n }\n }\n\n let (config_path, cfg) = tasks::load_project_config(cmd.config.clone())?;\n\n match cmd.action {\n Some(ReleaseAction::Github(cmd)) => gh_release::run(cmd),\n Some(ReleaseAction::Registry(opts)) => registry::publish(&config_path, &cfg, opts),\n Some(ReleaseAction::Task(opts)) => run_task(ReleaseOpts {\n config: config_path,\n args: opts.args,\n }),\n Some(ReleaseAction::Signing(cmd)) => release_signing::run(cmd),\n None => run_default(&config_path, &cfg),\n }\n}\n\npub fn run_task(opts: ReleaseOpts) -> Result<()> {\n let (config_path, cfg) = tasks::load_project_config(opts.config)?;\n let task_name = resolve_release_task(&cfg)?;\n\n tasks::run(crate::cli::TaskRunOpts {\n config: config_path,\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: task_name,\n args: opts.args,\n })\n}\n\nfn run_default(config_path: &Path, cfg: &Config) -> Result<()> {\n let provider = cfg\n .release\n .as_ref()\n .and_then(|release| release.default.as_deref())\n .or_else(|| {\n cfg.release\n .as_ref()\n .and_then(|release| release.registry.as_ref())\n .map(|_| \"registry\")\n })\n .unwrap_or(\"task\");\n\n match provider {\n \"registry\" => {\n registry::publish(config_path, cfg, crate::cli::RegistryReleaseOpts::default())\n }\n \"task\" | \"release\" => run_task(ReleaseOpts {\n config: config_path.to_path_buf(),\n args: Vec::new(),\n }),\n \"github\" | \"gh\" => gh_release::run(GhReleaseCommand { action: None }),\n other => bail!(\n \"Unknown release provider '{}'. Expected registry, task, or github.\",\n other\n ),\n }\n}\n" }, { "path": "src/release_signing.rs", "content": "use anyhow::{Context, Result, bail};\nuse base64::{Engine as _, engine::general_purpose::STANDARD as BASE64_STD};\nuse std::{\n fs,\n io::Write,\n process::{Command, Stdio},\n};\n\nuse crate::{\n cli::{\n ReleaseSigningAction, ReleaseSigningCommand, ReleaseSigningStoreOpts,\n ReleaseSigningSyncOpts,\n },\n env,\n};\n\nconst SIGNING_KEYS: [&str; 3] = [\n \"MACOS_SIGN_P12_B64\",\n \"MACOS_SIGN_P12_PASSWORD\",\n \"MACOS_SIGN_IDENTITY\",\n];\n\npub fn run(cmd: ReleaseSigningCommand) -> Result<()> {\n match cmd.action {\n ReleaseSigningAction::Status => status(),\n ReleaseSigningAction::Store(opts) => store(opts),\n ReleaseSigningAction::Sync(opts) => sync(opts),\n }\n}\n\nfn status() -> Result<()> {\n println!(\"macOS code signing (status)\");\n println!(\"──────────────────────────\");\n\n if cfg!(target_os = \"macos\") {\n let identities = list_codesign_identities().unwrap_or_default();\n let mut dev_id = Vec::new();\n let mut apple_dev = Vec::new();\n for name in identities {\n if name.starts_with(\"Developer ID Application:\") {\n dev_id.push(name);\n } else if name.starts_with(\"Apple Development:\") {\n apple_dev.push(name);\n }\n }\n\n if !dev_id.is_empty() {\n println!(\"Keychain: Developer ID Application identity found:\");\n for name in dev_id {\n println!(\" - {}\", name);\n }\n } else if !apple_dev.is_empty() {\n println!(\"Keychain: no Developer ID Application identity found.\");\n println!(\n \"Keychain: Apple Development identity found (not recommended for public distribution):\"\n );\n for name in apple_dev {\n println!(\" - {}\", name);\n }\n println!();\n println!(\n \"Next: create/download a Developer ID Application certificate (Apple Developer) and export it as .p12.\"\n );\n } else {\n println!(\"Keychain: no code signing identities found.\");\n }\n } else {\n println!(\"Keychain: not on macOS (skipping).\");\n }\n\n println!();\n\n // This may prompt for Touch ID if using cloud env store.\n match env::fetch_personal_env_vars(\n &SIGNING_KEYS\n .iter()\n .map(|s| s.to_string())\n .collect::<Vec<_>>(),\n ) {\n Ok(vars) => {\n for key in SIGNING_KEYS {\n if let Some(value) = vars.get(key) {\n // Avoid leaking secrets; show presence + size only.\n println!(\"Env store: {} = set ({} bytes)\", key, value.len());\n } else {\n println!(\"Env store: {} = missing\", key);\n }\n }\n }\n Err(err) => {\n println!(\"Env store: unable to read signing keys ({})\", err);\n println!(\"Next: run `f env login` (cloud) and `f env unlock` (Touch ID), then retry.\");\n }\n }\n\n println!();\n println!(\n \"GitHub: `f release signing sync` will copy env store values into GitHub Actions secrets via `gh`.\"\n );\n Ok(())\n}\n\nfn list_codesign_identities() -> Result<Vec<String>> {\n let output = Command::new(\"security\")\n .args([\"find-identity\", \"-v\", \"-p\", \"codesigning\"])\n .output()\n .context(\"failed to run `security find-identity`\")?;\n if !output.status.success() {\n bail!(\"`security find-identity` failed\");\n }\n let text = String::from_utf8_lossy(&output.stdout);\n let mut out = Vec::new();\n for line in text.lines() {\n // Example:\n // 1) <hash> \"Developer ID Application: Name (TEAMID)\"\n let Some(quoted) = line.split('\"').nth(1) else {\n continue;\n };\n let name = quoted.trim();\n if !name.is_empty() {\n out.push(name.to_string());\n }\n }\n Ok(out)\n}\n\nfn store(opts: ReleaseSigningStoreOpts) -> Result<()> {\n if !cfg!(target_os = \"macos\") {\n bail!(\"release signing store is only supported on macOS\");\n }\n\n let p12_path = opts\n .p12\n .clone()\n .context(\"--p12 is required (path to exported .p12)\")?;\n let p12_bytes = fs::read(&p12_path)\n .with_context(|| format!(\"failed to read p12 file at {}\", p12_path.display()))?;\n\n let identity = opts.identity.clone().context(\"--identity is required\")?;\n let password = opts\n .p12_password\n .clone()\n .context(\"--p12-password is required\")?;\n\n if !identity.starts_with(\"Developer ID Application:\") {\n eprintln!(\n \"Warning: identity does not look like a Developer ID Application certificate: {}\",\n identity\n );\n }\n\n let p12_b64 = BASE64_STD.encode(p12_bytes);\n\n if opts.dry_run {\n println!(\"[dry-run] Would set Flow personal env keys:\");\n println!(\" - MACOS_SIGN_P12_B64 ({} bytes)\", p12_b64.len());\n println!(\" - MACOS_SIGN_P12_PASSWORD ({} bytes)\", password.len());\n println!(\" - MACOS_SIGN_IDENTITY ({} bytes)\", identity.len());\n return Ok(());\n }\n\n // Store in Flow personal env store (cloud if logged in; may prompt).\n env::set_personal_env_var(\"MACOS_SIGN_P12_B64\", &p12_b64)?;\n env::set_personal_env_var(\"MACOS_SIGN_P12_PASSWORD\", &password)?;\n env::set_personal_env_var(\"MACOS_SIGN_IDENTITY\", &identity)?;\n\n println!(\"✓ Stored signing materials in Flow personal env store.\");\n Ok(())\n}\n\nfn sync(opts: ReleaseSigningSyncOpts) -> Result<()> {\n let keys: Vec<String> = SIGNING_KEYS.iter().map(|k| k.to_string()).collect();\n let vars = env::fetch_personal_env_vars(&keys)\n .context(\"failed to read signing keys from Flow personal env store\")?;\n\n if opts.dry_run {\n println!(\"[dry-run] Would set GitHub Actions secrets via `gh secret set`:\");\n for key in SIGNING_KEYS {\n if vars.contains_key(key) {\n println!(\" - {} (set in env store)\", key);\n } else {\n println!(\" - {} (missing in env store)\", key);\n }\n }\n if let Some(repo) = opts.repo.as_deref() {\n println!(\"Repo: {}\", repo);\n } else {\n println!(\"Repo: (from current directory)\");\n }\n if SIGNING_KEYS.iter().any(|k| !vars.contains_key(*k)) {\n println!();\n println!(\"Next: set missing keys with `f release signing store ...`.\");\n }\n return Ok(());\n }\n\n for key in SIGNING_KEYS {\n if !vars.contains_key(key) {\n bail!(\n \"missing {} in Flow env store. Set it with `f release signing store ...` (or `f env set {}`) first.\",\n key,\n key\n );\n }\n }\n\n ensure_gh_available()?;\n for key in SIGNING_KEYS {\n let value = vars.get(key).expect(\"checked above\");\n gh_secret_set(opts.repo.as_deref(), key, value)?;\n println!(\"✓ Set GitHub secret: {}\", key);\n }\n\n Ok(())\n}\n\nfn ensure_gh_available() -> Result<()> {\n let status = Command::new(\"gh\")\n .args([\"--version\"])\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .context(\"failed to run `gh` (GitHub CLI)\")?;\n if !status.success() {\n bail!(\"`gh` is installed but not working\");\n }\n Ok(())\n}\n\nfn gh_secret_set(repo: Option<&str>, name: &str, value: &str) -> Result<()> {\n let mut cmd = Command::new(\"gh\");\n cmd.args([\"secret\", \"set\", name]);\n if let Some(repo) = repo {\n cmd.args([\"--repo\", repo]);\n }\n // Avoid passing secrets via argv (ps); `gh secret set` reads from stdin when --body is omitted.\n\n let mut child = cmd\n .stdin(Stdio::piped())\n .stdout(Stdio::null())\n .spawn()\n .with_context(|| format!(\"failed to spawn `gh secret set {}`\", name))?;\n\n {\n let stdin = child\n .stdin\n .as_mut()\n .context(\"failed to open stdin for gh\")?;\n stdin.write_all(value.as_bytes())?;\n }\n\n let status = child.wait()?;\n if !status.success() {\n bail!(\"`gh secret set {}` failed\", name);\n }\n Ok(())\n}\n" }, { "path": "src/repo_capsule.rs", "content": "use std::collections::BTreeSet;\nuse std::fs;\nuse std::path::{Path, PathBuf};\nuse std::time::{SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result, bail};\nuse serde::{Deserialize, Serialize};\n\nuse crate::cli::{RepoAliasAction, RepoAliasCommand, RepoCapsuleOpts};\nuse crate::{config, project_snapshot};\n\nconst DEFAULT_STORE_DIR: &str = \"~/repos/garden-co/jazz2/.jazz2/flow-repo-capsules\";\nconst STORE_DIR_ENV: &str = \"FLOW_REPO_CAPSULE_STORE\";\nconst CAPSULE_VERSION: u32 = 1;\nconst REGISTRY_FILE: &str = \"repo-aliases.json\";\nconst DEFAULT_SHELF_CONFIG: &str = \"~/.agents/shelf/config.json\";\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\npub struct RepoCapsule {\n pub version: u32,\n pub repo_root: String,\n pub repo_name: String,\n pub repo_id: String,\n pub origin_url: Option<String>,\n pub summary: String,\n pub languages: Vec<String>,\n pub manifests: Vec<String>,\n pub commands: Vec<String>,\n pub important_paths: Vec<String>,\n pub docs_hints: Vec<String>,\n pub updated_at_unix: u64,\n watched: Vec<PathStamp>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\nstruct PathStamp {\n path: String,\n exists: bool,\n len: u64,\n modified_sec: u64,\n modified_nsec: u32,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\npub struct RepoCapsuleReference {\n pub matched: String,\n pub repo_root: String,\n pub output: String,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\npub struct RepoAliasEntry {\n pub alias: String,\n pub path: String,\n pub source: String,\n pub updated_at_unix: u64,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]\nstruct RepoAliasRegistry {\n version: u32,\n aliases: Vec<RepoAliasEntry>,\n}\n\n#[derive(Debug, Clone, Serialize)]\nstruct RepoAliasImportSummary {\n imported: usize,\n skipped: usize,\n aliases: Vec<RepoAliasEntry>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ShelfConfigFile {\n #[serde(default)]\n repos: Vec<ShelfRepoEntry>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ShelfRepoEntry {\n alias: String,\n}\n\npub fn run_capsule(opts: RepoCapsuleOpts) -> Result<()> {\n let target = resolve_target_path(opts.path.as_deref())?;\n let capsule = if opts.refresh {\n refresh_capsule_for_path(&target)?\n } else {\n load_or_refresh_capsule_for_path(&target)?\n };\n\n if opts.json {\n println!(\"{}\", serde_json::to_string_pretty(&capsule)?);\n } else {\n print!(\"{}\", render_capsule_report(&capsule));\n }\n Ok(())\n}\n\npub fn run_alias(cmd: RepoAliasCommand) -> Result<()> {\n match cmd.action.unwrap_or(RepoAliasAction::List { json: false }) {\n RepoAliasAction::List { json } => {\n let aliases = list_aliases()?;\n if json {\n println!(\"{}\", serde_json::to_string_pretty(&aliases)?);\n } else if aliases.is_empty() {\n println!(\"No repo aliases registered.\");\n } else {\n for entry in aliases {\n println!(\"{} -> {} ({})\", entry.alias, entry.path, entry.source);\n }\n }\n }\n RepoAliasAction::Set { alias, path, json } => {\n let entry = set_alias(&alias, &path, \"manual\")?;\n if json {\n println!(\"{}\", serde_json::to_string_pretty(&entry)?);\n } else {\n println!(\"{} -> {}\", entry.alias, entry.path);\n }\n }\n RepoAliasAction::Remove { alias } => {\n remove_alias(&alias)?;\n println!(\"Removed alias {}\", normalize_alias(&alias));\n }\n RepoAliasAction::ImportShelf { config, json } => {\n let summary = import_shelf_aliases(config.as_deref())?;\n if json {\n println!(\"{}\", serde_json::to_string_pretty(&summary)?);\n } else {\n println!(\n \"Imported {} alias(es), skipped {}.\",\n summary.imported, summary.skipped\n );\n for entry in summary.aliases {\n println!(\"{} -> {} ({})\", entry.alias, entry.path, entry.source);\n }\n }\n }\n }\n Ok(())\n}\n\npub fn load_or_refresh_capsule_for_path(path: &Path) -> Result<RepoCapsule> {\n let root = resolve_reference_root(path)?;\n load_or_refresh_capsule_for_root(&storage_dir(), &root)\n}\n\npub fn refresh_capsule_for_path(path: &Path) -> Result<RepoCapsule> {\n let root = resolve_reference_root(path)?;\n refresh_capsule_for_root(&storage_dir(), &root)\n}\n\npub fn list_aliases() -> Result<Vec<RepoAliasEntry>> {\n let mut aliases = load_alias_registry(&storage_dir())?.aliases;\n aliases.sort_by(|a, b| a.alias.cmp(&b.alias));\n Ok(aliases)\n}\n\npub fn set_alias(alias: &str, path: &str, source: &str) -> Result<RepoAliasEntry> {\n set_alias_in_store(&storage_dir(), alias, path, source)\n}\n\nfn set_alias_in_store(\n store_dir: &Path,\n alias: &str,\n path: &str,\n source: &str,\n) -> Result<RepoAliasEntry> {\n let target = resolve_target_path(Some(path))?;\n let root = resolve_reference_root(&target)?;\n let _ = load_or_refresh_capsule_for_root(store_dir, &root)?;\n let mut registry = load_alias_registry(store_dir)?;\n let entry = RepoAliasEntry {\n alias: normalize_alias(alias),\n path: root.display().to_string(),\n source: source.to_string(),\n updated_at_unix: now_unix(),\n };\n registry.aliases.retain(|value| value.alias != entry.alias);\n registry.aliases.push(entry.clone());\n save_alias_registry(store_dir, ®istry)?;\n Ok(entry)\n}\n\npub fn remove_alias(alias: &str) -> Result<()> {\n let store_dir = storage_dir();\n let mut registry = load_alias_registry(&store_dir)?;\n registry\n .aliases\n .retain(|value| value.alias != normalize_alias(alias));\n save_alias_registry(&store_dir, ®istry)\n}\n\nfn import_shelf_aliases(config_path: Option<&str>) -> Result<RepoAliasImportSummary> {\n let config_path = config::expand_path(config_path.unwrap_or(DEFAULT_SHELF_CONFIG));\n import_shelf_aliases_into_store(&storage_dir(), &config_path)\n}\n\nfn import_shelf_aliases_into_store(\n store_dir: &Path,\n config_path: &Path,\n) -> Result<RepoAliasImportSummary> {\n let payload = fs::read_to_string(&config_path)\n .with_context(|| format!(\"read {}\", config_path.display()))?;\n let parsed =\n serde_json::from_str::<ShelfConfigFile>(&payload).context(\"parse Shelf config JSON\")?;\n let shelf_repos_dir = config_path\n .parent()\n .map(|value| value.join(\"repos\"))\n .unwrap_or_else(|| config::expand_path(\"~/.agents/shelf/repos\"));\n\n let mut imported = Vec::new();\n let mut skipped = 0usize;\n for repo in parsed.repos {\n let alias = normalize_alias(&repo.alias);\n let path = shelf_repos_dir.join(&alias);\n if !path.exists() {\n skipped += 1;\n continue;\n }\n match set_alias_in_store(store_dir, &alias, &path.display().to_string(), \"shelf\") {\n Ok(entry) => imported.push(entry),\n Err(_) => skipped += 1,\n }\n }\n\n Ok(RepoAliasImportSummary {\n imported: imported.len(),\n skipped,\n aliases: imported,\n })\n}\n\npub fn resolve_reference_candidates(\n target_path: &Path,\n query_text: &str,\n candidates: &[String],\n limit: usize,\n) -> Result<Vec<RepoCapsuleReference>> {\n let store_dir = storage_dir();\n let registry = load_alias_registry(&store_dir)?;\n let mut seen_roots = BTreeSet::new();\n let mut matches = Vec::new();\n\n for candidate in candidates {\n if matches.len() >= limit {\n break;\n }\n let Some(root) =\n resolve_reference_candidate_root(target_path, query_text, candidate, ®istry)\n else {\n continue;\n };\n let root_key = root.display().to_string();\n if !seen_roots.insert(root_key) {\n continue;\n }\n let capsule = load_or_refresh_capsule_for_root(&store_dir, &root)?;\n matches.push(RepoCapsuleReference {\n matched: candidate.clone(),\n repo_root: capsule.repo_root.clone(),\n output: render_reference_output(&capsule, candidate),\n });\n }\n\n Ok(matches)\n}\n\nfn load_or_refresh_capsule_for_root(store_dir: &Path, root: &Path) -> Result<RepoCapsule> {\n if let Some(existing) = load_capsule(store_dir, root)? {\n if capsule_is_fresh(&existing) {\n return Ok(existing);\n }\n }\n refresh_capsule_for_root(store_dir, root)\n}\n\nfn refresh_capsule_for_root(store_dir: &Path, root: &Path) -> Result<RepoCapsule> {\n let capsule = build_capsule(root)?;\n save_capsule(store_dir, &capsule)?;\n Ok(capsule)\n}\n\nfn resolve_target_path(path: Option<&str>) -> Result<PathBuf> {\n let base = match path.map(str::trim).filter(|value| !value.is_empty()) {\n Some(value) => config::expand_path(value),\n None => std::env::current_dir().context(\"read current dir\")?,\n };\n Ok(base.canonicalize().unwrap_or(base))\n}\n\nfn resolve_reference_root(path: &Path) -> Result<PathBuf> {\n let Some(root) = detect_reference_root(path) else {\n bail!(\"no repo or flow project found for {}\", path.display());\n };\n Ok(root)\n}\n\nfn resolve_candidate_root(target_path: &Path, candidate: &str) -> Option<PathBuf> {\n let trimmed = candidate.trim();\n if trimmed.is_empty() {\n return None;\n }\n\n let expanded = if trimmed.starts_with(\"~/\") {\n config::expand_path(trimmed)\n } else if Path::new(trimmed).is_absolute() {\n PathBuf::from(trimmed)\n } else if trimmed.starts_with(\"./\") || trimmed.starts_with(\"../\") {\n target_path.join(trimmed)\n } else {\n return None;\n };\n\n if !expanded.exists() {\n return None;\n }\n detect_reference_root(&expanded)\n}\n\nfn resolve_reference_candidate_root(\n target_path: &Path,\n query_text: &str,\n candidate: &str,\n registry: &RepoAliasRegistry,\n) -> Option<PathBuf> {\n if looks_like_local_path(candidate) {\n return resolve_candidate_root(target_path, candidate);\n }\n\n let alias = normalize_alias(candidate);\n let entry = registry.aliases.iter().find(|value| value.alias == alias)?;\n if !alias_reference_allowed(query_text, &entry.alias) {\n return None;\n }\n\n let path = PathBuf::from(&entry.path);\n if !path.exists() {\n return None;\n }\n detect_reference_root(&path)\n}\n\nfn alias_reference_allowed(query_text: &str, alias: &str) -> bool {\n let normalized_query = query_text.to_ascii_lowercase();\n let alias = normalize_alias(alias);\n if normalized_query.trim() == alias {\n return true;\n }\n\n let cue_prefixes = [\n \"see \", \"in \", \"from \", \"using \", \"compare \", \"inspect \", \"study \", \"read \", \"use \",\n \"open \",\n ];\n cue_prefixes.iter().any(|prefix| {\n normalized_query.contains(&format!(\"{prefix}{alias}\"))\n || normalized_query.contains(&format!(\"{prefix}{alias} \"))\n || normalized_query.contains(&format!(\"{prefix}{alias},\"))\n })\n}\n\nfn normalize_alias(value: &str) -> String {\n value.trim().to_ascii_lowercase()\n}\n\nfn detect_reference_root(path: &Path) -> Option<PathBuf> {\n let base = if path.is_dir() {\n path.to_path_buf()\n } else {\n path.parent()?.to_path_buf()\n };\n\n if let Some(root) = find_git_root(&base) {\n return Some(root.canonicalize().unwrap_or(root));\n }\n if let Some(flow_toml) = project_snapshot::find_flow_toml_upwards(&base) {\n let root = flow_toml.parent().unwrap_or(Path::new(\".\")).to_path_buf();\n return Some(root.canonicalize().unwrap_or(root));\n }\n if base.exists() {\n return Some(base.canonicalize().unwrap_or(base));\n }\n None\n}\n\nfn looks_like_local_path(candidate: &str) -> bool {\n let trimmed = candidate.trim();\n trimmed.starts_with(\"~/\")\n || trimmed.starts_with('/')\n || trimmed.starts_with(\"./\")\n || trimmed.starts_with(\"../\")\n}\n\nfn find_git_root(start: &Path) -> Option<PathBuf> {\n let mut current = if start.is_dir() {\n start.to_path_buf()\n } else {\n start.parent()?.to_path_buf()\n };\n loop {\n let dot_git = current.join(\".git\");\n if dot_git.is_dir() || dot_git.is_file() {\n return Some(current);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\nfn build_capsule(root: &Path) -> Result<RepoCapsule> {\n let root = root.canonicalize().unwrap_or_else(|_| root.to_path_buf());\n let repo_root = root.display().to_string();\n let repo_name = root\n .file_name()\n .and_then(|value| value.to_str())\n .unwrap_or(\"repo\")\n .to_string();\n let origin_url = read_origin_url(&root);\n let repo_id = infer_repo_id(&root, origin_url.as_deref());\n let manifests = detect_manifests(&root);\n let languages = detect_languages(&root, &manifests);\n let commands = detect_commands(&root, &manifests);\n let important_paths = detect_important_paths(&root);\n let docs_hints = detect_docs_hints(&root);\n let summary = build_summary(&repo_id, &languages, &manifests, &commands, &docs_hints);\n let watched = collect_watched_stamps(&root);\n let updated_at_unix = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0);\n\n Ok(RepoCapsule {\n version: CAPSULE_VERSION,\n repo_root,\n repo_name,\n repo_id,\n origin_url,\n summary,\n languages,\n manifests,\n commands,\n important_paths,\n docs_hints,\n updated_at_unix,\n watched,\n })\n}\n\nfn build_summary(\n repo_id: &str,\n languages: &[String],\n manifests: &[String],\n commands: &[String],\n docs_hints: &[String],\n) -> String {\n let mut parts = vec![repo_id.to_string()];\n if !languages.is_empty() {\n parts.push(format!(\"languages: {}\", languages.join(\", \")));\n }\n if !manifests.is_empty() {\n parts.push(format!(\n \"manifests: {}\",\n manifests\n .iter()\n .take(4)\n .cloned()\n .collect::<Vec<_>>()\n .join(\", \")\n ));\n }\n if !commands.is_empty() {\n parts.push(format!(\n \"commands: {}\",\n commands\n .iter()\n .take(3)\n .cloned()\n .collect::<Vec<_>>()\n .join(\", \")\n ));\n }\n if let Some(hint) = docs_hints.first() {\n parts.push(format!(\"note: {}\", trim_chars(hint, 120)));\n }\n trim_chars(&parts.join(\" | \"), 360)\n}\n\nfn detect_manifests(root: &Path) -> Vec<String> {\n let candidates = [\n \"flow.toml\",\n \"package.json\",\n \"Cargo.toml\",\n \"pyproject.toml\",\n \"go.mod\",\n \"justfile\",\n \"Justfile\",\n \"Makefile\",\n \"flake.nix\",\n \"wrangler.toml\",\n \"wrangler.json\",\n \"wrangler.jsonc\",\n \"uv.lock\",\n \"pnpm-lock.yaml\",\n \"bun.lockb\",\n \"bun.lock\",\n ];\n candidates\n .into_iter()\n .filter(|candidate| root.join(candidate).exists())\n .map(|value| value.to_string())\n .collect()\n}\n\nfn detect_languages(root: &Path, manifests: &[String]) -> Vec<String> {\n let mut langs = BTreeSet::new();\n let manifests_set: BTreeSet<_> = manifests.iter().map(String::as_str).collect();\n\n if manifests_set.contains(\"Cargo.toml\") {\n langs.insert(\"Rust\".to_string());\n }\n if manifests_set.contains(\"package.json\")\n || manifests_set.contains(\"bun.lockb\")\n || manifests_set.contains(\"bun.lock\")\n || root.join(\"tsconfig.json\").exists()\n {\n langs.insert(\"TypeScript/JavaScript\".to_string());\n }\n if manifests_set.contains(\"pyproject.toml\") || manifests_set.contains(\"uv.lock\") {\n langs.insert(\"Python\".to_string());\n }\n if manifests_set.contains(\"go.mod\") {\n langs.insert(\"Go\".to_string());\n }\n if manifests_set.contains(\"flake.nix\") {\n langs.insert(\"Nix\".to_string());\n }\n if root.join(\"moon.mod.json\").exists() {\n langs.insert(\"MoonBit\".to_string());\n }\n langs.into_iter().collect()\n}\n\nfn detect_commands(root: &Path, manifests: &[String]) -> Vec<String> {\n let mut commands = Vec::new();\n let manifests_set: BTreeSet<_> = manifests.iter().map(String::as_str).collect();\n\n for task in read_flow_task_names(&root.join(\"flow.toml\"))\n .into_iter()\n .take(4)\n {\n commands.push(format!(\"f {}\", task));\n }\n\n for script in read_package_scripts(&root.join(\"package.json\"))\n .into_iter()\n .take(4)\n {\n commands.push(format!(\"npm run {}\", script));\n }\n\n if manifests_set.contains(\"Cargo.toml\") {\n commands.push(\"cargo test\".to_string());\n commands.push(\"cargo build\".to_string());\n }\n if manifests_set.contains(\"pyproject.toml\") || manifests_set.contains(\"uv.lock\") {\n commands.push(\"uv run pytest\".to_string());\n }\n if manifests_set.contains(\"go.mod\") {\n commands.push(\"go test ./...\".to_string());\n }\n if manifests_set.contains(\"flake.nix\") {\n commands.push(\"nix develop\".to_string());\n }\n\n dedupe_preserving_order(commands)\n .into_iter()\n .take(6)\n .collect()\n}\n\nfn read_flow_task_names(path: &Path) -> Vec<String> {\n let Ok(content) = fs::read_to_string(path) else {\n return Vec::new();\n };\n let Ok(value) = toml::from_str::<toml::Value>(&content) else {\n return Vec::new();\n };\n value\n .get(\"tasks\")\n .and_then(|value| value.as_array())\n .into_iter()\n .flatten()\n .filter_map(|task| {\n task.get(\"name\")\n .and_then(|value| value.as_str())\n .map(|value| value.to_string())\n })\n .collect()\n}\n\nfn read_package_scripts(path: &Path) -> Vec<String> {\n let Ok(content) = fs::read_to_string(path) else {\n return Vec::new();\n };\n let Ok(value) = serde_json::from_str::<serde_json::Value>(&content) else {\n return Vec::new();\n };\n let Some(scripts) = value.get(\"scripts\").and_then(|value| value.as_object()) else {\n return Vec::new();\n };\n\n let preferred = [\"dev\", \"start\", \"test\", \"build\", \"lint\", \"typecheck\"];\n let mut names = Vec::new();\n for name in preferred {\n if scripts.contains_key(name) {\n names.push(name.to_string());\n }\n }\n for name in scripts.keys() {\n if !names.iter().any(|existing| existing == name) {\n names.push(name.to_string());\n }\n }\n names\n}\n\nfn detect_important_paths(root: &Path) -> Vec<String> {\n let candidates = [\n \"flow.toml\",\n \"README.md\",\n \"README.mdx\",\n \"AGENTS.md\",\n \"agents.md\",\n \"package.json\",\n \"Cargo.toml\",\n \"pyproject.toml\",\n \"docs\",\n \"src\",\n \"apps\",\n \"crates\",\n \"packages\",\n \"workers\",\n ];\n\n candidates\n .into_iter()\n .filter(|candidate| root.join(candidate).exists())\n .map(|value| value.to_string())\n .take(8)\n .collect()\n}\n\nfn detect_docs_hints(root: &Path) -> Vec<String> {\n let mut hints = Vec::new();\n\n for (label, path) in [\n (\"AGENTS\", root.join(\"AGENTS.md\")),\n (\"AGENTS\", root.join(\"agents.md\")),\n (\"README\", root.join(\"README.md\")),\n (\"README\", root.join(\"README.mdx\")),\n (\"README\", root.join(\"readme.md\")),\n (\"README\", root.join(\"readme.mdx\")),\n ] {\n if let Some(hint) = read_text_hint(&path, label) {\n hints.push(hint);\n break;\n }\n }\n\n if let Some(hint) = read_docs_index_hint(&root.join(\"docs\")) {\n hints.push(hint);\n }\n\n hints.into_iter().take(3).collect()\n}\n\nfn read_text_hint(path: &Path, label: &str) -> Option<String> {\n let content = fs::read_to_string(path).ok()?;\n let mut lines = Vec::new();\n let mut in_code_block = false;\n for raw_line in content.lines() {\n let line = raw_line.trim();\n if line.starts_with(\"```\") {\n in_code_block = !in_code_block;\n continue;\n }\n if in_code_block || line.is_empty() {\n continue;\n }\n if matches!(line, \"---\" | \"+++\") || line.starts_with(\"title:\") {\n continue;\n }\n let normalized = line.trim_start_matches('#').trim_start_matches('-').trim();\n if normalized.is_empty()\n || normalized.starts_with('<')\n || normalized.starts_with('[')\n || normalized.eq_ignore_ascii_case(\"instructions\")\n {\n continue;\n }\n lines.push(normalized.to_string());\n if lines.len() >= 3 {\n break;\n }\n }\n\n if lines.is_empty() {\n None\n } else {\n Some(format!(\"{label}: {}\", trim_chars(&lines.join(\" \"), 220)))\n }\n}\n\nfn read_docs_index_hint(docs_dir: &Path) -> Option<String> {\n if !docs_dir.is_dir() {\n return None;\n }\n\n let mut names = fs::read_dir(docs_dir)\n .ok()?\n .flatten()\n .filter_map(|entry| {\n let path = entry.path();\n let ext = path.extension()?.to_str()?;\n if !matches!(ext, \"md\" | \"mdx\") {\n return None;\n }\n path.file_name()\n .and_then(|value| value.to_str())\n .map(|value| value.to_string())\n })\n .collect::<Vec<_>>();\n names.sort();\n names.truncate(5);\n if names.is_empty() {\n None\n } else {\n Some(format!(\"Docs: {}\", names.join(\", \")))\n }\n}\n\nfn collect_watched_stamps(root: &Path) -> Vec<PathStamp> {\n watched_paths(root)\n .into_iter()\n .map(|path| stamp_path(&path))\n .collect()\n}\n\nfn watched_paths(root: &Path) -> Vec<PathBuf> {\n let mut paths = vec![root.to_path_buf()];\n for candidate in [\n \"flow.toml\",\n \"README.md\",\n \"README.mdx\",\n \"readme.md\",\n \"readme.mdx\",\n \"AGENTS.md\",\n \"agents.md\",\n \"package.json\",\n \"Cargo.toml\",\n \"pyproject.toml\",\n \"go.mod\",\n \"justfile\",\n \"Justfile\",\n \"Makefile\",\n \"flake.nix\",\n \"docs/README.md\",\n \"docs/index.md\",\n \"docs/index.mdx\",\n ] {\n paths.push(root.join(candidate));\n }\n paths\n}\n\nfn stamp_path(path: &Path) -> PathStamp {\n let metadata = fs::metadata(path).ok();\n let exists = metadata.is_some();\n let (len, modified_sec, modified_nsec) = metadata\n .and_then(|meta| {\n let modified = meta.modified().ok()?;\n let duration = modified.duration_since(UNIX_EPOCH).ok()?;\n Some((meta.len(), duration.as_secs(), duration.subsec_nanos()))\n })\n .unwrap_or((0, 0, 0));\n\n PathStamp {\n path: path.display().to_string(),\n exists,\n len,\n modified_sec,\n modified_nsec,\n }\n}\n\nfn capsule_is_fresh(capsule: &RepoCapsule) -> bool {\n capsule\n .watched\n .iter()\n .all(|stamp| stamp_path(Path::new(&stamp.path)) == *stamp)\n}\n\nfn render_reference_output(capsule: &RepoCapsule, matched: &str) -> String {\n let mut lines = vec![format!(\"Repo reference: {}\", matched)];\n lines.push(format!(\"- Repo: {}\", capsule.repo_id));\n lines.push(format!(\"- Root: {}\", capsule.repo_root));\n if let Some(origin) = capsule.origin_url.as_deref() {\n lines.push(format!(\"- Remote: {}\", origin));\n }\n if !capsule.languages.is_empty() {\n lines.push(format!(\"- Languages: {}\", capsule.languages.join(\", \")));\n }\n if !capsule.commands.is_empty() {\n lines.push(format!(\n \"- Common commands: {}\",\n capsule\n .commands\n .iter()\n .take(4)\n .cloned()\n .collect::<Vec<_>>()\n .join(\", \")\n ));\n }\n if !capsule.important_paths.is_empty() {\n lines.push(format!(\n \"- Important paths: {}\",\n capsule\n .important_paths\n .iter()\n .take(5)\n .cloned()\n .collect::<Vec<_>>()\n .join(\", \")\n ));\n }\n for hint in capsule.docs_hints.iter().take(2) {\n lines.push(format!(\"- {}\", hint));\n }\n lines.join(\"\\n\")\n}\n\nfn render_capsule_report(capsule: &RepoCapsule) -> String {\n let mut out = String::new();\n out.push_str(&format!(\"Repo capsule: {}\\n\", capsule.repo_id));\n out.push_str(&format!(\"root: {}\\n\", capsule.repo_root));\n if let Some(origin) = capsule.origin_url.as_deref() {\n out.push_str(&format!(\"origin: {}\\n\", origin));\n }\n out.push_str(&format!(\"summary: {}\\n\", capsule.summary));\n if !capsule.languages.is_empty() {\n out.push_str(&format!(\"languages: {}\\n\", capsule.languages.join(\", \")));\n }\n if !capsule.manifests.is_empty() {\n out.push_str(&format!(\"manifests: {}\\n\", capsule.manifests.join(\", \")));\n }\n if !capsule.commands.is_empty() {\n out.push_str(&format!(\"commands: {}\\n\", capsule.commands.join(\", \")));\n }\n if !capsule.important_paths.is_empty() {\n out.push_str(\"important_paths:\\n\");\n for path in &capsule.important_paths {\n out.push_str(&format!(\"- {}\\n\", path));\n }\n }\n if !capsule.docs_hints.is_empty() {\n out.push_str(\"notes:\\n\");\n for hint in &capsule.docs_hints {\n out.push_str(&format!(\"- {}\\n\", hint));\n }\n }\n out\n}\n\nfn infer_repo_id(root: &Path, origin_url: Option<&str>) -> String {\n if let Some(origin) = origin_url\n && let Some(id) = parse_repo_id_from_remote(origin)\n {\n return id;\n }\n\n let name = root\n .file_name()\n .and_then(|value| value.to_str())\n .unwrap_or(\"repo\");\n if let Some(parent) = root\n .parent()\n .and_then(|value| value.file_name())\n .and_then(|value| value.to_str())\n {\n return format!(\"{}/{}\", parent, name);\n }\n name.to_string()\n}\n\nfn parse_repo_id_from_remote(remote: &str) -> Option<String> {\n let trimmed = remote.trim().trim_end_matches(\".git\");\n if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n return Some(rest.to_string());\n }\n if let Some(rest) = trimmed.strip_prefix(\"https://github.com/\") {\n return Some(rest.to_string());\n }\n if let Some(rest) = trimmed.strip_prefix(\"ssh://git@github.com/\") {\n return Some(rest.to_string());\n }\n None\n}\n\nfn read_origin_url(root: &Path) -> Option<String> {\n let git_dir = resolve_git_dir(root)?;\n let common_dir = resolve_common_git_dir(&git_dir);\n let config_path = common_dir.join(\"config\");\n parse_git_remote_url(&config_path, \"origin\")\n}\n\nfn resolve_git_dir(root: &Path) -> Option<PathBuf> {\n let dot_git = root.join(\".git\");\n if dot_git.is_dir() {\n return Some(dot_git);\n }\n let content = fs::read_to_string(&dot_git).ok()?;\n let gitdir = content.strip_prefix(\"gitdir:\")?.trim();\n let path = PathBuf::from(gitdir);\n let resolved = if path.is_absolute() {\n path\n } else {\n dot_git.parent()?.join(path)\n };\n Some(resolved.canonicalize().unwrap_or(resolved))\n}\n\nfn resolve_common_git_dir(git_dir: &Path) -> PathBuf {\n let commondir = git_dir.join(\"commondir\");\n let Ok(content) = fs::read_to_string(&commondir) else {\n return git_dir.to_path_buf();\n };\n let trimmed = content.trim();\n if trimmed.is_empty() {\n return git_dir.to_path_buf();\n }\n let path = PathBuf::from(trimmed);\n let resolved = if path.is_absolute() {\n path\n } else {\n git_dir.join(path)\n };\n resolved.canonicalize().unwrap_or(resolved)\n}\n\nfn parse_git_remote_url(config_path: &Path, remote_name: &str) -> Option<String> {\n let content = fs::read_to_string(config_path).ok()?;\n let mut in_remote = false;\n for raw_line in content.lines() {\n let line = raw_line.trim();\n if line.starts_with('[') && line.ends_with(']') {\n in_remote = parse_remote_section(line)\n .is_some_and(|value| value.eq_ignore_ascii_case(remote_name));\n continue;\n }\n if !in_remote {\n continue;\n }\n let Some((key, value)) = line.split_once('=') else {\n continue;\n };\n if key.trim().eq_ignore_ascii_case(\"url\") {\n return Some(value.trim().to_string());\n }\n }\n None\n}\n\nfn parse_remote_section(section: &str) -> Option<String> {\n let inner = section.strip_prefix('[')?.strip_suffix(']')?.trim();\n let rest = inner.strip_prefix(\"remote\")?.trim();\n let name = rest.strip_prefix('\"')?.strip_suffix('\"')?.trim();\n if name.is_empty() {\n None\n } else {\n Some(name.to_string())\n }\n}\n\nfn dedupe_preserving_order(values: Vec<String>) -> Vec<String> {\n let mut seen = BTreeSet::new();\n let mut deduped = Vec::new();\n for value in values {\n if seen.insert(value.clone()) {\n deduped.push(value);\n }\n }\n deduped\n}\n\nfn trim_chars(value: &str, limit: usize) -> String {\n if value.chars().count() <= limit {\n return value.to_string();\n }\n let keep = limit.saturating_sub(3);\n value.chars().take(keep).collect::<String>() + \"...\"\n}\n\nfn storage_dir() -> PathBuf {\n if let Ok(path) = std::env::var(STORE_DIR_ENV) {\n return config::expand_path(&path);\n }\n config::expand_path(DEFAULT_STORE_DIR)\n}\n\nfn registry_path(store_dir: &Path) -> PathBuf {\n store_dir.join(REGISTRY_FILE)\n}\n\nfn load_alias_registry(store_dir: &Path) -> Result<RepoAliasRegistry> {\n let path = registry_path(store_dir);\n if !path.exists() {\n return Ok(RepoAliasRegistry {\n version: 1,\n aliases: Vec::new(),\n });\n }\n\n let payload = fs::read_to_string(&path).with_context(|| format!(\"read {}\", path.display()))?;\n serde_json::from_str::<RepoAliasRegistry>(&payload)\n .with_context(|| format!(\"parse {}\", path.display()))\n}\n\nfn save_alias_registry(store_dir: &Path, registry: &RepoAliasRegistry) -> Result<()> {\n fs::create_dir_all(store_dir)\n .with_context(|| format!(\"create store dir {}\", store_dir.display()))?;\n let path = registry_path(store_dir);\n let payload = serde_json::to_string_pretty(registry)?;\n fs::write(&path, payload).with_context(|| format!(\"write {}\", path.display()))\n}\n\nfn now_unix() -> u64 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|value| value.as_secs())\n .unwrap_or(0)\n}\n\nfn save_capsule(store_dir: &Path, capsule: &RepoCapsule) -> Result<()> {\n fs::create_dir_all(store_dir)\n .with_context(|| format!(\"create store dir {}\", store_dir.display()))?;\n let path = capsule_path(store_dir, &capsule.repo_root);\n let payload = serde_json::to_string_pretty(capsule)?;\n fs::write(&path, payload).with_context(|| format!(\"write {}\", path.display()))\n}\n\nfn load_capsule(store_dir: &Path, root: &Path) -> Result<Option<RepoCapsule>> {\n if !store_dir.exists() {\n return Ok(None);\n }\n\n let path = capsule_path(store_dir, &root.display().to_string());\n if !path.exists() {\n return Ok(None);\n }\n\n let payload = fs::read_to_string(&path).with_context(|| format!(\"read {}\", path.display()))?;\n let capsule = serde_json::from_str::<RepoCapsule>(&payload)\n .with_context(|| format!(\"parse {}\", path.display()))?;\n Ok(Some(capsule))\n}\n\nfn capsule_path(store_dir: &Path, repo_root: &str) -> PathBuf {\n let hash = blake3::hash(repo_root.as_bytes()).to_hex().to_string();\n store_dir.join(format!(\"{hash}.json\"))\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use tempfile::tempdir;\n\n #[test]\n fn build_capsule_captures_repo_shape() {\n let dir = tempdir().expect(\"tempdir\");\n let root = dir.path().join(\"owner\").join(\"repo\");\n fs::create_dir_all(root.join(\".git\")).expect(\"create .git\");\n fs::write(\n root.join(\"README.md\"),\n \"# Repo\\n\\nFast TypeScript service\\n\",\n )\n .expect(\"write readme\");\n fs::write(\n root.join(\"AGENTS.md\"),\n \"Use flow tasks first.\\nKeep changes small.\\n\",\n )\n .expect(\"write agents\");\n fs::write(\n root.join(\"flow.toml\"),\n \"[[tasks]]\\nname = \\\"dev\\\"\\ncommand = \\\"bun run dev\\\"\\n\\n[[tasks]]\\nname = \\\"test\\\"\\ncommand = \\\"bun test\\\"\\n\",\n )\n .expect(\"write flow\");\n fs::write(\n root.join(\"package.json\"),\n r#\"{\"name\":\"repo\",\"scripts\":{\"dev\":\"vite\",\"test\":\"vitest\",\"build\":\"tsc -b\"}}\"#,\n )\n .expect(\"write package\");\n\n let capsule = build_capsule(&root).expect(\"build capsule\");\n assert_eq!(capsule.repo_id, \"owner/repo\");\n assert!(\n capsule\n .languages\n .iter()\n .any(|value| value == \"TypeScript/JavaScript\")\n );\n assert!(capsule.commands.iter().any(|value| value == \"f dev\"));\n assert!(capsule.commands.iter().any(|value| value == \"npm run test\"));\n assert!(\n capsule\n .docs_hints\n .iter()\n .any(|value| value.starts_with(\"AGENTS:\"))\n );\n }\n\n #[test]\n fn load_or_refresh_capsule_reuses_fresh_store() {\n let dir = tempdir().expect(\"tempdir\");\n let store = dir.path().join(\"store\");\n let root = dir.path().join(\"repo\");\n fs::create_dir_all(root.join(\".git\")).expect(\"create .git\");\n fs::write(root.join(\"README.md\"), \"# Repo\\n\\nhello\\n\").expect(\"write readme\");\n\n let first = load_or_refresh_capsule_for_root(&store, &root).expect(\"first load\");\n let second = load_or_refresh_capsule_for_root(&store, &root).expect(\"second load\");\n\n assert_eq!(first.repo_root, second.repo_root);\n assert_eq!(first.updated_at_unix, second.updated_at_unix);\n }\n\n #[test]\n fn resolve_reference_candidates_finds_repo_paths() {\n let dir = tempdir().expect(\"tempdir\");\n let store = dir.path().join(\"store\");\n let target = dir.path().join(\"target\");\n let repo = dir.path().join(\"external\");\n fs::create_dir_all(&target).expect(\"create target\");\n fs::create_dir_all(repo.join(\".git\")).expect(\"create .git\");\n fs::write(repo.join(\"README.md\"), \"# External\\n\\ncompare this repo\\n\")\n .expect(\"write readme\");\n\n let candidates = vec![repo.display().to_string()];\n let matches = resolve_reference_candidates_with_store(\n &store,\n &target,\n \"see external and compare\",\n &candidates,\n 2,\n )\n .expect(\"resolve refs\");\n assert_eq!(matches.len(), 1);\n assert!(matches[0].output.contains(\"Repo reference:\"));\n }\n\n #[test]\n fn resolve_reference_candidates_finds_registered_aliases() {\n let dir = tempdir().expect(\"tempdir\");\n let store = dir.path().join(\"store\");\n let target = dir.path().join(\"target\");\n let repo = dir.path().join(\"Effect-TS\").join(\"effect-smol\");\n fs::create_dir_all(&target).expect(\"create target\");\n fs::create_dir_all(repo.join(\".git\")).expect(\"create .git\");\n fs::write(repo.join(\"README.md\"), \"# effect-smol\\n\\nsmall repo\\n\").expect(\"write readme\");\n\n let entry = RepoAliasEntry {\n alias: \"effect-smol\".to_string(),\n path: repo.display().to_string(),\n source: \"manual\".to_string(),\n updated_at_unix: 1,\n };\n save_alias_registry(\n &store,\n &RepoAliasRegistry {\n version: 1,\n aliases: vec![entry],\n },\n )\n .expect(\"save registry\");\n\n let candidates = vec![\"effect-smol\".to_string()];\n let matches = resolve_reference_candidates_with_store(\n &store,\n &target,\n \"see effect-smol and compare architecture\",\n &candidates,\n 2,\n )\n .expect(\"resolve alias refs\");\n assert_eq!(matches.len(), 1);\n assert!(matches[0].output.contains(\"effect-smol\"));\n }\n\n #[test]\n fn import_shelf_aliases_loads_sibling_repos_dir() {\n let dir = tempdir().expect(\"tempdir\");\n let store = dir.path().join(\"store\");\n let shelf = dir.path().join(\"shelf\");\n let repos_dir = shelf.join(\"repos\");\n let repo = repos_dir.join(\"effect-smol\");\n fs::create_dir_all(repo.join(\".git\")).expect(\"create .git\");\n fs::write(repo.join(\"README.md\"), \"# effect-smol\\n\\nsmall repo\\n\").expect(\"write readme\");\n fs::create_dir_all(&shelf).expect(\"create shelf\");\n fs::write(\n shelf.join(\"config.json\"),\n r#\"{\"version\":1,\"syncIntervalMinutes\":60,\"repos\":[{\"alias\":\"effect-smol\"}]}\"#,\n )\n .expect(\"write shelf config\");\n\n let summary =\n import_shelf_aliases_into_store(&store, &shelf.join(\"config.json\")).expect(\"import\");\n\n assert_eq!(summary.imported, 1);\n assert_eq!(summary.skipped, 0);\n let aliases = load_alias_registry(&store).expect(\"load registry\").aliases;\n assert!(aliases.iter().any(|entry| entry.alias == \"effect-smol\"));\n }\n\n fn resolve_reference_candidates_with_store(\n store: &Path,\n target_path: &Path,\n query_text: &str,\n candidates: &[String],\n limit: usize,\n ) -> Result<Vec<RepoCapsuleReference>> {\n let registry = load_alias_registry(store)?;\n let mut seen_roots = BTreeSet::new();\n let mut matches = Vec::new();\n for candidate in candidates {\n if matches.len() >= limit {\n break;\n }\n let Some(root) =\n resolve_reference_candidate_root(target_path, query_text, candidate, ®istry)\n else {\n continue;\n };\n if !seen_roots.insert(root.display().to_string()) {\n continue;\n }\n let capsule = load_or_refresh_capsule_for_root(store, &root)?;\n matches.push(RepoCapsuleReference {\n matched: candidate.clone(),\n repo_root: capsule.repo_root.clone(),\n output: render_reference_output(&capsule, candidate),\n });\n }\n Ok(matches)\n }\n}\n" }, { "path": "src/repos.rs", "content": "//! Repository management commands.\n//!\n//! Supports cloning repos into a structured local directory.\n\nuse std::fs;\nuse std::io::Write;\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\nuse serde::Deserialize;\nuse url::Url;\n\nuse crate::cli::{CloneOpts, ReposAction, ReposCloneOpts, ReposCommand};\nuse crate::{config, publish, repo_capsule, ssh, ssh_keys, upstream, vcs};\n\nconst DEFAULT_REPOS_ROOT: &str = \"~/repos\";\nconst REPOS_ROOT_OVERRIDE_ENV: &str = \"FLOW_REPOS_ALLOW_ROOT_OVERRIDE\";\n\n/// Run the repos subcommand.\npub fn run(cmd: ReposCommand) -> Result<()> {\n match cmd.action {\n Some(ReposAction::Clone(opts)) => {\n let path = clone_repo(opts)?;\n open_in_zed(&path)?;\n Ok(())\n }\n Some(ReposAction::Create(opts)) => publish::run_github(opts),\n Some(ReposAction::Capsule(opts)) => repo_capsule::run_capsule(opts),\n Some(ReposAction::Alias(cmd)) => repo_capsule::run_alias(cmd),\n None => fuzzy_select_repo(),\n }\n}\n\n/// Clone into the current working directory (git clone style destination behavior).\npub fn clone_git_like(opts: CloneOpts) -> Result<()> {\n ssh::ensure_ssh_env();\n let mode = ssh::ssh_mode();\n if matches!(mode, ssh::SshMode::Force) && !ssh::has_identities() {\n match ssh_keys::ensure_default_identity(24) {\n Ok(()) => {}\n Err(err) => {\n bail!(\n \"SSH mode is forced but no key is available. Run `f ssh setup` or `f ssh unlock` (error: {})\",\n err\n );\n }\n }\n }\n\n let clone_url = resolve_git_like_clone_url(&opts.url)?;\n let mut cmd = Command::new(\"git\");\n cmd.arg(\"clone\").arg(&clone_url);\n if let Some(dir) = opts.directory {\n cmd.arg(dir);\n }\n\n let status = cmd\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run git clone\")?;\n\n if !status.success() {\n bail!(\"git clone failed\");\n }\n\n Ok(())\n}\n\nfn open_in_zed(path: &std::path::Path) -> Result<()> {\n std::process::Command::new(\"open\")\n .args([\"-a\", \"/Applications/Zed Preview.app\"])\n .arg(path)\n .status()\n .context(\"failed to open Zed\")?;\n Ok(())\n}\n\n/// Fuzzy search through repos in ~/repos and print the selected path.\nfn fuzzy_select_repo() -> Result<()> {\n let root = config::expand_path(DEFAULT_REPOS_ROOT);\n if !root.exists() {\n println!(\"No repos directory found at {}\", root.display());\n println!(\"Clone a repo with: f repos clone <url>\");\n return Ok(());\n }\n\n let repos = discover_repos(&root)?;\n if repos.is_empty() {\n println!(\"No repositories found in {}\", root.display());\n println!(\"Clone a repo with: f repos clone <url>\");\n return Ok(());\n }\n\n if which::which(\"fzf\").is_err() {\n println!(\"fzf not found on PATH – install it to use fuzzy selection.\");\n println!(\"Available repositories:\");\n for repo in &repos {\n println!(\" {}\", repo.display);\n }\n return Ok(());\n }\n\n if let Some(selected) = run_fzf(&repos)? {\n open_in_zed(&selected.path)?;\n }\n\n Ok(())\n}\n\nstruct RepoEntry {\n display: String,\n path: PathBuf,\n}\n\n/// Discover all repos in the root directory (owner/repo structure).\nfn discover_repos(root: &Path) -> Result<Vec<RepoEntry>> {\n let mut repos = Vec::new();\n\n let owners = match fs::read_dir(root) {\n Ok(entries) => entries,\n Err(_) => return Ok(repos),\n };\n\n for owner_entry in owners.flatten() {\n let owner_path = owner_entry.path();\n if !owner_path.is_dir() {\n continue;\n }\n\n let owner_name = match owner_path.file_name() {\n Some(name) => name.to_string_lossy().to_string(),\n None => continue,\n };\n\n // Skip hidden directories\n if owner_name.starts_with('.') {\n continue;\n }\n\n let repo_entries = match fs::read_dir(&owner_path) {\n Ok(entries) => entries,\n Err(_) => continue,\n };\n\n for repo_entry in repo_entries.flatten() {\n let repo_path = repo_entry.path();\n if !repo_path.is_dir() {\n continue;\n }\n\n let repo_name = match repo_path.file_name() {\n Some(name) => name.to_string_lossy().to_string(),\n None => continue,\n };\n\n // Skip hidden directories\n if repo_name.starts_with('.') {\n continue;\n }\n\n // Check if it's a git repo\n if repo_path.join(\".git\").exists() {\n repos.push(RepoEntry {\n display: format!(\"{}/{}\", owner_name, repo_name),\n path: repo_path,\n });\n }\n }\n }\n\n repos.sort_by(|a, b| a.display.cmp(&b.display));\n Ok(repos)\n}\n\nfn run_fzf(entries: &[RepoEntry]) -> Result<Option<&RepoEntry>> {\n let mut child = Command::new(\"fzf\")\n .arg(\"--prompt\")\n .arg(\"repo> \")\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n {\n let stdin = child.stdin.as_mut().context(\"failed to open fzf stdin\")?;\n for entry in entries {\n writeln!(stdin, \"{}\", entry.display)?;\n }\n }\n\n let output = child.wait_with_output()?;\n if !output.status.success() {\n return Ok(None);\n }\n\n let selection = String::from_utf8(output.stdout).context(\"fzf output was not valid UTF-8\")?;\n let selection = selection.trim();\n\n if selection.is_empty() {\n return Ok(None);\n }\n\n Ok(entries.iter().find(|e| e.display == selection))\n}\n\n#[derive(Debug, Clone)]\npub(crate) struct RepoRef {\n pub(crate) owner: String,\n pub(crate) repo: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct RepoInfo {\n fork: bool,\n parent: Option<RepoParent>,\n source: Option<RepoParent>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct RepoParent {\n #[serde(rename = \"ssh_url\")]\n ssh_url: String,\n #[serde(default)]\n clone_url: Option<String>,\n}\n\n#[derive(Debug)]\nenum RepoTarget {\n GitHub(RepoRef),\n Generic(GenericRepoRef),\n}\n\n#[derive(Debug)]\nstruct GenericRepoRef {\n path: Vec<String>,\n clone_url: String,\n}\n\npub(crate) fn clone_repo(opts: ReposCloneOpts) -> Result<PathBuf> {\n ssh::ensure_ssh_env();\n let mode = ssh::ssh_mode();\n if matches!(mode, ssh::SshMode::Force) && !ssh::has_identities() {\n match ssh_keys::ensure_default_identity(24) {\n Ok(()) => {}\n Err(err) => {\n bail!(\n \"SSH mode is forced but no key is available. Run `f ssh setup` or `f ssh unlock` (error: {})\",\n err\n );\n }\n }\n }\n // Always prefer SSH for GitHub clone/upstream URLs.\n let prefer_ssh = true;\n let repo_target = parse_repo_target(&opts.url)?;\n let root = normalize_root(&opts.root)?;\n let mut github_ref: Option<RepoRef> = None;\n let (target_dir, clone_url, is_github) = match repo_target {\n RepoTarget::GitHub(repo_ref) => {\n github_ref = Some(RepoRef {\n owner: repo_ref.owner.clone(),\n repo: repo_ref.repo.clone(),\n });\n let owner_dir = root.join(&repo_ref.owner);\n let target_dir = owner_dir.join(&repo_ref.repo);\n let clone_url = if prefer_ssh {\n format!(\"git@github.com:{}/{}.git\", repo_ref.owner, repo_ref.repo)\n } else {\n format!(\n \"https://github.com/{}/{}.git\",\n repo_ref.owner, repo_ref.repo\n )\n };\n (target_dir, clone_url, true)\n }\n RepoTarget::Generic(repo_ref) => {\n let mut target_dir = root.to_path_buf();\n let path_len = repo_ref.path.len();\n let parts = if path_len >= 2 {\n &repo_ref.path[path_len - 2..]\n } else {\n repo_ref.path.as_slice()\n };\n for part in parts {\n target_dir = target_dir.join(part);\n }\n (target_dir, repo_ref.clone_url, false)\n }\n };\n\n if preflight_clone_target(&target_dir)? {\n println!(\"Already cloned: {}\", target_dir.display());\n return Ok(target_dir);\n }\n\n if let Some(parent) = target_dir.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n\n let shallow = !opts.full;\n let fetch_depth = if shallow { Some(1) } else { None };\n run_git_clone(&clone_url, &target_dir, shallow)?;\n\n println!(\"✓ cloned to {}\", target_dir.display());\n\n if opts.no_upstream {\n if shallow {\n spawn_background_history_fetch(&target_dir, false)?;\n }\n init_jj_repo(&target_dir)?;\n return Ok(target_dir);\n }\n\n if !is_github {\n let upstream_url = opts\n .upstream_url\n .clone()\n .unwrap_or_else(|| clone_url.clone());\n let upstream_is_origin = upstream_url.trim() == clone_url.as_str();\n if upstream_is_origin {\n println!(\"No upstream provided; using origin as upstream.\");\n }\n configure_upstream(&target_dir, &upstream_url, fetch_depth)?;\n if shallow {\n spawn_background_history_fetch(&target_dir, !upstream_is_origin)?;\n }\n init_jj_repo(&target_dir)?;\n return Ok(target_dir);\n }\n\n let upstream_url = if let Some(url) = opts.upstream_url {\n Some(url)\n } else {\n let repo_ref = github_ref\n .as_ref()\n .ok_or_else(|| anyhow::anyhow!(\"missing GitHub repo reference\"))?;\n resolve_upstream_url(repo_ref, prefer_ssh)?\n };\n\n let (upstream_url, upstream_is_origin) = match upstream_url {\n Some(url) => {\n let is_origin = url.trim() == clone_url.as_str();\n (url, is_origin)\n }\n None => {\n println!(\"No fork detected; using origin as upstream.\");\n (clone_url.clone(), true)\n }\n };\n\n configure_upstream(&target_dir, &upstream_url, fetch_depth)?;\n if shallow {\n spawn_background_history_fetch(&target_dir, !upstream_is_origin)?;\n }\n\n init_jj_repo(&target_dir)?;\n Ok(target_dir)\n}\n\nfn preflight_clone_target(target_dir: &Path) -> Result<bool> {\n match clone_target_state(target_dir)? {\n CloneTargetState::Missing | CloneTargetState::EmptyDir => Ok(false),\n CloneTargetState::GitCheckout => Ok(true),\n CloneTargetState::OccupiedNonRepo => bail!(\n \"target path exists but is not a git checkout: {}\",\n target_dir.display()\n ),\n }\n}\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nenum CloneTargetState {\n Missing,\n EmptyDir,\n GitCheckout,\n OccupiedNonRepo,\n}\n\nfn clone_target_state(path: &Path) -> Result<CloneTargetState> {\n if !path.exists() {\n return Ok(CloneTargetState::Missing);\n }\n\n if path.join(\".git\").exists() {\n return Ok(CloneTargetState::GitCheckout);\n }\n\n if !path.is_dir() {\n return Ok(CloneTargetState::OccupiedNonRepo);\n }\n\n let mut entries =\n fs::read_dir(path).with_context(|| format!(\"failed to inspect {}\", path.display()))?;\n if entries.next().is_none() {\n return Ok(CloneTargetState::EmptyDir);\n }\n\n Ok(CloneTargetState::OccupiedNonRepo)\n}\n\nfn init_jj_repo(repo_dir: &Path) -> Result<()> {\n if repo_dir.join(\".jj\").exists() {\n return Ok(());\n }\n if vcs::ensure_jj_installed().is_err() {\n println!(\"⚠ jj not found; skipping jj init\");\n return Ok(());\n }\n\n let has_git = repo_dir.join(\".git\").exists();\n let mut cmd = Command::new(\"jj\");\n cmd.current_dir(repo_dir).arg(\"git\").arg(\"init\");\n if has_git {\n cmd.arg(\"--colocate\");\n }\n let status = cmd.status().context(\"failed to run jj git init\")?;\n if !status.success() {\n println!(\"⚠ jj git init failed; continuing\");\n return Ok(());\n }\n\n let _ = Command::new(\"jj\")\n .current_dir(repo_dir)\n .args([\"git\", \"fetch\"])\n .status();\n\n if jj_auto_track(repo_dir) {\n let branch = jj_default_branch(repo_dir);\n let remote = jj_default_remote(repo_dir);\n let track_ref = format!(\"{}@{}\", branch, remote);\n let _ = Command::new(\"jj\")\n .current_dir(repo_dir)\n .args([\"bookmark\", \"track\", &track_ref])\n .status();\n }\n\n println!(\"✓ jj initialized for {}\", repo_dir.display());\n Ok(())\n}\n\nfn jj_default_remote(repo_dir: &Path) -> String {\n if let Some(cfg) = load_jj_config(repo_dir) {\n if let Some(remote) = cfg.remote {\n return remote;\n }\n }\n \"origin\".to_string()\n}\n\nfn jj_auto_track(repo_dir: &Path) -> bool {\n load_jj_config(repo_dir)\n .and_then(|cfg| cfg.auto_track)\n .unwrap_or(true)\n}\n\nfn jj_default_branch(repo_dir: &Path) -> String {\n if let Some(cfg) = load_jj_config(repo_dir) {\n if let Some(branch) = cfg.default_branch {\n return branch;\n }\n }\n if git_ref_exists(repo_dir, \"refs/remotes/origin/main\")\n || git_ref_exists(repo_dir, \"refs/heads/main\")\n {\n return \"main\".to_string();\n }\n if git_ref_exists(repo_dir, \"refs/remotes/origin/master\")\n || git_ref_exists(repo_dir, \"refs/heads/master\")\n {\n return \"master\".to_string();\n }\n \"main\".to_string()\n}\n\nfn git_ref_exists(repo_dir: &Path, reference: &str) -> bool {\n Command::new(\"git\")\n .current_dir(repo_dir)\n .args([\"rev-parse\", \"--verify\", reference])\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .map(|s| s.success())\n .unwrap_or(false)\n}\n\nfn load_jj_config(repo_dir: &Path) -> Option<config::JjConfig> {\n let local = repo_dir.join(\"flow.toml\");\n if local.exists() {\n if let Ok(cfg) = config::load(&local) {\n if cfg.jj.is_some() {\n return cfg.jj;\n }\n }\n }\n\n let global = config::default_config_path();\n if global.exists() {\n if let Ok(cfg) = config::load(&global) {\n if cfg.jj.is_some() {\n return cfg.jj;\n }\n }\n }\n\n None\n}\n\nfn parse_repo_target(input: &str) -> Result<RepoTarget> {\n if is_github_input(input) {\n return parse_github_repo(input).map(RepoTarget::GitHub);\n }\n\n let generic = parse_generic_repo(input)?;\n Ok(RepoTarget::Generic(generic))\n}\n\nfn resolve_git_like_clone_url(input: &str) -> Result<String> {\n let trimmed = input.trim();\n if trimmed.is_empty() {\n bail!(\"missing repository URL\");\n }\n\n if trimmed.starts_with(\"git@github.com:\")\n || trimmed.contains(\"github.com/\")\n || looks_like_github_shorthand(trimmed)\n {\n let repo_ref = parse_github_repo(trimmed)?;\n return Ok(format!(\n \"git@github.com:{}/{}.git\",\n repo_ref.owner, repo_ref.repo\n ));\n }\n\n Ok(trimmed.to_string())\n}\n\nfn looks_like_github_shorthand(input: &str) -> bool {\n if input.contains(\"://\")\n || input.contains('@')\n || input.starts_with('/')\n || input.starts_with(\"./\")\n || input.starts_with(\"../\")\n || input.starts_with(\"~/\")\n {\n return false;\n }\n\n let mut parts = input.split('/');\n let Some(owner) = parts.next() else {\n return false;\n };\n let Some(repo) = parts.next() else {\n return false;\n };\n if parts.next().is_some() {\n return false;\n }\n\n if owner.is_empty() || repo.is_empty() {\n return false;\n }\n\n owner != \".\" && owner != \"..\" && repo != \".\" && repo != \"..\"\n}\n\nfn is_github_input(input: &str) -> bool {\n let trimmed = input.trim();\n if trimmed.starts_with(\"git@github.com:\") || trimmed.contains(\"github.com/\") {\n return true;\n }\n !trimmed.contains(\"://\") && !trimmed.contains('@')\n}\n\nfn parse_generic_repo(input: &str) -> Result<GenericRepoRef> {\n let trimmed = input.trim();\n if trimmed.is_empty() {\n bail!(\"missing repository URL\");\n }\n\n if let Ok(url) = Url::parse(trimmed) {\n let path = url\n .path()\n .trim_matches('/')\n .split('/')\n .filter(|p| !p.is_empty())\n .map(|p| p.trim_end_matches(\".git\").to_string())\n .collect::<Vec<_>>();\n if path.is_empty() {\n bail!(\"unable to parse repository path from: {}\", input);\n }\n return Ok(GenericRepoRef {\n path,\n clone_url: trimmed.to_string(),\n });\n }\n\n if let Some(at) = trimmed.find('@') {\n if let Some(colon) = trimmed[at + 1..].find(':') {\n let rest = &trimmed[at + 1 + colon + 1..];\n let path = rest\n .trim_matches('/')\n .split('/')\n .filter(|p| !p.is_empty())\n .map(|p| p.trim_end_matches(\".git\").to_string())\n .collect::<Vec<_>>();\n if path.is_empty() {\n bail!(\"unable to parse repository from: {}\", input);\n }\n return Ok(GenericRepoRef {\n path,\n clone_url: trimmed.to_string(),\n });\n }\n }\n\n bail!(\"unable to parse repository URL: {}\", input)\n}\n\npub(crate) fn parse_github_repo(input: &str) -> Result<RepoRef> {\n let trimmed = input.trim();\n if trimmed.is_empty() {\n bail!(\"missing repository URL\");\n }\n\n let path = if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n rest\n } else if let Some(idx) = trimmed.find(\"github.com/\") {\n &trimmed[idx + \"github.com/\".len()..]\n } else {\n trimmed\n };\n\n let path = path\n .trim_start_matches('/')\n .split(&['?', '#'][..])\n .next()\n .unwrap_or(path)\n .trim_end_matches('/');\n\n let mut parts = path.split('/');\n let owner = parts.next().unwrap_or(\"\").trim();\n let repo = parts.next().unwrap_or(\"\").trim();\n\n if owner.is_empty() || repo.is_empty() {\n bail!(\"unable to parse GitHub repo from: {}\", input);\n }\n\n let repo = repo.strip_suffix(\".git\").unwrap_or(repo);\n if repo.is_empty() {\n bail!(\"unable to parse GitHub repo from: {}\", input);\n }\n\n Ok(RepoRef {\n owner: owner.to_string(),\n repo: repo.to_string(),\n })\n}\n\npub(crate) fn normalize_root(raw: &str) -> Result<PathBuf> {\n let expanded = config::expand_path(raw);\n let cwd = std::env::current_dir().context(\"failed to resolve current directory\")?;\n let root = if expanded.is_absolute() {\n expanded\n } else {\n cwd.join(expanded)\n };\n\n let default_root = config::expand_path(DEFAULT_REPOS_ROOT);\n if root != default_root && !repos_root_override_enabled() {\n bail!(\n \"repos root is immutable; use {} or set {}=1 to override\",\n default_root.display(),\n REPOS_ROOT_OVERRIDE_ENV\n );\n }\n\n Ok(root)\n}\n\nfn repos_root_override_enabled() -> bool {\n match std::env::var(REPOS_ROOT_OVERRIDE_ENV) {\n Ok(value) => {\n let trimmed = value.trim();\n !trimmed.is_empty() && trimmed != \"0\"\n }\n Err(_) => false,\n }\n}\n\nfn run_git_clone(url: &str, target_dir: &Path, shallow: bool) -> Result<()> {\n let mut cmd = Command::new(\"git\");\n cmd.arg(\"clone\");\n if shallow {\n cmd.args([\"--depth\", \"1\"]);\n }\n let status = cmd\n .arg(url)\n .arg(target_dir)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run git clone\")?;\n\n if !status.success() {\n bail!(\"git clone failed\");\n }\n\n Ok(())\n}\n\nfn resolve_upstream_url(repo_ref: &RepoRef, prefer_ssh: bool) -> Result<Option<String>> {\n let output = match Command::new(\"gh\")\n .args([\n \"api\",\n &format!(\"repos/{}/{}\", repo_ref.owner, repo_ref.repo),\n ])\n .output()\n {\n Ok(output) => output,\n Err(err) => {\n println!(\"gh not available; skipping upstream auto-setup ({})\", err);\n return Ok(None);\n }\n };\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n let message = stderr.trim();\n if message.is_empty() {\n println!(\"gh api failed; skipping upstream auto-setup\");\n } else {\n println!(\"gh api failed; skipping upstream auto-setup: {}\", message);\n }\n println!(\"Authenticate with: gh auth login\");\n return Ok(None);\n }\n\n let info: RepoInfo =\n serde_json::from_slice(&output.stdout).context(\"failed to parse gh api response\")?;\n\n if !info.fork {\n return Ok(None);\n }\n\n let parent = info.parent.or(info.source).map(|parent| {\n if prefer_ssh {\n parent.ssh_url\n } else {\n parent.clone_url.unwrap_or_else(|| parent.ssh_url)\n }\n });\n\n Ok(parent)\n}\n\nfn configure_upstream(repo_dir: &Path, upstream_url: &str, depth: Option<u32>) -> Result<()> {\n println!(\"Setting up upstream: {}\", upstream_url);\n\n let cwd = std::env::current_dir().context(\"failed to capture current directory\")?;\n std::env::set_current_dir(repo_dir)\n .with_context(|| format!(\"failed to enter {}\", repo_dir.display()))?;\n\n let result = upstream::setup_upstream_with_depth(Some(upstream_url), None, depth);\n\n if let Err(err) = std::env::set_current_dir(&cwd) {\n println!(\"warning: failed to restore working directory: {}\", err);\n }\n\n result\n}\n\nfn spawn_background_history_fetch(repo_dir: &Path, has_upstream: bool) -> Result<()> {\n let mut command = String::from(\"git fetch --unshallow --tags origin\");\n if has_upstream {\n command.push_str(\" && git fetch --tags upstream\");\n }\n\n let _child = Command::new(\"sh\")\n .arg(\"-c\")\n .arg(command)\n .current_dir(repo_dir)\n .stdin(Stdio::null())\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .spawn()\n .context(\"failed to spawn background history fetch\")?;\n\n println!(\"Fetching full history in background...\");\n\n Ok(())\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use tempfile::tempdir;\n\n #[test]\n fn preflight_clone_target_detects_git_checkout() {\n let dir = tempdir().expect(\"tempdir\");\n fs::create_dir_all(dir.path().join(\".git\")).expect(\"git dir\");\n\n let already_cloned = preflight_clone_target(dir.path()).expect(\"preflight\");\n\n assert!(already_cloned);\n }\n\n #[test]\n fn preflight_clone_target_allows_empty_dir() {\n let dir = tempdir().expect(\"tempdir\");\n\n let already_cloned = preflight_clone_target(dir.path()).expect(\"preflight\");\n\n assert!(!already_cloned);\n }\n\n #[test]\n fn preflight_clone_target_rejects_non_repo_dir() {\n let dir = tempdir().expect(\"tempdir\");\n fs::create_dir_all(dir.path().join(\"user_files\")).expect(\"user_files dir\");\n\n let err = preflight_clone_target(dir.path()).expect_err(\"expected non-repo error\");\n\n assert!(\n err.to_string()\n .contains(\"target path exists but is not a git checkout\")\n );\n }\n}\n" }, { "path": "src/reviews_todo.rs", "content": "use std::path::Path;\nuse std::process::Command;\n\nuse anyhow::{Result, bail};\nuse chrono::Utc;\n\nuse crate::cli::{CommitQueueAction, CommitQueueCommand, ReviewsTodoAction, ReviewsTodoCommand};\nuse crate::commit;\nuse crate::todo;\n\npub fn run(cmd: ReviewsTodoCommand) -> Result<()> {\n let action = cmd.action.unwrap_or(ReviewsTodoAction::List);\n match action {\n ReviewsTodoAction::List => list_review_todos(),\n ReviewsTodoAction::Show { id } => show_review_todo(&id),\n ReviewsTodoAction::Done { id } => done_review_todo(&id),\n ReviewsTodoAction::Fix { id, all } => fix_review_todos(id.as_deref(), all),\n ReviewsTodoAction::Codex { hashes, all } => commit::run_commit_queue(CommitQueueCommand {\n action: Some(CommitQueueAction::Review { hashes, all }),\n }),\n ReviewsTodoAction::ApproveAll {\n force,\n allow_issues,\n allow_unreviewed,\n } => commit::run_commit_queue(CommitQueueCommand {\n action: Some(CommitQueueAction::ApproveAll {\n force,\n allow_issues,\n allow_unreviewed,\n }),\n }),\n }\n}\n\nfn list_review_todos() -> Result<()> {\n let root = todo::project_root();\n let items = todo::load_review_todos(&root)?;\n if items.is_empty() {\n println!(\"No review todos.\");\n return Ok(());\n }\n\n let mut open_items: Vec<_> = items\n .iter()\n .filter(|item| item.status != \"completed\")\n .collect();\n\n if open_items.is_empty() {\n println!(\"All review todos resolved.\");\n return Ok(());\n }\n\n // Sort by priority (P1 first)\n open_items.sort_by(|a, b| {\n let pa = a.priority.as_deref().unwrap_or(\"P4\");\n let pb = b.priority.as_deref().unwrap_or(\"P4\");\n pa.cmp(pb)\n });\n\n let (p1, p2, p3, p4, total) = todo::count_open_review_todos_by_priority(&root)?;\n println!(\n \"Review todos: {} open (P1:{} P2:{} P3:{} P4:{})\\n\",\n total, p1, p2, p3, p4\n );\n\n for item in &open_items {\n let priority = item.priority.as_deref().unwrap_or(\"P4\");\n let indicator = match priority {\n \"P1\" => \"[P1 !!]\",\n \"P2\" => \"[P2 ! ]\",\n \"P3\" => \"[P3 ]\",\n _ => \"[P4 ]\",\n };\n let short_id = &item.id[..item.id.len().min(8)];\n println!(\"{} {} {}\", indicator, short_id, item.title);\n }\n\n Ok(())\n}\n\nfn show_review_todo(id: &str) -> Result<()> {\n let root = todo::project_root();\n let (_, items) = todo::load_items_at_root(&root)?;\n let review_items: Vec<_> = items\n .iter()\n .filter(|item| {\n item.external_ref\n .as_deref()\n .map(|r| r.starts_with(\"flow-review-issue-\"))\n .unwrap_or(false)\n })\n .cloned()\n .collect();\n\n let idx = todo::find_item_index(&review_items, id)?;\n let item = &review_items[idx];\n\n let priority = item.priority.as_deref().unwrap_or(\"P4\");\n let indicator = match priority {\n \"P1\" => \"P1 (critical)\",\n \"P2\" => \"P2 (high)\",\n \"P3\" => \"P3 (medium)\",\n _ => \"P4 (low)\",\n };\n\n println!(\"ID: {}\", item.id);\n println!(\"Title: {}\", item.title);\n println!(\"Priority: {}\", indicator);\n println!(\"Status: {}\", item.status);\n println!(\"Created: {}\", item.created_at);\n if let Some(updated) = &item.updated_at {\n println!(\"Updated: {}\", updated);\n }\n if let Some(note) = &item.note {\n println!(\"\\n{}\", note);\n }\n\n Ok(())\n}\n\nfn done_review_todo(id: &str) -> Result<()> {\n let root = todo::project_root();\n let (path, mut items) = todo::load_items_at_root(&root)?;\n\n // Find among review items only\n let review_indices: Vec<usize> = items\n .iter()\n .enumerate()\n .filter(|(_, item)| {\n item.external_ref\n .as_deref()\n .map(|r| r.starts_with(\"flow-review-issue-\"))\n .unwrap_or(false)\n })\n .map(|(i, _)| i)\n .collect();\n\n // Match by id prefix among review items\n let mut matches = Vec::new();\n for &idx in &review_indices {\n if items[idx].id == id || items[idx].id.starts_with(id) {\n matches.push(idx);\n }\n }\n\n let idx = match matches.len() {\n 0 => bail!(\"Review todo '{}' not found\", id),\n 1 => matches[0],\n _ => bail!(\"Review todo id '{}' is ambiguous\", id),\n };\n\n if items[idx].status == \"completed\" {\n println!(\"Already completed: {}\", items[idx].id);\n return Ok(());\n }\n\n items[idx].status = \"completed\".to_string();\n items[idx].updated_at = Some(Utc::now().to_rfc3339());\n todo::save_items(&path, &items)?;\n println!(\"✓ {} -> completed\", items[idx].id);\n\n Ok(())\n}\n\nfn fix_review_todos(id: Option<&str>, all: bool) -> Result<()> {\n let root = todo::project_root();\n let items = todo::load_review_todos(&root)?;\n\n let open_items: Vec<_> = items\n .iter()\n .filter(|item| item.status != \"completed\")\n .collect();\n\n if open_items.is_empty() {\n println!(\"No open review todos to fix.\");\n return Ok(());\n }\n\n let to_fix: Vec<_> = if let Some(id) = id {\n let mut matched = Vec::new();\n for item in &open_items {\n if item.id == id || item.id.starts_with(id) {\n matched.push(*item);\n }\n }\n if matched.is_empty() {\n bail!(\"Review todo '{}' not found among open items\", id);\n }\n if matched.len() > 1 {\n bail!(\"Review todo id '{}' is ambiguous\", id);\n }\n matched\n } else if all {\n open_items\n } else {\n bail!(\"Specify a todo id or use --all to fix all open review todos\");\n };\n\n for item in &to_fix {\n fix_single_todo(&root, item)?;\n }\n\n Ok(())\n}\n\nfn fix_single_todo(root: &Path, item: &todo::TodoItem) -> Result<()> {\n let short_id = &item.id[..item.id.len().min(8)];\n let priority = item.priority.as_deref().unwrap_or(\"P4\");\n println!(\"==> Fixing [{}] {} : {}\", priority, short_id, item.title);\n\n // Extract commit SHA from note (line starting with \"Commit: \")\n let commit_sha = item\n .note\n .as_deref()\n .and_then(|note| {\n note.lines()\n .find(|line| line.starts_with(\"Commit: \"))\n .map(|line| line.trim_start_matches(\"Commit: \").trim().to_string())\n })\n .unwrap_or_default();\n\n // Get the original diff if we have a commit SHA\n let diff = if !commit_sha.is_empty() {\n let output = Command::new(\"git\")\n .args([\"show\", \"--format=\", \"--patch\", &commit_sha])\n .current_dir(root)\n .output();\n match output {\n Ok(o) if o.status.success() => String::from_utf8_lossy(&o.stdout).to_string(),\n _ => String::new(),\n }\n } else {\n String::new()\n };\n\n // Build the fix prompt\n let mut prompt = String::new();\n prompt.push_str(\"Fix the following code review issue.\\n\\n\");\n prompt.push_str(\"Issue: \");\n prompt.push_str(&item.title);\n prompt.push('\\n');\n if let Some(note) = &item.note {\n prompt.push_str(\"\\nDetails:\\n\");\n prompt.push_str(note);\n prompt.push('\\n');\n }\n if !diff.is_empty() {\n prompt.push_str(\"\\nOriginal diff:\\n```\\n\");\n // Truncate very large diffs\n let max_diff = 8000;\n if diff.len() > max_diff {\n prompt.push_str(&diff[..max_diff]);\n prompt.push_str(\"\\n... (truncated)\\n\");\n } else {\n prompt.push_str(&diff);\n }\n prompt.push_str(\"```\\n\");\n }\n prompt\n .push_str(\"\\nApply the minimal fix to resolve this issue. Only change what is necessary.\");\n\n let codex_bin = commit::configured_codex_bin_for_workdir(root);\n // Run codex with the same configured binary resolution as commit reviews.\n let status = Command::new(&codex_bin)\n .args([\"--approval-mode\", \"full-auto\", \"--quiet\", &prompt])\n .current_dir(root)\n .status();\n\n match status {\n Ok(s) if s.success() => {\n println!(\" ✓ Codex fix applied for {}\", short_id);\n // Mark todo as completed\n let (path, mut all_items) = todo::load_items_at_root(root)?;\n if let Ok(idx) = todo::find_item_index(&all_items, &item.id) {\n all_items[idx].status = \"completed\".to_string();\n all_items[idx].updated_at = Some(Utc::now().to_rfc3339());\n todo::save_items(&path, &all_items)?;\n }\n Ok(())\n }\n Ok(s) => {\n eprintln!(\n \" ✗ Codex exited with status {} for {}\",\n s.code().unwrap_or(-1),\n short_id\n );\n Ok(())\n }\n Err(e) => {\n eprintln!(\n \" ✗ Failed to run codex (bin: {}) for {}: {}\",\n codex_bin, short_id, e\n );\n Ok(())\n }\n }\n}\n" }, { "path": "src/rl_signals.rs", "content": "use std::fs::{self, OpenOptions};\nuse std::io::{BufWriter, Write};\nuse std::path::PathBuf;\nuse std::sync::OnceLock;\nuse std::sync::atomic::{AtomicU64, Ordering};\nuse std::sync::mpsc::{Receiver, SyncSender, sync_channel};\nuse std::thread;\nuse std::time::{SystemTime, UNIX_EPOCH};\n\nuse serde_json::{Map, Value, json};\nuse uuid::Uuid;\n\nuse crate::config;\nuse crate::secret_redact::redact_json_value;\n\nconst DEFAULT_SIGNAL_PATH: &str = \"out/logs/flow_rl_signals.jsonl\";\nconst DEFAULT_QUEUE_CAPACITY: usize = 8192;\n\nstruct SignalSink {\n enabled: bool,\n tx: Option<SyncSender<String>>,\n seq_mirror_enabled: bool,\n tx_seq: Option<SyncSender<String>>,\n dropped: AtomicU64,\n accepted: AtomicU64,\n dropped_seq: AtomicU64,\n accepted_seq: AtomicU64,\n}\n\nstatic SIGNAL_SINK: OnceLock<SignalSink> = OnceLock::new();\n\npub fn emit(mut payload: Value) {\n let sink = SIGNAL_SINK.get_or_init(SignalSink::from_env);\n if !sink.enabled {\n return;\n }\n\n if !payload.is_object() {\n payload = json!({ \"payload\": payload });\n }\n\n if let Value::Object(obj) = &mut payload {\n obj.entry(\"schema_version\".to_string())\n .or_insert_with(|| Value::String(\"flow_rl_event_v1\".to_string()));\n obj.entry(\"source\".to_string())\n .or_insert_with(|| Value::String(\"flow\".to_string()));\n obj.entry(\"ts_unix_ms\".to_string())\n .or_insert_with(|| Value::Number(now_unix_ms().into()));\n }\n\n redact_json_value(&mut payload);\n\n let Ok(line) = serde_json::to_string(&payload) else {\n return;\n };\n\n if let Some(tx) = sink.tx.as_ref() {\n if tx.try_send(line).is_ok() {\n sink.accepted.fetch_add(1, Ordering::Relaxed);\n } else {\n sink.dropped.fetch_add(1, Ordering::Relaxed);\n }\n }\n\n if sink.seq_mirror_enabled\n && let Some(seq_line) = payload_to_seq_router_row(&payload)\n && let Some(tx_seq) = sink.tx_seq.as_ref()\n {\n if tx_seq.try_send(seq_line).is_ok() {\n sink.accepted_seq.fetch_add(1, Ordering::Relaxed);\n } else {\n sink.dropped_seq.fetch_add(1, Ordering::Relaxed);\n }\n }\n}\n\npub fn stats() -> Value {\n let sink = SIGNAL_SINK.get_or_init(SignalSink::from_env);\n json!({\n \"enabled\": sink.enabled,\n \"accepted\": sink.accepted.load(Ordering::Relaxed),\n \"dropped\": sink.dropped.load(Ordering::Relaxed),\n \"path\": signal_path().display().to_string(),\n \"seq_mirror\": {\n \"enabled\": sink.seq_mirror_enabled,\n \"accepted\": sink.accepted_seq.load(Ordering::Relaxed),\n \"dropped\": sink.dropped_seq.load(Ordering::Relaxed),\n \"path\": seq_mirror_path().display().to_string(),\n }\n })\n}\n\nimpl SignalSink {\n fn from_env() -> Self {\n if !env_enabled() {\n return Self {\n enabled: false,\n tx: None,\n seq_mirror_enabled: false,\n tx_seq: None,\n dropped: AtomicU64::new(0),\n accepted: AtomicU64::new(0),\n dropped_seq: AtomicU64::new(0),\n accepted_seq: AtomicU64::new(0),\n };\n }\n\n let path = signal_path();\n if let Some(parent) = path.parent() {\n if fs::create_dir_all(parent).is_err() {\n return Self {\n enabled: false,\n tx: None,\n seq_mirror_enabled: false,\n tx_seq: None,\n dropped: AtomicU64::new(0),\n accepted: AtomicU64::new(0),\n dropped_seq: AtomicU64::new(0),\n accepted_seq: AtomicU64::new(0),\n };\n }\n }\n\n let cap = std::env::var(\"FLOW_RL_SIGNALS_QUEUE\")\n .ok()\n .and_then(|raw| raw.parse::<usize>().ok())\n .unwrap_or(DEFAULT_QUEUE_CAPACITY)\n .max(64);\n let (tx, rx) = sync_channel::<String>(cap);\n\n let flush_every = flush_every();\n thread::spawn(move || writer_loop(path, rx, flush_every));\n\n let mut seq_mirror_enabled = false;\n let mut tx_seq = None;\n if seq_mirror_enabled_from_env() {\n let seq_path = seq_mirror_path();\n if let Some(parent) = seq_path.parent() {\n if fs::create_dir_all(parent).is_ok() {\n let (seq_tx, seq_rx) = sync_channel::<String>(cap);\n thread::spawn(move || writer_loop(seq_path, seq_rx, flush_every));\n tx_seq = Some(seq_tx);\n seq_mirror_enabled = true;\n }\n }\n }\n\n Self {\n enabled: true,\n tx: Some(tx),\n seq_mirror_enabled,\n tx_seq,\n dropped: AtomicU64::new(0),\n accepted: AtomicU64::new(0),\n dropped_seq: AtomicU64::new(0),\n accepted_seq: AtomicU64::new(0),\n }\n }\n}\n\nfn env_enabled() -> bool {\n let raw = std::env::var(\"FLOW_RL_SIGNALS\").unwrap_or_else(|_| \"true\".to_string());\n matches!(\n raw.to_ascii_lowercase().as_str(),\n \"1\" | \"true\" | \"yes\" | \"on\"\n )\n}\n\nfn signal_path() -> PathBuf {\n std::env::var(\"FLOW_RL_SIGNALS_PATH\")\n .ok()\n .filter(|v| !v.trim().is_empty())\n .map(|v| expand_tilde_path(&v))\n .unwrap_or_else(|| PathBuf::from(DEFAULT_SIGNAL_PATH))\n}\n\nfn seq_mirror_enabled_from_env() -> bool {\n let raw = std::env::var(\"FLOW_RL_SIGNALS_SEQ_MIRROR\").unwrap_or_else(|_| \"true\".to_string());\n matches!(\n raw.to_ascii_lowercase().as_str(),\n \"1\" | \"true\" | \"yes\" | \"on\"\n )\n}\n\nfn seq_mirror_path() -> PathBuf {\n std::env::var(\"FLOW_RL_SIGNALS_SEQ_PATH\")\n .ok()\n .or_else(|| std::env::var(\"SEQ_CH_MEM_PATH\").ok())\n .filter(|v| !v.trim().is_empty())\n .map(|v| expand_tilde_path(&v))\n .unwrap_or_else(default_seq_mirror_path)\n}\n\nfn default_seq_mirror_path() -> PathBuf {\n config::global_state_dir().join(\"rl\").join(\"seq_mem.jsonl\")\n}\n\nfn expand_tilde_path(value: &str) -> PathBuf {\n if value == \"~\"\n && let Ok(home) = std::env::var(\"HOME\")\n {\n return PathBuf::from(home);\n }\n if let Some(suffix) = value.strip_prefix(\"~/\")\n && let Ok(home) = std::env::var(\"HOME\")\n {\n return PathBuf::from(home).join(suffix);\n }\n PathBuf::from(value)\n}\n\nfn writer_loop(path: PathBuf, rx: Receiver<String>, flush_every: usize) {\n let file = OpenOptions::new().create(true).append(true).open(&path);\n let Ok(file) = file else {\n return;\n };\n\n let mut writer = BufWriter::new(file);\n let mut pending = 0usize;\n let flush_every = flush_every.max(1);\n\n for line in rx {\n if writer.write_all(line.as_bytes()).is_err() {\n continue;\n }\n if writer.write_all(b\"\\n\").is_err() {\n continue;\n }\n pending += 1;\n if pending >= flush_every {\n let _ = writer.flush();\n pending = 0;\n }\n }\n\n let _ = writer.flush();\n}\n\nfn flush_every() -> usize {\n std::env::var(\"FLOW_RL_SIGNALS_FLUSH_EVERY\")\n .ok()\n .and_then(|raw| raw.trim().parse::<usize>().ok())\n .unwrap_or(1)\n .max(1)\n}\n\nfn now_unix_ms() -> u64 {\n match SystemTime::now().duration_since(UNIX_EPOCH) {\n Ok(dur) => dur.as_millis() as u64,\n Err(_) => 0,\n }\n}\n\nfn payload_to_seq_router_row(payload: &Value) -> Option<String> {\n let obj = payload.as_object()?;\n let event_type = obj.get(\"event_type\")?.as_str()?;\n if !event_type.starts_with(\"flow.router.\") {\n return None;\n }\n\n let ts_ms = obj\n .get(\"ts_unix_ms\")\n .and_then(Value::as_u64)\n .unwrap_or_else(now_unix_ms);\n let ok = obj.get(\"ok\").and_then(Value::as_bool).unwrap_or(true);\n let session_id = obj\n .get(\"session_id\")\n .and_then(Value::as_str)\n .unwrap_or(\"flow\")\n .to_string();\n let event_id = obj\n .get(\"event_id\")\n .and_then(Value::as_str)\n .map(ToString::to_string)\n .unwrap_or_else(|| format!(\"evt_{}\", Uuid::new_v4().simple()));\n\n let subject = obj\n .get(\"subject\")\n .cloned()\n .unwrap_or_else(|| Value::Object(Map::new()));\n let subject_json = serde_json::to_string(&subject).ok()?;\n let row = json!({\n \"ts_ms\": ts_ms,\n \"dur_us\": 0,\n \"ok\": ok,\n \"session_id\": session_id,\n \"event_id\": event_id,\n \"content_hash\": format!(\"flow-router-{}\", Uuid::new_v4().simple()),\n \"name\": event_type,\n \"subject\": subject_json,\n });\n serde_json::to_string(&row).ok()\n}\n\npub fn attrs_to_object(attrs: Vec<(String, String)>) -> Map<String, Value> {\n let mut out = Map::new();\n for (k, v) in attrs {\n if k.is_empty() {\n continue;\n }\n out.insert(k, Value::String(v));\n }\n out\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn router_event_maps_to_seq_row() {\n let payload = json!({\n \"event_type\": \"flow.router.decision.v1\",\n \"session_id\": \"sess-1\",\n \"ok\": true,\n \"ts_unix_ms\": 1700000000000u64,\n \"subject\": {\n \"decision_id\": \"dec-1\",\n \"chosen_task\": \"ai:flow/dev-check\",\n }\n });\n\n let line = payload_to_seq_router_row(&payload).expect(\"router event should map\");\n let parsed: Value = serde_json::from_str(&line).expect(\"json line\");\n assert_eq!(\n parsed.get(\"name\").and_then(Value::as_str),\n Some(\"flow.router.decision.v1\")\n );\n assert_eq!(\n parsed.get(\"session_id\").and_then(Value::as_str),\n Some(\"sess-1\")\n );\n assert_eq!(parsed.get(\"ok\").and_then(Value::as_bool), Some(true));\n assert_eq!(\n parsed.get(\"ts_ms\").and_then(Value::as_u64),\n Some(1700000000000u64)\n );\n assert!(\n parsed\n .get(\"subject\")\n .and_then(Value::as_str)\n .unwrap_or(\"\")\n .contains(\"\\\"decision_id\\\":\\\"dec-1\\\"\")\n );\n }\n\n #[test]\n fn non_router_event_not_mirrored() {\n let payload = json!({\n \"event_type\": \"everruns.run_started\",\n \"session_id\": \"sess-1\",\n });\n assert!(payload_to_seq_router_row(&payload).is_none());\n }\n}\n" }, { "path": "src/running.rs", "content": "use std::{\n collections::HashMap,\n path::{Path, PathBuf},\n time::{Duration, SystemTime, UNIX_EPOCH},\n};\n\nuse anyhow::{Context, Result};\nuse rusqlite::{Connection, params};\nuse serde::{Deserialize, Serialize};\n\n/// A process started by flow\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct RunningProcess {\n /// Process ID of the main task process\n pub pid: u32,\n /// Process group ID (for killing child processes)\n pub pgid: u32,\n /// Name of the task from flow.toml\n pub task_name: String,\n /// Full command that was executed\n pub command: String,\n /// Timestamp when the process was started (ms since epoch)\n pub started_at: u128,\n /// Canonical path to the flow.toml that defines this task\n pub config_path: PathBuf,\n /// Canonical path to the project root directory\n pub project_root: PathBuf,\n /// Whether flox environment was used\n pub used_flox: bool,\n /// Optional project name from flow.toml\n #[serde(default)]\n pub project_name: Option<String>,\n}\n\n/// All running processes tracked by flow\n#[derive(Debug, Clone, Default, Serialize, Deserialize)]\npub struct RunningProcesses {\n /// Map from project config path to list of running processes\n pub projects: HashMap<String, Vec<RunningProcess>>,\n}\n\n/// Returns ~/.config/flow/running.sqlite\npub fn running_processes_path() -> PathBuf {\n crate::config::global_state_dir().join(\"running.sqlite\")\n}\n\nfn open_running_db(path: &Path) -> Result<Connection> {\n if let Some(parent) = path.parent() {\n std::fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n\n let conn =\n Connection::open(path).with_context(|| format!(\"failed to open {}\", path.display()))?;\n conn.busy_timeout(Duration::from_secs(5))\n .context(\"failed to set running DB busy timeout\")?;\n conn.pragma_update(None, \"journal_mode\", \"WAL\")\n .context(\"failed to enable running DB WAL\")?;\n conn.pragma_update(None, \"synchronous\", \"NORMAL\")\n .context(\"failed to tune running DB sync mode\")?;\n conn.pragma_update(None, \"temp_store\", \"MEMORY\")\n .context(\"failed to tune running DB temp store\")?;\n conn.execute_batch(\n \"CREATE TABLE IF NOT EXISTS running_processes (\n pid INTEGER PRIMARY KEY,\n pgid INTEGER NOT NULL,\n task_name TEXT NOT NULL,\n command TEXT NOT NULL,\n started_at INTEGER NOT NULL,\n config_path TEXT NOT NULL,\n project_root TEXT NOT NULL,\n used_flox INTEGER NOT NULL,\n project_name TEXT\n );\n CREATE INDEX IF NOT EXISTS idx_running_processes_config_path\n ON running_processes(config_path);\n CREATE INDEX IF NOT EXISTS idx_running_processes_started_at\n ON running_processes(started_at);\",\n )\n .context(\"failed to initialize running-process schema\")?;\n Ok(conn)\n}\n\nfn read_processes(conn: &Connection, config_path: Option<&Path>) -> Result<Vec<RunningProcess>> {\n let mut processes = Vec::new();\n\n if let Some(config_path) = config_path {\n let config_path = config_path.to_string_lossy().to_string();\n let mut stmt = conn\n .prepare(\n \"SELECT pid, pgid, task_name, command, started_at, config_path, project_root,\n used_flox, project_name\n FROM running_processes\n WHERE config_path = ?1\n ORDER BY started_at ASC\",\n )\n .context(\"failed to prepare filtered running-process query\")?;\n let rows = stmt\n .query_map(params![config_path], row_to_running_process)\n .context(\"failed to query filtered running processes\")?;\n for row in rows {\n processes.push(row.context(\"failed to decode running process row\")?);\n }\n } else {\n let mut stmt = conn\n .prepare(\n \"SELECT pid, pgid, task_name, command, started_at, config_path, project_root,\n used_flox, project_name\n FROM running_processes\n ORDER BY started_at ASC\",\n )\n .context(\"failed to prepare running-process query\")?;\n let rows = stmt\n .query_map([], row_to_running_process)\n .context(\"failed to query running processes\")?;\n for row in rows {\n processes.push(row.context(\"failed to decode running process row\")?);\n }\n }\n\n Ok(processes)\n}\n\nfn row_to_running_process(row: &rusqlite::Row<'_>) -> rusqlite::Result<RunningProcess> {\n let started_at_raw: i64 = row.get(4)?;\n Ok(RunningProcess {\n pid: row.get(0)?,\n pgid: row.get(1)?,\n task_name: row.get(2)?,\n command: row.get(3)?,\n started_at: u128::try_from(started_at_raw.max(0)).unwrap_or(0),\n config_path: PathBuf::from(row.get::<_, String>(5)?),\n project_root: PathBuf::from(row.get::<_, String>(6)?),\n used_flox: row.get::<_, i64>(7)? != 0,\n project_name: row.get(8)?,\n })\n}\n\nfn remove_processes(conn: &mut Connection, pids: &[u32]) -> Result<()> {\n if pids.is_empty() {\n return Ok(());\n }\n\n let tx = conn\n .transaction()\n .context(\"failed to start running-process cleanup transaction\")?;\n {\n let mut stmt = tx\n .prepare(\"DELETE FROM running_processes WHERE pid = ?1\")\n .context(\"failed to prepare running-process cleanup statement\")?;\n for pid in pids {\n stmt.execute(params![pid])\n .with_context(|| format!(\"failed to delete stale running process {}\", pid))?;\n }\n }\n tx.commit()\n .context(\"failed to commit running-process cleanup transaction\")?;\n Ok(())\n}\n\nfn collect_alive_processes(\n conn: &mut Connection,\n config_path: Option<&Path>,\n) -> Result<Vec<RunningProcess>> {\n let rows = read_processes(conn, config_path)?;\n let mut alive = Vec::with_capacity(rows.len());\n let mut stale = Vec::new();\n\n for process in rows {\n if process_alive(process.pid) {\n alive.push(process);\n } else {\n stale.push(process.pid);\n }\n }\n\n remove_processes(conn, &stale)?;\n Ok(alive)\n}\n\nfn load_running_processes_at(path: &Path) -> Result<RunningProcesses> {\n let mut conn = open_running_db(path)?;\n let processes = collect_alive_processes(&mut conn, None)?;\n let mut grouped: HashMap<String, Vec<RunningProcess>> = HashMap::new();\n for process in processes {\n grouped\n .entry(process.config_path.display().to_string())\n .or_default()\n .push(process);\n }\n Ok(RunningProcesses { projects: grouped })\n}\n\nfn register_process_at(path: &Path, entry: RunningProcess) -> Result<()> {\n let mut conn = open_running_db(path)?;\n let tx = conn\n .transaction()\n .context(\"failed to start running-process register transaction\")?;\n tx.execute(\n \"INSERT INTO running_processes (\n pid, pgid, task_name, command, started_at, config_path, project_root,\n used_flox, project_name\n ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)\n ON CONFLICT(pid) DO UPDATE SET\n pgid = excluded.pgid,\n task_name = excluded.task_name,\n command = excluded.command,\n started_at = excluded.started_at,\n config_path = excluded.config_path,\n project_root = excluded.project_root,\n used_flox = excluded.used_flox,\n project_name = excluded.project_name\",\n params![\n entry.pid,\n entry.pgid,\n entry.task_name,\n entry.command,\n i64::try_from(entry.started_at).unwrap_or(i64::MAX),\n entry.config_path.display().to_string(),\n entry.project_root.display().to_string(),\n if entry.used_flox { 1i64 } else { 0i64 },\n entry.project_name,\n ],\n )\n .with_context(|| format!(\"failed to register running process {}\", entry.task_name))?;\n tx.commit()\n .context(\"failed to commit running-process register transaction\")?;\n Ok(())\n}\n\nfn unregister_process_at(path: &Path, pid: u32) -> Result<()> {\n let conn = open_running_db(path)?;\n conn.execute(\"DELETE FROM running_processes WHERE pid = ?1\", params![pid])\n .with_context(|| format!(\"failed to unregister running process {}\", pid))?;\n Ok(())\n}\n\nfn get_project_processes_at(path: &Path, config_path: &Path) -> Result<Vec<RunningProcess>> {\n let mut conn = open_running_db(path)?;\n collect_alive_processes(&mut conn, Some(config_path))\n}\n\n/// Load running processes, validating that PIDs are still alive.\npub fn load_running_processes() -> Result<RunningProcesses> {\n load_running_processes_at(&running_processes_path())\n}\n\n/// Register a new running process.\npub fn register_process(entry: RunningProcess) -> Result<()> {\n register_process_at(&running_processes_path(), entry)\n}\n\n/// Unregister a process by PID.\npub fn unregister_process(pid: u32) -> Result<()> {\n unregister_process_at(&running_processes_path(), pid)\n}\n\n/// Get processes for a specific project.\npub fn get_project_processes(config_path: &Path) -> Result<Vec<RunningProcess>> {\n get_project_processes_at(&running_processes_path(), config_path)\n}\n\n/// Check if a process is alive.\npub fn process_alive(pid: u32) -> bool {\n #[cfg(unix)]\n {\n let result = unsafe { libc::kill(pid as libc::pid_t, 0) };\n if result == 0 {\n return true;\n }\n matches!(\n std::io::Error::last_os_error().raw_os_error(),\n Some(libc::EPERM)\n )\n }\n #[cfg(windows)]\n {\n use std::process::Command;\n use std::process::Stdio;\n Command::new(\"tasklist\")\n .stdout(Stdio::piped())\n .stderr(Stdio::null())\n .output()\n .map(|o| {\n o.status.success() && String::from_utf8_lossy(&o.stdout).contains(&pid.to_string())\n })\n .unwrap_or(false)\n }\n}\n\n/// Get process group ID for a PID.\n#[cfg(unix)]\npub fn get_pgid(pid: u32) -> Option<u32> {\n let pgid = unsafe { libc::getpgid(pid as libc::pid_t) };\n if pgid < 0 { None } else { Some(pgid as u32) }\n}\n\n#[cfg(not(unix))]\npub fn get_pgid(pid: u32) -> Option<u32> {\n Some(pid)\n}\n\n/// Get current timestamp in milliseconds.\npub fn now_ms() -> u128 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|d| d.as_millis())\n .unwrap_or(0)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use tempfile::TempDir;\n\n fn sample_process(pid: u32, root: &Path) -> RunningProcess {\n RunningProcess {\n pid,\n pgid: get_pgid(std::process::id()).unwrap_or(pid),\n task_name: \"dev\".to_string(),\n command: \"cargo run\".to_string(),\n started_at: now_ms(),\n config_path: root.join(\"flow.toml\"),\n project_root: root.to_path_buf(),\n used_flox: false,\n project_name: Some(\"flow\".to_string()),\n }\n }\n\n #[test]\n fn register_load_and_unregister_round_trip() {\n let dir = TempDir::new().expect(\"tempdir\");\n let db_path = dir.path().join(\"running.sqlite\");\n let process = sample_process(std::process::id(), dir.path());\n\n register_process_at(&db_path, process.clone()).expect(\"register process\");\n let loaded = load_running_processes_at(&db_path).expect(\"load processes\");\n let key = process.config_path.display().to_string();\n let entries = loaded.projects.get(&key).expect(\"project entries\");\n assert_eq!(entries.len(), 1);\n assert_eq!(entries[0].pid, process.pid);\n\n let project_entries =\n get_project_processes_at(&db_path, &process.config_path).expect(\"project entries\");\n assert_eq!(project_entries.len(), 1);\n assert_eq!(project_entries[0].task_name, process.task_name);\n\n unregister_process_at(&db_path, process.pid).expect(\"unregister process\");\n let loaded = load_running_processes_at(&db_path).expect(\"reload processes\");\n assert!(loaded.projects.is_empty());\n }\n\n #[test]\n fn stale_processes_are_removed_on_read() {\n let dir = TempDir::new().expect(\"tempdir\");\n let db_path = dir.path().join(\"running.sqlite\");\n let process = sample_process(999_999, dir.path());\n\n register_process_at(&db_path, process.clone()).expect(\"register process\");\n let loaded = load_running_processes_at(&db_path).expect(\"load processes\");\n assert!(\n loaded.projects.is_empty(),\n \"stale process should be dropped\"\n );\n\n let project_entries =\n get_project_processes_at(&db_path, &process.config_path).expect(\"project entries\");\n assert!(\n project_entries.is_empty(),\n \"stale project process should be removed\"\n );\n }\n}\n" }, { "path": "src/screen.rs", "content": "use anyhow::{Context, Result};\nuse serde::Serialize;\nuse std::{\n fmt,\n sync::Arc,\n time::{Duration, SystemTime, UNIX_EPOCH},\n};\nuse tokio::{\n sync::{RwLock, broadcast},\n time,\n};\n\nuse crate::cli::ScreenOpts;\n\n#[derive(Clone)]\npub struct ScreenBroadcaster {\n sender: broadcast::Sender<ScreenFrame>,\n latest: Arc<RwLock<Option<ScreenFrame>>>,\n}\n\n#[derive(Debug, Clone, Serialize)]\npub struct ScreenFrame {\n pub frame_number: u64,\n pub captured_at_ms: u128,\n pub encoding: String,\n pub payload: String,\n}\n\nimpl fmt::Display for ScreenFrame {\n fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {\n write!(\n f,\n \"#{frame:<5} @ {ts}ms | {}\",\n self.payload,\n frame = self.frame_number,\n ts = self.captured_at_ms\n )\n }\n}\n\nimpl ScreenBroadcaster {\n pub fn with_mock_stream(buffer: usize, fps: u8) -> Self {\n let broadcaster = Self::new(buffer);\n broadcaster.spawn_mock_stream(fps);\n broadcaster\n }\n\n pub fn new(buffer: usize) -> Self {\n let (sender, _) = broadcast::channel(buffer);\n Self {\n sender,\n latest: Arc::new(RwLock::new(None)),\n }\n }\n\n pub fn subscribe(&self) -> broadcast::Receiver<ScreenFrame> {\n self.sender.subscribe()\n }\n\n pub async fn latest(&self) -> Option<ScreenFrame> {\n self.latest.read().await.clone()\n }\n\n fn spawn_mock_stream(&self, fps: u8) {\n let fps = fps.max(1);\n let period = Duration::from_millis((1000 / fps as u64).max(1));\n let mut frame_number = 0_u64;\n let handle = self.clone();\n\n tokio::spawn(async move {\n let mut ticker = time::interval(period);\n loop {\n ticker.tick().await;\n frame_number += 1;\n let payload = build_ascii_frame(frame_number);\n let frame = ScreenFrame {\n frame_number,\n captured_at_ms: current_epoch_ms(),\n encoding: \"text/mock\".to_string(),\n payload,\n };\n\n handle.publish(frame).await;\n }\n });\n }\n\n async fn publish(&self, frame: ScreenFrame) {\n {\n let mut guard = self.latest.write().await;\n *guard = Some(frame.clone());\n }\n\n // Ignore lagging consumers; they'll resubscribe and catch up.\n let _ = self.sender.send(frame);\n }\n}\n\npub async fn preview(opts: ScreenOpts) -> Result<()> {\n let generator = ScreenBroadcaster::with_mock_stream(opts.frame_buffer, opts.fps);\n let mut rx = generator.subscribe();\n\n for _ in 0..opts.frames {\n let frame = rx\n .recv()\n .await\n .context(\"screen preview channel closed unexpectedly\")?;\n\n println!(\"{frame}\");\n }\n\n Ok(())\n}\n\nfn current_epoch_ms() -> u128 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|dur| dur.as_millis())\n .unwrap_or(0)\n}\n\nfn build_ascii_frame(frame: u64) -> String {\n const WIDTH: usize = 32;\n const FILL: char = '#';\n const EMPTY: char = '.';\n\n let position = (frame as usize) % WIDTH;\n let mut line = String::with_capacity(WIDTH);\n for idx in 0..WIDTH {\n if idx == position {\n line.push(FILL);\n } else {\n line.push(EMPTY);\n }\n }\n\n line\n}\n" }, { "path": "src/sealer_crypto.rs", "content": "use anyhow::Result;\nuse bs58;\nuse crypto_secretbox::{\n XSalsa20Poly1305,\n aead::{Aead, KeyInit},\n};\nuse rand::{TryRng, rngs::SysRng};\nuse x25519_dalek::{PublicKey, StaticSecret};\n\nconst SECRET_PREFIX: &str = \"sealerSecret_z\";\nconst ID_PREFIX: &str = \"sealer_z\";\n\npub fn new_x25519_private_key() -> Vec<u8> {\n let mut bytes = [0u8; 32];\n SysRng\n .try_fill_bytes(&mut bytes)\n .expect(\"system RNG should provide x25519 key material\");\n bytes.to_vec()\n}\n\npub fn get_sealer_id(secret: &str) -> Result<String> {\n let secret_raw = secret\n .strip_prefix(SECRET_PREFIX)\n .ok_or_else(|| anyhow::anyhow!(\"invalid sealer secret prefix\"))?;\n let private_bytes = bs58::decode(secret_raw)\n .into_vec()\n .map_err(|e| anyhow::anyhow!(\"invalid base58 sealer secret: {e}\"))?;\n let bytes: [u8; 32] = private_bytes\n .as_slice()\n .try_into()\n .map_err(|_| anyhow::anyhow!(\"invalid sealer secret length\"))?;\n\n let public = PublicKey::from(&StaticSecret::from(bytes)).to_bytes();\n Ok(format!(\n \"{}{}\",\n ID_PREFIX,\n bs58::encode(public).into_string()\n ))\n}\n\npub fn seal(\n message: &[u8],\n sender_secret: &str,\n recipient_id: &str,\n nonce_material: &[u8],\n) -> Result<Vec<u8>> {\n let sender_secret = decode_secret(sender_secret)?;\n let recipient_public = decode_id(recipient_id)?;\n let sender_key = StaticSecret::from(sender_secret);\n let recipient_key = PublicKey::from(recipient_public);\n let shared_secret = sender_key.diffie_hellman(&recipient_key).to_bytes();\n let nonce = derive_nonce(nonce_material);\n let cipher = XSalsa20Poly1305::new(&shared_secret.into());\n let ciphertext = cipher\n .encrypt(&nonce.into(), message)\n .map_err(|_| anyhow::anyhow!(\"failed to seal message\"))?;\n Ok(ciphertext)\n}\n\npub fn unseal(\n sealed_message: &[u8],\n recipient_secret: &str,\n sender_id: &str,\n nonce_material: &[u8],\n) -> Result<Vec<u8>> {\n let recipient_secret = decode_secret(recipient_secret)?;\n let sender_public = decode_id(sender_id)?;\n let recipient_key = StaticSecret::from(recipient_secret);\n let sender_key = PublicKey::from(sender_public);\n let shared_secret = recipient_key.diffie_hellman(&sender_key).to_bytes();\n let nonce = derive_nonce(nonce_material);\n let cipher = XSalsa20Poly1305::new(&shared_secret.into());\n let plaintext = cipher\n .decrypt(&nonce.into(), sealed_message)\n .map_err(|_| anyhow::anyhow!(\"failed to unseal message\"))?;\n Ok(plaintext)\n}\n\nfn decode_secret(value: &str) -> Result<[u8; 32]> {\n let encoded = value\n .strip_prefix(SECRET_PREFIX)\n .ok_or_else(|| anyhow::anyhow!(\"invalid sealer secret prefix\"))?;\n let bytes = bs58::decode(encoded)\n .into_vec()\n .map_err(|e| anyhow::anyhow!(\"invalid base58 secret: {e}\"))?;\n bytes\n .as_slice()\n .try_into()\n .map_err(|_| anyhow::anyhow!(\"invalid secret key length\"))\n}\n\nfn decode_id(value: &str) -> Result<[u8; 32]> {\n let encoded = value\n .strip_prefix(ID_PREFIX)\n .ok_or_else(|| anyhow::anyhow!(\"invalid sealer id prefix\"))?;\n let bytes = bs58::decode(encoded)\n .into_vec()\n .map_err(|e| anyhow::anyhow!(\"invalid base58 id: {e}\"))?;\n bytes\n .as_slice()\n .try_into()\n .map_err(|_| anyhow::anyhow!(\"invalid public key length\"))\n}\n\nfn derive_nonce(nonce_material: &[u8]) -> [u8; 24] {\n let hash = blake3::hash(nonce_material);\n let mut nonce = [0u8; 24];\n nonce.copy_from_slice(&hash.as_bytes()[..24]);\n nonce\n}\n" }, { "path": "src/secret_redact.rs", "content": "use std::collections::HashSet;\nuse std::sync::OnceLock;\n\nuse regex::{Captures, Regex};\nuse serde_json::Value;\n\nconst REDACTED: &str = \"[REDACTED]\";\n\npub fn redact_text(input: &str) -> String {\n if input.is_empty() {\n return String::new();\n }\n\n let mut text = input.to_string();\n\n text = url_credentials_regex()\n .replace_all(&text, |caps: &Captures| {\n let prefix = caps.name(\"prefix\").map(|m| m.as_str()).unwrap_or_default();\n format!(\"{prefix}{REDACTED}@\")\n })\n .to_string();\n\n text = bearer_regex()\n .replace_all(&text, |caps: &Captures| {\n let prefix = caps.name(\"prefix\").map(|m| m.as_str()).unwrap_or_default();\n format!(\"{prefix}{REDACTED}\")\n })\n .to_string();\n\n text = quoted_assignment_regex()\n .replace_all(&text, |caps: &Captures| {\n let full = caps.get(0).map(|m| m.as_str()).unwrap_or_default();\n let key = caps.name(\"key\").map(|m| m.as_str()).unwrap_or_default();\n if !is_sensitive_key(key) {\n return full.to_string();\n }\n let value = caps.name(\"value\").map(|m| m.as_str()).unwrap_or_default();\n if should_keep_assignment_value(value) {\n return full.to_string();\n }\n let prefix = caps.name(\"prefix\").map(|m| m.as_str()).unwrap_or_default();\n let suffix = caps.name(\"suffix\").map(|m| m.as_str()).unwrap_or_default();\n format!(\"{prefix}{REDACTED}{suffix}\")\n })\n .to_string();\n\n text = unquoted_assignment_regex()\n .replace_all(&text, |caps: &Captures| {\n let full = caps.get(0).map(|m| m.as_str()).unwrap_or_default();\n let key = caps.name(\"key\").map(|m| m.as_str()).unwrap_or_default();\n if !is_sensitive_key(key) {\n return full.to_string();\n }\n let value = caps.name(\"value\").map(|m| m.as_str()).unwrap_or_default();\n if should_keep_assignment_value(value) {\n return full.to_string();\n }\n let prefix = caps.name(\"prefix\").map(|m| m.as_str()).unwrap_or_default();\n format!(\"{prefix}{REDACTED}\")\n })\n .to_string();\n\n text = known_token_regex().replace_all(&text, REDACTED).to_string();\n\n text = generic_token_regex()\n .replace_all(&text, |caps: &Captures| {\n let token = caps.name(\"token\").map(|m| m.as_str()).unwrap_or_default();\n if looks_like_secretish_token(token) {\n REDACTED.to_string()\n } else {\n token.to_string()\n }\n })\n .to_string();\n\n text\n}\n\npub fn redact_json_value(value: &mut Value) {\n match value {\n Value::String(s) => {\n *s = redact_text(s);\n }\n Value::Array(items) => {\n for item in items {\n redact_json_value(item);\n }\n }\n Value::Object(map) => {\n for (key, item) in map.iter_mut() {\n if is_sensitive_key(key) {\n if let Value::String(_) = item {\n *item = Value::String(REDACTED.to_string());\n continue;\n }\n }\n redact_json_value(item);\n }\n }\n _ => {}\n }\n}\n\nfn should_keep_assignment_value(value: &str) -> bool {\n let trimmed = value.trim().trim_matches('\"').trim_matches('\\'');\n if trimmed.is_empty() {\n return true;\n }\n if trimmed == REDACTED {\n return true;\n }\n let lower = trimmed.to_ascii_lowercase();\n if matches!(\n lower.as_str(),\n \"true\" | \"false\" | \"null\" | \"none\" | \"undefined\"\n ) {\n return true;\n }\n trimmed.starts_with('$') || trimmed.starts_with(\"${\") || trimmed.starts_with(\"$(\")\n}\n\nfn looks_like_secretish_token(token: &str) -> bool {\n if token.len() < 28 || token.len() > 256 {\n return false;\n }\n if token.chars().all(|c| c.is_ascii_hexdigit()) {\n return false;\n }\n\n let has_alpha = token.chars().any(|c| c.is_ascii_alphabetic());\n let has_digit = token.chars().any(|c| c.is_ascii_digit());\n if !has_alpha || !has_digit {\n return false;\n }\n\n let has_upper = token.chars().any(|c| c.is_ascii_uppercase());\n let has_symbol = token.contains('-') || token.contains('_');\n if !has_upper && !has_symbol {\n return false;\n }\n\n let mut unique = HashSet::new();\n for ch in token.chars() {\n unique.insert(ch);\n }\n if unique.len() < 8 {\n return false;\n }\n\n shannon_entropy(token) >= 3.6\n}\n\nfn is_sensitive_key(raw_key: &str) -> bool {\n if raw_key.is_empty() {\n return false;\n }\n let key = raw_key.to_ascii_lowercase();\n if key == \"authorization\" || key == \"x-api-key\" {\n return true;\n }\n let needles = [\n \"token\",\n \"secret\",\n \"password\",\n \"passwd\",\n \"pwd\",\n \"api_key\",\n \"apikey\",\n \"private_key\",\n \"private-key\",\n \"client_secret\",\n \"client-secret\",\n \"bearer\",\n ];\n needles.iter().any(|needle| key.contains(needle))\n}\n\nfn shannon_entropy(input: &str) -> f64 {\n if input.is_empty() {\n return 0.0;\n }\n let mut counts = [0usize; 256];\n for byte in input.bytes() {\n counts[usize::from(byte)] += 1;\n }\n let len = input.len() as f64;\n let mut entropy = 0.0f64;\n for count in counts {\n if count == 0 {\n continue;\n }\n let p = count as f64 / len;\n entropy -= p * p.log2();\n }\n entropy\n}\n\nfn url_credentials_regex() -> &'static Regex {\n static RE: OnceLock<Regex> = OnceLock::new();\n RE.get_or_init(|| {\n Regex::new(r\"(?i)(?P<prefix>https?://)(?P<creds>[^\\s/@:]+:[^\\s/@]+)@\")\n .expect(\"valid url credentials regex\")\n })\n}\n\nfn bearer_regex() -> &'static Regex {\n static RE: OnceLock<Regex> = OnceLock::new();\n RE.get_or_init(|| {\n Regex::new(r\"(?i)(?P<prefix>\\bbearer\\s+)(?P<token>[A-Za-z0-9._~+/=-]{12,})\")\n .expect(\"valid bearer regex\")\n })\n}\n\nfn quoted_assignment_regex() -> &'static Regex {\n static RE: OnceLock<Regex> = OnceLock::new();\n RE.get_or_init(|| {\n Regex::new(\n r#\"(?i)(?P<prefix>[\"']?(?P<key>[A-Za-z_][A-Za-z0-9_-]{0,127})[\"']?\\s*[:=]\\s*[\"'])(?P<value>[^\"'\\\\n]{4,})(?P<suffix>[\"'])\"#,\n )\n .expect(\"valid quoted assignment regex\")\n })\n}\n\nfn unquoted_assignment_regex() -> &'static Regex {\n static RE: OnceLock<Regex> = OnceLock::new();\n RE.get_or_init(|| {\n Regex::new(\n r#\"(?i)(?P<prefix>[\"']?(?P<key>[A-Za-z_][A-Za-z0-9_-]{0,127})[\"']?\\s*[:=]\\s*)(?P<value>(?:bearer\\s+)?[^\\s,;'\"\\}\\]]+)\"#,\n )\n .expect(\"valid unquoted assignment regex\")\n })\n}\n\nfn known_token_regex() -> &'static Regex {\n static RE: OnceLock<Regex> = OnceLock::new();\n RE.get_or_init(|| {\n Regex::new(\n r\"(?i)\\b(?:ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{20,}|xox[baprs]-[A-Za-z0-9-]{20,}|AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9]{20,}|CFPAT-[A-Za-z0-9_-]{20,})\\b\",\n )\n .expect(\"valid known token regex\")\n })\n}\n\nfn generic_token_regex() -> &'static Regex {\n static RE: OnceLock<Regex> = OnceLock::new();\n RE.get_or_init(|| {\n Regex::new(r\"\\b(?P<token>[A-Za-z0-9][A-Za-z0-9_-]{27,})\\b\")\n .expect(\"valid generic token regex\")\n })\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use serde_json::json;\n\n fn test_token() -> String {\n [\"abcDEF0123\", \"456789TOKEN\"].concat()\n }\n\n #[test]\n fn redacts_bearer_and_assignments() {\n let token = test_token();\n let input = format!(\"Authorization: Bearer {token}\\nCLOUDFLARE_API_TOKEN={token}-foo\");\n let redacted = redact_text(&input);\n assert!(redacted.contains(\"[REDACTED]\"));\n assert!(redacted.contains(\"CLOUDFLARE_API_TOKEN=\"));\n assert!(!redacted.contains(&token));\n }\n\n #[test]\n fn redacts_url_credentials() {\n let input = \"https://user:supersecret@example.com/path\";\n let redacted = redact_text(input);\n assert_eq!(redacted, \"https://[REDACTED]@example.com/path\");\n }\n\n #[test]\n fn redacts_json_values_recursively() {\n let token = test_token();\n let mut value = json!({\n \"headers\": {\"Authorization\": format!(\"Bearer {token}\")},\n \"nested\": [{\"token\": format!(\"{token}-foo\")}]\n });\n redact_json_value(&mut value);\n let text = value.to_string();\n assert!(text.contains(\"[REDACTED]\"));\n assert!(!text.contains(&token));\n }\n}\n" }, { "path": "src/secrets.rs", "content": "use std::{\n collections::HashMap,\n env, fs,\n path::{Path, PathBuf},\n};\n\nuse anyhow::{Context, Result, bail};\nuse reqwest::blocking::Client;\n\nuse crate::{\n cli::{SecretsAction, SecretsCommand, SecretsFormat, SecretsListOpts, SecretsPullOpts},\n config::{self, Config, StorageConfig, StorageEnvConfig},\n};\n\npub fn run(cmd: SecretsCommand) -> Result<()> {\n match cmd.action {\n SecretsAction::List(opts) => list(opts),\n SecretsAction::Pull(opts) => pull(opts),\n }\n}\n\nfn list(opts: SecretsListOpts) -> Result<()> {\n let (config_path, cfg) = load_config(opts.config)?;\n let secrets = cfg.storage.ok_or_else(|| {\n anyhow::anyhow!(\"no [storage] block defined in {}\", config_path.display())\n })?;\n\n if secrets.envs.is_empty() {\n println!(\n \"No secret environments defined in {}\",\n config_path.display()\n );\n return Ok(());\n }\n\n println!(\n \"Environments defined in {} (provider: {}):\",\n config_path.display(),\n secrets.provider\n );\n for env_cfg in &secrets.envs {\n println!(\"\\n- {}\", env_cfg.name);\n if let Some(desc) = &env_cfg.description {\n println!(\" Description: {}\", desc);\n }\n if env_cfg.variables.is_empty() {\n println!(\" Variables: (unspecified)\");\n } else {\n let summary: Vec<String> = env_cfg\n .variables\n .iter()\n .map(|var| match &var.default {\n Some(default) if !default.is_empty() => {\n format!(\"{} (default: {})\", var.key, default)\n }\n Some(_) => format!(\"{} (default: empty)\", var.key),\n None => var.key.clone(),\n })\n .collect();\n println!(\" Variables: {}\", summary.join(\", \"));\n }\n }\n\n Ok(())\n}\n\nfn pull(opts: SecretsPullOpts) -> Result<()> {\n let (config_path, cfg) = load_config(opts.config)?;\n let secrets = cfg.storage.ok_or_else(|| {\n anyhow::anyhow!(\"no [storage] block defined in {}\", config_path.display())\n })?;\n\n let env_cfg = secrets\n .envs\n .iter()\n .find(|env| env.name == opts.env)\n .ok_or_else(|| {\n anyhow::anyhow!(\n \"unknown storage environment '{}' (available: {})\",\n opts.env,\n secrets\n .envs\n .iter()\n .map(|env| env.name.as_str())\n .collect::<Vec<_>>()\n .join(\", \")\n )\n })?;\n\n let values = fetch_remote_secrets(&secrets, env_cfg, opts.hub.clone())?;\n let ordered = order_variables(env_cfg, &values);\n let rendered = render_secrets(&ordered, opts.format);\n\n if let Some(path) = opts.output {\n write_output(&path, &rendered)?;\n println!(\"Saved {} secrets to {}\", env_cfg.name, path.display());\n } else {\n println!(\"{}\", rendered);\n }\n\n Ok(())\n}\n\nfn fetch_remote_secrets(\n cfg: &StorageConfig,\n env_cfg: &StorageEnvConfig,\n hub_override: Option<String>,\n) -> Result<HashMap<String, String>> {\n let api_key = env::var(&cfg.env_var).with_context(|| {\n format!(\n \"environment variable {} is not set; required to authenticate with secrets provider\",\n cfg.env_var\n )\n })?;\n\n let base_url = hub_override\n .or_else(|| Some(cfg.hub_url.clone()))\n .unwrap_or_else(|| \"https://myflow.sh\".to_string());\n let base = base_url.trim_end_matches('/');\n let url = format!(\"{}/api/secrets/{}/{}\", base, cfg.provider, env_cfg.name);\n\n let client = Client::builder()\n .build()\n .context(\"failed to build HTTP client\")?;\n let response = client\n .get(url)\n .bearer_auth(api_key)\n .send()\n .with_context(|| \"failed to call storage hub\")?\n .error_for_status()\n .with_context(|| \"storage hub returned an error response\")?;\n\n let mut body: HashMap<String, String> = response\n .json()\n .with_context(|| \"failed to parse storage hub response\")?;\n\n for var in &env_cfg.variables {\n if body.contains_key(&var.key) {\n continue;\n }\n\n if let Some(default) = &var.default {\n body.insert(var.key.clone(), default.clone());\n } else {\n bail!(\n \"storage hub response missing required variable '{}' for environment '{}'\",\n var.key,\n env_cfg.name\n );\n }\n }\n\n Ok(body)\n}\n\nfn order_variables(\n env_cfg: &StorageEnvConfig,\n values: &HashMap<String, String>,\n) -> Vec<(String, String)> {\n let mut ordered = Vec::new();\n for var in &env_cfg.variables {\n if let Some(value) = values.get(&var.key) {\n ordered.push((var.key.clone(), value.clone()));\n }\n }\n for (key, value) in values {\n if env_cfg.variables.iter().any(|v| v.key == *key) {\n continue;\n }\n ordered.push((key.clone(), value.clone()));\n }\n ordered\n}\n\nfn render_secrets(vars: &[(String, String)], format: SecretsFormat) -> String {\n match format {\n SecretsFormat::Shell => vars\n .iter()\n .map(|(k, v)| format!(\"export {}={}\", k, shell_quote(v)))\n .collect::<Vec<_>>()\n .join(\"\\n\"),\n SecretsFormat::Dotenv => vars\n .iter()\n .map(|(k, v)| format!(\"{}={}\", k, dotenv_quote(v)))\n .collect::<Vec<_>>()\n .join(\"\\n\"),\n }\n}\n\nfn shell_quote(value: &str) -> String {\n if value.is_empty() {\n \"''\".to_string()\n } else if value\n .chars()\n .all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | '.' | '/'))\n {\n value.to_string()\n } else {\n let escaped = value.replace('\\'', \"'\\\\''\");\n format!(\"'{}'\", escaped)\n }\n}\n\nfn dotenv_quote(value: &str) -> String {\n if value\n .bytes()\n .all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'z' | b'A'..=b'Z' | b'_' | b'.' | b'-' | b'/'))\n {\n value.to_string()\n } else {\n format!(\"\\\"{}\\\"\", value.replace('\\\\', \"\\\\\\\\\").replace('\"', \"\\\\\\\"\"))\n }\n}\n\nfn write_output(path: &Path, contents: &str) -> Result<()> {\n if let Some(parent) = path.parent() {\n if !parent.as_os_str().is_empty() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create directory {}\", parent.display()))?;\n }\n }\n fs::write(path, contents.as_bytes())\n .with_context(|| format!(\"failed to write secrets to {}\", path.display()))?;\n Ok(())\n}\n\nfn load_config(path: PathBuf) -> Result<(PathBuf, Config)> {\n let config_path = resolve_path(path)?;\n let cfg = config::load(&config_path).with_context(|| {\n format!(\n \"failed to load configuration from {}\",\n config_path.display()\n )\n })?;\n Ok((config_path, cfg))\n}\n\nfn resolve_path(path: PathBuf) -> Result<PathBuf> {\n if path.is_absolute() {\n Ok(path)\n } else {\n Ok(env::current_dir()?.join(path))\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use mockito::Server;\n use std::path::PathBuf;\n\n fn fixture_path(relative: &str) -> PathBuf {\n PathBuf::from(env!(\"CARGO_MANIFEST_DIR\")).join(relative)\n }\n\n struct EnvVarGuard {\n key: String,\n previous: Option<String>,\n }\n\n impl EnvVarGuard {\n fn set(key: &str, value: &str) -> Self {\n let previous = env::var(key).ok();\n unsafe {\n env::set_var(key, value);\n }\n Self {\n key: key.to_string(),\n previous,\n }\n }\n }\n\n impl Drop for EnvVarGuard {\n fn drop(&mut self) {\n if let Some(value) = &self.previous {\n unsafe {\n env::set_var(&self.key, value);\n }\n } else {\n unsafe {\n env::remove_var(&self.key);\n }\n }\n }\n }\n\n #[test]\n fn project_config_fixture_is_loadable_and_fetches_mocked_secrets() {\n let cfg = config::load(fixture_path(\"test-data/project-config/flow.toml\"))\n .expect(\"project config fixture should parse\");\n\n assert_eq!(cfg.tasks.len(), 3, \"fixture defines three tasks\");\n let commit = cfg\n .tasks\n .iter()\n .find(|task| task.name == \"commit\")\n .expect(\"commit task should exist\");\n assert_eq!(\n commit.dependencies,\n [\"github.com/nikivdev/fast\"],\n \"commit task should depend on fast\"\n );\n\n let storage = cfg\n .storage\n .clone()\n .expect(\"fixture should define a storage provider\");\n assert_eq!(storage.provider, \"myflow.sh\");\n let env_cfg = storage\n .envs\n .iter()\n .find(|env| env.name == \"local\")\n .expect(\"local storage env should exist\");\n\n let _guard = EnvVarGuard::set(&storage.env_var, \"test-token\");\n\n let mut server = Server::new();\n let endpoint = format!(\"/api/secrets/{}/{}\", storage.provider, env_cfg.name);\n let mock = server\n .mock(\"GET\", endpoint.as_str())\n .match_header(\"authorization\", \"Bearer test-token\")\n .with_status(200)\n .with_header(\"content-type\", \"application/json\")\n .with_body(\n r#\"{\n \"DATABASE_URL\": \"postgres://localhost/flow\"\n }\"#,\n )\n .create();\n\n let values =\n fetch_remote_secrets(&storage, env_cfg, Some(server.url())).expect(\"mock fetch works\");\n mock.assert();\n\n assert_eq!(\n values.get(\"DATABASE_URL\").map(String::as_str),\n Some(\"postgres://localhost/flow\")\n );\n assert_eq!(values.get(\"OPENAI_API_KEY\").map(String::as_str), Some(\"\"));\n }\n}\n" }, { "path": "src/seq_client.rs", "content": "use std::io::{BufRead, BufReader, Write};\nuse std::path::Path;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result, bail};\nuse serde::{Deserialize, Serialize};\nuse serde_json::Value;\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct RpcRequest {\n pub op: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub args: Option<Value>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub request_id: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub run_id: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub tool_call_id: Option<String>,\n}\n\nimpl RpcRequest {\n pub fn new(op: impl Into<String>) -> Self {\n Self {\n op: op.into(),\n args: None,\n request_id: None,\n run_id: None,\n tool_call_id: None,\n }\n }\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct RpcResponse {\n pub ok: bool,\n pub op: String,\n #[serde(default)]\n pub request_id: String,\n #[serde(default)]\n pub run_id: String,\n #[serde(default)]\n pub tool_call_id: String,\n #[serde(default)]\n pub ts_ms: u64,\n #[serde(default)]\n pub dur_us: u64,\n #[serde(default)]\n pub result: Option<Value>,\n #[serde(default)]\n pub error: Option<String>,\n}\n\n#[cfg(unix)]\npub struct SeqClient {\n reader: BufReader<std::os::unix::net::UnixStream>,\n read_buf: Vec<u8>,\n}\n\n#[cfg(unix)]\nimpl SeqClient {\n pub fn connect_with_timeout(socket_path: impl AsRef<Path>, timeout: Duration) -> Result<Self> {\n let path = socket_path.as_ref();\n let stream = std::os::unix::net::UnixStream::connect(path)\n .with_context(|| format!(\"failed to connect to seqd socket {}\", path.display()))?;\n stream\n .set_read_timeout(Some(timeout))\n .context(\"failed to set seqd socket read timeout\")?;\n stream\n .set_write_timeout(Some(timeout))\n .context(\"failed to set seqd socket write timeout\")?;\n Ok(Self {\n reader: BufReader::new(stream),\n read_buf: Vec::with_capacity(1024),\n })\n }\n\n pub fn call(&mut self, req: &RpcRequest) -> Result<RpcResponse> {\n let mut encoded = serde_json::to_vec(req).context(\"failed to encode seqd rpc request\")?;\n encoded.push(b'\\n');\n let stream = self.reader.get_mut();\n stream\n .write_all(&encoded)\n .context(\"failed to write seqd rpc request\")?;\n stream.flush().context(\"failed to flush seqd rpc request\")?;\n\n self.read_buf.clear();\n self.reader\n .read_until(b'\\n', &mut self.read_buf)\n .context(\"failed to read seqd rpc response\")?;\n\n if self.read_buf.last() == Some(&b'\\n') {\n self.read_buf.pop();\n }\n\n if self.read_buf.is_empty() {\n bail!(\"empty response from seqd\");\n }\n if self.read_buf.len() > 1_000_000 {\n bail!(\"seqd rpc response exceeded 1MB line limit\");\n }\n\n let resp: RpcResponse = crate::json_parse::parse_json_bytes_in_place(&mut self.read_buf)\n .context(\"failed to decode seqd rpc response json\")?;\n Ok(resp)\n }\n}\n\n#[cfg(not(unix))]\npub struct SeqClient;\n\n#[cfg(not(unix))]\nimpl SeqClient {\n pub fn connect_with_timeout(\n _socket_path: impl AsRef<Path>,\n _timeout: Duration,\n ) -> Result<Self> {\n bail!(\"seq client is only supported on unix platforms\")\n }\n\n pub fn call(&mut self, _req: &RpcRequest) -> Result<RpcResponse> {\n bail!(\"seq client is only supported on unix platforms\")\n }\n}\n\n#[cfg(test)]\n#[cfg(unix)]\nmod tests {\n use super::*;\n use std::io::Read;\n use std::os::unix::net::UnixListener;\n use std::thread;\n use tempfile::tempdir;\n\n #[test]\n fn rpc_roundtrip_line_delimited() -> Result<()> {\n let dir = tempdir()?;\n let socket_path = dir.path().join(\"seqd.sock\");\n let listener = UnixListener::bind(&socket_path)?;\n\n let server = thread::spawn(move || -> Result<()> {\n let (mut stream, _) = listener.accept()?;\n let mut got = Vec::new();\n let mut byte = [0u8; 1];\n loop {\n let n = stream.read(&mut byte)?;\n if n == 0 || byte[0] == b'\\n' {\n break;\n }\n got.push(byte[0]);\n }\n let req_text = String::from_utf8(got).context(\"req not utf8\")?;\n let req: RpcRequest = serde_json::from_str(&req_text).context(\"req not json\")?;\n if req.op != \"ping\" {\n bail!(\"unexpected op\");\n }\n\n let reply = serde_json::json!({\n \"ok\": true,\n \"op\": \"ping\",\n \"request_id\": req.request_id.unwrap_or_default(),\n \"run_id\": req.run_id.unwrap_or_default(),\n \"tool_call_id\": req.tool_call_id.unwrap_or_default(),\n \"ts_ms\": 1,\n \"dur_us\": 2,\n \"result\": {\"pong\": true}\n })\n .to_string();\n stream.write_all(reply.as_bytes())?;\n stream.write_all(b\"\\n\")?;\n Ok(())\n });\n\n let mut client = SeqClient::connect_with_timeout(&socket_path, Duration::from_secs(2))?;\n let mut req = RpcRequest::new(\"ping\");\n req.request_id = Some(\"abc\".to_string());\n let resp = client.call(&req)?;\n assert!(resp.ok);\n assert_eq!(resp.op, \"ping\");\n assert_eq!(resp.request_id, \"abc\");\n server.join().expect(\"server thread panicked\")?;\n Ok(())\n }\n}\n" }, { "path": "src/seq_rpc.rs", "content": "use std::path::PathBuf;\nuse std::time::Duration;\n\nuse anyhow::{Context, Result, bail};\nuse serde_json::{Value, json};\n\nuse crate::cli::{\n SeqRpcAction, SeqRpcCommand, SeqRpcIdOpts, SeqRpcOpenAppOpts, SeqRpcRawOpts,\n SeqRpcScreenshotOpts,\n};\nuse crate::seq_client::{RpcRequest, SeqClient};\n\npub fn run(cmd: SeqRpcCommand) -> Result<()> {\n let socket = resolve_socket_path(cmd.socket);\n let timeout = Duration::from_millis(cmd.timeout_ms.max(1));\n let mut client = SeqClient::connect_with_timeout(&socket, timeout)\n .with_context(|| format!(\"failed to connect to seqd at {}\", socket.display()))?;\n let req = build_request(cmd.action)?;\n let resp = client.call(&req)?;\n\n if cmd.pretty {\n println!(\"{}\", serde_json::to_string_pretty(&resp)?);\n } else {\n println!(\"{}\", serde_json::to_string(&resp)?);\n }\n\n if resp.ok {\n Ok(())\n } else {\n bail!(\n \"seqd rpc op '{}' failed: {}\",\n resp.op,\n resp.error.unwrap_or_else(|| \"unknown error\".to_string())\n )\n }\n}\n\nfn resolve_socket_path(cli_socket: Option<PathBuf>) -> PathBuf {\n if let Some(path) = cli_socket {\n return path;\n }\n if let Ok(value) = std::env::var(\"SEQ_SOCKET_PATH\")\n && !value.trim().is_empty()\n {\n return PathBuf::from(value);\n }\n if let Ok(value) = std::env::var(\"SEQD_SOCKET\")\n && !value.trim().is_empty()\n {\n return PathBuf::from(value);\n }\n PathBuf::from(\"/tmp/seqd.sock\")\n}\n\nfn build_request(action: SeqRpcAction) -> Result<RpcRequest> {\n match action {\n SeqRpcAction::Ping(ids) => Ok(with_ids(RpcRequest::new(\"ping\"), ids)),\n SeqRpcAction::AppState(ids) => Ok(with_ids(RpcRequest::new(\"app_state\"), ids)),\n SeqRpcAction::Perf(ids) => Ok(with_ids(RpcRequest::new(\"perf\"), ids)),\n SeqRpcAction::OpenApp(opts) => Ok(build_open_app(\"open_app\", opts)),\n SeqRpcAction::OpenAppToggle(opts) => Ok(build_open_app(\"open_app_toggle\", opts)),\n SeqRpcAction::Screenshot(opts) => Ok(build_screenshot(opts)),\n SeqRpcAction::Rpc(opts) => build_raw(opts),\n }\n}\n\nfn build_open_app(op: &str, opts: SeqRpcOpenAppOpts) -> RpcRequest {\n let mut req = with_ids(RpcRequest::new(op), opts.ids);\n req.args = Some(json!({ \"name\": opts.name }));\n req\n}\n\nfn build_screenshot(opts: SeqRpcScreenshotOpts) -> RpcRequest {\n let mut req = with_ids(RpcRequest::new(\"screenshot\"), opts.ids);\n req.args = Some(json!({ \"path\": opts.path }));\n req\n}\n\nfn build_raw(opts: SeqRpcRawOpts) -> Result<RpcRequest> {\n let mut req = with_ids(RpcRequest::new(opts.op), opts.ids);\n if let Some(args_json) = opts.args_json {\n let parsed: Value = serde_json::from_str(&args_json)\n .with_context(|| format!(\"failed to parse --args-json as JSON: {}\", args_json))?;\n req.args = Some(parsed);\n }\n Ok(req)\n}\n\nfn with_ids(mut req: RpcRequest, ids: SeqRpcIdOpts) -> RpcRequest {\n req.request_id = ids.request_id;\n req.run_id = ids.run_id;\n req.tool_call_id = ids.tool_call_id;\n req\n}\n" }, { "path": "src/server.rs", "content": "use std::{\n collections::HashMap,\n convert::Infallible,\n net::SocketAddr,\n path::Path,\n pin::Pin,\n sync::{Arc, mpsc as std_mpsc},\n time::Duration,\n};\n\nuse anyhow::{Context, Result};\nuse axum::{\n Router,\n extract::{Json as AxumJson, Path as AxumPath, Query, State},\n http::{Method, StatusCode},\n response::{\n IntoResponse, Json,\n sse::{Event, KeepAlive, Sse},\n },\n routing::{get, post},\n};\nuse futures::{Stream, StreamExt};\nuse notify::RecursiveMode;\nuse notify_debouncer_mini::new_debouncer;\nuse serde::{Deserialize, Serialize};\nuse serde_json::json;\nuse tokio::sync::{RwLock, mpsc};\nuse tokio_stream::wrappers::BroadcastStream;\nuse tower_http::cors::{Any, CorsLayer};\n\nuse crate::{\n ai,\n cli::DaemonOpts,\n config::{self, Config, ServerConfig},\n daemon_snapshot,\n log_store::{self, LogEntry, LogQuery},\n running,\n screen::ScreenBroadcaster,\n servers::{LogLine, ManagedServer, ServerSnapshot},\n skills,\n supervisor,\n terminal,\n};\n\nconst LOG_BUFFER_CAPACITY: usize = 2048;\n\ntype ServerStore = Arc<RwLock<HashMap<String, Arc<ManagedServer>>>>;\n\n/// Unified process snapshot returned by GET /processes.\n#[derive(Debug, Clone, Serialize, Deserialize)]\nstruct ProcessSnapshot {\n name: String,\n source: String,\n project: Option<String>,\n command: String,\n status: String,\n pid: Option<u32>,\n port: Option<u16>,\n #[serde(rename = \"startedAt\")]\n started_at: Option<u128>,\n}\n\n#[derive(Clone)]\nstruct AppState {\n screen: ScreenBroadcaster,\n servers: ServerStore,\n}\n\ntype DynSseStream = dyn Stream<Item = std::result::Result<Event, Infallible>> + Send;\n\npub async fn run(opts: DaemonOpts) -> Result<()> {\n let screen = ScreenBroadcaster::with_mock_stream(opts.frame_buffer, opts.fps);\n\n // Load configuration for managed servers.\n let config_path = opts\n .config\n .clone()\n .unwrap_or_else(config::default_config_path);\n let mut cfg: Config = config::load_or_default(&config_path);\n tracing::info!(\n path = %config_path.display(),\n server_count = cfg.servers.len(),\n \"loaded flow config\"\n );\n if let Some(version) = cfg.version {\n tracing::debug!(version, \"config version detected\");\n }\n\n terminal::maybe_enable_terminal_tracing(&cfg.options);\n\n let servers_store: ServerStore = Arc::new(RwLock::new(HashMap::new()));\n sync_servers(&servers_store, std::mem::take(&mut cfg.servers)).await;\n\n if let Some(stream) = cfg.stream.as_ref() {\n tracing::info!(\n provider = %stream.provider,\n hotkey = %stream.hotkey.as_deref().unwrap_or(\"\"),\n toggle_url = %stream.toggle_url.as_deref().unwrap_or(\"\"),\n \"stream config detected\"\n );\n }\n\n let state = AppState {\n screen,\n servers: Arc::clone(&servers_store),\n };\n\n let (reload_tx, mut reload_rx) = mpsc::channel(4);\n if let Err(err) = spawn_config_watcher(&config_path, reload_tx.clone()) {\n tracing::warn!(?err, \"failed to watch config for changes\");\n }\n\n let servers_for_reload = Arc::clone(&servers_store);\n let config_path_for_reload = config_path.clone();\n tokio::spawn(async move {\n while reload_rx.recv().await.is_some() {\n if let Err(err) = reload_config(&config_path_for_reload, &servers_for_reload).await {\n tracing::warn!(?err, \"config reload failed\");\n }\n }\n });\n\n let cors = CorsLayer::new()\n .allow_origin(Any)\n .allow_methods([Method::GET, Method::POST, Method::OPTIONS])\n .allow_headers(Any);\n\n let router = Router::new()\n .route(\"/health\", get(health))\n .route(\"/codex/skills\", get(codex_skills))\n .route(\"/codex/eval\", get(codex_eval))\n .route(\"/codex/resolve\", post(codex_resolve))\n .route(\"/codex/skills/sync\", post(codex_skills_sync))\n .route(\"/codex/skills/reload\", post(codex_skills_reload))\n .route(\"/daemons\", get(daemons))\n .route(\"/daemons/:name/start\", post(daemon_start))\n .route(\"/daemons/:name/stop\", post(daemon_stop))\n .route(\"/daemons/:name/restart\", post(daemon_restart))\n .route(\"/screen/latest\", get(screen_latest))\n .route(\"/screen/stream\", get(screen_stream))\n .route(\"/servers\", get(servers_list))\n .route(\"/logs\", get(all_logs))\n .route(\"/servers/:name/logs\", get(server_logs))\n .route(\"/servers/:name/logs/stream\", get(server_logs_stream))\n // Unified process management endpoints\n .route(\"/processes\", get(processes_list))\n .route(\"/processes/:name/start\", post(process_start))\n .route(\"/processes/:name/stop\", post(process_stop))\n .route(\"/processes/:name/restart\", post(process_restart))\n .route(\"/processes/:name/logs/stream\", get(process_logs_stream))\n // Log ingestion endpoints\n .route(\"/logs/ingest\", post(logs_ingest))\n .route(\"/logs/query\", get(logs_query))\n .layer(cors)\n .with_state(state);\n\n let addr = SocketAddr::from((opts.host, opts.port));\n tracing::info!(\n \"flowd listening on http://{addr} (mock fps: {}, buffer: {}, config: {})\",\n opts.fps,\n opts.frame_buffer,\n config_path.display(),\n );\n\n let listener = tokio::net::TcpListener::bind(addr).await?;\n axum::serve(listener, router)\n .with_graceful_shutdown(shutdown_signal())\n .await?;\n\n Ok(())\n}\n\nasync fn health() -> impl IntoResponse {\n Json(json!({\n \"status\": \"ok\",\n \"message\": \"flow daemon ready\"\n }))\n}\n\n#[derive(Debug, Deserialize)]\nstruct CodexSkillsQuery {\n path: Option<String>,\n #[serde(default = \"default_codex_skills_limit\")]\n limit: usize,\n}\n\n#[derive(Debug, Deserialize)]\nstruct CodexEvalQuery {\n path: Option<String>,\n #[serde(default = \"default_codex_eval_limit\")]\n limit: usize,\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct CodexSkillsSyncRequest {\n path: Option<String>,\n #[serde(default)]\n skills: Vec<String>,\n #[serde(default)]\n force: bool,\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct CodexSkillsReloadRequest {\n path: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct CodexResolveRequest {\n path: Option<String>,\n query: String,\n #[serde(default)]\n exact_cwd: bool,\n}\n\nfn default_codex_skills_limit() -> usize {\n 12\n}\n\nfn default_codex_eval_limit() -> usize {\n 200\n}\n\nfn resolve_codex_skills_target(path: Option<&str>) -> PathBuf {\n let candidate = path\n .map(config::expand_path)\n .unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| config::expand_path(\"~\")));\n if candidate.is_absolute() {\n candidate\n } else {\n std::env::current_dir()\n .unwrap_or_else(|_| config::expand_path(\"~\"))\n .join(candidate)\n }\n}\n\nasync fn codex_skills(Query(query): Query<CodexSkillsQuery>) -> impl IntoResponse {\n let target_path = resolve_codex_skills_target(query.path.as_deref());\n let limit = query.limit.clamp(1, 50);\n let result = tokio::task::spawn_blocking(move || {\n ai::codex_skills_dashboard_snapshot(&target_path, limit)\n })\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"codex skills task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn codex_eval(Query(query): Query<CodexEvalQuery>) -> impl IntoResponse {\n let target_path = resolve_codex_skills_target(query.path.as_deref());\n let limit = query.limit.clamp(20, 1000);\n let result = tokio::task::spawn_blocking(move || ai::codex_eval_snapshot(&target_path, limit))\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"codex eval task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn codex_resolve(AxumJson(payload): AxumJson<CodexResolveRequest>) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n ai::codex_resolve_inspector(payload.path, payload.query, payload.exact_cwd)\n })\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"codex resolve task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn codex_skills_sync(AxumJson(payload): AxumJson<CodexSkillsSyncRequest>) -> impl IntoResponse {\n let target_path = resolve_codex_skills_target(payload.path.as_deref());\n let result = tokio::task::spawn_blocking(move || {\n let installed = ai::codex_skill_source_sync(&target_path, &payload.skills, payload.force)?;\n Ok::<_, anyhow::Error>(json!({\n \"targetPath\": target_path.display().to_string(),\n \"installed\": installed,\n }))\n })\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(snapshot)).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"codex skills sync task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn codex_skills_reload(\n AxumJson(payload): AxumJson<CodexSkillsReloadRequest>,\n) -> impl IntoResponse {\n let target_path = resolve_codex_skills_target(payload.path.as_deref());\n let result = tokio::task::spawn_blocking(move || {\n let reloaded = skills::reload_codex_skills_for_cwd(&target_path)?;\n Ok::<_, anyhow::Error>(json!({\n \"targetPath\": target_path.display().to_string(),\n \"reloaded\": reloaded,\n }))\n })\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(snapshot)).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"codex skills reload task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn daemons() -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(|| daemon_snapshot::load_daemon_snapshot(None)).await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"daemon snapshot task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn daemon_start(AxumPath(name): AxumPath<String>) -> impl IntoResponse {\n daemon_action_response(name, daemon_snapshot::FlowDaemonAction::Start).await\n}\n\nasync fn daemon_stop(AxumPath(name): AxumPath<String>) -> impl IntoResponse {\n daemon_action_response(name, daemon_snapshot::FlowDaemonAction::Stop).await\n}\n\nasync fn daemon_restart(AxumPath(name): AxumPath<String>) -> impl IntoResponse {\n daemon_action_response(name, daemon_snapshot::FlowDaemonAction::Restart).await\n}\n\nasync fn daemon_action_response(\n name: String,\n action: daemon_snapshot::FlowDaemonAction,\n) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n daemon_snapshot::run_daemon_action(&name, action, None)\n })\n .await;\n\n match result {\n Ok(Ok(snapshot)) => (StatusCode::OK, Json(json!(snapshot))).into_response(),\n Ok(Err(err)) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response(),\n Err(err) => (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": format!(\"daemon action task failed: {err}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn screen_latest(State(state): State<AppState>) -> impl IntoResponse {\n match state.screen.latest().await {\n Some(frame) => (StatusCode::OK, Json(frame)).into_response(),\n None => StatusCode::NO_CONTENT.into_response(),\n }\n}\n\nasync fn screen_stream(\n State(state): State<AppState>,\n) -> Sse<impl Stream<Item = std::result::Result<Event, Infallible>>> {\n let stream = BroadcastStream::new(state.screen.subscribe()).filter_map(|result| async move {\n match result {\n Ok(frame) => match serde_json::to_string(&frame) {\n Ok(payload) => Some(Ok(Event::default().data(payload))),\n Err(err) => {\n tracing::error!(?err, \"failed to serialize screen frame\");\n None\n }\n },\n Err(err) => {\n tracing::warn!(?err, \"screen broadcast channel dropped event\");\n None\n }\n }\n });\n\n Sse::new(stream).keep_alive(\n KeepAlive::new()\n .interval(Duration::from_secs(5))\n .text(\":flowd keep-alive\"),\n )\n}\n\nasync fn servers_list(State(state): State<AppState>) -> impl IntoResponse {\n let servers = state.servers.read().await;\n let futures_iter = servers\n .values()\n .cloned()\n .map(|server| async move { server.snapshot().await });\n\n let snapshots: Vec<ServerSnapshot> = futures::future::join_all(futures_iter).await;\n\n (StatusCode::OK, Json(snapshots)).into_response()\n}\n\n#[derive(Debug, Deserialize)]\nstruct LogsQuery {\n #[serde(default = \"default_logs_limit\")]\n limit: usize,\n}\n\nfn default_logs_limit() -> usize {\n 512\n}\n\nasync fn server_logs(\n State(state): State<AppState>,\n AxumPath(name): AxumPath<String>,\n Query(query): Query<LogsQuery>,\n) -> impl IntoResponse {\n let server = {\n let guard = state.servers.read().await;\n guard.get(&name).cloned()\n };\n\n match server {\n Some(server) => {\n let lines: Vec<LogLine> = server.recent_logs(query.limit).await;\n (StatusCode::OK, Json(lines)).into_response()\n }\n None => (\n StatusCode::NOT_FOUND,\n Json(json!({ \"error\": format!(\"unknown server {name}\") })),\n )\n .into_response(),\n }\n}\n\nasync fn all_logs(\n State(state): State<AppState>,\n Query(query): Query<LogsQuery>,\n) -> impl IntoResponse {\n let servers: Vec<_> = {\n let guard = state.servers.read().await;\n guard.values().cloned().collect()\n };\n\n let mut entries: Vec<LogLine> = Vec::new();\n for server in servers {\n let mut lines = server.recent_logs(query.limit).await;\n entries.append(&mut lines);\n }\n\n entries.sort_by_key(|line| line.timestamp_ms);\n if entries.len() > query.limit {\n entries = entries.split_off(entries.len() - query.limit);\n }\n\n (StatusCode::OK, Json(entries)).into_response()\n}\n\nasync fn server_logs_stream(\n State(state): State<AppState>,\n AxumPath(name): AxumPath<String>,\n) -> Sse<Pin<Box<DynSseStream>>> {\n let server = {\n let guard = state.servers.read().await;\n guard.get(&name).cloned()\n };\n\n let (stream, enable_keep_alive) = match server {\n Some(server) => {\n let receiver = server.subscribe();\n let stream = BroadcastStream::new(receiver).filter_map(|result| async move {\n match result {\n Ok(line) => match serde_json::to_string(&line) {\n Ok(payload) => Some(Ok(Event::default().data(payload))),\n Err(err) => {\n tracing::error!(?err, \"failed to serialize log line\");\n None\n }\n },\n Err(err) => {\n tracing::warn!(?err, \"server log broadcast channel dropped event\");\n None\n }\n }\n });\n\n (Box::pin(stream) as Pin<Box<DynSseStream>>, true)\n }\n None => {\n let stream = futures::stream::once(async move {\n Ok(Event::default().data(\n serde_json::to_string(&json!({\n \"error\": format!(\"unknown server {name}\")\n }))\n .unwrap_or_else(|_| \"{\\\"error\\\":\\\"unknown server\\\"}\".to_string()),\n ))\n });\n\n (Box::pin(stream) as Pin<Box<DynSseStream>>, false)\n }\n };\n\n let sse = Sse::new(stream);\n if enable_keep_alive {\n sse.keep_alive(\n KeepAlive::new()\n .interval(Duration::from_secs(5))\n .text(\":flowd log keep-alive\"),\n )\n } else {\n sse\n }\n}\n\n// ============================================================================\n// Unified Process Management Endpoints\n// ============================================================================\n\n/// GET /processes - Returns all running processes from servers, daemons, and tasks.\nasync fn processes_list(State(state): State<AppState>) -> impl IntoResponse {\n let mut snapshots: Vec<ProcessSnapshot> = Vec::new();\n\n // 1. Managed servers from ServerStore\n {\n let servers = state.servers.read().await;\n let futures_iter = servers\n .values()\n .cloned()\n .map(|server| async move { server.snapshot().await });\n let server_snapshots: Vec<ServerSnapshot> = futures::future::join_all(futures_iter).await;\n for s in server_snapshots {\n snapshots.push(ProcessSnapshot {\n name: s.name.clone(),\n source: \"server\".to_string(),\n project: None,\n command: if s.args.is_empty() {\n s.command.clone()\n } else {\n format!(\"{} {}\", s.command, s.args.join(\" \"))\n },\n status: s.status.clone(),\n pid: s.pid,\n port: s.port,\n started_at: None,\n });\n }\n }\n\n // 2. Supervisor daemons via IPC\n if let Ok(socket_path) = supervisor::resolve_socket_path(None) {\n if socket_path.exists() {\n let ipc_result = tokio::task::spawn_blocking(move || {\n let request = supervisor::IpcRequest {\n action: supervisor::SupervisorIpcAction::Status {\n config_path: None,\n },\n };\n supervisor::send_request(&socket_path, &request)\n })\n .await;\n\n if let Ok(Ok(response)) = ipc_result {\n if let Some(daemons) = response.daemons {\n for d in daemons {\n // Skip duplicates already covered by managed servers\n if snapshots.iter().any(|s| s.name == d.name) {\n continue;\n }\n let port = d\n .health_url\n .as_deref()\n .and_then(|url| url.rsplit(':').next())\n .and_then(|port_path| {\n port_path.split('/').next().and_then(|p| p.parse().ok())\n });\n snapshots.push(ProcessSnapshot {\n name: d.name,\n source: \"daemon\".to_string(),\n project: None,\n command: d\n .description\n .unwrap_or_default(),\n status: if d.running { \"running\".to_string() } else { \"stopped\".to_string() },\n pid: d.pid,\n port,\n started_at: None,\n });\n }\n }\n }\n }\n }\n\n // 3. Running tasks from the persistent running-process store\n let task_result = tokio::task::spawn_blocking(|| running::load_running_processes()).await;\n if let Ok(Ok(processes)) = task_result {\n for procs in processes.projects.values() {\n for p in procs {\n snapshots.push(ProcessSnapshot {\n name: p.task_name.clone(),\n source: \"task\".to_string(),\n project: p.project_name.clone(),\n command: p.command.clone(),\n status: \"running\".to_string(),\n pid: Some(p.pid),\n port: None,\n started_at: Some(p.started_at),\n });\n }\n }\n }\n\n (StatusCode::OK, Json(snapshots)).into_response()\n}\n\n/// POST /processes/:name/start\nasync fn process_start(\n State(state): State<AppState>,\n AxumPath(name): AxumPath<String>,\n) -> impl IntoResponse {\n // Try managed server first\n {\n let servers = state.servers.read().await;\n if let Some(server) = servers.get(&name) {\n return match server.start().await {\n Ok(()) => (StatusCode::OK, Json(json!({ \"ok\": true, \"message\": format!(\"{name} started\") }))).into_response(),\n Err(err) => (StatusCode::INTERNAL_SERVER_ERROR, Json(json!({ \"error\": err.to_string() }))).into_response(),\n };\n }\n }\n\n // Try supervisor daemon\n let daemon_name = name.clone();\n let ipc_result = tokio::task::spawn_blocking(move || {\n let socket_path = supervisor::resolve_socket_path(None)?;\n let request = supervisor::IpcRequest {\n action: supervisor::SupervisorIpcAction::StartDaemon {\n name: daemon_name,\n config_path: None,\n },\n };\n supervisor::send_request(&socket_path, &request)\n })\n .await;\n\n match ipc_result {\n Ok(Ok(resp)) if resp.ok => {\n (StatusCode::OK, Json(json!({ \"ok\": true, \"message\": resp.message }))).into_response()\n }\n Ok(Ok(resp)) => {\n (StatusCode::BAD_REQUEST, Json(json!({ \"error\": resp.message }))).into_response()\n }\n _ => {\n (StatusCode::NOT_FOUND, Json(json!({ \"error\": format!(\"unknown process {name}\") }))).into_response()\n }\n }\n}\n\n/// POST /processes/:name/stop\nasync fn process_stop(\n State(state): State<AppState>,\n AxumPath(name): AxumPath<String>,\n) -> impl IntoResponse {\n // Try managed server first\n {\n let servers = state.servers.read().await;\n if let Some(server) = servers.get(&name) {\n return match server.stop().await {\n Ok(()) => (StatusCode::OK, Json(json!({ \"ok\": true, \"message\": format!(\"{name} stopped\") }))).into_response(),\n Err(err) => (StatusCode::INTERNAL_SERVER_ERROR, Json(json!({ \"error\": err.to_string() }))).into_response(),\n };\n }\n }\n\n // Try supervisor daemon\n let daemon_name = name.clone();\n let ipc_result = tokio::task::spawn_blocking(move || {\n let socket_path = supervisor::resolve_socket_path(None)?;\n let request = supervisor::IpcRequest {\n action: supervisor::SupervisorIpcAction::StopDaemon {\n name: daemon_name,\n config_path: None,\n },\n };\n supervisor::send_request(&socket_path, &request)\n })\n .await;\n\n match ipc_result {\n Ok(Ok(resp)) if resp.ok => {\n (StatusCode::OK, Json(json!({ \"ok\": true, \"message\": resp.message }))).into_response()\n }\n Ok(Ok(resp)) => {\n (StatusCode::BAD_REQUEST, Json(json!({ \"error\": resp.message }))).into_response()\n }\n _ => {\n (StatusCode::NOT_FOUND, Json(json!({ \"error\": format!(\"unknown process {name}\") }))).into_response()\n }\n }\n}\n\n/// POST /processes/:name/restart\nasync fn process_restart(\n State(state): State<AppState>,\n AxumPath(name): AxumPath<String>,\n) -> impl IntoResponse {\n // Try managed server: stop then start\n {\n let servers = state.servers.read().await;\n if let Some(server) = servers.get(&name) {\n let _ = server.stop().await;\n tokio::time::sleep(Duration::from_millis(300)).await;\n return match server.start().await {\n Ok(()) => (StatusCode::OK, Json(json!({ \"ok\": true, \"message\": format!(\"{name} restarted\") }))).into_response(),\n Err(err) => (StatusCode::INTERNAL_SERVER_ERROR, Json(json!({ \"error\": err.to_string() }))).into_response(),\n };\n }\n }\n\n // Try supervisor daemon\n let daemon_name = name.clone();\n let ipc_result = tokio::task::spawn_blocking(move || {\n let socket_path = supervisor::resolve_socket_path(None)?;\n let request = supervisor::IpcRequest {\n action: supervisor::SupervisorIpcAction::RestartDaemon {\n name: daemon_name,\n config_path: None,\n },\n };\n supervisor::send_request(&socket_path, &request)\n })\n .await;\n\n match ipc_result {\n Ok(Ok(resp)) if resp.ok => {\n (StatusCode::OK, Json(json!({ \"ok\": true, \"message\": resp.message }))).into_response()\n }\n Ok(Ok(resp)) => {\n (StatusCode::BAD_REQUEST, Json(json!({ \"error\": resp.message }))).into_response()\n }\n _ => {\n (StatusCode::NOT_FOUND, Json(json!({ \"error\": format!(\"unknown process {name}\") }))).into_response()\n }\n }\n}\n\n/// GET /processes/:name/logs/stream - SSE log stream for any process type.\nasync fn process_logs_stream(\n State(state): State<AppState>,\n AxumPath(name): AxumPath<String>,\n) -> Sse<Pin<Box<DynSseStream>>> {\n // Check if it's a managed server — delegate to existing broadcast\n let server = {\n let guard = state.servers.read().await;\n guard.get(&name).cloned()\n };\n\n if let Some(server) = server {\n let receiver = server.subscribe();\n let stream = BroadcastStream::new(receiver).filter_map(|result| async move {\n match result {\n Ok(line) => match serde_json::to_string(&line) {\n Ok(payload) => Some(Ok(Event::default().data(payload))),\n Err(_) => None,\n },\n Err(_) => None,\n }\n });\n\n return Sse::new(Box::pin(stream) as Pin<Box<DynSseStream>>).keep_alive(\n KeepAlive::new()\n .interval(Duration::from_secs(5))\n .text(\":flowd process log keep-alive\"),\n );\n }\n\n // For daemons/tasks: tail log files via polling\n let log_path = find_process_log_path(&name).await;\n\n let stream: Pin<Box<DynSseStream>> = match log_path {\n Some(path) => {\n let stream = futures::stream::unfold(\n (path, 0u64),\n |(path, last_pos)| async move {\n tokio::time::sleep(Duration::from_millis(500)).await;\n let metadata = tokio::fs::metadata(&path).await.ok()?;\n let file_len = metadata.len();\n if file_len <= last_pos {\n return Some((Vec::new(), (path, last_pos)));\n }\n let mut file = tokio::fs::File::open(&path).await.ok()?;\n tokio::io::AsyncSeekExt::seek(\n &mut file,\n std::io::SeekFrom::Start(last_pos),\n )\n .await\n .ok()?;\n let mut buf = vec![0u8; (file_len - last_pos).min(65536) as usize];\n let n = tokio::io::AsyncReadExt::read(&mut file, &mut buf).await.ok()?;\n buf.truncate(n);\n let new_pos = last_pos + n as u64;\n let text = String::from_utf8_lossy(&buf).to_string();\n let events: Vec<std::result::Result<Event, Infallible>> = text\n .lines()\n .filter(|l| !l.is_empty())\n .map(|line| {\n Ok(Event::default().data(\n serde_json::to_string(&json!({\n \"line\": line,\n \"stream\": \"stdout\",\n \"timestamp_ms\": running::now_ms(),\n }))\n .unwrap_or_default(),\n ))\n })\n .collect();\n Some((events, (path, new_pos)))\n },\n )\n .flat_map(futures::stream::iter);\n Box::pin(stream)\n }\n None => {\n let stream = futures::stream::once(async move {\n Ok(Event::default().data(\n json!({ \"error\": format!(\"no logs found for {name}\") }).to_string(),\n ))\n });\n Box::pin(stream)\n }\n };\n\n Sse::new(stream).keep_alive(\n KeepAlive::new()\n .interval(Duration::from_secs(5))\n .text(\":flowd process log keep-alive\"),\n )\n}\n\n/// Find log file path for a daemon or task by name.\nasync fn find_process_log_path(name: &str) -> Option<std::path::PathBuf> {\n let state_dir = config::global_state_dir();\n\n // Check daemon stdout log\n let daemon_log = state_dir.join(\"daemons\").join(name).join(\"stdout.log\");\n if tokio::fs::metadata(&daemon_log).await.is_ok() {\n return Some(daemon_log);\n }\n\n // Check task log files under ~/.config/flow/logs/\n let logs_dir = state_dir.join(\"logs\");\n if let Ok(mut entries) = tokio::fs::read_dir(&logs_dir).await {\n while let Ok(Some(entry)) = entries.next_entry().await {\n let project_dir = entry.path();\n let task_log = project_dir.join(format!(\"{name}.log\"));\n if tokio::fs::metadata(&task_log).await.is_ok() {\n return Some(task_log);\n }\n }\n }\n\n None\n}\n\nasync fn reload_config(path: &Path, servers: &ServerStore) -> Result<()> {\n let mut cfg = config::load(path)\n .with_context(|| format!(\"failed to reload config at {}\", path.display()))?;\n tracing::info!(path = %path.display(), \"config changed; reloading\");\n\n sync_servers(servers, std::mem::take(&mut cfg.servers)).await;\n\n if let Some(stream) = cfg.stream {\n tracing::info!(\n provider = %stream.provider,\n hotkey = %stream.hotkey.as_deref().unwrap_or(\"\"),\n toggle_url = %stream.toggle_url.as_deref().unwrap_or(\"\"),\n \"stream config updated\"\n );\n }\n\n Ok(())\n}\n\nasync fn sync_servers(store: &ServerStore, configs: Vec<ServerConfig>) {\n let mut desired: HashMap<String, ServerConfig> = HashMap::new();\n for cfg in configs.into_iter() {\n desired.insert(cfg.name.clone(), cfg);\n }\n\n let mut to_stop: Vec<Arc<ManagedServer>> = Vec::new();\n let mut to_start: Vec<Arc<ManagedServer>> = Vec::new();\n\n {\n let mut guard = store.write().await;\n\n guard.retain(|name, server| {\n if !desired.contains_key(name) {\n to_stop.push(server.clone());\n false\n } else {\n true\n }\n });\n\n for (name, cfg) in desired.into_iter() {\n if let Some(existing) = guard.get(&name) {\n if existing.config() == &cfg {\n continue;\n }\n to_stop.push(existing.clone());\n guard.remove(&name);\n }\n\n let managed = ManagedServer::new(cfg.clone(), LOG_BUFFER_CAPACITY);\n if cfg.autostart {\n to_start.push(managed.clone());\n }\n guard.insert(name, managed);\n }\n }\n\n for server in to_stop {\n if let Err(err) = server.stop().await {\n tracing::warn!(\n ?err,\n name = server.config().name,\n \"failed to stop managed server during reload\"\n );\n }\n }\n\n for server in to_start {\n tokio::spawn(async move {\n if let Err(err) = server.start().await {\n tracing::error!(\n ?err,\n server = server.config().name,\n \"failed to start managed server\"\n );\n }\n });\n }\n}\n\nfn spawn_config_watcher(path: &Path, tx: mpsc::Sender<()>) -> notify::Result<()> {\n let target = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());\n let watch_root = target\n .parent()\n .map(Path::to_path_buf)\n .unwrap_or_else(|| target.clone());\n\n std::thread::spawn(move || {\n let (event_tx, event_rx) = std_mpsc::channel();\n let mut debouncer = match new_debouncer(Duration::from_millis(250), event_tx) {\n Ok(debouncer) => debouncer,\n Err(err) => {\n tracing::error!(?err, \"failed to initialize config watcher\");\n return;\n }\n };\n\n if let Err(err) = debouncer\n .watcher()\n .watch(&watch_root, RecursiveMode::NonRecursive)\n {\n tracing::error!(?err, path = %watch_root.display(), \"failed to watch config directory\");\n return;\n }\n\n while let Ok(result) = event_rx.recv() {\n match result {\n Ok(events) => {\n let should_reload = events.iter().any(|event| same_file(&target, &event.path));\n if should_reload && tx.blocking_send(()).is_err() {\n break;\n }\n }\n Err(err) => tracing::warn!(?err, \"config watcher error\"),\n }\n }\n });\n\n Ok(())\n}\n\nfn same_file(a: &Path, b: &Path) -> bool {\n if a == b {\n return true;\n }\n\n if let Ok(canon) = b.canonicalize() {\n if canon == a {\n return true;\n }\n }\n\n a.file_name()\n .is_some_and(|name| Some(name) == b.file_name())\n}\n\nasync fn shutdown_signal() {\n if tokio::signal::ctrl_c().await.is_ok() {\n tracing::info!(\"shutdown signal received\");\n }\n}\n\n// ============================================================================\n// Log Ingestion Endpoints\n// ============================================================================\n\n/// Request body for log ingestion - single entry or batch.\n#[derive(Debug, Deserialize)]\n#[serde(untagged)]\nenum IngestRequest {\n Single(LogEntry),\n Batch(Vec<LogEntry>),\n}\n\n/// POST /logs/ingest - Ingest log entries into the database.\nasync fn logs_ingest(Json(payload): Json<IngestRequest>) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n let mut conn = match log_store::open_log_db() {\n Ok(c) => c,\n Err(e) => return Err(e),\n };\n\n match payload {\n IngestRequest::Single(entry) => {\n let id = log_store::insert_log(&conn, &entry)?;\n Ok(json!({ \"inserted\": 1, \"ids\": [id] }))\n }\n IngestRequest::Batch(entries) => {\n let ids = log_store::insert_logs(&mut conn, &entries)?;\n Ok(json!({ \"inserted\": ids.len(), \"ids\": ids }))\n }\n }\n })\n .await;\n\n match result {\n Ok(Ok(response)) => (StatusCode::OK, Json(response)).into_response(),\n Ok(Err(err)) => {\n tracing::error!(?err, \"log ingest failed\");\n (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response()\n }\n Err(err) => {\n tracing::error!(?err, \"log ingest task panicked\");\n (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": \"internal error\" })),\n )\n .into_response()\n }\n }\n}\n\n/// GET /logs/query - Query stored logs with filters.\nasync fn logs_query(Query(query): Query<LogQuery>) -> impl IntoResponse {\n let result = tokio::task::spawn_blocking(move || {\n let conn = log_store::open_log_db()?;\n log_store::query_logs(&conn, &query)\n })\n .await;\n\n match result {\n Ok(Ok(entries)) => (StatusCode::OK, Json(entries)).into_response(),\n Ok(Err(err)) => {\n tracing::error!(?err, \"log query failed\");\n (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": err.to_string() })),\n )\n .into_response()\n }\n Err(err) => {\n tracing::error!(?err, \"log query task panicked\");\n (\n StatusCode::INTERNAL_SERVER_ERROR,\n Json(json!({ \"error\": \"internal error\" })),\n )\n .into_response()\n }\n }\n}\n" }, { "path": "src/servers.rs", "content": "use std::{\n collections::VecDeque,\n sync::Arc,\n time::{SystemTime, UNIX_EPOCH},\n};\n\nuse anyhow::{Context, Result};\nuse serde::{Deserialize, Serialize};\nuse tokio::{\n io::{AsyncBufReadExt, BufReader},\n process::Command,\n sync::{Mutex, RwLock, broadcast, mpsc},\n};\n\nuse crate::config::ServerConfig;\n\n/// Origin of a log line (stdout or stderr).\n#[derive(Debug, Clone, Serialize, Deserialize)]\n#[serde(rename_all = \"lowercase\")]\npub enum LogStream {\n Stdout,\n Stderr,\n}\n\n/// Single log entry from a managed server process.\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct LogLine {\n /// Name of the server that produced this line.\n pub server: String,\n /// Milliseconds since UNIX epoch when the line was captured.\n pub timestamp_ms: u128,\n /// Which stream the line came from.\n pub stream: LogStream,\n /// The raw text of the log line.\n pub line: String,\n}\n\n#[derive(Debug)]\nenum ProcessState {\n Idle,\n Starting,\n Running { pid: u32 },\n Exited { code: Option<i32> },\n Failed { error: String },\n}\n\n#[derive(Debug, Clone, Copy)]\nenum ServerControl {\n Terminate,\n}\n\n/// Snapshot of the current state of a managed server, suitable for JSON APIs.\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ServerSnapshot {\n pub name: String,\n pub command: String,\n pub args: Vec<String>,\n pub port: Option<u16>,\n pub working_dir: Option<std::path::PathBuf>,\n pub autostart: bool,\n pub status: String,\n pub pid: Option<u32>,\n pub exit_code: Option<i32>,\n}\n\n/// In-process supervisor for a single child HTTP server defined in the config.\n#[derive(Debug)]\npub struct ManagedServer {\n cfg: ServerConfig,\n state: RwLock<ProcessState>,\n log_tx: broadcast::Sender<LogLine>,\n log_buffer: RwLock<VecDeque<LogLine>>,\n log_buffer_capacity: usize,\n control: Mutex<Option<mpsc::Sender<ServerControl>>>,\n}\n\nimpl ManagedServer {\n pub fn new(cfg: ServerConfig, log_buffer_capacity: usize) -> Arc<Self> {\n let (log_tx, _) = broadcast::channel(1024);\n Arc::new(Self {\n cfg,\n state: RwLock::new(ProcessState::Idle),\n log_tx,\n log_buffer: RwLock::new(VecDeque::with_capacity(log_buffer_capacity)),\n log_buffer_capacity,\n control: Mutex::new(None),\n })\n }\n\n pub fn config(&self) -> &ServerConfig {\n &self.cfg\n }\n\n pub fn subscribe(&self) -> broadcast::Receiver<LogLine> {\n self.log_tx.subscribe()\n }\n\n pub async fn snapshot(&self) -> ServerSnapshot {\n let state = self.state.read().await;\n let (status, pid, exit_code) = match &*state {\n ProcessState::Idle => (\"idle\".to_string(), None, None),\n ProcessState::Starting => (\"starting\".to_string(), None, None),\n ProcessState::Running { pid } => (\"running\".to_string(), Some(*pid), None),\n ProcessState::Exited { code } => (\"exited\".to_string(), None, *code),\n ProcessState::Failed { error } => (format!(\"failed: {error}\"), None, None),\n };\n\n ServerSnapshot {\n name: self.cfg.name.clone(),\n command: self.cfg.command.clone(),\n args: self.cfg.args.clone(),\n port: self.cfg.port,\n working_dir: self.cfg.working_dir.clone(),\n autostart: self.cfg.autostart,\n status,\n pid,\n exit_code,\n }\n }\n\n pub async fn recent_logs(&self, limit: usize) -> Vec<LogLine> {\n let guard = self.log_buffer.read().await;\n let len = guard.len();\n let start = len.saturating_sub(limit);\n guard.iter().skip(start).cloned().collect()\n }\n\n /// Spawn the configured process and begin capturing stdout/stderr.\n ///\n /// This method returns immediately after the process has been started; a\n /// background task monitors for process exit.\n pub async fn start(self: &Arc<Self>) -> Result<()> {\n {\n let state = self.state.read().await;\n if matches!(\n *state,\n ProcessState::Starting | ProcessState::Running { .. }\n ) {\n return Ok(());\n }\n }\n\n {\n let mut state = self.state.write().await;\n *state = ProcessState::Starting;\n }\n\n let mut cmd = Command::new(&self.cfg.command);\n cmd.args(&self.cfg.args);\n\n if let Some(dir) = &self.cfg.working_dir {\n cmd.current_dir(dir);\n }\n\n if !self.cfg.env.is_empty() {\n cmd.envs(self.cfg.env.clone());\n }\n\n cmd.stdout(std::process::Stdio::piped());\n cmd.stderr(std::process::Stdio::piped());\n\n let mut child = cmd\n .spawn()\n .with_context(|| format!(\"failed to spawn managed server {}\", self.cfg.name))?;\n\n {\n let pid = child.id().unwrap_or(0);\n let mut state = self.state.write().await;\n *state = ProcessState::Running { pid };\n }\n\n let (control_tx, mut control_rx) = mpsc::channel(1);\n {\n let mut guard = self.control.lock().await;\n *guard = Some(control_tx);\n }\n\n let server = Arc::clone(self);\n\n // stdout task\n if let Some(stdout) = child.stdout.take() {\n Self::spawn_log_task(Arc::clone(&server), stdout, LogStream::Stdout);\n }\n\n // stderr task\n if let Some(stderr) = child.stderr.take() {\n Self::spawn_log_task(server.clone(), stderr, LogStream::Stderr);\n }\n\n // wait for exit\n tokio::spawn(async move {\n let status = tokio::select! {\n status = child.wait() => status,\n ctrl = control_rx.recv() => {\n if matches!(ctrl, Some(ServerControl::Terminate)) {\n if let Err(err) = child.kill().await {\n tracing::warn!(?err, server = server.cfg.name, \"failed to terminate server child\");\n }\n }\n child.wait().await\n }\n };\n\n {\n let mut guard = server.control.lock().await;\n *guard = None;\n }\n\n let mut state = server.state.write().await;\n match status {\n Ok(status) => {\n *state = ProcessState::Exited {\n code: status.code(),\n }\n }\n Err(err) => {\n *state = ProcessState::Failed {\n error: err.to_string(),\n }\n }\n }\n });\n\n Ok(())\n }\n\n pub async fn stop(&self) -> Result<()> {\n let tx = { self.control.lock().await.clone() };\n if let Some(tx) = tx {\n let _ = tx.send(ServerControl::Terminate).await;\n }\n Ok(())\n }\n\n fn spawn_log_task<R>(server: Arc<Self>, reader: R, stream: LogStream)\n where\n R: tokio::io::AsyncRead + Unpin + Send + 'static,\n {\n tokio::spawn(async move {\n let mut lines = BufReader::new(reader).lines();\n while let Ok(Some(line)) = lines.next_line().await {\n let entry = LogLine {\n server: server.cfg.name.clone(),\n timestamp_ms: current_epoch_ms(),\n stream: stream.clone(),\n line,\n };\n server.push_log(entry).await;\n }\n });\n }\n\n async fn push_log(&self, line: LogLine) {\n // broadcast; ignore errors if there are no subscribers\n let _ = self.log_tx.send(line.clone());\n\n let mut buf = self.log_buffer.write().await;\n if buf.len() == self.log_buffer_capacity {\n buf.pop_front();\n }\n buf.push_back(line);\n }\n}\n\nfn current_epoch_ms() -> u128 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|d| d.as_millis())\n .unwrap_or(0)\n}\n" }, { "path": "src/servers_tui.rs", "content": "use std::{\n io,\n time::{Duration, Instant},\n};\n\nuse anyhow::{Context, Result};\nuse crossterm::{\n event::{self, Event as CEvent, KeyCode, KeyEvent},\n execute,\n terminal::{EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode},\n};\nuse ratatui::{\n Terminal,\n backend::CrosstermBackend,\n layout::{Constraint, Direction, Layout},\n style::{Color, Modifier, Style},\n text::{Line, Span},\n widgets::{Block, Borders, List, ListItem, ListState, Paragraph, Wrap},\n};\n\nuse crate::{\n cli::ServersOpts,\n servers::{LogLine, LogStream, ServerSnapshot},\n};\n\nconst LOG_LIMIT: usize = 512;\n\npub fn run(opts: ServersOpts) -> Result<()> {\n let base_url = format!(\"http://{}:{}\", opts.host, opts.port);\n let client = reqwest::blocking::Client::new();\n\n // Set up terminal\n enable_raw_mode().context(\"failed to enable raw mode\")?;\n let mut stdout = io::stdout();\n execute!(stdout, EnterAlternateScreen).context(\"failed to enter alternate screen\")?;\n let backend = CrosstermBackend::new(stdout);\n let mut terminal = Terminal::new(backend).context(\"failed to create terminal backend\")?;\n\n let app_result = run_app(&mut terminal, client, base_url);\n\n // Restore terminal state on exit\n disable_raw_mode().ok();\n let _ = terminal.show_cursor();\n drop(terminal);\n let mut stdout = io::stdout();\n execute!(stdout, LeaveAlternateScreen).ok();\n\n app_result\n}\n\nstruct App {\n client: reqwest::blocking::Client,\n base_url: String,\n servers: Vec<ServerSnapshot>,\n selected: usize,\n logs: Vec<LogLine>,\n log_scroll: u16,\n focus_server: bool,\n last_servers_refresh: Instant,\n last_logs_refresh: Instant,\n}\n\nimpl App {\n fn new(client: reqwest::blocking::Client, base_url: String) -> Result<Self> {\n let mut app = Self {\n client,\n base_url,\n servers: Vec::new(),\n selected: 0,\n logs: Vec::new(),\n log_scroll: 0,\n focus_server: true,\n last_servers_refresh: Instant::now(),\n last_logs_refresh: Instant::now(),\n };\n app.refresh_servers()?;\n app.refresh_logs()?;\n Ok(app)\n }\n\n fn selected_server_name(&self) -> Option<&str> {\n self.servers.get(self.selected).map(|s| s.name.as_str())\n }\n\n fn refresh_servers(&mut self) -> Result<()> {\n let url = format!(\"{}/servers\", self.base_url);\n let resp = self\n .client\n .get(&url)\n .send()\n .with_context(|| format!(\"failed to GET {url}\"))?;\n\n if !resp.status().is_success() {\n anyhow::bail!(\n \"daemon responded with {} when fetching servers\",\n resp.status()\n );\n }\n\n let servers = resp\n .json::<Vec<ServerSnapshot>>()\n .context(\"failed to decode /servers response\")?;\n\n self.servers = servers;\n if self.selected >= self.servers.len() {\n self.selected = self.servers.len().saturating_sub(1);\n }\n self.last_servers_refresh = Instant::now();\n Ok(())\n }\n\n fn refresh_logs(&mut self) -> Result<()> {\n let request = if self.focus_server {\n let name = match self.selected_server_name() {\n Some(name) => name,\n None => {\n self.logs.clear();\n self.focus_server = false;\n self.last_logs_refresh = Instant::now();\n return Ok(());\n }\n };\n format!(\"{}/servers/{}/logs\", self.base_url, name)\n } else {\n format!(\"{}/logs\", self.base_url)\n };\n\n let resp = self\n .client\n .get(&request)\n .query(&[(\"limit\", LOG_LIMIT)])\n .send()\n .with_context(|| format!(\"failed to GET {request}\"))?;\n\n if resp.status().is_success() {\n let logs = resp\n .json::<Vec<LogLine>>()\n .context(\"failed to decode logs response\")?;\n self.logs = logs;\n } else {\n self.logs.clear();\n }\n\n self.last_logs_refresh = Instant::now();\n Ok(())\n }\n\n fn maybe_refresh(&mut self) -> Result<()> {\n let now = Instant::now();\n if now.duration_since(self.last_servers_refresh) > Duration::from_secs(5) {\n let _ = self.refresh_servers();\n }\n if now.duration_since(self.last_logs_refresh) > Duration::from_secs(1) {\n let _ = self.refresh_logs();\n }\n Ok(())\n }\n\n fn select_next(&mut self) -> Result<()> {\n if !self.servers.is_empty() && self.selected + 1 < self.servers.len() {\n self.selected += 1;\n self.log_scroll = 0;\n self.refresh_logs()?;\n }\n Ok(())\n }\n\n fn select_prev(&mut self) -> Result<()> {\n if !self.servers.is_empty() && self.selected > 0 {\n self.selected -= 1;\n self.log_scroll = 0;\n self.refresh_logs()?;\n }\n Ok(())\n }\n\n fn scroll_down(&mut self) {\n self.log_scroll = self.log_scroll.saturating_add(1);\n }\n\n fn scroll_up(&mut self) {\n self.log_scroll = self.log_scroll.saturating_sub(1);\n }\n\n fn toggle_focus(&mut self) -> Result<()> {\n if self.servers.is_empty() {\n return Ok(());\n }\n self.focus_server = !self.focus_server;\n self.log_scroll = 0;\n self.refresh_logs()\n }\n\n fn show_all_logs(&mut self) -> Result<()> {\n if self.focus_server {\n self.focus_server = false;\n self.log_scroll = 0;\n self.refresh_logs()\n } else {\n Ok(())\n }\n }\n\n fn log_scope_label(&self) -> String {\n if self.focus_server {\n match self.selected_server_name() {\n Some(name) => format!(\"Focused: {}\", name),\n None => \"Focused: (none)\".to_string(),\n }\n } else {\n \"All servers\".to_string()\n }\n }\n}\n\nfn run_app<B: ratatui::backend::Backend>(\n terminal: &mut Terminal<B>,\n client: reqwest::blocking::Client,\n base_url: String,\n) -> Result<()> {\n let mut app = App::new(client, base_url)?;\n let tick_rate = Duration::from_millis(250);\n\n loop {\n terminal\n .draw(|f| draw_ui(f, &app))\n .context(\"failed to draw TUI frame\")?;\n\n if crossterm::event::poll(tick_rate)? {\n if let CEvent::Key(key) = event::read()? {\n if handle_key(&mut app, key)? {\n break;\n }\n }\n }\n\n app.maybe_refresh()?;\n }\n\n Ok(())\n}\n\nfn handle_key(app: &mut App, key: KeyEvent) -> Result<bool> {\n match key.code {\n KeyCode::Char('q') => return Ok(true),\n KeyCode::Esc => return Ok(true),\n KeyCode::Down | KeyCode::Char('j') => {\n app.select_next()?;\n }\n KeyCode::Up | KeyCode::Char('k') => {\n app.select_prev()?;\n }\n KeyCode::PageDown | KeyCode::Char('J') => {\n app.scroll_down();\n }\n KeyCode::PageUp | KeyCode::Char('K') => {\n app.scroll_up();\n }\n KeyCode::Char('r') => {\n app.refresh_servers()?;\n app.refresh_logs()?;\n }\n KeyCode::Char('f') => {\n app.toggle_focus()?;\n }\n KeyCode::Char('a') => {\n app.show_all_logs()?;\n }\n _ => {}\n }\n\n Ok(false)\n}\n\nfn draw_ui(f: &mut ratatui::Frame<'_>, app: &App) {\n let size = f.size();\n\n let layout = Layout::default()\n .direction(Direction::Vertical)\n .constraints([Constraint::Min(0), Constraint::Length(3)])\n .split(size);\n\n let chunks = Layout::default()\n .direction(Direction::Horizontal)\n .constraints([Constraint::Percentage(30), Constraint::Percentage(70)])\n .split(layout[0]);\n\n // Servers list\n let servers_items: Vec<ListItem> = if app.servers.is_empty() {\n vec![ListItem::new(\"No servers (check config or daemon)\")]\n } else {\n app.servers\n .iter()\n .map(|s| {\n let label = match s.port {\n Some(port) => format!(\"{}:{} [{}]\", s.name, port, s.status),\n None => format!(\"{} [{}]\", s.name, s.status),\n };\n ListItem::new(label)\n })\n .collect()\n };\n\n let mut list_state = ListState::default();\n if !app.servers.is_empty() {\n list_state.select(Some(app.selected));\n }\n\n let servers_list = List::new(servers_items)\n .block(\n Block::default()\n .borders(Borders::ALL)\n .title(\"Servers (↑/↓, r = reload, q = quit)\"),\n )\n .highlight_style(Style::default().add_modifier(Modifier::REVERSED))\n .highlight_symbol(\"▶ \");\n\n f.render_stateful_widget(servers_list, chunks[0], &mut list_state);\n\n // Logs pane\n let log_lines: Vec<Line> = if app.logs.is_empty() {\n vec![Line::from(Span::raw(\"No logs yet\"))]\n } else {\n app.logs\n .iter()\n .map(|line| {\n let ts = format_ts(line.timestamp_ms);\n let stream = match line.stream {\n LogStream::Stdout => (\"OUT\", Style::default().fg(Color::Green)),\n LogStream::Stderr => (\"ERR\", Style::default().fg(Color::Red)),\n };\n let server_label = Span::styled(\n format!(\"{:<12}\", line.server),\n Style::default()\n .fg(Color::LightCyan)\n .add_modifier(Modifier::BOLD),\n );\n Line::from(vec![\n Span::styled(\n format!(\"[{ts}]\"),\n Style::default().add_modifier(Modifier::DIM),\n ),\n Span::raw(\" \"),\n server_label,\n Span::raw(\" \"),\n Span::styled(stream.0, stream.1.add_modifier(Modifier::BOLD)),\n Span::raw(\" \"),\n Span::raw(line.line.trim_end()),\n ])\n })\n .collect()\n };\n\n let scope = app.log_scope_label();\n let title = format!(\"Logs ({scope}) – PgUp/PgDn scroll • f focus toggle • a all logs\");\n\n let logs_widget = Paragraph::new(log_lines)\n .block(Block::default().borders(Borders::ALL).title(title))\n .scroll((app.log_scroll, 0));\n\n f.render_widget(logs_widget, chunks[1]);\n\n let help = Paragraph::new(Line::from(vec![\n Span::styled(\"Hub: \", Style::default().add_modifier(Modifier::BOLD)),\n Span::raw(&app.base_url),\n Span::raw(\" | q quit • r refresh • j/k select • f focus • a all logs\"),\n ]))\n .block(Block::default().borders(Borders::ALL).title(\"Help\"))\n .wrap(Wrap { trim: true });\n\n f.render_widget(help, layout[1]);\n}\n\nfn format_ts(ms: u128) -> String {\n let secs = ms / 1000;\n let millis = ms % 1000;\n format!(\"{secs}.{millis:03}\")\n}\n" }, { "path": "src/services.rs", "content": "use std::collections::HashMap;\nuse std::io::{self, IsTerminal, Write};\nuse std::path::{Path, PathBuf};\n\nuse anyhow::{Context, Result};\nuse crossterm::event::{self, Event as CEvent, KeyCode};\nuse crossterm::terminal::{disable_raw_mode, enable_raw_mode};\n\nuse crate::cli::{ServicesAction, ServicesCommand, StripeModeArg, StripeServiceOpts};\nuse crate::{config, deploy, env};\n\npub fn run(cmd: ServicesCommand) -> Result<()> {\n match cmd.action {\n Some(ServicesAction::Stripe(opts)) => run_stripe(opts),\n Some(ServicesAction::List) | None => list_services(),\n }\n}\n\nfn list_services() -> Result<()> {\n println!(\"Available service setup flows:\");\n println!(\" stripe - Guided Stripe env setup\");\n Ok(())\n}\n\npub fn maybe_run_stripe_setup(\n project_root: &Path,\n flow_cfg: &config::Config,\n env_name: &str,\n) -> Result<()> {\n let stripe_keys = collect_stripe_keys(flow_cfg);\n if stripe_keys.is_empty() {\n return Ok(());\n }\n\n let required_keys = stripe_keys\n .iter()\n .filter(|key| stripe_key_spec(key).required)\n .cloned()\n .collect::<Vec<_>>();\n if required_keys.is_empty() {\n return Ok(());\n }\n\n let existing = fetch_project_env_vars_allow_missing(env_name, &required_keys)?;\n let missing_required = required_keys\n .iter()\n .filter(|key| {\n existing\n .get(*key)\n .map(|value| value.trim().is_empty())\n .unwrap_or(true)\n })\n .cloned()\n .collect::<Vec<_>>();\n\n if missing_required.is_empty() {\n println!(\"Stripe env vars already configured; skipping Stripe setup.\");\n return Ok(());\n }\n\n println!(\"Stripe env vars missing: {}\", missing_required.join(\", \"));\n if !prompt_yes_no(\"Run Stripe setup now?\", true)? {\n return Ok(());\n }\n\n let mode_default = default_stripe_mode_for_env(env_name);\n let mode = prompt_stripe_mode(mode_default)?;\n\n run_stripe(StripeServiceOpts {\n path: Some(project_root.to_path_buf()),\n environment: Some(env_name.to_string()),\n mode,\n force: false,\n apply: false,\n no_apply: true,\n })\n}\n\nfn run_stripe(opts: StripeServiceOpts) -> Result<()> {\n let (project_root, flow_path, flow_cfg) = resolve_project_root(opts.path.as_ref())?;\n let _dir_guard = DirGuard::new(&project_root)?;\n\n let project_name = flow_cfg\n .project_name\n .clone()\n .or_else(|| {\n project_root\n .file_name()\n .and_then(|name| name.to_str())\n .map(|s| s.to_string())\n })\n .unwrap_or_else(|| \"project\".to_string());\n\n let env_name = opts.environment.clone().or_else(|| {\n flow_cfg\n .cloudflare\n .as_ref()\n .and_then(|cfg| cfg.environment.clone())\n });\n let env_name = env_name.unwrap_or_else(|| \"production\".to_string());\n\n println!(\"Stripe setup\");\n println!(\"------------\");\n println!(\"Project: {}\", project_name);\n println!(\"Config: {}\", flow_path.display());\n println!(\"Env: {}\", env_name);\n println!(\n \"Mode: {}\",\n match opts.mode {\n StripeModeArg::Test => \"test\",\n StripeModeArg::Live => \"live\",\n }\n );\n println!();\n\n let keys = collect_stripe_keys(&flow_cfg);\n let specs = keys\n .into_iter()\n .map(|key| stripe_key_spec(&key))\n .collect::<Vec<_>>();\n\n let key_names: Vec<String> = specs.iter().map(|spec| spec.key.clone()).collect();\n let existing = fetch_project_env_vars_allow_missing(&env_name, &key_names)?;\n\n let has_optional = specs.iter().any(|spec| !spec.required);\n let include_optional = if has_optional {\n prompt_yes_no(\"Set optional Stripe keys?\", false)?\n } else {\n false\n };\n\n let mut missing_required = Vec::new();\n let mut updated = 0usize;\n\n for spec in specs {\n if !spec.required && !include_optional {\n continue;\n }\n\n if existing.contains_key(&spec.key) && !opts.force {\n println!(\"OK {} already set (use --force to update)\", spec.key);\n continue;\n }\n\n println!();\n println!(\n \"{}{}\",\n spec.key,\n if spec.required { \" (required)\" } else { \"\" }\n );\n println!(\" {}\", spec.description);\n for line in spec.instructions(opts.mode) {\n println!(\" - {}\", line);\n }\n\n let value = if spec.secret {\n prompt_secret(\"Enter value (leave blank to skip)\")?\n } else {\n prompt_line(\"Enter value (leave blank to skip)\", None)?\n };\n let trimmed = value.trim();\n if trimmed.is_empty() {\n if spec.required {\n missing_required.push(spec.key.clone());\n println!(\" WARN Skipped required key.\");\n } else {\n println!(\" Skipped.\");\n }\n continue;\n }\n\n if let Some(prefix) = spec.expected_prefix(opts.mode) {\n if !trimmed.starts_with(prefix) {\n println!(\n \" WARN Value does not look like {} (expected prefix: {}).\",\n spec.key, prefix\n );\n }\n }\n\n env::set_project_env_var(&spec.key, trimmed, &env_name, Some(spec.description))?;\n updated += 1;\n }\n\n println!();\n println!(\"Stripe setup complete. Updated {} key(s).\", updated);\n if !missing_required.is_empty() {\n println!(\"Missing required keys:\");\n for key in &missing_required {\n println!(\" - {}\", key);\n }\n }\n\n if should_apply_env(&opts) {\n apply_cloudflare_env(&project_root, &flow_cfg)?;\n } else {\n println!(\"Skipped applying envs to Cloudflare.\");\n }\n\n Ok(())\n}\n\nfn apply_cloudflare_env(project_root: &Path, flow_cfg: &config::Config) -> Result<()> {\n let Some(cf) = flow_cfg.cloudflare.as_ref() else {\n println!(\"No [cloudflare] section found; skip apply.\");\n return Ok(());\n };\n if !is_cloud_source(cf.env_source.as_deref()) {\n println!(\"cloudflare.env_source is not set to \\\"cloud\\\"; skip apply.\");\n return Ok(());\n }\n deploy::apply_cloudflare_env(project_root, Some(flow_cfg))\n}\n\nfn should_apply_env(opts: &StripeServiceOpts) -> bool {\n if opts.apply {\n return true;\n }\n if opts.no_apply {\n return false;\n }\n prompt_yes_no(\"Apply envs to Cloudflare now?\", true).unwrap_or(false)\n}\n\nfn is_cloud_source(source: Option<&str>) -> bool {\n matches!(\n source.map(|s| s.to_ascii_lowercase()).as_deref(),\n Some(\"cloud\") | Some(\"remote\") | Some(\"myflow\")\n )\n}\n\nfn fetch_project_env_vars_allow_missing(\n env_name: &str,\n keys: &[String],\n) -> Result<HashMap<String, String>> {\n match env::fetch_project_env_vars(env_name, keys) {\n Ok(values) => Ok(values),\n Err(err) => {\n let msg = format!(\"{err:#}\");\n if msg.contains(\"Project not found.\") {\n println!(\"Project not found yet; it will be created on first set.\");\n Ok(HashMap::new())\n } else {\n println!(\"Unable to read existing env vars: {err}\");\n println!(\"Run `f env login` to authenticate with cloud.\");\n Err(err)\n }\n }\n }\n}\n\nfn default_stripe_mode_for_env(env_name: &str) -> StripeModeArg {\n if env_name.eq_ignore_ascii_case(\"production\") {\n StripeModeArg::Live\n } else {\n StripeModeArg::Test\n }\n}\n\nfn prompt_stripe_mode(default: StripeModeArg) -> Result<StripeModeArg> {\n let default_label = match default {\n StripeModeArg::Test => \"test\",\n StripeModeArg::Live => \"live\",\n };\n let value = prompt_line(\"Stripe mode (test/live)\", Some(default_label))?;\n match value.trim().to_ascii_lowercase().as_str() {\n \"\" => Ok(default),\n \"test\" | \"t\" => Ok(StripeModeArg::Test),\n \"live\" | \"l\" => Ok(StripeModeArg::Live),\n other => {\n println!(\"Unknown mode '{other}', using {default_label}.\");\n Ok(default)\n }\n }\n}\n\nfn collect_stripe_keys(flow_cfg: &config::Config) -> Vec<String> {\n let mut keys = Vec::new();\n if let Some(cf) = flow_cfg.cloudflare.as_ref() {\n for key in cf.env_keys.iter().chain(cf.env_vars.iter()) {\n if is_stripe_key(key) && !keys.contains(key) {\n keys.push(key.clone());\n }\n }\n }\n if keys.is_empty() {\n keys = vec![\n \"STRIPE_SECRET_KEY\",\n \"STRIPE_WEBHOOK_SECRET\",\n \"STRIPE_PRO_PRICE_ID\",\n \"STRIPE_REFILL_PRICE_ID\",\n \"VITE_STRIPE_PUBLISHABLE_KEY\",\n ]\n .into_iter()\n .map(|key| key.to_string())\n .collect();\n }\n keys\n}\n\nfn is_stripe_key(key: &str) -> bool {\n key.starts_with(\"STRIPE_\") || key.starts_with(\"VITE_STRIPE_\")\n}\n\nstruct StripeKeySpec {\n key: String,\n required: bool,\n secret: bool,\n description: &'static str,\n test_steps: &'static [&'static str],\n live_steps: &'static [&'static str],\n expected_test_prefix: Option<&'static str>,\n expected_live_prefix: Option<&'static str>,\n}\n\nimpl StripeKeySpec {\n fn instructions(&self, mode: StripeModeArg) -> &'static [&'static str] {\n match mode {\n StripeModeArg::Test => self.test_steps,\n StripeModeArg::Live => self.live_steps,\n }\n }\n\n fn expected_prefix(&self, mode: StripeModeArg) -> Option<&'static str> {\n match mode {\n StripeModeArg::Test => self.expected_test_prefix,\n StripeModeArg::Live => self.expected_live_prefix,\n }\n }\n}\n\nfn stripe_key_spec(key: &str) -> StripeKeySpec {\n match key {\n \"STRIPE_SECRET_KEY\" => StripeKeySpec {\n key: key.to_string(),\n required: true,\n secret: true,\n description: \"Server secret key for Stripe API access.\",\n test_steps: &[\n \"Stripe Dashboard (test mode) -> Developers -> API keys.\",\n \"Copy the Secret key (starts with sk_test_).\",\n ],\n live_steps: &[\n \"Stripe Dashboard (live mode) -> Developers -> API keys.\",\n \"Copy the Secret key (starts with sk_live_).\",\n ],\n expected_test_prefix: Some(\"sk_test_\"),\n expected_live_prefix: Some(\"sk_live_\"),\n },\n \"VITE_STRIPE_PUBLISHABLE_KEY\" => StripeKeySpec {\n key: key.to_string(),\n required: true,\n secret: false,\n description: \"Client publishable key for Stripe.js.\",\n test_steps: &[\n \"Stripe Dashboard (test mode) -> Developers -> API keys.\",\n \"Copy the Publishable key (starts with pk_test_).\",\n ],\n live_steps: &[\n \"Stripe Dashboard (live mode) -> Developers -> API keys.\",\n \"Copy the Publishable key (starts with pk_live_).\",\n ],\n expected_test_prefix: Some(\"pk_test_\"),\n expected_live_prefix: Some(\"pk_live_\"),\n },\n \"STRIPE_WEBHOOK_SECRET\" => StripeKeySpec {\n key: key.to_string(),\n required: true,\n secret: true,\n description: \"Webhook signing secret for Stripe events.\",\n test_steps: &[\n \"Local dev: run `stripe listen --print-secret` to get a whsec_... value.\",\n \"Or Stripe Dashboard (test mode) -> Developers -> Webhooks -> Add endpoint.\",\n ],\n live_steps: &[\n \"Stripe Dashboard (live mode) -> Developers -> Webhooks -> Add endpoint.\",\n \"Copy the Signing secret (starts with whsec_).\",\n ],\n expected_test_prefix: Some(\"whsec_\"),\n expected_live_prefix: Some(\"whsec_\"),\n },\n \"STRIPE_PRO_PRICE_ID\" => StripeKeySpec {\n key: key.to_string(),\n required: true,\n secret: false,\n description: \"Price ID for your main subscription plan.\",\n test_steps: &[\n \"Stripe Dashboard (test mode) -> Products -> select your plan.\",\n \"Copy the Price ID (starts with price_).\",\n ],\n live_steps: &[\n \"Stripe Dashboard (live mode) -> Products -> select your plan.\",\n \"Copy the Price ID (starts with price_).\",\n ],\n expected_test_prefix: Some(\"price_\"),\n expected_live_prefix: Some(\"price_\"),\n },\n \"STRIPE_REFILL_PRICE_ID\" => StripeKeySpec {\n key: key.to_string(),\n required: false,\n secret: false,\n description: \"Optional price ID for top-up/refill credits.\",\n test_steps: &[\n \"Stripe Dashboard (test mode) -> Products -> create a refill product.\",\n \"Copy the Price ID (starts with price_).\",\n ],\n live_steps: &[\n \"Stripe Dashboard (live mode) -> Products -> create a refill product.\",\n \"Copy the Price ID (starts with price_).\",\n ],\n expected_test_prefix: Some(\"price_\"),\n expected_live_prefix: Some(\"price_\"),\n },\n _ => {\n let is_secret = key.contains(\"SECRET\") || key.contains(\"WEBHOOK\");\n StripeKeySpec {\n key: key.to_string(),\n required: false,\n secret: is_secret,\n description: \"Stripe-related configuration value.\",\n test_steps: &[\"Stripe Dashboard (test mode) -> copy the requested value.\"],\n live_steps: &[\"Stripe Dashboard (live mode) -> copy the requested value.\"],\n expected_test_prefix: None,\n expected_live_prefix: None,\n }\n }\n }\n}\n\nfn resolve_project_root(path: Option<&PathBuf>) -> Result<(PathBuf, PathBuf, config::Config)> {\n let start = match path {\n Some(path) => path.clone(),\n None => std::env::current_dir().context(\"failed to read current directory\")?,\n };\n let flow_path = if start.is_file()\n && start.file_name().and_then(|name| name.to_str()) == Some(\"flow.toml\")\n {\n start.clone()\n } else {\n find_flow_toml(&start)\n .ok_or_else(|| anyhow::anyhow!(\"flow.toml not found. Run from a Flow project.\"))?\n };\n let project_root = flow_path\n .parent()\n .map(|p| p.to_path_buf())\n .unwrap_or_else(|| start.clone());\n let flow_cfg = config::load(&flow_path)?;\n Ok((project_root, flow_path, flow_cfg))\n}\n\nfn find_flow_toml(start: &PathBuf) -> Option<PathBuf> {\n let mut current = start.clone();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\nstruct DirGuard {\n previous: PathBuf,\n}\n\nimpl DirGuard {\n fn new(path: &Path) -> Result<Self> {\n let previous = std::env::current_dir().context(\"failed to read current directory\")?;\n std::env::set_current_dir(path)\n .with_context(|| format!(\"failed to switch to {}\", path.display()))?;\n Ok(Self { previous })\n }\n}\n\nimpl Drop for DirGuard {\n fn drop(&mut self) {\n let _ = std::env::set_current_dir(&self.previous);\n }\n}\n\nfn prompt_line(message: &str, default: Option<&str>) -> Result<String> {\n if let Some(default) = default {\n print!(\"{message} [{default}]: \");\n } else {\n print!(\"{message}: \");\n }\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n return Ok(default.unwrap_or(\"\").to_string());\n }\n Ok(trimmed.to_string())\n}\n\nfn prompt_secret(message: &str) -> Result<String> {\n print!(\"{message}: \");\n io::stdout().flush()?;\n let input = rpassword::read_password().context(\"failed to read secret input\")?;\n Ok(input.trim().to_string())\n}\n\nfn prompt_yes_no(message: &str, default_yes: bool) -> Result<bool> {\n let prompt = if default_yes { \"[Y/n]\" } else { \"[y/N]\" };\n print!(\"{message} {prompt}: \");\n io::stdout().flush()?;\n if io::stdin().is_terminal() {\n return read_yes_no_key(default_yes);\n }\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n if answer.is_empty() {\n return Ok(default_yes);\n }\n Ok(answer == \"y\" || answer == \"yes\")\n}\n\nfn read_yes_no_key(default_yes: bool) -> Result<bool> {\n enable_raw_mode().context(\"failed to enable raw mode\")?;\n let mut selection = default_yes;\n let mut echo_char: Option<char> = None;\n loop {\n if let CEvent::Key(key) = event::read()? {\n match key.code {\n KeyCode::Char('y') | KeyCode::Char('Y') => {\n selection = true;\n echo_char = Some('y');\n break;\n }\n KeyCode::Char('n') | KeyCode::Char('N') => {\n selection = false;\n echo_char = Some('n');\n break;\n }\n KeyCode::Enter => {\n break;\n }\n KeyCode::Esc => {\n selection = false;\n break;\n }\n _ => {}\n }\n }\n }\n\n disable_raw_mode().context(\"failed to disable raw mode\")?;\n if let Some(ch) = echo_char {\n println!(\"{ch}\");\n } else {\n println!();\n }\n Ok(selection)\n}\n" }, { "path": "src/setup.rs", "content": "use std::collections::{BTreeMap, HashMap, HashSet};\nuse std::fs;\nuse std::io::{self, IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\nuse std::time::{SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result};\nuse crossterm::event::{self, Event as CEvent, KeyCode};\nuse crossterm::terminal::{disable_raw_mode, enable_raw_mode};\nuse ignore::WalkBuilder;\nuse serde::{Deserialize, Serialize};\n\nuse crate::{\n agents,\n cli::{SetupOpts, SetupTarget, TaskRunOpts},\n config, deploy, docs, skills, start,\n tasks::{self, load_project_config},\n};\n\npub fn run(opts: SetupOpts) -> Result<()> {\n let (project_root, config_path) = resolve_project_root(&opts.config)?;\n let mut created_flow_toml = false;\n let mut upgraded_flow_toml = false;\n\n match opts.target {\n Some(SetupTarget::Docs) => {\n return docs::create_docs_scaffold_at(&project_root, false);\n }\n Some(SetupTarget::Deploy) => {\n return setup_deploy(&project_root, &config_path);\n }\n Some(SetupTarget::Release) => {\n return setup_release(&project_root, &config_path);\n }\n None => {}\n }\n\n if maybe_run_existing_setup_task(&config_path)? {\n return Ok(());\n }\n\n if !start::is_bootstrapped(&project_root) || !config_path.exists() {\n start::run_at(&project_root)?;\n }\n\n if !config_path.exists() {\n create_flow_toml_auto(&project_root, &config_path)?;\n created_flow_toml = true;\n }\n if !created_flow_toml {\n match maybe_upgrade_existing_flow_toml(&project_root, &config_path) {\n Ok(true) => {\n upgraded_flow_toml = true;\n println!(\"Updated flow.toml with Codex-first baseline sections.\");\n }\n Ok(false) => {}\n Err(err) => {\n eprintln!(\"⚠ failed to update flow.toml baseline: {err}\");\n }\n }\n }\n\n let (config_path, cfg) = load_project_config(config_path)?;\n\n // Ensure Codex/Claude skills are present before running any setup task.\n // This is the main entrypoint users expect to \"load project skills\".\n let skills_summary = skills::ensure_project_skills_at(&project_root, &cfg)?;\n if !skills_summary.is_noop() {\n if skills_summary.task_skills_created > 0 || skills_summary.task_skills_updated > 0 {\n println!(\n \"✓ Synced flow.toml tasks to .ai/skills (created {}, updated {})\",\n skills_summary.task_skills_created, skills_summary.task_skills_updated\n );\n }\n if !skills_summary.installed_skills.is_empty() {\n println!(\n \"✓ Installed skills: {}\",\n skills_summary.installed_skills.join(\", \")\n );\n }\n }\n\n if upgraded_flow_toml {\n skills::maybe_reload_codex_skills(\n &project_root,\n cfg.skills.as_ref(),\n \"setup baseline upgrade\",\n );\n }\n\n ensure_bike_gitignore(&project_root)?;\n ensure_project_dependencies(&cfg)?;\n ensure_pnpm_only_built_deps(&project_root)?;\n\n if tasks::find_task(&cfg, \"setup\").is_some() {\n if created_flow_toml {\n println!(\"Running setup task...\");\n }\n let config_path_for_task = config_path.clone();\n let result = tasks::run(TaskRunOpts {\n config: config_path_for_task,\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: \"setup\".to_string(),\n args: Vec::new(),\n });\n if let Err(err) = refresh_skills_after_setup_task(&project_root, &config_path) {\n eprintln!(\"⚠ failed to refresh project skills after setup task: {err}\");\n }\n if result.is_ok() {\n if let Err(err) = write_setup_checkpoint(&project_root, &config_path) {\n eprintln!(\"⚠ failed to write setup checkpoint: {err}\");\n }\n }\n return result;\n }\n\n if cfg.aliases.is_empty() {\n println!(\n \"# No setup task or aliases defined in {}.\",\n config_path.display()\n );\n println!(\"# Add a setup task or an alias table like:\");\n println!(\"# [[alias]]\");\n println!(\"# fr = \\\"f run\\\"\");\n if let Err(err) = write_setup_checkpoint(&project_root, &config_path) {\n eprintln!(\"⚠ failed to write setup checkpoint: {err}\");\n }\n return Ok(());\n }\n\n println!(\"# flow aliases from {}\", config_path.display());\n println!(\n \"# Apply them in your shell with: eval \\\"$(f setup --config {})\\\"\",\n config_path.display()\n );\n\n for line in format_alias_lines(&cfg.aliases) {\n println!(\"{line}\");\n }\n\n if let Err(err) = write_setup_checkpoint(&project_root, &config_path) {\n eprintln!(\"⚠ failed to write setup checkpoint: {err}\");\n }\n\n Ok(())\n}\n\nfn maybe_run_existing_setup_task(config_path: &Path) -> Result<bool> {\n if !config_path.exists() {\n return Ok(false);\n }\n\n let (config_path, cfg) = load_project_config(config_path.to_path_buf())?;\n if tasks::find_task(&cfg, \"setup\").is_none() {\n return Ok(false);\n }\n\n tasks::run(TaskRunOpts {\n config: config_path,\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: \"setup\".to_string(),\n args: Vec::new(),\n })?;\n\n Ok(true)\n}\n\nfn refresh_skills_after_setup_task(project_root: &Path, config_path: &Path) -> Result<()> {\n let (_, cfg) = load_project_config(config_path.to_path_buf())?;\n let summary = skills::ensure_project_skills_at(project_root, &cfg)?;\n if !summary.is_noop() {\n if summary.task_skills_created > 0 || summary.task_skills_updated > 0 {\n println!(\n \"✓ Refreshed flow.toml tasks to .ai/skills after setup (created {}, updated {})\",\n summary.task_skills_created, summary.task_skills_updated\n );\n }\n if !summary.installed_skills.is_empty() {\n println!(\n \"✓ Installed skills after setup: {}\",\n summary.installed_skills.join(\", \")\n );\n }\n skills::maybe_reload_codex_skills(\n project_root,\n cfg.skills.as_ref(),\n \"setup post-task skill sync\",\n );\n }\n Ok(())\n}\n\n#[derive(Serialize)]\nstruct SetupCheckpoint {\n version: u32,\n commit: String,\n timestamp_ms: u64,\n config_path: String,\n source: String,\n}\n\nfn current_git_commit(project_root: &Path) -> Option<String> {\n let output = Command::new(\"git\")\n .arg(\"-C\")\n .arg(project_root)\n .arg(\"rev-parse\")\n .arg(\"HEAD\")\n .stdout(Stdio::piped())\n .stderr(Stdio::null())\n .output()\n .ok()?;\n if !output.status.success() {\n return None;\n }\n let commit = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if commit.is_empty() {\n None\n } else {\n Some(commit)\n }\n}\n\nfn write_setup_checkpoint(project_root: &Path, config_path: &Path) -> Result<()> {\n let rise_dir = project_root.join(\".rise\");\n fs::create_dir_all(&rise_dir)?;\n let timestamp_ms = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .unwrap_or_default()\n .as_millis() as u64;\n let checkpoint = SetupCheckpoint {\n version: 1,\n commit: current_git_commit(project_root).unwrap_or_default(),\n timestamp_ms,\n config_path: config_path.display().to_string(),\n source: \"flow\".to_string(),\n };\n let payload = serde_json::to_string_pretty(&checkpoint)?;\n fs::write(rise_dir.join(\"setup.json\"), payload)?;\n Ok(())\n}\n\nfn ensure_bike_gitignore(project_root: &Path) -> Result<()> {\n add_gitignore_entry(project_root, \".ai/todos/*.bike\")?;\n add_gitignore_entry(project_root, \".ai/review-log.jsonl\")\n}\n\nfn ensure_project_dependencies(cfg: &config::Config) -> Result<()> {\n if cfg.dependencies.is_empty() {\n return Ok(());\n }\n\n let mut commands = Vec::new();\n for spec in cfg.dependencies.values() {\n spec.extend_commands(&mut commands);\n }\n\n let mut missing = std::collections::BTreeSet::new();\n for command in commands {\n if which::which(&command).is_err() {\n missing.insert(command);\n }\n }\n\n if missing.is_empty() {\n return Ok(());\n }\n\n println!(\n \"Missing dependencies: {}\",\n missing.iter().cloned().collect::<Vec<_>>().join(\", \")\n );\n\n if !brew_available() {\n println!(\"Homebrew not found. Install missing deps manually.\");\n return Ok(());\n }\n\n let mut packages = std::collections::BTreeSet::new();\n for command in &missing {\n if let Some(pkg) = brew_package_for_command(command) {\n packages.insert(pkg);\n } else {\n println!(\n \" - No brew mapping for '{}'; install it manually.\",\n command\n );\n }\n }\n\n if packages.is_empty() {\n return Ok(());\n }\n\n println!(\n \"Installing missing deps with Homebrew: {}\",\n packages.iter().cloned().collect::<Vec<_>>().join(\", \")\n );\n\n for pkg in packages {\n let status = Command::new(\"brew\")\n .args([\"install\", &pkg])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .with_context(|| format!(\"failed to run brew install {}\", pkg))?;\n if !status.success() {\n println!(\" - brew install {} failed; install it manually.\", pkg);\n }\n }\n\n Ok(())\n}\n\nfn brew_available() -> bool {\n Command::new(\"brew\")\n .arg(\"--version\")\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .map(|s| s.success())\n .unwrap_or(false)\n}\n\nfn brew_package_for_command(command: &str) -> Option<String> {\n match command {\n \"pnpm\" => Some(\"pnpm\".to_string()),\n \"yarn\" => Some(\"yarn\".to_string()),\n \"bun\" => Some(\"bun\".to_string()),\n \"node\" | \"npm\" => Some(\"node\".to_string()),\n \"python\" | \"python3\" => Some(\"python\".to_string()),\n \"go\" => Some(\"go\".to_string()),\n \"rustc\" | \"cargo\" => Some(\"rust\".to_string()),\n \"wasm-pack\" => Some(\"wasm-pack\".to_string()),\n _ => None,\n }\n}\n\nfn ensure_pnpm_only_built_deps(project_root: &Path) -> Result<()> {\n let workspace_path = project_root.join(\"pnpm-workspace.yaml\");\n if !workspace_path.exists() {\n return Ok(());\n }\n\n let mut content = fs::read_to_string(&workspace_path)\n .with_context(|| format!(\"failed to read {}\", workspace_path.display()))?;\n let mut needed = std::collections::BTreeSet::new();\n if repo_contains_package(project_root, \"electron\") {\n needed.insert(\"electron\".to_string());\n }\n if repo_contains_package(project_root, \"@swc/core\") {\n needed.insert(\"@swc/core\".to_string());\n }\n\n if needed.is_empty() {\n return Ok(());\n }\n\n let has_only_built = content.contains(\"onlyBuiltDependencies:\");\n let mut lines: Vec<String> = content.lines().map(|l| l.to_string()).collect();\n let mut start_idx = None;\n for (idx, line) in lines.iter().enumerate() {\n if line.trim() == \"onlyBuiltDependencies:\" {\n start_idx = Some(idx);\n break;\n }\n }\n\n if start_idx.is_none() {\n lines.push(\"\".to_string());\n lines.push(\"onlyBuiltDependencies:\".to_string());\n start_idx = Some(lines.len() - 1);\n }\n\n let start_idx = start_idx.unwrap();\n\n let mut existing = std::collections::BTreeSet::new();\n let mut insert_at = start_idx + 1;\n for idx in start_idx + 1..lines.len() {\n let line = lines[idx].trim();\n if !line.starts_with(\"- \") {\n insert_at = idx;\n break;\n }\n existing.insert(line.trim_start_matches(\"- \").trim().to_string());\n insert_at = idx + 1;\n }\n\n let missing: Vec<String> = needed\n .into_iter()\n .filter(|dep| !existing.contains(dep))\n .collect();\n if missing.is_empty() {\n return Ok(());\n }\n\n for (offset, dep) in missing.iter().enumerate() {\n lines.insert(insert_at + offset, format!(\" - {}\", dep));\n }\n\n content = lines.join(\"\\n\");\n if !content.ends_with('\\n') {\n content.push('\\n');\n }\n fs::write(&workspace_path, content)\n .with_context(|| format!(\"failed to update {}\", workspace_path.display()))?;\n if has_only_built {\n println!(\n \"Updated pnpm-workspace.yaml onlyBuiltDependencies with: {}\",\n missing.join(\", \")\n );\n } else {\n println!(\n \"Added pnpm-workspace.yaml onlyBuiltDependencies with: {}\",\n missing.join(\", \")\n );\n }\n Ok(())\n}\n\nfn repo_contains_package(project_root: &Path, needle: &str) -> bool {\n let walker = WalkBuilder::new(project_root)\n .hidden(false)\n .ignore(true)\n .git_ignore(true)\n .git_exclude(true)\n .build();\n\n for entry in walker.flatten() {\n if entry.path().file_name().and_then(|n| n.to_str()) != Some(\"package.json\") {\n continue;\n }\n if let Ok(text) = fs::read_to_string(entry.path()) {\n if text.contains(&format!(\"\\\"{}\\\"\", needle)) {\n return true;\n }\n }\n }\n false\n}\n\nfn resolve_project_root(config_path: &PathBuf) -> Result<(PathBuf, PathBuf)> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n let resolved = if config_path.is_absolute() {\n config_path.clone()\n } else {\n cwd.join(config_path)\n };\n let root = resolved.parent().map(|p| p.to_path_buf()).unwrap_or(cwd);\n Ok((root, resolved))\n}\n\nfn setup_deploy(project_root: &Path, config_path: &Path) -> Result<()> {\n let server_reason = detect_server_project(project_root);\n let auto_mode = server_reason.is_some();\n\n if !config_path.exists() {\n if auto_mode {\n create_flow_toml_auto(project_root, config_path)?;\n } else {\n create_flow_toml_interactive(project_root, config_path)?;\n }\n }\n\n let mut flow_content = fs::read_to_string(config_path).unwrap_or_default();\n if has_host_section(&flow_content) {\n if auto_mode {\n repair_existing_host_config(project_root, config_path, &flow_content)?;\n } else {\n println!(\"flow.toml already includes [host] configuration.\");\n }\n return Ok(());\n }\n\n let is_tty = io::stdin().is_terminal();\n let mut defaults = deploy_defaults(project_root);\n\n if let Some(reason) = server_reason.as_deref() {\n println!(\"Detected server project: {reason}\");\n if !auto_mode && is_tty && !prompt_yes_no(\"Configure Linux host deployment now?\", true)? {\n println!(\"Skipped host setup. Run `f setup deploy` later to configure.\");\n return Ok(());\n }\n\n let _ = deploy::ensure_deploy_helper();\n\n let template = load_server_setup_template();\n if let Some(template) = template.as_ref() {\n println!(\"Using server setup template from {}.\", template.source);\n }\n apply_server_template(&mut defaults, template.as_ref(), project_root);\n\n if !auto_mode && is_tty && prompt_yes_no(\"Use AI to draft host config?\", true)? {\n println!(\"Generating host config with AI...\");\n io::stdout().flush()?;\n let result = generate_host_config_with_agent(project_root, None);\n match result {\n Ok(text) => {\n if let Some(host_cfg) = extract_host_config(&text) {\n if let Some(reason) = host_config_mismatch_reason(project_root, &host_cfg) {\n println!(\"Warning: {}\", reason);\n println!(\"Using detected defaults instead.\");\n } else {\n apply_host_overrides(&mut defaults, &host_cfg);\n }\n } else {\n println!(\"Warning: AI output did not include [host] config.\");\n }\n }\n Err(err) => {\n println!(\"Warning: AI generation failed: {}\", err);\n }\n }\n }\n }\n\n let (dest, run, service, setup_script, env_file, domain, ssl, port) = if server_reason.is_some()\n {\n (\n defaults.dest.clone(),\n defaults.run.clone(),\n Some(defaults.service.clone()),\n normalize_optional(defaults.setup_path.clone()),\n defaults.env_file.clone(),\n defaults.domain.clone(),\n defaults.ssl && defaults.domain.is_some(),\n if defaults.domain.is_some() {\n defaults.port\n } else {\n None\n },\n )\n } else {\n let dest = if is_tty {\n prompt_line(\"Remote deploy path\", Some(&defaults.dest))?\n } else {\n defaults.dest.clone()\n };\n\n let run = if is_tty {\n let value = prompt_line(\"Run command\", defaults.run.as_deref())?;\n normalize_optional(value)\n } else {\n defaults.run.clone()\n };\n\n if run.is_none() {\n println!(\"Warning: no run command set; deploy will not create a systemd service.\");\n }\n\n let service = if is_tty {\n let value = prompt_line(\"Systemd service name\", Some(&defaults.service))?;\n normalize_optional(value)\n } else {\n Some(defaults.service.clone())\n };\n\n let setup_script = if is_tty {\n let value = prompt_line(\n \"Setup script path (relative to repo)\",\n Some(&defaults.setup_path),\n )?;\n normalize_optional(value)\n } else {\n Some(defaults.setup_path.clone())\n };\n\n let env_file = if is_tty {\n prompt_line_optional(\n \"Env file to upload (copied to remote as .env)\",\n defaults.env_file.as_deref(),\n )?\n } else {\n defaults.env_file.clone()\n };\n\n let domain = if is_tty {\n prompt_line_optional(\"Domain (blank to skip)\", defaults.domain.as_deref())?\n } else {\n defaults.domain.clone()\n };\n\n let ssl = if is_tty && domain.is_some() {\n prompt_yes_no(\"Enable SSL via Let's Encrypt?\", defaults.ssl)?\n } else {\n defaults.ssl && domain.is_some()\n };\n\n let port = if domain.is_some() {\n if is_tty {\n prompt_u16_optional(\"Service port for nginx\", defaults.port)?\n } else {\n defaults.port\n }\n } else {\n None\n };\n\n (\n dest,\n run,\n service,\n setup_script,\n env_file,\n domain,\n ssl,\n port,\n )\n };\n\n if server_reason.is_some() && run.is_none() {\n println!(\"Warning: no run command set; deploy will not create a systemd service.\");\n }\n\n if let Some(script_path) = setup_script.as_ref() {\n if let Some(content) = defaults.setup_script_content.as_deref() {\n ensure_setup_script(project_root, script_path, content, false)?;\n }\n }\n\n if let Some(env_path) = env_file.as_ref() {\n ensure_env_file(\n project_root,\n env_path,\n defaults.env_example.as_ref(),\n !auto_mode && is_tty,\n auto_mode,\n )?;\n }\n\n if auto_mode {\n maybe_configure_deploy_host(true)?;\n } else if is_tty {\n maybe_configure_deploy_host(false)?;\n }\n\n let host_cfg = HostSetupConfig {\n dest,\n setup: setup_script,\n run,\n port,\n service,\n env_file,\n domain,\n ssl,\n };\n\n let host_section = render_host_section(&host_cfg);\n flow_content = append_section(&flow_content, &host_section);\n fs::write(config_path, flow_content)\n .with_context(|| format!(\"failed to write {}\", config_path.display()))?;\n\n println!(\"Added [host] config to flow.toml.\");\n println!(\"Next: run `f deploy` to deploy.\");\n Ok(())\n}\n\nfn setup_release(project_root: &Path, config_path: &Path) -> Result<()> {\n if !config_path.exists() {\n create_flow_toml_interactive(project_root, config_path)?;\n }\n\n let mut flow_content = fs::read_to_string(config_path).unwrap_or_default();\n if has_host_section(&flow_content) {\n println!(\"flow.toml already includes [host] configuration.\");\n return Ok(());\n }\n\n let Some(reason) = detect_server_project(project_root) else {\n println!(\"No server project detected. Add [host] manually or run `f setup deploy`.\");\n return Ok(());\n };\n println!(\"Detected server project: {reason}\");\n\n if io::stdin().is_terminal() && !prompt_yes_no(\"Configure Linux host deployment now?\", true)? {\n println!(\"Skipped host setup. Run `f setup deploy` or edit flow.toml later.\");\n return Ok(());\n }\n\n let template = load_server_setup_template();\n if let Some(template) = template.as_ref() {\n println!(\"Using server setup template from {}.\", template.source);\n }\n\n let mut defaults = deploy_defaults(project_root);\n apply_server_template(&mut defaults, template.as_ref(), project_root);\n\n if defaults.run.is_none() {\n println!(\"Warning: no run command set; deploy will not create a systemd service.\");\n }\n\n if let Some(content) = defaults.setup_script_content.as_deref() {\n if !defaults.setup_path.trim().is_empty() {\n ensure_setup_script(project_root, &defaults.setup_path, content, false)?;\n }\n }\n\n if let Some(env_path) = defaults.env_file.as_ref() {\n ensure_env_file(\n project_root,\n env_path,\n defaults.env_example.as_ref(),\n false,\n false,\n )?;\n }\n\n if io::stdin().is_terminal() {\n maybe_configure_deploy_host(false)?;\n }\n\n let host_cfg = HostSetupConfig {\n dest: defaults.dest,\n setup: normalize_optional(defaults.setup_path),\n run: defaults.run,\n port: defaults.port,\n service: Some(defaults.service),\n env_file: defaults.env_file,\n domain: defaults.domain,\n ssl: defaults.ssl,\n };\n\n let host_section = render_host_section(&host_cfg);\n flow_content = append_section(&flow_content, &host_section);\n fs::write(config_path, flow_content)\n .with_context(|| format!(\"failed to write {}\", config_path.display()))?;\n\n println!(\"Added [host] config to flow.toml.\");\n println!(\"Next: run `f deploy` to deploy.\");\n Ok(())\n}\n\nfn create_flow_toml_interactive(project_root: &Path, config_path: &Path) -> Result<()> {\n println!(\"No flow.toml found. Let's create one.\");\n\n if !io::stdin().is_terminal() {\n let content = default_flow_template(project_root);\n write_flow_toml(config_path, &content)?;\n return Ok(());\n }\n\n let use_ai = prompt_yes_no(\"Generate setup/dev tasks with AI?\", true)?;\n let mut content: Option<String> = None;\n let mut streamed_ai_output = false;\n let mut used_ai_content = false;\n\n if use_ai {\n let hint_input = prompt_optional(\"Any notes about how dev should run? (optional)\")?;\n let hint = if hint_input.trim().is_empty() {\n None\n } else {\n Some(hint_input.as_str())\n };\n println!(\"Generating flow.toml with AI...\");\n io::stdout().flush()?;\n let use_streaming = io::stdin().is_terminal();\n let result = if use_streaming {\n generate_flow_toml_with_agent_streaming(project_root, hint)\n } else {\n generate_flow_toml_with_agent(project_root, hint)\n };\n match result {\n Ok(text) => {\n if use_streaming {\n streamed_ai_output = true;\n }\n if let Some(toml) = extract_flow_toml(&text) {\n if let Some(reason) = ai_flow_toml_mismatch_reason(project_root, &toml) {\n println!(\"Warning: {}\", reason);\n println!(\"Using detected defaults instead.\");\n } else {\n content = Some(toml);\n used_ai_content = true;\n }\n } else {\n println!(\"Warning: AI output did not include flow.toml content.\");\n }\n }\n Err(err) => {\n println!(\"Warning: AI generation failed: {}\", err);\n }\n }\n }\n\n if content.is_none() {\n let defaults = suggested_commands(project_root);\n let setup_cmd = defaults.setup.unwrap_or_default();\n let dev_cmd = defaults.dev.unwrap_or_default();\n content = Some(render_flow_toml(&setup_cmd, &dev_cmd, defaults.deps));\n println!(\"Using detected defaults. Edit flow.toml if needed.\");\n }\n\n let mut content =\n ensure_trailing_newline(content.unwrap_or_else(|| default_flow_template(project_root)));\n let enable_bun_testing_gate = detect_bun_context(project_root, &content);\n content = ensure_codex_flow_baseline(&content, enable_bun_testing_gate);\n\n if !used_ai_content || !streamed_ai_output {\n println!(\"\\nProposed flow.toml:\\n\");\n println!(\"{}\", content);\n }\n write_flow_toml(config_path, &content)?;\n println!(\"Created flow.toml\");\n Ok(())\n}\n\nfn create_flow_toml_auto(project_root: &Path, config_path: &Path) -> Result<()> {\n println!(\"No flow.toml found. Creating with detected defaults.\\n\");\n let mut content = ensure_trailing_newline(default_flow_template(project_root));\n let enable_bun_testing_gate = detect_bun_context(project_root, &content);\n content = ensure_codex_flow_baseline(&content, enable_bun_testing_gate);\n println!(\"{}\", content);\n write_flow_toml(config_path, &content)?;\n println!(\"Created flow.toml\");\n Ok(())\n}\n\nfn maybe_upgrade_existing_flow_toml(project_root: &Path, config_path: &Path) -> Result<bool> {\n if !config_path.exists() {\n return Ok(false);\n }\n\n let current = fs::read_to_string(config_path)\n .with_context(|| format!(\"failed to read {}\", config_path.display()))?;\n let current = ensure_trailing_newline(current);\n let enable_bun_testing_gate = detect_bun_context(project_root, ¤t);\n let updated = ensure_codex_flow_baseline(¤t, enable_bun_testing_gate);\n if updated == current {\n return Ok(false);\n }\n\n write_flow_toml(config_path, &updated)?;\n Ok(true)\n}\n\nfn repair_existing_host_config(\n project_root: &Path,\n config_path: &Path,\n flow_content: &str,\n) -> Result<()> {\n let Some(reason) = detect_server_project(project_root) else {\n println!(\"flow.toml already includes [host] configuration.\");\n return Ok(());\n };\n println!(\"Detected server project: {reason}\");\n\n let cfg = config::load(config_path)?;\n let Some(mut host_cfg) = cfg.host else {\n println!(\"flow.toml already includes [host] configuration.\");\n return Ok(());\n };\n\n let mut defaults = deploy_defaults(project_root);\n let template = load_server_setup_template();\n apply_server_template(&mut defaults, template.as_ref(), project_root);\n\n let mut changed = false;\n let mut force_setup_script = false;\n\n if host_cfg.dest.is_none() {\n host_cfg.dest = Some(defaults.dest.clone());\n changed = true;\n }\n\n if host_cfg.run.is_none() {\n if let Some(run) = defaults.run.clone() {\n host_cfg.run = Some(run);\n changed = true;\n }\n } else if let Some(run) = host_cfg.run.as_deref() {\n if let Some(default_run) = defaults.run.clone() {\n if let Some(reason) = command_mismatch_reason(project_root, run) {\n println!(\"Warning: replacing run command: {reason}\");\n host_cfg.run = Some(default_run);\n changed = true;\n }\n }\n }\n\n if host_cfg.service.is_none() {\n host_cfg.service = Some(defaults.service.clone());\n changed = true;\n }\n\n if host_cfg.setup.is_none() {\n if !defaults.setup_path.trim().is_empty() {\n host_cfg.setup = Some(defaults.setup_path.clone());\n changed = true;\n }\n } else if let Some(setup) = host_cfg.setup.as_deref() {\n if let Some(reason) = setup_script_mismatch_reason(project_root, setup) {\n println!(\"Warning: replacing setup script: {reason}\");\n if !defaults.setup_path.trim().is_empty() {\n host_cfg.setup = Some(defaults.setup_path.clone());\n changed = true;\n force_setup_script = true;\n }\n }\n }\n\n if host_cfg.env_file.is_none() {\n if let Some(env_file) = defaults.env_file.clone() {\n host_cfg.env_file = Some(env_file);\n changed = true;\n }\n }\n\n if let Some(setup_path) = host_cfg.setup.as_deref() {\n if let Some(content) = defaults.setup_script_content.as_deref() {\n ensure_setup_script(project_root, setup_path, content, force_setup_script)?;\n }\n }\n\n if let Some(env_path) = host_cfg.env_file.as_deref() {\n ensure_env_file(\n project_root,\n env_path,\n defaults.env_example.as_ref(),\n false,\n true,\n )?;\n }\n\n maybe_configure_deploy_host(true)?;\n\n if host_cfg.run.is_none() {\n println!(\"Warning: no run command set; deploy will not create a systemd service.\");\n }\n\n if changed {\n let host_section = render_host_section(&HostSetupConfig {\n dest: host_cfg.dest.unwrap_or_else(|| defaults.dest.clone()),\n setup: host_cfg.setup,\n run: host_cfg.run,\n port: host_cfg.port,\n service: host_cfg.service,\n env_file: host_cfg.env_file,\n domain: host_cfg.domain,\n ssl: host_cfg.ssl,\n });\n let updated = replace_host_section(flow_content, &host_section);\n fs::write(config_path, updated)\n .with_context(|| format!(\"failed to write {}\", config_path.display()))?;\n println!(\"Updated [host] config in flow.toml.\");\n } else {\n println!(\"Host config looks good.\");\n }\n\n Ok(())\n}\n\nstruct DeployDefaults {\n dest: String,\n run: Option<String>,\n service: String,\n setup_path: String,\n setup_script_content: Option<String>,\n env_example: Option<PathBuf>,\n env_file: Option<String>,\n port: Option<u16>,\n domain: Option<String>,\n ssl: bool,\n}\n\nstruct HostSetupConfig {\n dest: String,\n setup: Option<String>,\n run: Option<String>,\n port: Option<u16>,\n service: Option<String>,\n env_file: Option<String>,\n domain: Option<String>,\n ssl: bool,\n}\n\nstruct ServerSetupTemplate {\n host: deploy::HostConfig,\n source: String,\n}\n\nfn deploy_defaults(project_root: &Path) -> DeployDefaults {\n let project_name = guess_project_name(project_root);\n let dest = format!(\"/opt/{}\", project_name);\n let run = default_run_command(project_root, &project_name);\n let service = project_name.clone();\n let setup_path = \"deploy/setup.sh\".to_string();\n let setup_script_content = Some(default_setup_script(project_root));\n let env_example = find_env_example(project_root, &project_name);\n let env_file = env_example\n .as_ref()\n .and_then(|path| strip_example_suffix(project_root, path));\n let port = Some(8080);\n let domain = None;\n let ssl = false;\n\n DeployDefaults {\n dest,\n run,\n service,\n setup_path,\n setup_script_content,\n env_example,\n env_file,\n port,\n domain,\n ssl,\n }\n}\n\nfn load_server_setup_template() -> Option<ServerSetupTemplate> {\n let mut host_config: Option<deploy::HostConfig> = None;\n let mut source: Option<String> = None;\n\n let global_path = config::default_config_path();\n if global_path.exists() {\n if let Ok(cfg) = config::load(&global_path) {\n if let Some(setup) = cfg.setup {\n if let Some(server) = setup.server {\n if let Some(template_path) = server.template {\n let path = config::expand_path(&template_path);\n if path.exists() {\n if let Ok(template_cfg) = config::load(&path) {\n if let Some(host) = template_cfg.host {\n host_config = Some(host);\n source = Some(path.display().to_string());\n }\n }\n }\n }\n\n if let Some(host) = server.host {\n host_config = Some(match host_config {\n Some(existing) => merge_host_config(existing, host),\n None => host,\n });\n source = Some(format!(\"{} (inline)\", global_path.display()));\n }\n }\n }\n }\n }\n\n if host_config.is_none() {\n if let Ok(template) = std::env::var(\"FLOW_SETUP_TEMPLATE\") {\n let template_path = config::expand_path(&template);\n if template_path.exists() {\n if let Ok(cfg) = config::load(&template_path) {\n if let Some(host) = cfg.host {\n host_config = Some(host);\n source = Some(template_path.display().to_string());\n }\n }\n }\n }\n }\n\n host_config.map(|host| ServerSetupTemplate {\n host,\n source: source.unwrap_or_else(|| \"unknown\".to_string()),\n })\n}\n\nfn merge_host_config(base: deploy::HostConfig, overlay: deploy::HostConfig) -> deploy::HostConfig {\n deploy::HostConfig {\n dest: overlay.dest.or(base.dest),\n setup: overlay.setup.or(base.setup),\n run: overlay.run.or(base.run),\n port: overlay.port.or(base.port),\n service: overlay.service.or(base.service),\n env_file: overlay.env_file.or(base.env_file),\n env_source: overlay.env_source.or(base.env_source),\n env_keys: if overlay.env_keys.is_empty() {\n base.env_keys\n } else {\n overlay.env_keys\n },\n env_project: overlay.env_project || base.env_project,\n environment: overlay.environment.or(base.environment),\n service_token: overlay.service_token.or(base.service_token),\n domain: overlay.domain.or(base.domain),\n ssl: overlay.ssl || base.ssl,\n }\n}\n\nfn apply_host_overrides(defaults: &mut DeployDefaults, host: &deploy::HostConfig) {\n if let Some(dest) = host.dest.as_deref() {\n defaults.dest = dest.to_string();\n }\n\n if let Some(run) = host.run.as_deref() {\n defaults.run = Some(run.to_string());\n }\n\n if let Some(service) = host.service.as_deref() {\n defaults.service = service.to_string();\n }\n\n if let Some(setup) = host.setup.as_deref() {\n if looks_like_inline_script(setup) {\n defaults.setup_script_content = Some(setup.to_string());\n } else if !setup.trim().is_empty() {\n defaults.setup_path = setup.to_string();\n defaults.setup_script_content = None;\n }\n }\n\n if let Some(env_file) = host.env_file.as_deref() {\n if !env_file.trim().is_empty() {\n defaults.env_file = Some(env_file.to_string());\n }\n }\n\n if let Some(port) = host.port {\n defaults.port = Some(port);\n }\n\n if let Some(domain) = host.domain.as_deref() {\n if !domain.trim().is_empty() {\n defaults.domain = Some(domain.to_string());\n }\n }\n\n if host.ssl {\n defaults.ssl = true;\n }\n}\n\nfn apply_server_template(\n defaults: &mut DeployDefaults,\n template: Option<&ServerSetupTemplate>,\n project_root: &Path,\n) {\n let Some(template) = template else {\n return;\n };\n let host = &template.host;\n\n if let Some(setup) = host.setup.as_ref() {\n if let Some(reason) = setup_script_mismatch_reason(project_root, setup) {\n println!(\"Warning: skipping template setup script: {reason}\");\n } else if looks_like_inline_script(setup) {\n defaults.setup_script_content = Some(setup.to_string());\n } else {\n defaults.setup_path = setup.to_string();\n defaults.setup_script_content = None;\n }\n }\n\n if defaults.dest.trim().is_empty() {\n if let Some(dest) = host.dest.as_deref() {\n defaults.dest = dest.to_string();\n }\n }\n if defaults.run.is_none() {\n if let Some(run) = host.run.as_deref() {\n defaults.run = Some(run.to_string());\n }\n }\n if defaults.service.trim().is_empty() {\n if let Some(service) = host.service.as_deref() {\n defaults.service = service.to_string();\n }\n }\n\n if let Some(env_file) = host.env_file.as_ref() {\n if defaults.env_file.is_none() {\n defaults.env_file = Some(env_file.to_string());\n }\n }\n if host.port.is_some() {\n defaults.port = host.port;\n }\n if let Some(domain) = host.domain.as_ref() {\n defaults.domain = Some(domain.to_string());\n }\n if host.ssl {\n defaults.ssl = true;\n }\n}\n\nfn looks_like_inline_script(value: &str) -> bool {\n value.contains('\\n') || value.trim_start().starts_with(\"#!\") || value.contains(\"set -e\")\n}\n\nfn render_host_section(cfg: &HostSetupConfig) -> String {\n let mut out = String::from(\"[host]\\n\");\n out.push_str(&format!(\"dest = \\\"{}\\\"\\n\", toml_escape(&cfg.dest)));\n if let Some(setup) = &cfg.setup {\n out.push_str(&format!(\"setup = \\\"{}\\\"\\n\", toml_escape(setup)));\n }\n if let Some(run) = &cfg.run {\n out.push_str(&format!(\"run = \\\"{}\\\"\\n\", toml_escape(run)));\n }\n if let Some(port) = cfg.port {\n out.push_str(&format!(\"port = {port}\\n\"));\n }\n if let Some(service) = &cfg.service {\n out.push_str(&format!(\"service = \\\"{}\\\"\\n\", toml_escape(service)));\n }\n if let Some(env_file) = &cfg.env_file {\n out.push_str(&format!(\"env_file = \\\"{}\\\"\\n\", toml_escape(env_file)));\n }\n if let Some(domain) = &cfg.domain {\n out.push_str(&format!(\"domain = \\\"{}\\\"\\n\", toml_escape(domain)));\n }\n if cfg.ssl {\n out.push_str(\"ssl = true\\n\");\n }\n out\n}\n\nfn has_host_section(content: &str) -> bool {\n content.lines().any(|line| line.trim() == \"[host]\")\n}\n\nfn append_section(content: &str, section: &str) -> String {\n let mut out = content.to_string();\n if !out.ends_with('\\n') {\n out.push('\\n');\n }\n if !out.ends_with(\"\\n\\n\") {\n out.push('\\n');\n }\n out.push_str(section.trim_end());\n out.push('\\n');\n out\n}\n\nfn replace_host_section(content: &str, section: &str) -> String {\n let mut lines: Vec<String> = content.lines().map(|line| line.to_string()).collect();\n let had_trailing_newline = content.ends_with('\\n');\n let section_lines: Vec<String> = section\n .trim_end()\n .lines()\n .map(|line| line.to_string())\n .collect();\n\n if let Some(start) = lines.iter().position(|line| line.trim() == \"[host]\") {\n let end = find_section_end(&lines, start + 1);\n let mut updated = Vec::new();\n updated.extend_from_slice(&lines[..start]);\n updated.extend(section_lines);\n updated.extend_from_slice(&lines[end..]);\n lines = updated;\n } else {\n if !lines.is_empty()\n && !lines\n .last()\n .map(|line| line.trim().is_empty())\n .unwrap_or(false)\n {\n lines.push(String::new());\n }\n lines.extend(section_lines);\n }\n\n let mut out = lines.join(\"\\n\");\n if had_trailing_newline {\n out.push('\\n');\n }\n out\n}\n\nfn find_section_end(lines: &[String], start: usize) -> usize {\n for (idx, line) in lines.iter().enumerate().skip(start) {\n let trimmed = line.trim();\n if trimmed.starts_with('[') && trimmed.ends_with(']') {\n return idx;\n }\n }\n lines.len()\n}\n\nfn ensure_setup_script(\n project_root: &Path,\n script_path: &str,\n content: &str,\n overwrite: bool,\n) -> Result<()> {\n let path = project_root.join(script_path);\n if path.exists() && !overwrite {\n return Ok(());\n }\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n fs::write(&path, ensure_trailing_newline(content.to_string()))\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n #[cfg(unix)]\n {\n use std::os::unix::fs::PermissionsExt;\n let mut perms = fs::metadata(&path)?.permissions();\n perms.set_mode(0o755);\n fs::set_permissions(&path, perms)?;\n }\n if overwrite && path.exists() {\n println!(\"Updated {}\", path.display());\n } else {\n println!(\"Created {}\", path.display());\n }\n Ok(())\n}\n\nfn ensure_env_file(\n project_root: &Path,\n env_file: &str,\n env_example: Option<&PathBuf>,\n interactive: bool,\n auto_gitignore: bool,\n) -> Result<()> {\n let env_path = project_root.join(env_file);\n if env_path.exists() {\n return Ok(());\n }\n\n if let Some(example_path) = env_example {\n if example_path.exists() {\n let should_copy = if interactive {\n prompt_yes_no(\n &format!(\n \"Copy {} to {}?\",\n display_relative(project_root, example_path),\n env_file\n ),\n true,\n )?\n } else {\n true\n };\n\n if should_copy {\n if let Some(parent) = env_path.parent() {\n fs::create_dir_all(parent)?;\n }\n fs::copy(example_path, &env_path).with_context(|| {\n format!(\n \"failed to copy {} to {}\",\n example_path.display(),\n env_path.display()\n )\n })?;\n println!(\"Created {}\", env_path.display());\n }\n }\n }\n\n if env_path.exists() && interactive {\n if prompt_yes_no(\"Add env file to .gitignore?\", true)? {\n add_gitignore_entry(project_root, env_file)?;\n }\n }\n\n if env_path.exists() && auto_gitignore && !interactive {\n add_gitignore_entry(project_root, env_file)?;\n }\n\n Ok(())\n}\n\npub(crate) fn add_gitignore_entry(project_root: &Path, entry: &str) -> Result<()> {\n let gitignore_path = project_root.join(\".gitignore\");\n let mut content = if gitignore_path.exists() {\n fs::read_to_string(&gitignore_path)?\n } else {\n String::new()\n };\n\n if content.lines().any(|line| line.trim() == entry) {\n return Ok(());\n }\n\n if !content.is_empty() && !content.ends_with('\\n') {\n content.push('\\n');\n }\n if !content.is_empty() && !content.ends_with(\"\\n\\n\") {\n content.push('\\n');\n }\n content.push_str(entry);\n content.push('\\n');\n\n fs::write(&gitignore_path, content)\n .with_context(|| format!(\"failed to write {}\", gitignore_path.display()))?;\n Ok(())\n}\n\nfn maybe_configure_deploy_host(auto_mode: bool) -> Result<()> {\n let existing = deploy::load_deploy_config()?.host;\n if existing.is_some() && auto_mode {\n return Ok(());\n }\n\n let default_conn = existing\n .as_ref()\n .map(|host| format!(\"{}@{}:{}\", host.user, host.host, host.port))\n .or_else(deploy::default_linux_connection_string);\n\n if auto_mode {\n if let Some(conn_str) = default_conn.as_deref() {\n let conn = deploy::HostConnection::parse(conn_str)?;\n let mut config = deploy::load_deploy_config()?;\n config.host = Some(conn);\n deploy::save_deploy_config(&config)?;\n println!(\"Configured deploy host: {}\", conn_str);\n } else {\n println!(\"Host not configured. Run `f deploy config`.\");\n }\n return Ok(());\n }\n\n let should_configure = if existing.is_some() {\n prompt_yes_no(\"Configure deploy host now?\", false)?\n } else {\n prompt_yes_no(\"Configure deploy host now?\", true)?\n };\n\n if !should_configure {\n if existing.is_none() {\n println!(\"Host not configured. Run `f deploy set-host user@host:port`.\");\n }\n return Ok(());\n }\n\n let prompt = \"SSH host (user@host:port)\";\n let input = prompt_line(prompt, default_conn.as_deref())?;\n if input.trim().is_empty() {\n if existing.is_none() {\n println!(\"Host not configured. Run `f deploy set-host user@host:port`.\");\n }\n return Ok(());\n }\n let conn = deploy::HostConnection::parse(input.trim())?;\n let mut config = deploy::load_deploy_config()?;\n config.host = Some(conn);\n deploy::save_deploy_config(&config)?;\n println!(\"Configured deploy host.\");\n Ok(())\n}\n\nfn guess_project_name(project_root: &Path) -> String {\n if let Some(name) = cargo_package_name(project_root) {\n return name;\n }\n if let Some(name) = package_json_name(project_root) {\n return name;\n }\n project_root\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(\"app\")\n .to_string()\n}\n\nfn cargo_package_name(project_root: &Path) -> Option<String> {\n let path = project_root.join(\"Cargo.toml\");\n let content = fs::read_to_string(&path).ok()?;\n let value: toml::Value = toml::from_str(&content).ok()?;\n let name = value\n .get(\"package\")\n .and_then(toml::Value::as_table)\n .and_then(|pkg| pkg.get(\"name\"))\n .and_then(toml::Value::as_str)?;\n Some(name.to_string())\n}\n\nfn package_json_name(project_root: &Path) -> Option<String> {\n let path = project_root.join(\"package.json\");\n let content = fs::read_to_string(&path).ok()?;\n let value: serde_json::Value = serde_json::from_str(&content).ok()?;\n let name = value.get(\"name\")?.as_str()?;\n Some(strip_scope(name).to_string())\n}\n\nfn strip_scope(name: &str) -> &str {\n name.rsplit('/').next().unwrap_or(name)\n}\n\nfn default_run_command(project_root: &Path, project_name: &str) -> Option<String> {\n if project_root.join(\"Cargo.toml\").exists() {\n return Some(format!(\"./target/release/{}\", project_name));\n }\n None\n}\n\nfn default_setup_script(project_root: &Path) -> String {\n if project_root.join(\"Cargo.toml\").exists() {\n return rust_deploy_setup_script();\n }\n if project_root.join(\"package.json\").exists() {\n return node_deploy_setup_script();\n }\n generic_deploy_setup_script()\n}\n\nfn rust_deploy_setup_script() -> String {\n r#\"#!/usr/bin/env bash\nset -euo pipefail\n\nif ! command -v cargo >/dev/null 2>&1; then\n curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y\n if [ -f \"$HOME/.cargo/env\" ]; then\n . \"$HOME/.cargo/env\"\n fi\nfi\n\ncargo build --release\n\"#\n .to_string()\n}\n\nfn node_deploy_setup_script() -> String {\n r#\"#!/usr/bin/env bash\nset -euo pipefail\n\nif [ -f pnpm-lock.yaml ]; then\n pnpm install\nelif [ -f yarn.lock ]; then\n yarn install\nelif [ -f bun.lockb ]; then\n bun install\nelif [ -f package-lock.json ]; then\n npm ci\nelse\n npm install\nfi\n\nnpm run build\n\"#\n .to_string()\n}\n\nfn generic_deploy_setup_script() -> String {\n r#\"#!/usr/bin/env bash\nset -euo pipefail\n\necho \"TODO: add remote setup steps\"\n\"#\n .to_string()\n}\n\nfn find_env_example(project_root: &Path, project_name: &str) -> Option<PathBuf> {\n let candidates = [\n format!(\"deploy/{}.env.example\", project_name),\n \"deploy/.env.example\".to_string(),\n \".env.example\".to_string(),\n ];\n for candidate in candidates {\n let path = project_root.join(&candidate);\n if path.exists() {\n return Some(path);\n }\n }\n None\n}\n\nfn strip_example_suffix(project_root: &Path, path: &Path) -> Option<String> {\n let rel = path.strip_prefix(project_root).ok()?;\n let rel_str = rel.to_string_lossy();\n let trimmed = rel_str.strip_suffix(\".example\")?;\n Some(trimmed.to_string())\n}\n\nfn display_relative(project_root: &Path, path: &Path) -> String {\n path.strip_prefix(project_root)\n .map(|p| p.to_string_lossy().to_string())\n .unwrap_or_else(|_| path.to_string_lossy().to_string())\n}\n\nfn write_flow_toml(path: &Path, content: &str) -> Result<()> {\n fs::write(path, content).with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(())\n}\n\nfn generate_flow_toml_with_agent(project_root: &Path, hint: Option<&str>) -> Result<String> {\n let mut prompt = String::new();\n prompt.push_str(\n \"Read the project files and generate a minimal flow.toml with setup and dev tasks.\\n\\n\",\n );\n prompt.push_str(\"Requirements:\\n\");\n prompt.push_str(\"- Detect the project type by looking at files (Cargo.toml, package.json, *.tex, *.py, go.mod, etc.)\\n\");\n prompt.push_str(\"- Include only what is needed to make dev work reliably.\\n\");\n prompt.push_str(\"- The dev task must depend on setup (dependencies = [\\\"setup\\\"]).\\n\");\n prompt.push_str(\"- Add descriptions and shortcuts for setup (s) and dev (d).\\n\");\n prompt.push_str(\"- Use [deps] for required binaries.\\n\");\n prompt.push_str(\"- If a task prompts for input, set interactive = true.\\n\");\n prompt.push_str(\"- Include Codex baseline sections: [skills], [skills.codex], [commit.skill_gate], and [commit.skill_gate.min_version].\\n\");\n prompt.push_str(\n \"- Output ONLY the flow.toml content in a ```toml code block, no other commentary.\\n\\n\",\n );\n prompt.push_str(\"# flow.toml examples by project type:\\n\\n\");\n prompt.push_str(\"## Rust project (Cargo.toml exists):\\n\");\n prompt.push_str(\"[deps]\\n\");\n prompt.push_str(\"cargo = \\\"cargo\\\"\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"setup\\\"\\n\");\n prompt.push_str(\"command = \\\"cargo build --locked\\\"\\n\");\n prompt.push_str(\"dependencies = [\\\"cargo\\\"]\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"dev\\\"\\n\");\n prompt.push_str(\"command = \\\"cargo run\\\"\\n\");\n prompt.push_str(\"dependencies = [\\\"setup\\\"]\\n\\n\");\n prompt.push_str(\"## Node.js project (package.json exists):\\n\");\n prompt.push_str(\"[deps]\\n\");\n prompt.push_str(\"node = [\\\"node\\\", \\\"npm\\\"] # or pnpm, yarn, bun based on lock file\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"setup\\\"\\n\");\n prompt.push_str(\"command = \\\"npm install\\\" # or pnpm install, yarn, bun install\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"dev\\\"\\n\");\n prompt.push_str(\"command = \\\"npm run dev\\\"\\n\");\n prompt.push_str(\"dependencies = [\\\"setup\\\"]\\n\\n\");\n prompt.push_str(\"## LaTeX project (.tex files exist):\\n\");\n prompt.push_str(\"[deps]\\n\");\n prompt.push_str(\"pdflatex = \\\"pdflatex\\\" # or latexmk if .latexmkrc exists\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"setup\\\"\\n\");\n prompt.push_str(\"command = \\\"echo 'LaTeX project ready'\\\"\\n\");\n prompt.push_str(\"dependencies = [\\\"pdflatex\\\"]\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"dev\\\"\\n\");\n prompt.push_str(\"command = \\\"pdflatex main.tex\\\" # use detected main .tex file\\n\");\n prompt.push_str(\"description = \\\"Compile document\\\"\\n\");\n prompt.push_str(\"dependencies = [\\\"setup\\\"]\\n\\n\");\n prompt.push_str(\n \"## Python project (pyproject.toml, setup.py, requirements.txt, or .py files):\\n\",\n );\n prompt.push_str(\"[deps]\\n\");\n prompt.push_str(\"python = \\\"python3\\\"\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"setup\\\"\\n\");\n prompt.push_str(\"command = \\\"pip install -e .\\\" # or pip install -r requirements.txt\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"dev\\\"\\n\");\n prompt.push_str(\n \"command = \\\"python main.py\\\" # use entry point from pyproject.toml or main .py file\\n\\n\",\n );\n prompt.push_str(\"## Go project (go.mod exists):\\n\");\n prompt.push_str(\"[deps]\\n\");\n prompt.push_str(\"go = \\\"go\\\"\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"setup\\\"\\n\");\n prompt.push_str(\"command = \\\"go mod download\\\"\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"dev\\\"\\n\");\n prompt.push_str(\"command = \\\"go run .\\\"\\n\\n\");\n\n if let Some(guidance) = project_guidance(project_root) {\n prompt.push_str(\"Guidance:\\n\");\n prompt.push_str(&guidance);\n prompt.push('\\n');\n }\n\n let hints = project_hints(project_root);\n if !hints.is_empty() {\n prompt.push_str(\"Detected project hints:\\n\");\n for hint in hints {\n prompt.push_str(\"- \");\n prompt.push_str(&hint);\n prompt.push('\\n');\n }\n prompt.push('\\n');\n }\n\n if let Some(hint) = hint {\n if !hint.trim().is_empty() {\n prompt.push_str(\"User notes:\\n\");\n prompt.push_str(hint.trim());\n prompt.push('\\n');\n }\n }\n\n agents::run_flow_agent_capture(&prompt)\n}\n\nfn generate_flow_toml_with_agent_streaming(\n project_root: &Path,\n hint: Option<&str>,\n) -> Result<String> {\n let mut prompt = String::new();\n prompt.push_str(\n \"Read the project files and generate a minimal flow.toml with setup and dev tasks.\\n\\n\",\n );\n prompt.push_str(\"Requirements:\\n\");\n prompt.push_str(\"- Detect the project type by looking at files (Cargo.toml, package.json, *.tex, *.py, go.mod, etc.)\\n\");\n prompt.push_str(\"- Include only what is needed to make dev work reliably.\\n\");\n prompt.push_str(\"- The dev task must depend on setup (dependencies = [\\\"setup\\\"]).\\n\");\n prompt.push_str(\"- Add descriptions and shortcuts for setup (s) and dev (d).\\n\");\n prompt.push_str(\"- Use [deps] for required binaries.\\n\");\n prompt.push_str(\"- If a task prompts for input, set interactive = true.\\n\");\n prompt.push_str(\"- Include Codex baseline sections: [skills], [skills.codex], [commit.skill_gate], and [commit.skill_gate.min_version].\\n\");\n prompt.push_str(\n \"- Output ONLY the flow.toml content in a ```toml code block, no other commentary.\\n\\n\",\n );\n prompt.push_str(\"# flow.toml examples by project type:\\n\\n\");\n prompt.push_str(\"## Rust project (Cargo.toml exists):\\n\");\n prompt.push_str(\"[deps]\\n\");\n prompt.push_str(\"cargo = \\\"cargo\\\"\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"setup\\\"\\n\");\n prompt.push_str(\"command = \\\"cargo build --locked\\\"\\n\");\n prompt.push_str(\"dependencies = [\\\"cargo\\\"]\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"dev\\\"\\n\");\n prompt.push_str(\"command = \\\"cargo run\\\"\\n\");\n prompt.push_str(\"dependencies = [\\\"setup\\\"]\\n\\n\");\n prompt.push_str(\"## Node.js project (package.json exists):\\n\");\n prompt.push_str(\"[deps]\\n\");\n prompt.push_str(\"node = [\\\"node\\\", \\\"npm\\\"] # or pnpm, yarn, bun based on lock file\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"setup\\\"\\n\");\n prompt.push_str(\"command = \\\"npm install\\\" # or pnpm install, yarn, bun install\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"dev\\\"\\n\");\n prompt.push_str(\"command = \\\"npm run dev\\\"\\n\");\n prompt.push_str(\"dependencies = [\\\"setup\\\"]\\n\\n\");\n prompt.push_str(\"## LaTeX project (.tex files exist):\\n\");\n prompt.push_str(\"[deps]\\n\");\n prompt.push_str(\"pdflatex = \\\"pdflatex\\\" # or latexmk if .latexmkrc exists\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"setup\\\"\\n\");\n prompt.push_str(\"command = \\\"echo 'LaTeX project ready'\\\"\\n\");\n prompt.push_str(\"dependencies = [\\\"pdflatex\\\"]\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"dev\\\"\\n\");\n prompt.push_str(\"command = \\\"pdflatex main.tex\\\" # use detected main .tex file\\n\");\n prompt.push_str(\"description = \\\"Compile document\\\"\\n\");\n prompt.push_str(\"dependencies = [\\\"setup\\\"]\\n\\n\");\n prompt.push_str(\n \"## Python project (pyproject.toml, setup.py, requirements.txt, or .py files):\\n\",\n );\n prompt.push_str(\"[deps]\\n\");\n prompt.push_str(\"python = \\\"python3\\\"\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"setup\\\"\\n\");\n prompt.push_str(\"command = \\\"pip install -e .\\\" # or pip install -r requirements.txt\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"dev\\\"\\n\");\n prompt.push_str(\n \"command = \\\"python main.py\\\" # use entry point from pyproject.toml or main .py file\\n\\n\",\n );\n prompt.push_str(\"## Go project (go.mod exists):\\n\");\n prompt.push_str(\"[deps]\\n\");\n prompt.push_str(\"go = \\\"go\\\"\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"setup\\\"\\n\");\n prompt.push_str(\"command = \\\"go mod download\\\"\\n\\n\");\n prompt.push_str(\"[[tasks]]\\n\");\n prompt.push_str(\"name = \\\"dev\\\"\\n\");\n prompt.push_str(\"command = \\\"go run .\\\"\\n\\n\");\n\n if let Some(guidance) = project_guidance(project_root) {\n prompt.push_str(\"Guidance:\\n\");\n prompt.push_str(&guidance);\n prompt.push('\\n');\n }\n\n let hints = project_hints(project_root);\n if !hints.is_empty() {\n prompt.push_str(\"Detected project hints:\\n\");\n for hint in hints {\n prompt.push_str(\"- \");\n prompt.push_str(&hint);\n prompt.push('\\n');\n }\n prompt.push('\\n');\n }\n\n if let Some(hint) = hint {\n if !hint.trim().is_empty() {\n prompt.push_str(\"User notes:\\n\");\n prompt.push_str(hint.trim());\n prompt.push('\\n');\n }\n }\n\n agents::run_flow_agent_capture_streaming(&prompt)\n}\n\nfn extract_flow_toml(raw: &str) -> Option<String> {\n if let Some(block) = extract_fenced_block(raw, \"toml\") {\n return Some(block);\n }\n if let Some(block) = extract_fenced_block(raw, \"\") {\n return Some(block);\n }\n if raw.contains(\"[[tasks]]\") {\n return Some(raw.trim().to_string());\n }\n None\n}\n\nfn extract_fenced_block(raw: &str, tag: &str) -> Option<String> {\n let fence = if tag.is_empty() {\n \"```\".to_string()\n } else {\n format!(\"```{tag}\")\n };\n let start = raw.find(&fence)?;\n let after = &raw[start + fence.len()..];\n let after = after.strip_prefix('\\n').unwrap_or(after);\n let end = after.find(\"```\")?;\n Some(after[..end].trim().to_string())\n}\n\n#[derive(Deserialize)]\nstruct HostWrapper {\n host: Option<deploy::HostConfig>,\n}\n\nfn generate_host_config_with_agent(project_root: &Path, hint: Option<&str>) -> Result<String> {\n let defaults = deploy_defaults(project_root);\n let mut prompt = String::new();\n prompt.push_str(\"Read the project and generate a minimal [host] config for flow.toml.\\n\");\n prompt.push_str(\"Requirements:\\n\");\n prompt.push_str(\"- Output ONLY TOML with a [host] section.\\n\");\n prompt.push_str(\"- No explanations, no narration, no markdown fences.\\n\");\n prompt.push_str(\"- Use relative paths for setup/env_file.\\n\");\n prompt.push_str(\"- Use a production run command (avoid dev servers).\\n\");\n prompt.push_str(\"- Keep it minimal; omit fields you cannot infer.\\n\\n\");\n\n prompt.push_str(\"Suggested defaults:\\n\");\n prompt.push_str(&format!(\"- dest: {}\\n\", defaults.dest));\n if let Some(run) = defaults.run.as_deref() {\n prompt.push_str(&format!(\"- run: {}\\n\", run));\n }\n prompt.push_str(&format!(\"- service: {}\\n\", defaults.service));\n if !defaults.setup_path.trim().is_empty() {\n prompt.push_str(&format!(\"- setup: {}\\n\", defaults.setup_path));\n }\n if let Some(env_file) = defaults.env_file.as_deref() {\n prompt.push_str(&format!(\"- env_file: {}\\n\", env_file));\n }\n if let Some(env_example) = defaults.env_example.as_ref() {\n prompt.push_str(&format!(\n \"- env example: {}\\n\",\n display_relative(project_root, env_example)\n ));\n }\n if let Some(port) = defaults.port {\n prompt.push_str(&format!(\"- port: {}\\n\", port));\n }\n prompt.push('\\n');\n\n if let Some(guidance) = project_guidance(project_root) {\n prompt.push_str(\"Guidance:\\n\");\n prompt.push_str(&guidance);\n prompt.push('\\n');\n }\n\n let hints = project_hints(project_root);\n if !hints.is_empty() {\n prompt.push_str(\"Detected project hints:\\n\");\n for hint in hints {\n prompt.push_str(\"- \");\n prompt.push_str(&hint);\n prompt.push('\\n');\n }\n prompt.push('\\n');\n }\n\n if let Some(hint) = hint {\n if !hint.trim().is_empty() {\n prompt.push_str(\"User notes:\\n\");\n prompt.push_str(hint.trim());\n prompt.push('\\n');\n }\n }\n\n agents::run_flow_agent_capture(&prompt)\n}\n\nfn extract_host_config(raw: &str) -> Option<deploy::HostConfig> {\n let content = extract_fenced_block(raw, \"toml\")\n .or_else(|| extract_fenced_block(raw, \"\"))\n .unwrap_or_else(|| raw.trim().to_string());\n\n if content.trim().is_empty() {\n return None;\n }\n\n if content.contains(\"[host]\") {\n if let Ok(wrapper) = toml::from_str::<HostWrapper>(&content) {\n if let Some(host) = wrapper.host {\n if host_has_values(&host) {\n return Some(host);\n }\n }\n }\n } else if let Ok(host) = toml::from_str::<deploy::HostConfig>(&content) {\n if host_has_values(&host) {\n return Some(host);\n }\n }\n\n None\n}\n\nfn host_has_values(host: &deploy::HostConfig) -> bool {\n host.dest.is_some()\n || host.setup.is_some()\n || host.run.is_some()\n || host.port.is_some()\n || host.service.is_some()\n || host.env_file.is_some()\n || host.domain.is_some()\n || host.ssl\n}\n\nfn host_config_mismatch_reason(\n project_root: &Path,\n host_cfg: &deploy::HostConfig,\n) -> Option<String> {\n let has_cargo = project_root.join(\"Cargo.toml\").exists();\n let has_package = project_root.join(\"package.json\").exists();\n\n let mut uses_node = false;\n let mut uses_cargo = false;\n\n if let Some(run) = host_cfg.run.as_deref() {\n uses_node |= command_uses_node_tool(run);\n uses_cargo |= command_uses_cargo_tool(run);\n }\n\n if let Some(setup) = host_cfg.setup.as_deref() {\n if looks_like_inline_script(setup) {\n uses_node |= command_uses_node_tool(setup);\n uses_cargo |= command_uses_cargo_tool(setup);\n } else {\n let setup_path = project_root.join(setup);\n if setup_path.exists() {\n if let Ok(content) = fs::read_to_string(&setup_path) {\n uses_node |= command_uses_node_tool(&content);\n uses_cargo |= command_uses_cargo_tool(&content);\n }\n }\n }\n }\n\n if has_cargo && !has_package && uses_node {\n return Some(\n \"AI suggested Node tooling (bun/npm/pnpm/yarn), but no package.json was found.\"\n .to_string(),\n );\n }\n if has_package && !has_cargo && uses_cargo {\n return Some(\"AI suggested Cargo commands, but no Cargo.toml was found.\".to_string());\n }\n\n if let Some(reason) = host_config_name_mismatch(project_root, host_cfg) {\n return Some(reason);\n }\n\n None\n}\n\nfn command_mismatch_reason(project_root: &Path, command: &str) -> Option<String> {\n let has_cargo = project_root.join(\"Cargo.toml\").exists();\n let has_package = project_root.join(\"package.json\").exists();\n\n let uses_node = command_uses_node_tool(command);\n let uses_cargo = command_uses_cargo_tool(command);\n\n if has_cargo && !has_package && uses_node {\n return Some(\n \"uses Node tooling but no package.json was found for this project.\".to_string(),\n );\n }\n if has_package && !has_cargo && uses_cargo {\n return Some(\"uses Cargo but no Cargo.toml was found for this project.\".to_string());\n }\n\n None\n}\n\nfn setup_script_mismatch_reason(project_root: &Path, setup: &str) -> Option<String> {\n let has_cargo = project_root.join(\"Cargo.toml\").exists();\n let has_package = project_root.join(\"package.json\").exists();\n\n let mut uses_node = false;\n let mut uses_cargo = false;\n\n if looks_like_inline_script(setup) {\n uses_node |= command_uses_node_tool(setup);\n uses_cargo |= command_uses_cargo_tool(setup);\n } else {\n let setup_path = project_root.join(setup);\n if setup_path.exists() {\n if let Ok(content) = fs::read_to_string(&setup_path) {\n uses_node |= command_uses_node_tool(&content);\n uses_cargo |= command_uses_cargo_tool(&content);\n }\n }\n }\n\n if has_cargo && !has_package && uses_node {\n return Some(\n \"uses Node tooling but no package.json was found for this project.\".to_string(),\n );\n }\n if has_package && !has_cargo && uses_cargo {\n return Some(\"uses Cargo but no Cargo.toml was found for this project.\".to_string());\n }\n\n None\n}\n\nfn host_config_name_mismatch(project_root: &Path, host_cfg: &deploy::HostConfig) -> Option<String> {\n let expected_names = expected_project_names(project_root);\n if expected_names.is_empty() {\n return None;\n }\n\n let tokens = host_name_tokens(host_cfg);\n if tokens.is_empty() {\n return None;\n }\n\n let mut counts: HashMap<String, usize> = HashMap::new();\n for token in tokens {\n if expected_names.contains(&token) {\n continue;\n }\n *counts.entry(token).or_insert(0) += 1;\n }\n\n let (token, count) = counts.into_iter().max_by_key(|(_, count)| *count)?;\n if count < 2 {\n return None;\n }\n\n let project_name = guess_project_name(project_root);\n Some(format!(\n \"AI suggested host config for '{}', but the project looks like '{}'.\",\n token, project_name\n ))\n}\n\nfn expected_project_names(project_root: &Path) -> HashSet<String> {\n let mut names = HashSet::new();\n let guessed = guess_project_name(project_root);\n if !guessed.is_empty() {\n names.insert(guessed.to_ascii_lowercase());\n }\n if let Some(name) = cargo_package_name(project_root) {\n names.insert(name.to_ascii_lowercase());\n }\n if let Some(name) = package_json_name(project_root) {\n names.insert(name.to_ascii_lowercase());\n }\n if let Some(folder) = project_root.file_name().and_then(|name| name.to_str()) {\n names.insert(folder.to_ascii_lowercase());\n }\n for name in cargo_bin_names(project_root) {\n names.insert(name);\n }\n names\n}\n\nfn cargo_bin_names(project_root: &Path) -> Vec<String> {\n let path = project_root.join(\"Cargo.toml\");\n let content = match fs::read_to_string(&path) {\n Ok(content) => content,\n Err(_) => return Vec::new(),\n };\n let value: toml::Value = match toml::from_str(&content) {\n Ok(value) => value,\n Err(_) => return Vec::new(),\n };\n\n let mut names = Vec::new();\n if let Some(bins) = value.get(\"bin\").and_then(toml::Value::as_array) {\n for bin in bins {\n if let Some(name) = bin.get(\"name\").and_then(toml::Value::as_str) {\n names.push(name.to_ascii_lowercase());\n }\n }\n }\n names\n}\n\nfn host_name_tokens(host: &deploy::HostConfig) -> Vec<String> {\n let mut tokens = Vec::new();\n\n if let Some(service) = host.service.as_deref() {\n if let Some(token) = normalize_host_token(service) {\n tokens.push(token);\n }\n }\n\n if let Some(dest) = host.dest.as_deref() {\n if let Some(seg) = Path::new(dest).file_name().and_then(|s| s.to_str()) {\n if let Some(token) = normalize_host_token(seg) {\n tokens.push(token);\n }\n }\n }\n\n if let Some(run) = host.run.as_deref() {\n if let Some(bin) = extract_run_binary(run) {\n if let Some(token) = normalize_host_token(&bin) {\n tokens.push(token);\n }\n }\n }\n\n if let Some(env_file) = host.env_file.as_deref() {\n if let Some(env_name) = extract_env_name(env_file) {\n if let Some(token) = normalize_host_token(&env_name) {\n tokens.push(token);\n }\n }\n }\n\n tokens\n}\n\nfn extract_run_binary(run: &str) -> Option<String> {\n let first = run.trim().split_whitespace().next()?;\n let trimmed = first.trim_matches(|c| c == '\"' || c == '\\'');\n let name = Path::new(trimmed)\n .file_name()?\n .to_string_lossy()\n .to_string();\n if name.is_empty() { None } else { Some(name) }\n}\n\nfn extract_env_name(env_file: &str) -> Option<String> {\n let file_name = Path::new(env_file).file_name()?.to_string_lossy();\n if file_name.starts_with('.') {\n return None;\n }\n let mut stem = Path::new(&*file_name)\n .file_stem()\n .map(|s| s.to_string_lossy().to_string())?;\n if let Some(stripped) = stem.strip_suffix(\".env\") {\n stem = stripped.to_string();\n }\n if stem.is_empty() { None } else { Some(stem) }\n}\n\nfn normalize_host_token(token: &str) -> Option<String> {\n let trimmed = token.trim_matches(|c: char| !c.is_ascii_alphanumeric() && c != '-' && c != '_');\n if trimmed.len() < 2 {\n return None;\n }\n let lower = trimmed.to_ascii_lowercase();\n if is_host_stop_token(&lower) {\n None\n } else {\n Some(lower)\n }\n}\n\nfn is_host_stop_token(token: &str) -> bool {\n matches!(\n token,\n \"app\"\n | \"service\"\n | \"server\"\n | \"api\"\n | \"web\"\n | \"backend\"\n | \"frontend\"\n | \"bin\"\n | \"target\"\n | \"release\"\n | \"debug\"\n | \"dist\"\n | \"build\"\n | \"deploy\"\n | \"env\"\n | \"cargo\"\n | \"bun\"\n | \"npm\"\n | \"pnpm\"\n | \"yarn\"\n | \"node\"\n )\n}\n\nstruct SuggestedCommands {\n setup: Option<String>,\n dev: Option<String>,\n deps: Vec<DepSpec>,\n}\n\nenum DepSpec {\n Single(&'static str, &'static str),\n Multiple(&'static str, &'static [&'static str]),\n}\n\nfn suggested_commands(project_root: &Path) -> SuggestedCommands {\n // Check root level first\n let cargo = project_root.join(\"Cargo.toml\").exists();\n if cargo {\n return SuggestedCommands {\n setup: Some(\"cargo build --locked\".to_string()),\n dev: Some(\"cargo run\".to_string()),\n deps: vec![DepSpec::Single(\"cargo\", \"cargo\")],\n };\n }\n\n let package_json = project_root.join(\"package.json\").exists();\n if package_json {\n return suggest_node_commands(project_root, None);\n }\n\n // Check for LaTeX project\n if let Some(cmds) = suggest_latex_commands(project_root, None) {\n return cmds;\n }\n\n // Check subdirectories for project files\n let subdir_projects = find_subdir_projects(project_root);\n\n if let Some(subdir) = subdir_projects.cargo {\n return SuggestedCommands {\n setup: Some(format!(\"cd {subdir} && cargo build --locked\")),\n dev: Some(format!(\"cd {subdir} && cargo run\")),\n deps: vec![DepSpec::Single(\"cargo\", \"cargo\")],\n };\n }\n\n if let Some(subdir) = subdir_projects.package {\n let subdir_path = project_root.join(&subdir);\n return suggest_node_commands(&subdir_path, Some(&subdir));\n }\n\n if let Some(subdir) = subdir_projects.latex {\n let subdir_path = project_root.join(&subdir);\n if let Some(cmds) = suggest_latex_commands(&subdir_path, Some(&subdir)) {\n return cmds;\n }\n }\n\n SuggestedCommands {\n setup: None,\n dev: None,\n deps: Vec::new(),\n }\n}\n\nfn suggest_node_commands(project_path: &Path, subdir: Option<&str>) -> SuggestedCommands {\n let prefix = subdir.map(|s| format!(\"cd {s} && \")).unwrap_or_default();\n\n // Check lock files first (most reliable indicator)\n if project_path.join(\"pnpm-lock.yaml\").exists() {\n return SuggestedCommands {\n setup: Some(format!(\"{prefix}pnpm install\")),\n dev: Some(format!(\"{prefix}pnpm dev\")),\n deps: vec![DepSpec::Single(\"pnpm\", \"pnpm\")],\n };\n }\n if project_path.join(\"yarn.lock\").exists() {\n return SuggestedCommands {\n setup: Some(format!(\"{prefix}yarn install\")),\n dev: Some(format!(\"{prefix}yarn dev\")),\n deps: vec![DepSpec::Single(\"yarn\", \"yarn\")],\n };\n }\n if project_path.join(\"bun.lockb\").exists() {\n return SuggestedCommands {\n setup: Some(format!(\"{prefix}bun install\")),\n dev: Some(format!(\"{prefix}bun dev\")),\n deps: vec![DepSpec::Single(\"bun\", \"bun\")],\n };\n }\n if project_path.join(\"package-lock.json\").exists() {\n return SuggestedCommands {\n setup: Some(format!(\"{prefix}npm ci\")),\n dev: Some(format!(\"{prefix}npm run dev\")),\n deps: vec![DepSpec::Multiple(\"node\", &[\"node\", \"npm\"])],\n };\n }\n\n // No lock file - check package.json for hints\n if let Some(pm) = detect_package_manager_from_json(project_path) {\n return match pm.as_str() {\n \"pnpm\" => SuggestedCommands {\n setup: Some(format!(\"{prefix}pnpm install\")),\n dev: Some(format!(\"{prefix}pnpm dev\")),\n deps: vec![DepSpec::Single(\"pnpm\", \"pnpm\")],\n },\n \"yarn\" => SuggestedCommands {\n setup: Some(format!(\"{prefix}yarn install\")),\n dev: Some(format!(\"{prefix}yarn dev\")),\n deps: vec![DepSpec::Single(\"yarn\", \"yarn\")],\n },\n \"bun\" => SuggestedCommands {\n setup: Some(format!(\"{prefix}bun install\")),\n dev: Some(format!(\"{prefix}bun dev\")),\n deps: vec![DepSpec::Single(\"bun\", \"bun\")],\n },\n _ => SuggestedCommands {\n setup: Some(format!(\"{prefix}npm install\")),\n dev: Some(format!(\"{prefix}npm run dev\")),\n deps: vec![DepSpec::Multiple(\"node\", &[\"node\", \"npm\"])],\n },\n };\n }\n\n SuggestedCommands {\n setup: Some(format!(\"{prefix}npm install\")),\n dev: Some(format!(\"{prefix}npm run dev\")),\n deps: vec![DepSpec::Multiple(\"node\", &[\"node\", \"npm\"])],\n }\n}\n\n/// Detect LaTeX project and suggest build commands.\n/// Looks for .tex files and determines the main document file.\nfn suggest_latex_commands(project_path: &Path, subdir: Option<&str>) -> Option<SuggestedCommands> {\n let prefix = subdir.map(|s| format!(\"cd {s} && \")).unwrap_or_default();\n\n // Find .tex files in the project\n let tex_files: Vec<_> = fs::read_dir(project_path)\n .ok()?\n .filter_map(|e| e.ok())\n .filter(|e| e.path().extension().is_some_and(|ext| ext == \"tex\"))\n .map(|e| e.file_name().to_string_lossy().to_string())\n .collect();\n\n if tex_files.is_empty() {\n return None;\n }\n\n // Determine the main LaTeX file\n let main_file = detect_main_tex_file(project_path, &tex_files);\n\n // Check for Makefile or latexmk config\n let has_makefile = project_path.join(\"Makefile\").exists();\n let has_latexmkrc =\n project_path.join(\".latexmkrc\").exists() || project_path.join(\"latexmkrc\").exists();\n\n if has_makefile {\n return Some(SuggestedCommands {\n setup: Some(format!(\"{prefix}echo 'LaTeX project ready'\")),\n dev: Some(format!(\"{prefix}make\")),\n deps: vec![\n DepSpec::Single(\"pdflatex\", \"pdflatex\"),\n DepSpec::Single(\"make\", \"make\"),\n ],\n });\n }\n\n if has_latexmkrc {\n return Some(SuggestedCommands {\n setup: Some(format!(\"{prefix}echo 'LaTeX project ready'\")),\n dev: Some(format!(\"{prefix}latexmk\")),\n deps: vec![DepSpec::Single(\"latexmk\", \"latexmk\")],\n });\n }\n\n // Default to pdflatex with detected main file\n Some(SuggestedCommands {\n setup: Some(format!(\"{prefix}echo 'LaTeX project ready'\")),\n dev: Some(format!(\"{prefix}pdflatex {main_file}\")),\n deps: vec![DepSpec::Single(\"pdflatex\", \"pdflatex\")],\n })\n}\n\n/// Detect the main .tex file in a LaTeX project.\n/// Priority: main.tex > document.tex > single .tex file > first alphabetically\nfn detect_main_tex_file(project_path: &Path, tex_files: &[String]) -> String {\n // Common main file names\n for name in [\n \"main.tex\",\n \"document.tex\",\n \"paper.tex\",\n \"thesis.tex\",\n \"cv.tex\",\n \"resume.tex\",\n ] {\n if tex_files.contains(&name.to_string()) {\n return name.to_string();\n }\n }\n\n // If only one .tex file, use it\n if tex_files.len() == 1 {\n return tex_files[0].clone();\n }\n\n // Look for \\documentclass in files to find the main document\n for file in tex_files {\n let path = project_path.join(file);\n if let Ok(content) = fs::read_to_string(&path) {\n // Main document has \\documentclass, included files don't\n if content.contains(\"\\\\documentclass\") {\n return file.clone();\n }\n }\n }\n\n // Fallback to first file alphabetically\n let mut sorted = tex_files.to_vec();\n sorted.sort();\n sorted\n .first()\n .cloned()\n .unwrap_or_else(|| \"main.tex\".to_string())\n}\n\n/// Detect package manager from package.json content.\n/// Checks: packageManager field, catalog: protocol usage, script commands.\nfn detect_package_manager_from_json(project_path: &Path) -> Option<String> {\n let path = project_path.join(\"package.json\");\n let content = fs::read_to_string(&path).ok()?;\n let value: serde_json::Value = serde_json::from_str(&content).ok()?;\n\n // 1. Check packageManager field (e.g., \"pnpm@9.0.0\", \"yarn@4.0.0\", \"bun@1.0.0\")\n if let Some(pm) = value.get(\"packageManager\").and_then(|v| v.as_str()) {\n let pm_lower = pm.to_lowercase();\n if pm_lower.starts_with(\"pnpm\") {\n return Some(\"pnpm\".to_string());\n }\n if pm_lower.starts_with(\"yarn\") {\n return Some(\"yarn\".to_string());\n }\n if pm_lower.starts_with(\"bun\") {\n return Some(\"bun\".to_string());\n }\n if pm_lower.starts_with(\"npm\") {\n return Some(\"npm\".to_string());\n }\n }\n\n // 2. Check for catalog: protocol in dependencies (pnpm workspace feature)\n let has_catalog = has_catalog_protocol(&value);\n if has_catalog {\n return Some(\"pnpm\".to_string());\n }\n\n // 3. Check scripts for package manager hints\n if let Some(scripts) = value.get(\"scripts\").and_then(|v| v.as_object()) {\n let scripts_str = scripts\n .values()\n .filter_map(|v| v.as_str())\n .collect::<Vec<_>>()\n .join(\" \");\n\n // Check for explicit package manager usage in scripts\n if scripts_str.contains(\"pnpm \") || scripts_str.contains(\"pnpm run\") {\n return Some(\"pnpm\".to_string());\n }\n if scripts_str.contains(\"bun run\") || scripts_str.contains(\"bun \") {\n return Some(\"bun\".to_string());\n }\n if scripts_str.contains(\"yarn \") {\n return Some(\"yarn\".to_string());\n }\n }\n\n None\n}\n\n/// Check if package.json uses catalog: protocol in any dependency field.\nfn has_catalog_protocol(value: &serde_json::Value) -> bool {\n let dep_fields = [\n \"dependencies\",\n \"devDependencies\",\n \"peerDependencies\",\n \"optionalDependencies\",\n ];\n\n for field in dep_fields {\n if let Some(deps) = value.get(field).and_then(|v| v.as_object()) {\n for version in deps.values() {\n if let Some(v) = version.as_str() {\n if v.starts_with(\"catalog:\") {\n return true;\n }\n }\n }\n }\n }\n\n // Also check workspaces.catalog (pnpm/yarn workspace catalog definition)\n if value\n .get(\"workspaces\")\n .and_then(|v| v.get(\"catalog\"))\n .is_some()\n {\n return true;\n }\n\n false\n}\n\nfn default_flow_template(project_root: &Path) -> String {\n let defaults = suggested_commands(project_root);\n let setup_cmd = defaults.setup.unwrap_or_default();\n let dev_cmd = defaults.dev.unwrap_or_default();\n render_flow_toml(&setup_cmd, &dev_cmd, defaults.deps)\n}\n\nfn project_hints(project_root: &Path) -> Vec<String> {\n let mut hints = Vec::new();\n let candidates = [\n \"Cargo.toml\",\n \"package.json\",\n \"pnpm-lock.yaml\",\n \"yarn.lock\",\n \"bun.lockb\",\n \"package-lock.json\",\n \"pyproject.toml\",\n \"requirements.txt\",\n \"Makefile\",\n \"justfile\",\n \"Dockerfile\",\n ];\n for name in candidates {\n if project_root.join(name).exists() {\n hints.push(format!(\"{name}\"));\n }\n }\n\n // Check for project files in immediate subdirectories\n if let Ok(entries) = fs::read_dir(project_root) {\n for entry in entries.flatten() {\n let path = entry.path();\n if !path.is_dir() {\n continue;\n }\n let subdir_name = match path.file_name().and_then(|n| n.to_str()) {\n Some(name) if !name.starts_with('.') => name,\n _ => continue,\n };\n for name in [\"Cargo.toml\", \"package.json\"] {\n if path.join(name).exists() {\n hints.push(format!(\"{subdir_name}/{name}\"));\n }\n }\n }\n }\n\n hints\n}\n\nfn project_guidance(project_root: &Path) -> Option<String> {\n let has_cargo = project_root.join(\"Cargo.toml\").exists();\n let has_package = project_root.join(\"package.json\").exists();\n let has_tex = has_tex_files(project_root);\n\n // Check for project files in subdirectories\n let subdir_projects = find_subdir_projects(project_root);\n\n let cargo_found = has_cargo || subdir_projects.cargo.is_some();\n let package_found = has_package || subdir_projects.package.is_some();\n let latex_found = has_tex || subdir_projects.latex.is_some();\n\n // LaTeX-only projects\n if latex_found && !cargo_found && !package_found {\n if let Some(ref subdir) = subdir_projects.latex {\n return Some(format!(\n \"Detected LaTeX project in {subdir}/. Use pdflatex/latexmk commands. Avoid bun/npm/pnpm/yarn/cargo.\"\n ));\n }\n return Some(\"Detected LaTeX project (.tex files). Use pdflatex or latexmk to compile; avoid bun/npm/pnpm/yarn/cargo.\".to_string());\n }\n\n match (\n cargo_found,\n package_found,\n &subdir_projects.cargo,\n &subdir_projects.package,\n ) {\n (true, false, Some(subdir), _) => Some(format!(\n \"Detected Rust project in {subdir}/. Run cargo commands from that directory (cd {subdir} && cargo build). Avoid bun/npm/pnpm/yarn.\"\n )),\n (true, false, None, _) => Some(\n \"Detected Rust project (Cargo.toml). Use cargo commands; avoid bun/npm/pnpm/yarn.\"\n .to_string(),\n ),\n (false, true, _, Some(subdir)) => Some(format!(\n \"Detected Node project in {subdir}/. Run npm/pnpm/yarn/bun commands from that directory. Avoid cargo.\"\n )),\n (false, true, _, None) => Some(\n \"Detected Node project (package.json). Use npm/pnpm/yarn/bun commands; avoid cargo.\"\n .to_string(),\n ),\n (true, true, _, _) => {\n Some(\"Detected Rust + Node. Use the right tool for each step.\".to_string())\n }\n _ => None,\n }\n}\n\n/// Find project files (Cargo.toml, package.json, .tex files) in immediate subdirectories.\nstruct SubdirProjects {\n cargo: Option<String>,\n package: Option<String>,\n latex: Option<String>,\n}\n\nfn find_subdir_projects(project_root: &Path) -> SubdirProjects {\n let mut cargo_subdir = None;\n let mut package_subdir = None;\n let mut latex_subdir = None;\n\n let entries = match fs::read_dir(project_root) {\n Ok(entries) => entries,\n Err(_) => {\n return SubdirProjects {\n cargo: None,\n package: None,\n latex: None,\n };\n }\n };\n\n for entry in entries.flatten() {\n let path = entry.path();\n if !path.is_dir() {\n continue;\n }\n let subdir_name = match path.file_name().and_then(|n| n.to_str()) {\n Some(name) if !name.starts_with('.') => name.to_string(),\n _ => continue,\n };\n\n if cargo_subdir.is_none() && path.join(\"Cargo.toml\").exists() {\n cargo_subdir = Some(subdir_name.clone());\n }\n if package_subdir.is_none() && path.join(\"package.json\").exists() {\n package_subdir = Some(subdir_name.clone());\n }\n if latex_subdir.is_none() && has_tex_files(&path) {\n latex_subdir = Some(subdir_name);\n }\n\n if cargo_subdir.is_some() && package_subdir.is_some() && latex_subdir.is_some() {\n break;\n }\n }\n\n SubdirProjects {\n cargo: cargo_subdir,\n package: package_subdir,\n latex: latex_subdir,\n }\n}\n\n/// Check if a directory contains .tex files\nfn has_tex_files(path: &Path) -> bool {\n fs::read_dir(path)\n .map(|entries| {\n entries\n .flatten()\n .any(|e| e.path().extension().is_some_and(|ext| ext == \"tex\"))\n })\n .unwrap_or(false)\n}\n\nfn detect_server_project(project_root: &Path) -> Option<String> {\n if let Some(reason) = detect_rust_server(project_root) {\n return Some(reason);\n }\n if let Some(reason) = detect_node_server(project_root) {\n return Some(reason);\n }\n None\n}\n\nfn detect_rust_server(project_root: &Path) -> Option<String> {\n let path = project_root.join(\"Cargo.toml\");\n let content = fs::read_to_string(&path).ok()?;\n let value: toml::Value = toml::from_str(&content).ok()?;\n\n let mut deps = std::collections::HashSet::new();\n if let Some(table) = value.get(\"dependencies\").and_then(toml::Value::as_table) {\n deps.extend(table.keys().cloned());\n }\n if let Some(workspace) = value.get(\"workspace\").and_then(toml::Value::as_table) {\n if let Some(table) = workspace\n .get(\"dependencies\")\n .and_then(toml::Value::as_table)\n {\n deps.extend(table.keys().cloned());\n }\n }\n\n let server_deps = [\n \"axum\",\n \"actix-web\",\n \"warp\",\n \"rocket\",\n \"hyper\",\n \"tower-http\",\n \"tonic\",\n ];\n for dep in server_deps {\n if deps.contains(dep) {\n return Some(format!(\"Rust server crate detected: {dep}\"));\n }\n }\n\n None\n}\n\nfn detect_node_server(project_root: &Path) -> Option<String> {\n let path = project_root.join(\"package.json\");\n let content = fs::read_to_string(&path).ok()?;\n let value: serde_json::Value = serde_json::from_str(&content).ok()?;\n\n let mut deps = std::collections::HashSet::new();\n for key in [\"dependencies\", \"devDependencies\", \"peerDependencies\"] {\n if let Some(table) = value.get(key).and_then(|v| v.as_object()) {\n deps.extend(table.keys().cloned());\n }\n }\n\n let server_deps = [\n \"express\", \"fastify\", \"koa\", \"hono\", \"next\", \"remix\", \"nestjs\",\n ];\n for dep in server_deps {\n if deps.contains(dep) {\n return Some(format!(\"Node server framework detected: {dep}\"));\n }\n }\n\n None\n}\n\nfn ai_flow_toml_mismatch_reason(project_root: &Path, toml_content: &str) -> Option<String> {\n let has_cargo = project_root.join(\"Cargo.toml\").exists();\n let has_package = project_root.join(\"package.json\").exists();\n let has_tex = has_tex_files(project_root);\n\n // Also check subdirectories\n let subdir_projects = find_subdir_projects(project_root);\n let cargo_found = has_cargo || subdir_projects.cargo.is_some();\n let package_found = has_package || subdir_projects.package.is_some();\n let latex_found = has_tex || subdir_projects.latex.is_some();\n\n let parsed: toml::Value = toml::from_str(toml_content).ok()?;\n\n let tasks = parsed.get(\"tasks\").and_then(toml::Value::as_array)?;\n\n let mut uses_node = false;\n let mut uses_cargo = false;\n let mut uses_latex = false;\n\n for task in tasks {\n let command = match task.get(\"command\").and_then(toml::Value::as_str) {\n Some(cmd) => cmd,\n None => continue,\n };\n uses_node |= command_uses_node_tool(command);\n uses_cargo |= command_uses_cargo_tool(command);\n uses_latex |= command_uses_latex_tool(command);\n }\n\n if cargo_found && !package_found && uses_node {\n return Some(\n \"AI suggested Node tooling (bun/npm/pnpm/yarn), but no package.json was found.\"\n .to_string(),\n );\n }\n if package_found && !cargo_found && uses_cargo {\n return Some(\"AI suggested Cargo commands, but no Cargo.toml was found.\".to_string());\n }\n if !latex_found && uses_latex {\n return Some(\"AI suggested LaTeX commands, but no .tex files were found.\".to_string());\n }\n\n None\n}\n\nfn command_uses_node_tool(command: &str) -> bool {\n [\"bun\", \"npm\", \"pnpm\", \"yarn\"]\n .iter()\n .any(|tool| command_mentions_tool(command, tool))\n}\n\nfn command_uses_cargo_tool(command: &str) -> bool {\n command_mentions_tool(command, \"cargo\")\n}\n\nfn command_uses_latex_tool(command: &str) -> bool {\n [\n \"pdflatex\", \"xelatex\", \"lualatex\", \"latexmk\", \"latex\", \"bibtex\", \"biber\",\n ]\n .iter()\n .any(|tool| command_mentions_tool(command, tool))\n}\n\nfn command_mentions_tool(command: &str, tool: &str) -> bool {\n command.split_whitespace().any(|part| {\n let trimmed =\n part.trim_matches(|c: char| !c.is_ascii_alphanumeric() && c != '-' && c != '_');\n trimmed.eq_ignore_ascii_case(tool)\n })\n}\n\nfn render_flow_toml(setup_cmd: &str, dev_cmd: &str, deps: Vec<DepSpec>) -> String {\n let setup_cmd = setup_cmd.trim();\n let dev_cmd = dev_cmd.trim();\n let setup_cmd = if setup_cmd.is_empty() {\n \"echo TODO: add setup command\"\n } else {\n setup_cmd\n };\n let dev_cmd = if dev_cmd.is_empty() {\n \"echo TODO: add dev command\"\n } else {\n dev_cmd\n };\n\n // Determine appropriate descriptions based on project type\n let dev_description = if command_uses_latex_tool(dev_cmd) {\n \"Compile document\"\n } else {\n \"Run development server\"\n };\n\n let enable_bun_testing_gate = template_uses_bun(setup_cmd, dev_cmd, &deps);\n let mut out = String::from(\"version = 1\\n\\n\");\n out.push_str(\"[[tasks]]\\n\");\n out.push_str(\"name = \\\"setup\\\"\\n\");\n out.push_str(&format!(\"command = \\\"{}\\\"\\n\", toml_escape(setup_cmd)));\n out.push_str(\"description = \\\"Install tools and dependencies\\\"\\n\");\n out.push_str(\"shortcuts = [\\\"s\\\"]\\n\");\n if command_needs_interactive(setup_cmd) {\n out.push_str(\"interactive = true\\n\");\n }\n if !deps.is_empty() {\n out.push_str(\"dependencies = [\");\n out.push_str(\n &deps\n .iter()\n .map(|d| format!(\"\\\"{}\\\"\", dep_name(d)))\n .collect::<Vec<_>>()\n .join(\", \"),\n );\n out.push_str(\"]\\n\");\n }\n out.push('\\n');\n out.push_str(\"[[tasks]]\\n\");\n out.push_str(\"name = \\\"dev\\\"\\n\");\n out.push_str(&format!(\"command = \\\"{}\\\"\\n\", toml_escape(dev_cmd)));\n out.push_str(&format!(\"description = \\\"{dev_description}\\\"\\n\"));\n out.push_str(\"dependencies = [\\\"setup\\\"]\\n\");\n out.push_str(\"shortcuts = [\\\"d\\\"]\\n\");\n if command_needs_interactive(dev_cmd) {\n out.push_str(\"interactive = true\\n\");\n }\n\n if !deps.is_empty() {\n out.push('\\n');\n out.push_str(\"[deps]\\n\");\n for dep in deps {\n match dep {\n DepSpec::Single(name, cmd) => {\n out.push_str(&format!(\"{name} = \\\"{cmd}\\\"\\n\"));\n }\n DepSpec::Multiple(name, cmds) => {\n let joined = cmds\n .iter()\n .map(|c| format!(\"\\\"{c}\\\"\"))\n .collect::<Vec<_>>()\n .join(\", \");\n out.push_str(&format!(\"{name} = [{joined}]\\n\"));\n }\n }\n }\n }\n\n ensure_codex_flow_baseline(&out, enable_bun_testing_gate)\n}\n\nfn contains_toml_section(content: &str, section_header: &str) -> bool {\n content.lines().any(|line| line.trim() == section_header)\n}\n\nfn append_toml_section_if_missing(out: &mut String, section_header: &str, section_body: &str) {\n if contains_toml_section(out, section_header) {\n return;\n }\n if !out.ends_with('\\n') {\n out.push('\\n');\n }\n if !out.ends_with(\"\\n\\n\") {\n out.push('\\n');\n }\n out.push_str(section_body.trim_end());\n out.push('\\n');\n}\n\nfn ensure_codex_flow_baseline(content: &str, enable_bun_testing_gate: bool) -> String {\n let mut out = ensure_trailing_newline(content.to_string());\n\n append_toml_section_if_missing(\n &mut out,\n \"[skills]\",\n r#\"[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\"#,\n );\n\n append_toml_section_if_missing(\n &mut out,\n \"[skills.codex]\",\n r#\"[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\"#,\n );\n\n append_toml_section_if_missing(\n &mut out,\n \"[commit.skill_gate]\",\n r#\"[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\"#,\n );\n\n append_toml_section_if_missing(\n &mut out,\n \"[commit.skill_gate.min_version]\",\n r#\"[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\"#,\n );\n\n if enable_bun_testing_gate {\n append_toml_section_if_missing(\n &mut out,\n \"[commit.testing]\",\n r#\"[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\"#,\n );\n }\n\n ensure_trailing_newline(out)\n}\n\nfn template_uses_bun(setup_cmd: &str, dev_cmd: &str, deps: &[DepSpec]) -> bool {\n if command_mentions_tool(setup_cmd, \"bun\") || command_mentions_tool(dev_cmd, \"bun\") {\n return true;\n }\n deps.iter().any(|dep| match dep {\n DepSpec::Single(name, cmd) => {\n name.eq_ignore_ascii_case(\"bun\") || cmd.eq_ignore_ascii_case(\"bun\")\n }\n DepSpec::Multiple(name, cmds) => {\n name.eq_ignore_ascii_case(\"bun\")\n || cmds.iter().any(|cmd| cmd.eq_ignore_ascii_case(\"bun\"))\n }\n })\n}\n\nfn detect_bun_context(project_root: &Path, content: &str) -> bool {\n if project_root.join(\"bun.lock\").exists() || project_root.join(\"bun.lockb\").exists() {\n return true;\n }\n if project_root.join(\"build.zig\").exists() && project_root.join(\"src/bun.js\").exists() {\n return true;\n }\n let lowered = content.to_ascii_lowercase();\n lowered.contains(\"bun install\")\n || lowered.contains(\"bun run\")\n || lowered.contains(\"bun dev\")\n || lowered.contains(\"bun test\")\n}\n\nfn command_needs_interactive(command: &str) -> bool {\n let lower = command.to_ascii_lowercase();\n lower.contains(\"read -p\")\n || lower.contains(\"read -s\")\n || lower.contains(\"fzf\")\n || lower.contains(\"password\")\n}\n\nfn dep_name(dep: &DepSpec) -> &'static str {\n match dep {\n DepSpec::Single(name, _) => name,\n DepSpec::Multiple(name, _) => name,\n }\n}\n\nfn toml_escape(value: &str) -> String {\n value.replace('\\\\', \"\\\\\\\\\").replace('\"', \"\\\\\\\"\")\n}\n\nfn ensure_trailing_newline(mut content: String) -> String {\n if !content.ends_with('\\n') {\n content.push('\\n');\n }\n content\n}\n\nfn prompt_yes_no(message: &str, default_yes: bool) -> Result<bool> {\n let prompt = if default_yes { \"[Y/n]\" } else { \"[y/N]\" };\n print!(\"{message} {prompt}: \");\n io::stdout().flush()?;\n if io::stdin().is_terminal() {\n return read_yes_no_key(default_yes);\n }\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let answer = input.trim().to_ascii_lowercase();\n if answer.is_empty() {\n return Ok(default_yes);\n }\n Ok(answer == \"y\" || answer == \"yes\")\n}\n\nfn prompt_optional(message: &str) -> Result<String> {\n print!(\"{message}: \");\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n Ok(input.trim().to_string())\n}\n\nfn prompt_line(message: &str, default: Option<&str>) -> Result<String> {\n if let Some(default) = default {\n print!(\"{message} [{default}]: \");\n } else {\n print!(\"{message}: \");\n }\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n let trimmed = input.trim();\n if trimmed.is_empty() {\n return Ok(default.unwrap_or(\"\").to_string());\n }\n Ok(trimmed.to_string())\n}\n\nfn read_yes_no_key(default_yes: bool) -> Result<bool> {\n enable_raw_mode().context(\"failed to enable raw mode\")?;\n let mut selection = default_yes;\n let mut echo_char: Option<char> = None;\n loop {\n if let CEvent::Key(key) = event::read()? {\n match key.code {\n KeyCode::Char('y') | KeyCode::Char('Y') => {\n selection = true;\n echo_char = Some('y');\n break;\n }\n KeyCode::Char('n') | KeyCode::Char('N') => {\n selection = false;\n echo_char = Some('n');\n break;\n }\n KeyCode::Enter => {\n break;\n }\n KeyCode::Esc => {\n selection = false;\n break;\n }\n _ => {}\n }\n }\n }\n\n disable_raw_mode().context(\"failed to disable raw mode\")?;\n if let Some(ch) = echo_char {\n println!(\"{ch}\");\n } else {\n println!();\n }\n Ok(selection)\n}\n\nfn prompt_line_optional(message: &str, default: Option<&str>) -> Result<Option<String>> {\n let value = prompt_line(message, default)?;\n Ok(normalize_optional(value))\n}\n\nfn prompt_u16_optional(message: &str, default: Option<u16>) -> Result<Option<u16>> {\n let default_str = default.map(|v| v.to_string());\n let value = prompt_line_optional(message, default_str.as_deref())?;\n match value {\n Some(text) => text.parse::<u16>().map(Some).context(\"invalid port value\"),\n None => Ok(None),\n }\n}\n\nfn normalize_optional(value: String) -> Option<String> {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n }\n}\n\nfn format_alias_lines(aliases: &std::collections::HashMap<String, String>) -> Vec<String> {\n let mut ordered = BTreeMap::new();\n for (name, target) in aliases {\n ordered.insert(name, target);\n }\n\n ordered\n .into_iter()\n .map(|(name, target)| format!(\"alias {name}='{}'\", escape_single_quotes(target)))\n .collect()\n}\n\nfn escape_single_quotes(value: &str) -> String {\n value.replace('\\'', \"'\\\\''\")\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use std::collections::HashMap;\n use tempfile::tempdir;\n\n #[test]\n fn formats_alias_lines_in_order() {\n let mut aliases = HashMap::new();\n aliases.insert(\"fr\".to_string(), \"f run\".to_string());\n aliases.insert(\"ft\".to_string(), \"f tasks\".to_string());\n\n let lines = format_alias_lines(&aliases);\n assert_eq!(\n lines,\n vec![\n \"alias fr='f run'\".to_string(),\n \"alias ft='f tasks'\".to_string()\n ]\n );\n }\n\n #[test]\n fn escapes_single_quotes_in_commands() {\n let cmd = \"echo 'hello'\";\n assert_eq!(escape_single_quotes(cmd), \"echo '\\\\''hello'\\\\''\");\n }\n\n #[test]\n fn render_flow_toml_includes_codex_skill_baseline() {\n let toml = render_flow_toml(\"cargo build --locked\", \"cargo run\", vec![]);\n assert!(toml.contains(\"[skills]\"));\n assert!(toml.contains(\"[skills.codex]\"));\n assert!(toml.contains(\"[commit.skill_gate]\"));\n assert!(toml.contains(\"[commit.skill_gate.min_version]\"));\n assert!(!toml.contains(\"[commit.testing]\"));\n }\n\n #[test]\n fn render_flow_toml_enables_bun_testing_gate_for_bun_templates() {\n let toml = render_flow_toml(\n \"bun install\",\n \"bun run dev\",\n vec![DepSpec::Single(\"bun\", \"bun\")],\n );\n assert!(toml.contains(\"[commit.testing]\"));\n assert!(toml.contains(\"runner = \\\"bun\\\"\"));\n assert!(toml.contains(\"mode = \\\"block\\\"\"));\n }\n\n #[test]\n fn upgrade_existing_flow_toml_adds_codex_baseline() {\n let dir = tempdir().expect(\"tempdir\");\n let config_path = dir.path().join(\"flow.toml\");\n fs::write(\n &config_path,\n r#\"version = 1\n\n[[tasks]]\nname = \"setup\"\ncommand = \"echo setup\"\n\"#,\n )\n .expect(\"write flow.toml\");\n\n let changed = maybe_upgrade_existing_flow_toml(dir.path(), &config_path)\n .expect(\"upgrade should succeed\");\n assert!(changed, \"existing file should be upgraded\");\n\n let updated = fs::read_to_string(&config_path).expect(\"read updated flow.toml\");\n assert!(updated.contains(\"[skills]\"));\n assert!(updated.contains(\"[skills.codex]\"));\n assert!(updated.contains(\"[commit.skill_gate]\"));\n assert!(updated.contains(\"[commit.skill_gate.min_version]\"));\n assert!(!updated.contains(\"[commit.testing]\"));\n }\n\n #[test]\n fn upgrade_existing_flow_toml_adds_bun_testing_gate_in_bun_context() {\n let dir = tempdir().expect(\"tempdir\");\n let config_path = dir.path().join(\"flow.toml\");\n fs::write(\n &config_path,\n r#\"version = 1\n\n[[tasks]]\nname = \"setup\"\ncommand = \"bun install\"\n\"#,\n )\n .expect(\"write flow.toml\");\n fs::write(dir.path().join(\"bun.lock\"), \"\").expect(\"write bun.lock\");\n\n let changed = maybe_upgrade_existing_flow_toml(dir.path(), &config_path)\n .expect(\"upgrade should succeed\");\n assert!(changed, \"existing file should be upgraded\");\n\n let updated = fs::read_to_string(&config_path).expect(\"read updated flow.toml\");\n assert!(updated.contains(\"[commit.testing]\"));\n assert!(updated.contains(\"runner = \\\"bun\\\"\"));\n }\n\n #[test]\n fn run_prefers_existing_setup_task_without_flow_bootstrap() {\n let dir = tempdir().expect(\"tempdir\");\n let config_path = dir.path().join(\"flow.toml\");\n fs::write(\n &config_path,\n r#\"version = 1\n\n[[tasks]]\nname = \"setup\"\ncommand = \"printf ok > setup-ran.txt\"\n\"#,\n )\n .expect(\"write flow.toml\");\n\n run(SetupOpts {\n config: config_path.clone(),\n target: None,\n })\n .expect(\"setup should delegate to project task\");\n\n assert!(\n dir.path().join(\"setup-ran.txt\").exists(),\n \"project setup task should run\"\n );\n assert!(\n !dir.path().join(\".ai\").exists(),\n \"flow bootstrap should not create .ai when project setup exists\"\n );\n assert!(\n !dir.path().join(\".gitignore\").exists(),\n \"flow bootstrap should not rewrite .gitignore when project setup exists\"\n );\n\n let flow_toml = fs::read_to_string(&config_path).expect(\"read flow.toml\");\n assert!(\n !flow_toml.contains(\"[skills]\"),\n \"flow setup baseline should not be injected when project setup exists\"\n );\n }\n}\n" }, { "path": "src/skills.rs", "content": "//! Codex skills management.\n//!\n//! Skills are stored in .ai/skills/<name>/SKILL.md (gitignored by default).\n\nuse std::fs;\nuse std::io::{BufRead, BufReader, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\nuse std::time::{Duration, Instant};\n\nuse anyhow::{Context, Result, bail};\nuse serde_json::json;\n\nuse crate::cli::{SkillsAction, SkillsCommand, SkillsFetchAction, SkillsFetchCommand};\nuse crate::commit::configured_codex_bin_for_workdir;\nuse crate::config;\nuse crate::start;\n\nconst DEFAULT_ENV_SKILL: &str = include_str!(\"../.ai/skills/env/skill.md\");\nconst DEFAULT_QUALITY_BUN_FEATURE_DELIVERY_SKILL: &str =\n include_str!(\"../.ai/skills/quality-bun-feature-delivery/skill.md\");\nconst DEFAULT_PR_MARKDOWN_BODY_FILE_SKILL: &str =\n include_str!(\"../.ai/skills/pr-markdown-body-file/skill.md\");\n\n#[derive(Debug, Default)]\npub struct SkillsEnforceSummary {\n pub task_skills_created: usize,\n pub task_skills_updated: usize,\n pub installed_skills: Vec<String>,\n}\n\nimpl SkillsEnforceSummary {\n pub fn is_noop(&self) -> bool {\n self.task_skills_created == 0\n && self.task_skills_updated == 0\n && self.installed_skills.is_empty()\n }\n}\n\n#[derive(Debug, Clone, Copy)]\nstruct SkillSyncOptions {\n generate_openai_yaml: bool,\n task_skill_allow_implicit_invocation: bool,\n}\n\nimpl Default for SkillSyncOptions {\n fn default() -> Self {\n Self {\n generate_openai_yaml: true,\n task_skill_allow_implicit_invocation: false,\n }\n }\n}\n\n/// Run the skills subcommand.\npub fn run(cmd: SkillsCommand) -> Result<()> {\n let action = cmd.action.unwrap_or(SkillsAction::List);\n\n match action {\n SkillsAction::List => list_skills()?,\n SkillsAction::New { name, description } => new_skill(&name, description.as_deref())?,\n SkillsAction::Show { name } => show_skill(&name)?,\n SkillsAction::Edit { name } => edit_skill(&name)?,\n SkillsAction::Remove { name } => remove_skill(&name)?,\n SkillsAction::Install { name } => install_skill(&name)?,\n SkillsAction::Publish { name } => publish_skill(&name)?,\n SkillsAction::Search { query } => list_remote_skills(query.as_deref())?,\n SkillsAction::Sync => sync_skills()?,\n SkillsAction::Reload => reload_skills()?,\n SkillsAction::Fetch(fetch) => fetch_skills(&fetch)?,\n }\n\n Ok(())\n}\n\n/// Get the skills directory for the current project.\nfn get_skills_dir() -> Result<PathBuf> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n Ok(get_skills_dir_at(&cwd))\n}\n\nfn get_skills_dir_at(project_root: &Path) -> PathBuf {\n project_root.join(\".ai\").join(\"skills\")\n}\n\npub fn read_skill_content_at(project_root: &Path, name: &str) -> Result<Option<String>> {\n let skill_dir = get_skills_dir_at(project_root).join(name);\n let Some(skill_file) = find_skill_file(&skill_dir) else {\n return Ok(None);\n };\n let content = fs::read_to_string(&skill_file)\n .with_context(|| format!(\"failed to read {}\", skill_file.display()))?;\n Ok(Some(content))\n}\n\npub fn read_skill_frontmatter_field_at(\n project_root: &Path,\n name: &str,\n field: &str,\n) -> Result<Option<String>> {\n let Some(content) = read_skill_content_at(project_root, name)? else {\n return Ok(None);\n };\n Ok(parse_frontmatter_field(&content, field))\n}\n\npub fn read_skill_version_at(project_root: &Path, name: &str) -> Result<Option<u32>> {\n let Some(raw) = read_skill_frontmatter_field_at(project_root, name, \"version\")? else {\n return Ok(None);\n };\n let trimmed = raw.trim().trim_matches('\"').trim_matches('\\'');\n if trimmed.is_empty() {\n return Ok(None);\n }\n match trimmed.parse::<u32>() {\n Ok(version) => Ok(Some(version)),\n Err(_) => Ok(None),\n }\n}\n\nfn skill_file_lower(skill_dir: &Path) -> PathBuf {\n skill_dir.join(\"skill.md\")\n}\n\nfn skill_file_upper(skill_dir: &Path) -> PathBuf {\n skill_dir.join(\"SKILL.md\")\n}\n\nfn has_exact_skill_filename(skill_dir: &Path, filename: &str) -> Result<bool> {\n if !skill_dir.exists() {\n return Ok(false);\n }\n for entry in fs::read_dir(skill_dir)? {\n let entry = entry?;\n if entry.file_name().to_string_lossy() == filename {\n return Ok(true);\n }\n }\n Ok(false)\n}\n\nfn find_skill_file(skill_dir: &Path) -> Option<PathBuf> {\n let upper = skill_file_upper(skill_dir);\n if upper.exists() {\n return Some(upper);\n }\n let lower = skill_file_lower(skill_dir);\n if lower.exists() {\n return Some(lower);\n }\n None\n}\n\nfn normalize_single_skill_file(skill_dir: &Path) -> Result<bool> {\n if !skill_dir.exists() {\n return Ok(false);\n }\n\n let lower = skill_file_lower(skill_dir);\n let upper = skill_file_upper(skill_dir);\n let lower_exact = has_exact_skill_filename(skill_dir, \"skill.md\")?;\n let upper_exact = has_exact_skill_filename(skill_dir, \"SKILL.md\")?;\n\n if upper_exact && lower_exact {\n fs::remove_file(&lower)?;\n return Ok(true);\n }\n\n if upper_exact {\n return Ok(false);\n }\n\n if !lower_exact {\n return Ok(false);\n }\n\n // Case-only renames are unreliable on case-insensitive filesystems, so\n // rename through a temporary filename.\n let tmp = skill_dir.join(\".flow-skill-case-tmp.md\");\n if tmp.exists() {\n fs::remove_file(&tmp)?;\n }\n fs::rename(&lower, &tmp)?;\n fs::rename(&tmp, &upper)?;\n Ok(true)\n}\n\nfn normalize_skill_files(skills_dir: &Path) -> Result<usize> {\n if !skills_dir.exists() {\n return Ok(0);\n }\n let mut renamed = 0usize;\n for entry in fs::read_dir(skills_dir).context(\"failed to read skills directory\")? {\n let entry = entry?;\n let path = entry.path();\n if path.is_dir() && normalize_single_skill_file(&path)? {\n renamed += 1;\n }\n }\n Ok(renamed)\n}\n\n/// Ensure symlinks exist from .claude/skills and .codex/skills to .ai/skills\nfn ensure_symlinks() -> Result<()> {\n let cwd = std::env::current_dir()?;\n ensure_symlinks_at(&cwd)\n}\n\nfn ensure_symlinks_at(project_root: &Path) -> Result<()> {\n let ai_skills = project_root.join(\".ai\").join(\"skills\");\n\n if !ai_skills.exists() {\n return Ok(());\n }\n\n // Create .claude/skills -> .ai/skills\n let claude_dir = project_root.join(\".claude\");\n let claude_skills = claude_dir.join(\"skills\");\n create_symlink_if_needed(&ai_skills, &claude_dir, &claude_skills)?;\n\n // Create .codex/skills -> .ai/skills\n let codex_dir = project_root.join(\".codex\");\n let codex_skills = codex_dir.join(\"skills\");\n create_symlink_if_needed(&ai_skills, &codex_dir, &codex_skills)?;\n\n Ok(())\n}\n\nfn merge_skill_entries_into_existing_dir(source_dir: &Path, existing_dir: &Path) -> Result<()> {\n if !existing_dir.exists() {\n fs::create_dir_all(existing_dir)?;\n }\n\n for entry in fs::read_dir(source_dir).context(\"failed to read source skills directory\")? {\n let entry = entry?;\n let source_path = entry.path();\n let name = entry.file_name();\n let dest_path = existing_dir.join(name);\n\n if dest_path.exists() || dest_path.is_symlink() {\n continue;\n }\n\n #[cfg(unix)]\n {\n use std::os::unix::fs::symlink;\n symlink(&source_path, &dest_path)?;\n }\n\n #[cfg(windows)]\n {\n if source_path.is_dir() {\n use std::os::windows::fs::symlink_dir;\n symlink_dir(&source_path, &dest_path)?;\n } else {\n use std::os::windows::fs::symlink_file;\n symlink_file(&source_path, &dest_path)?;\n }\n }\n }\n\n Ok(())\n}\n\n/// Create a symlink if it doesn't exist or points elsewhere.\nfn create_symlink_if_needed(\n target: &PathBuf,\n parent_dir: &PathBuf,\n link_path: &PathBuf,\n) -> Result<()> {\n // Create parent directory if needed\n if !parent_dir.exists() {\n fs::create_dir_all(parent_dir)?;\n }\n\n // Check if symlink already exists and points to correct target\n if link_path.is_symlink() {\n if let Ok(existing_target) = fs::read_link(link_path) {\n if existing_target == *target || existing_target == PathBuf::from(\"../.ai/skills\") {\n return Ok(()); // Already correct\n }\n }\n // Wrong target, remove it\n fs::remove_file(link_path)?;\n } else if link_path.exists() {\n // It's a real directory, keep the directory and merge missing local skills into it.\n if link_path.is_dir() {\n merge_skill_entries_into_existing_dir(target, link_path)?;\n }\n return Ok(());\n }\n\n // Create relative symlink: .claude/skills -> ../.ai/skills\n #[cfg(unix)]\n {\n use std::os::unix::fs::symlink;\n symlink(\"../.ai/skills\", link_path)?;\n }\n\n #[cfg(windows)]\n {\n use std::os::windows::fs::symlink_dir;\n symlink_dir(target, link_path)?;\n }\n\n Ok(())\n}\n\n/// List all skills in the project.\nfn list_skills() -> Result<()> {\n let skills_dir = get_skills_dir()?;\n\n if !skills_dir.exists() {\n println!(\"No skills found. Create one with: f skills new <name>\");\n return Ok(());\n }\n\n let entries = fs::read_dir(&skills_dir).context(\"failed to read skills directory\")?;\n\n let mut skills: Vec<(String, Option<String>)> = Vec::new();\n\n for entry in entries {\n let entry = entry?;\n let path = entry.path();\n\n if path.is_dir() {\n let name = path\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(\"\")\n .to_string();\n\n let description =\n find_skill_file(&path).and_then(|skill_file| parse_skill_description(&skill_file));\n\n skills.push((name, description));\n }\n }\n\n if skills.is_empty() {\n println!(\"No skills found. Create one with: f skills new <name>\");\n return Ok(());\n }\n\n skills.sort_by(|a, b| a.0.cmp(&b.0));\n\n println!(\"Skills in .ai/skills/:\\n\");\n for (name, desc) in skills {\n if let Some(d) = desc {\n println!(\" {} - {}\", name, d);\n } else {\n println!(\" {}\", name);\n }\n }\n\n Ok(())\n}\n\n/// Parse the description from a skill file.\nfn parse_skill_description(path: &Path) -> Option<String> {\n let content = fs::read_to_string(path).ok()?;\n\n // Look for description in YAML frontmatter\n if content.starts_with(\"---\") {\n let parts: Vec<&str> = content.splitn(3, \"---\").collect();\n if parts.len() >= 2 {\n for line in parts[1].lines() {\n let line = line.trim();\n if line.starts_with(\"description:\") {\n return Some(line.trim_start_matches(\"description:\").trim().to_string());\n }\n }\n }\n }\n\n None\n}\n\nfn resolve_skill_sync_options(skills_cfg: Option<&config::SkillsConfig>) -> SkillSyncOptions {\n let mut options = SkillSyncOptions::default();\n if let Some(codex_cfg) = skills_cfg.and_then(|cfg| cfg.codex.as_ref()) {\n if let Some(value) = codex_cfg.generate_openai_yaml {\n options.generate_openai_yaml = value;\n }\n if let Some(value) = codex_cfg.task_skill_allow_implicit_invocation {\n options.task_skill_allow_implicit_invocation = value;\n }\n }\n options\n}\n\nfn should_force_reload_after_sync(skills_cfg: Option<&config::SkillsConfig>) -> bool {\n skills_cfg\n .and_then(|cfg| cfg.codex.as_ref())\n .and_then(|cfg| cfg.force_reload_after_sync)\n .unwrap_or(true)\n}\n\nfn task_name_to_display_name(task_name: &str) -> String {\n task_name\n .split(['-', '_', ' '])\n .filter(|part| !part.is_empty())\n .map(|part| {\n let mut chars = part.chars();\n let Some(first) = chars.next() else {\n return String::new();\n };\n format!(\n \"{}{}\",\n first.to_ascii_uppercase(),\n chars.as_str().to_ascii_lowercase()\n )\n })\n .filter(|part| !part.is_empty())\n .collect::<Vec<_>>()\n .join(\" \")\n}\n\nfn truncate_chars(value: &str, max_chars: usize) -> String {\n if value.chars().count() <= max_chars {\n return value.to_string();\n }\n let mut out = String::new();\n for (idx, ch) in value.chars().enumerate() {\n if idx >= max_chars.saturating_sub(1) {\n break;\n }\n out.push(ch);\n }\n out.push('…');\n out\n}\n\nfn yaml_quote(value: &str) -> String {\n format!(\n \"\\\"{}\\\"\",\n value\n .replace('\\\\', \"\\\\\\\\\")\n .replace('\"', \"\\\\\\\"\")\n .replace('\\n', \" \")\n )\n}\n\nfn render_task_skill_openai_yaml(\n task: &config::TaskConfig,\n allow_implicit_invocation: bool,\n) -> String {\n let desc = task.description.as_deref().unwrap_or(\"Flow task\");\n let display_name = task_name_to_display_name(&task.name);\n let short_description = truncate_chars(desc, 64);\n let default_prompt = format!(\"Use ${} to {}.\", task.name, desc.trim_end_matches('.'));\n\n format!(\n \"interface:\\n display_name: {}\\n short_description: {}\\n default_prompt: {}\\n\\npolicy:\\n allow_implicit_invocation: {}\\n\",\n yaml_quote(&display_name),\n yaml_quote(&short_description),\n yaml_quote(&default_prompt),\n if allow_implicit_invocation {\n \"true\"\n } else {\n \"false\"\n }\n )\n}\n\nfn write_task_skill_metadata(\n skill_dir: &Path,\n task: &config::TaskConfig,\n options: SkillSyncOptions,\n) -> Result<()> {\n if !options.generate_openai_yaml {\n return Ok(());\n }\n\n let agents_dir = skill_dir.join(\"agents\");\n let metadata_path = agents_dir.join(\"openai.yaml\");\n let content = render_task_skill_openai_yaml(task, options.task_skill_allow_implicit_invocation);\n\n let should_write = match fs::read_to_string(&metadata_path) {\n Ok(existing) => existing != content,\n Err(err) if err.kind() == std::io::ErrorKind::NotFound => true,\n Err(err) => return Err(err.into()),\n };\n if should_write {\n fs::create_dir_all(&agents_dir)?;\n fs::write(&metadata_path, content)?;\n }\n\n Ok(())\n}\n\n/// Create a new skill.\nfn new_skill(name: &str, description: Option<&str>) -> Result<()> {\n let skills_dir = get_skills_dir()?;\n let skill_dir = skills_dir.join(name);\n\n if skill_dir.exists() {\n bail!(\"Skill '{}' already exists\", name);\n }\n\n // Create skill directory\n fs::create_dir_all(&skill_dir).context(\"failed to create skill directory\")?;\n\n // Create SKILL.md\n let desc = description.unwrap_or(\"TODO: Add description\");\n let fm_name = yaml_quote(name);\n let fm_desc = yaml_quote(desc);\n let content = format!(\n r#\"---\nname: {}\ndescription: {}\n---\n\n# {}\n\n## Instructions\n\nTODO: Add instructions for this skill.\n\n## Examples\n\n```bash\n# Example usage\n```\n\"#,\n fm_name, fm_desc, name\n );\n\n let skill_file = skill_file_upper(&skill_dir);\n fs::write(&skill_file, content).context(\"failed to write SKILL.md\")?;\n\n // Ensure symlinks exist for Claude Code and Codex\n ensure_symlinks()?;\n\n println!(\"Created skill: {}\", skill_dir.display());\n println!(\"\\nEdit it with: f skills edit {}\", name);\n\n Ok(())\n}\n\n/// Show skill details.\nfn show_skill(name: &str) -> Result<()> {\n let skills_dir = get_skills_dir()?;\n let skill_dir = skills_dir.join(name);\n let Some(skill_file) = find_skill_file(&skill_dir) else {\n bail!(\"Skill '{}' not found\", name);\n };\n\n let content = fs::read_to_string(&skill_file).context(\"failed to read skill file\")?;\n\n println!(\"{}\", content);\n\n Ok(())\n}\n\n/// Edit a skill in the user's editor.\nfn edit_skill(name: &str) -> Result<()> {\n let skills_dir = get_skills_dir()?;\n let skill_dir = skills_dir.join(name);\n let skill_file = if normalize_single_skill_file(&skill_dir)? {\n skill_file_upper(&skill_dir)\n } else if let Some(path) = find_skill_file(&skill_dir) {\n path\n } else {\n bail!(\n \"Skill '{}' not found. Create it with: f skills new {}\",\n name,\n name\n );\n };\n\n let editor = std::env::var(\"EDITOR\").unwrap_or_else(|_| \"vim\".to_string());\n\n Command::new(&editor)\n .arg(&skill_file)\n .status()\n .with_context(|| format!(\"failed to open editor: {}\", editor))?;\n\n Ok(())\n}\n\n/// Remove a skill.\nfn remove_skill(name: &str) -> Result<()> {\n let skills_dir = get_skills_dir()?;\n let skill_dir = skills_dir.join(name);\n\n if !skill_dir.exists() {\n bail!(\"Skill '{}' not found\", name);\n }\n\n fs::remove_dir_all(&skill_dir).context(\"failed to remove skill directory\")?;\n\n println!(\"Removed skill: {}\", name);\n\n Ok(())\n}\n\n/// Publish a local skill to the shared registry.\nfn publish_skill(name: &str) -> Result<()> {\n let skills_dir = get_skills_dir()?;\n let skill_dir = skills_dir.join(name);\n let Some(skill_file) = find_skill_file(&skill_dir) else {\n bail!(\n \"Skill '{}' not found locally. Create it first with: f skills new {}\",\n name,\n name\n );\n };\n\n let content = fs::read_to_string(&skill_file).context(\"failed to read skill file\")?;\n\n // Parse description from YAML frontmatter\n let description = parse_frontmatter_field(&content, \"description\")\n .unwrap_or_else(|| format!(\"{} skill\", name));\n\n // Get auth token\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n let token = myflow_token(&cwd).ok_or_else(|| {\n anyhow::anyhow!(\n \"No myflow token found. Set MYFLOW_TOKEN env var, add myflow_token to flow.toml, or run `f auth login`\"\n )\n })?;\n\n println!(\"Publishing skill '{}'...\", name);\n\n let client = reqwest::blocking::Client::new();\n let response = client\n .put(SKILLS_API_URL)\n .header(\"Authorization\", format!(\"Bearer {}\", token))\n .header(\"Content-Type\", \"application/json\")\n .json(&serde_json::json!({\n \"name\": name,\n \"description\": description,\n \"content\": content,\n \"source\": \"flow-cli\",\n }))\n .send()\n .context(\"failed to publish skill to registry\")?;\n\n if !response.status().is_success() {\n let status = response.status();\n let body = response.text().unwrap_or_default();\n bail!(\"Failed to publish skill: HTTP {} — {}\", status, body);\n }\n\n println!(\"Published skill '{}' to registry.\", name);\n println!(\"Others can install it with: f skills install {}\", name);\n\n Ok(())\n}\n\n/// Parse a field value from YAML frontmatter (between --- delimiters).\nfn parse_frontmatter_field(content: &str, field: &str) -> Option<String> {\n let trimmed = content.trim_start();\n if !trimmed.starts_with(\"---\") {\n return None;\n }\n let after_start = &trimmed[3..];\n let end = after_start.find(\"\\n---\")?;\n let frontmatter = &after_start[..end];\n for line in frontmatter.lines() {\n let line = line.trim();\n if let Some(rest) = line.strip_prefix(&format!(\"{}:\", field)) {\n let value = rest.trim();\n if !value.is_empty() {\n return Some(value.to_string());\n }\n }\n }\n None\n}\n\n/// Get myflow auth token from env, flow.toml, or auth.toml.\nfn myflow_token(repo_root: &Path) -> Option<String> {\n // 1. Check env var\n if let Ok(value) = std::env::var(\"MYFLOW_TOKEN\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n }\n }\n\n // 2. Check flow.toml\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(token) = cfg.options.myflow_token {\n let trimmed = token.trim().to_string();\n if !trimmed.is_empty() {\n return Some(trimmed);\n }\n }\n }\n }\n\n // 3. Fall back to ~/.config/flow/auth.toml token\n let config_dir = dirs::config_dir()?.join(\"flow\");\n let auth_path = config_dir.join(\"auth.toml\");\n if auth_path.exists() {\n if let Ok(content) = fs::read_to_string(&auth_path) {\n if let Ok(auth) = toml::from_str::<toml::Value>(&content) {\n if let Some(token) = auth.get(\"token\").and_then(|v| v.as_str()) {\n let trimmed = token.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n }\n }\n }\n }\n }\n\n None\n}\n\nconst SKILLS_API_URL: &str = \"https://myflow.sh/api/skills\";\n\nfn codex_skills_dir() -> Option<PathBuf> {\n if let Some(home) = std::env::var_os(\"CODEX_HOME\").map(PathBuf::from) {\n return Some(home.join(\"skills\"));\n }\n let home = std::env::var_os(\"HOME\").map(PathBuf::from)?;\n Some(home.join(\".codex\").join(\"skills\"))\n}\n\nfn read_local_skill_content(name: &str) -> Option<String> {\n let skills_dir = codex_skills_dir()?;\n // Codex skills typically store the body in SKILL.md.\n let candidates = [\n skills_dir.join(name).join(\"SKILL.md\"),\n skills_dir.join(name).join(\"skill.md\"),\n ];\n for path in candidates {\n if let Ok(content) = fs::read_to_string(&path) {\n if !content.trim().is_empty() {\n return Some(content);\n }\n }\n }\n None\n}\n\nfn load_seq_config(project_root: &Path) -> Result<Option<config::SkillsSeqConfig>> {\n let flow_toml = project_root.join(\"flow.toml\");\n if !flow_toml.exists() {\n return Ok(None);\n }\n let cfg = config::load(&flow_toml)?;\n Ok(cfg.skills.and_then(|skills| skills.seq))\n}\n\nfn default_seq_repo() -> PathBuf {\n if let Some(home) = std::env::var_os(\"HOME\").map(PathBuf::from) {\n return home.join(\"code\").join(\"seq\");\n }\n PathBuf::from(\"~/code/seq\")\n}\n\nfn resolve_path_arg(raw: &str, base: &Path) -> PathBuf {\n let expanded = config::expand_path(raw);\n if expanded.is_absolute() {\n expanded\n } else {\n base.join(expanded)\n }\n}\n\nfn resolve_seq_script_path(\n project_root: &Path,\n fetch: &SkillsFetchCommand,\n seq_cfg: Option<&config::SkillsSeqConfig>,\n) -> PathBuf {\n if let Some(raw) = fetch\n .script_path\n .as_deref()\n .or_else(|| seq_cfg.and_then(|cfg| cfg.script_path.as_deref()))\n {\n return resolve_path_arg(raw, project_root);\n }\n\n let repo = if let Some(raw) = fetch\n .seq_repo\n .as_deref()\n .or_else(|| seq_cfg.and_then(|cfg| cfg.seq_repo.as_deref()))\n {\n resolve_path_arg(raw, project_root)\n } else {\n default_seq_repo()\n };\n repo.join(\"tools\").join(\"teach_deps.py\")\n}\n\nfn fetch_skills(fetch: &SkillsFetchCommand) -> Result<()> {\n let project_root = std::env::current_dir().context(\"failed to get current directory\")?;\n let seq_cfg = load_seq_config(&project_root)?;\n let seq_cfg_ref = seq_cfg.as_ref();\n\n if let Some(mode) = seq_cfg_ref.and_then(|cfg| cfg.mode.as_deref()) {\n if mode != \"local-cli\" {\n println!(\n \"warning: [skills.seq] mode='{}' is not implemented yet; using local-cli\",\n mode\n );\n }\n }\n\n let script_path = resolve_seq_script_path(&project_root, fetch, seq_cfg_ref);\n if !script_path.exists() {\n bail!(\n \"seq teach script not found at {} (set [skills.seq].script_path or --script-path)\",\n script_path.display()\n );\n }\n\n let out_dir = fetch\n .out_dir\n .clone()\n .or_else(|| seq_cfg_ref.and_then(|cfg| cfg.out_dir.clone()))\n .unwrap_or_else(|| \".ai/skills\".to_string());\n\n let scraper_base_url = fetch\n .scraper_base_url\n .clone()\n .or_else(|| seq_cfg_ref.and_then(|cfg| cfg.scraper_base_url.clone()));\n let scraper_api_key = fetch\n .scraper_api_key\n .clone()\n .or_else(|| seq_cfg_ref.and_then(|cfg| cfg.scraper_api_key.clone()));\n let cache_ttl_hours = fetch\n .cache_ttl_hours\n .or_else(|| seq_cfg_ref.and_then(|cfg| cfg.cache_ttl_hours));\n let allow_direct_fallback = fetch.allow_direct_fallback\n || seq_cfg_ref\n .and_then(|cfg| cfg.allow_direct_fallback)\n .unwrap_or(false);\n let mem_events_path = fetch\n .mem_events_path\n .clone()\n .or_else(|| seq_cfg_ref.and_then(|cfg| cfg.mem_events_path.clone()));\n\n let mut args: Vec<String> = Vec::new();\n let force = match &fetch.action {\n SkillsFetchAction::Dep {\n deps,\n ecosystem,\n force,\n } => {\n if deps.is_empty() {\n bail!(\"skills fetch dep requires at least one dependency\");\n }\n args.push(\"dep\".to_string());\n args.extend(deps.iter().cloned());\n if let Some(eco) = ecosystem {\n args.push(\"--ecosystem\".to_string());\n args.push(eco.clone());\n }\n *force\n }\n SkillsFetchAction::Auto {\n top,\n ecosystems,\n force,\n } => {\n args.push(\"auto\".to_string());\n let resolved_top = top.or_else(|| seq_cfg_ref.and_then(|cfg| cfg.top));\n if let Some(value) = resolved_top {\n args.push(\"--top\".to_string());\n args.push(value.to_string());\n }\n let resolved_ecosystems = ecosystems\n .clone()\n .or_else(|| seq_cfg_ref.and_then(|cfg| cfg.ecosystems.clone()));\n if let Some(value) = resolved_ecosystems {\n args.push(\"--ecosystems\".to_string());\n args.push(value);\n }\n *force\n }\n SkillsFetchAction::Url { urls, name, force } => {\n if urls.is_empty() {\n bail!(\"skills fetch url requires at least one URL\");\n }\n args.push(\"url\".to_string());\n args.extend(urls.iter().cloned());\n if let Some(value) = name {\n args.push(\"--name\".to_string());\n args.push(value.clone());\n }\n *force\n }\n };\n\n args.push(\"--repo\".to_string());\n args.push(project_root.display().to_string());\n args.push(\"--out-dir\".to_string());\n args.push(out_dir.clone());\n\n if force {\n args.push(\"--force\".to_string());\n }\n if let Some(value) = scraper_base_url {\n args.push(\"--scraper-base-url\".to_string());\n args.push(value);\n }\n if let Some(value) = cache_ttl_hours {\n args.push(\"--cache-ttl-hours\".to_string());\n args.push(value.to_string());\n }\n if allow_direct_fallback {\n args.push(\"--allow-direct-fallback\".to_string());\n }\n if fetch.no_mem_events {\n args.push(\"--no-mem-events\".to_string());\n }\n if let Some(value) = mem_events_path {\n args.push(\"--mem-events-path\".to_string());\n args.push(value);\n }\n\n let mut cmd = Command::new(\"python3\");\n cmd.arg(&script_path);\n cmd.args(&args);\n cmd.current_dir(&project_root);\n if let Some(api_key) = scraper_api_key {\n cmd.env(\"SEQ_SCRAPER_API_KEY\", api_key);\n }\n\n let status = cmd.status().context(\"failed to run seq teach script\")?;\n if !status.success() {\n if let Some(code) = status.code() {\n bail!(\"skills fetch failed with exit code {}\", code);\n }\n bail!(\"skills fetch failed: process terminated by signal\");\n }\n\n let out_path = {\n let parsed = PathBuf::from(&out_dir);\n if parsed.is_absolute() {\n parsed\n } else {\n project_root.join(parsed)\n }\n };\n let renamed = normalize_skill_files(&out_path)?;\n ensure_symlinks_at(&project_root)?;\n\n println!(\"Fetched skills via seq into {}\", out_path.display());\n if renamed > 0 {\n println!(\"Normalized {} skill file(s) to SKILL.md\", renamed);\n }\n println!(\"Symlinked to .claude/skills/ and .codex/skills/\");\n\n Ok(())\n}\n\n/// Install a skill from the global skills registry.\nfn install_skill(name: &str) -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n let installed = install_skill_inner(&cwd, name, false, false)?;\n if installed {\n let flow_toml = cwd.join(\"flow.toml\");\n let cfg = if flow_toml.exists() {\n config::load_or_default(&flow_toml)\n } else {\n config::Config::default()\n };\n maybe_reload_codex_skills(&cwd, cfg.skills.as_ref(), \"skills install\");\n }\n Ok(())\n}\n\nfn install_skill_inner(\n project_root: &Path,\n name: &str,\n allow_existing: bool,\n quiet: bool,\n) -> Result<bool> {\n let skills_dir = get_skills_dir_at(project_root);\n let skill_dir = skills_dir.join(name);\n\n if skill_dir.exists() {\n if allow_existing {\n return Ok(false);\n }\n bail!(\n \"Skill '{}' already exists locally. Remove it first with: f skills remove {}\",\n name,\n name\n );\n }\n\n // Prefer local Codex skills (e.g. ~/.codex/skills/<name>/SKILL.md) when present.\n if let Some(content) = read_local_skill_content(name) {\n if !quiet {\n println!(\"Installing skill '{}' from local Codex skills...\", name);\n }\n\n fs::create_dir_all(&skill_dir)?;\n fs::write(skill_file_upper(&skill_dir), content)?;\n\n ensure_symlinks_at(project_root)?;\n\n if !quiet {\n println!(\"Installed skill: {}\", name);\n println!(\" Source: local (~/.codex/skills/)\");\n }\n\n return Ok(true);\n }\n\n if !quiet {\n println!(\"Fetching skill '{}' from registry...\", name);\n }\n\n // Fetch skill from API.\n let url = format!(\"{}?name={}\", SKILLS_API_URL, name);\n let response = reqwest::blocking::get(&url).context(\"failed to fetch skill from registry\")?;\n\n if response.status() == 404 {\n bail!(\n \"Skill '{}' not found in local Codex skills or registry\",\n name\n );\n }\n\n if !response.status().is_success() {\n bail!(\"Failed to fetch skill: HTTP {}\", response.status());\n }\n\n let skill: SkillResponse = response.json().context(\"failed to parse skill response\")?;\n\n // Create skill directory and write SKILL.md.\n fs::create_dir_all(&skill_dir)?;\n fs::write(skill_file_upper(&skill_dir), &skill.content)?;\n\n // Ensure symlinks\n ensure_symlinks_at(project_root)?;\n\n if !quiet {\n println!(\"Installed skill: {}\", name);\n println!(\n \" Source: {}\",\n skill.source.unwrap_or_else(|| \"unknown\".to_string())\n );\n if let Some(author) = skill.author {\n println!(\" Author: {}\", author);\n }\n }\n\n Ok(true)\n}\n\n#[derive(Debug, serde::Deserialize)]\n#[allow(dead_code)]\nstruct SkillResponse {\n name: String,\n description: String,\n content: String,\n source: Option<String>,\n author: Option<String>,\n}\n\n/// List available skills from the registry.\nfn list_remote_skills(search: Option<&str>) -> Result<()> {\n let url = if let Some(q) = search {\n format!(\"{}?search={}\", SKILLS_API_URL, q)\n } else {\n SKILLS_API_URL.to_string()\n };\n\n let response = reqwest::blocking::get(&url).context(\"failed to fetch skills from registry\")?;\n\n if !response.status().is_success() {\n bail!(\"Failed to fetch skills: HTTP {}\", response.status());\n }\n\n let skills: Vec<SkillListItem> = response.json().context(\"failed to parse skills response\")?;\n\n if skills.is_empty() {\n println!(\"No skills found in registry.\");\n return Ok(());\n }\n\n println!(\"Available skills from registry:\\n\");\n for skill in skills {\n let source = skill.source.unwrap_or_else(|| \"unknown\".to_string());\n println!(\" {} [{}]\", skill.name, source);\n println!(\" {}\", skill.description);\n println!();\n }\n\n println!(\"Install with: f skills install <name>\");\n\n Ok(())\n}\n\n#[derive(Debug, serde::Deserialize)]\nstruct SkillListItem {\n name: String,\n description: String,\n source: Option<String>,\n}\n\nfn codex_write_msg(writer: &mut dyn Write, msg: &serde_json::Value) -> Result<()> {\n let mut line = serde_json::to_string(msg)?;\n line.push('\\n');\n writer.write_all(line.as_bytes())?;\n writer.flush()?;\n Ok(())\n}\n\nfn codex_read_response(\n lines: &mut std::io::Lines<std::io::BufReader<std::process::ChildStdout>>,\n expected_id: u64,\n deadline: Instant,\n) -> Result<serde_json::Value> {\n loop {\n if Instant::now() >= deadline {\n bail!(\"codex app-server response timed out\");\n }\n let line = match lines.next() {\n Some(Ok(line)) => line,\n Some(Err(err)) => bail!(\"failed to read from codex app-server: {}\", err),\n None => bail!(\"codex app-server closed stdout unexpectedly\"),\n };\n if line.trim().is_empty() {\n continue;\n }\n let msg: serde_json::Value = serde_json::from_str(&line)\n .with_context(|| format!(\"invalid JSON from codex app-server: {}\", line))?;\n if msg.get(\"id\").and_then(|v| v.as_u64()) == Some(expected_id) {\n if let Some(err) = msg.get(\"error\") {\n let message = err\n .get(\"message\")\n .and_then(|v| v.as_str())\n .unwrap_or(\"unknown codex app-server error\");\n bail!(\"codex app-server error: {}\", message);\n }\n return Ok(msg);\n }\n }\n}\n\npub(crate) fn reload_codex_skills_for_cwd(cwd: &Path) -> Result<usize> {\n let codex_bin = configured_codex_bin_for_workdir(cwd);\n\n let mut child = Command::new(&codex_bin)\n .arg(\"app-server\")\n .current_dir(cwd)\n .stdin(std::process::Stdio::piped())\n .stdout(std::process::Stdio::piped())\n .stderr(std::process::Stdio::piped())\n .spawn()\n .context(\"failed to run codex app-server\")?;\n\n let mut stdin = child.stdin.take().context(\"missing codex stdin\")?;\n let stdout = child.stdout.take().context(\"missing codex stdout\")?;\n let mut lines = BufReader::new(stdout).lines();\n let handshake_deadline = Instant::now() + Duration::from_secs(15);\n\n codex_write_msg(\n &mut stdin,\n &json!({\n \"id\": 1,\n \"method\": \"initialize\",\n \"params\": {\n \"clientInfo\": { \"name\": \"flow\", \"title\": \"Flow CLI\", \"version\": \"0.1.0\" },\n \"capabilities\": { \"experimentalApi\": true }\n }\n }),\n )?;\n let _ = codex_read_response(&mut lines, 1, handshake_deadline)\n .context(\"codex app-server did not respond to initialize\")?;\n codex_write_msg(&mut stdin, &json!({ \"method\": \"initialized\" }))?;\n\n let op_deadline = Instant::now() + Duration::from_secs(20);\n codex_write_msg(\n &mut stdin,\n &json!({\n \"id\": 2,\n \"method\": \"skills/list\",\n \"params\": {\n \"cwds\": [cwd.to_string_lossy().to_string()],\n \"forceReload\": true\n }\n }),\n )?;\n let response = codex_read_response(&mut lines, 2, op_deadline)?;\n\n let skill_count = response\n .pointer(\"/result/data/0/skills\")\n .and_then(|v| v.as_array())\n .map(|skills| skills.len())\n .unwrap_or(0);\n let error_count = response\n .pointer(\"/result/data/0/errors\")\n .and_then(|v| v.as_array())\n .map(|errors| errors.len())\n .unwrap_or(0);\n\n let _ = codex_write_msg(\n &mut stdin,\n &json!({\n \"id\": 3,\n \"method\": \"shutdown\"\n }),\n );\n drop(stdin);\n let _ = child.kill();\n let _ = child.wait();\n\n if error_count > 0 {\n eprintln!(\n \"warning: Codex reported {} skill loader error(s) while reloading\",\n error_count\n );\n }\n\n Ok(skill_count)\n}\n\npub(crate) fn maybe_reload_codex_skills(\n project_root: &Path,\n skills_cfg: Option<&config::SkillsConfig>,\n reason: &str,\n) {\n if !should_force_reload_after_sync(skills_cfg) {\n return;\n }\n\n match reload_codex_skills_for_cwd(project_root) {\n Ok(skill_count) => {\n println!(\n \"Codex skills reloaded ({} skills) after {}\",\n skill_count, reason\n );\n }\n Err(err) => {\n eprintln!(\n \"warning: failed to force-reload Codex skills after {}: {}\",\n reason, err\n );\n }\n }\n}\n\nfn reload_skills() -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n let skill_count = reload_codex_skills_for_cwd(&cwd)?;\n println!(\"Codex skills reloaded ({} skills)\", skill_count);\n Ok(())\n}\n\nfn render_task_skill(task: &config::TaskConfig) -> String {\n let desc = task.description.as_deref().unwrap_or(\"Flow task\");\n let command = task.command.lines().collect::<Vec<_>>().join(\"\\n\");\n let fm_name = yaml_quote(&task.name);\n let fm_desc = yaml_quote(desc);\n format!(\n r#\"---\nname: {}\ndescription: {}\nsource: flow.toml\n---\n\nRun with `f {}`.\n\n```bash\n{}\n```\n\"#,\n fm_name, fm_desc, task.name, command\n )\n}\n\nfn sync_tasks_to_skills(\n skills_dir: &Path,\n tasks: &[config::TaskConfig],\n options: SkillSyncOptions,\n) -> Result<(usize, usize)> {\n fs::create_dir_all(skills_dir)?;\n\n let mut created = 0;\n let mut updated = 0;\n\n for task in tasks {\n let skill_dir = skills_dir.join(&task.name);\n fs::create_dir_all(&skill_dir)?;\n\n let existed = find_skill_file(&skill_dir).is_some();\n let normalized = normalize_single_skill_file(&skill_dir)?;\n let skill_file = skill_file_upper(&skill_dir);\n let content = render_task_skill(task);\n let should_write = match fs::read_to_string(&skill_file) {\n Ok(existing) => existing != content,\n Err(err) if err.kind() == std::io::ErrorKind::NotFound => true,\n Err(err) => return Err(err.into()),\n };\n\n if should_write {\n fs::write(&skill_file, content)?;\n }\n if !existed {\n created += 1;\n } else if should_write || normalized {\n updated += 1;\n }\n\n write_task_skill_metadata(&skill_dir, task, options)?;\n }\n\n Ok((created, updated))\n}\n\n/// Sync flow.toml tasks as skills.\nfn sync_skills() -> Result<()> {\n let cwd = std::env::current_dir()?;\n let flow_toml = cwd.join(\"flow.toml\");\n\n if !flow_toml.exists() {\n bail!(\"No flow.toml found in current directory\");\n }\n\n // Load flow.toml\n let cfg = config::load(&flow_toml)?;\n\n let skills_dir = get_skills_dir()?;\n let normalized = normalize_skill_files(&skills_dir)?;\n let options = resolve_skill_sync_options(cfg.skills.as_ref());\n let (created, updated) = sync_tasks_to_skills(&skills_dir, &cfg.tasks, options)?;\n\n // Ensure symlinks exist for Claude Code and Codex\n ensure_symlinks()?;\n\n println!(\"Synced {} tasks from flow.toml\", cfg.tasks.len());\n if created > 0 {\n println!(\" Created: {}\", created);\n }\n if updated > 0 {\n println!(\" Updated: {}\", updated);\n }\n if normalized > 0 {\n println!(\" Normalized: {}\", normalized);\n }\n println!(\"\\nSymlinked to .claude/skills/ and .codex/skills/\");\n maybe_reload_codex_skills(&cwd, cfg.skills.as_ref(), \"skills sync\");\n\n Ok(())\n}\n\npub(crate) fn enforce_skills_from_config(\n project_root: &Path,\n cfg: &config::Config,\n) -> Result<SkillsEnforceSummary> {\n let Some(skills_cfg) = cfg.skills.as_ref() else {\n return Ok(SkillsEnforceSummary::default());\n };\n\n let skills_dir = get_skills_dir_at(project_root);\n let mut summary = SkillsEnforceSummary::default();\n let _ = normalize_skill_files(&skills_dir)?;\n\n if skills_cfg.sync_tasks {\n let options = resolve_skill_sync_options(Some(skills_cfg));\n let (created, updated) = sync_tasks_to_skills(&skills_dir, &cfg.tasks, options)?;\n summary.task_skills_created = created;\n summary.task_skills_updated = updated;\n ensure_symlinks_at(project_root)?;\n }\n\n for name in &skills_cfg.install {\n let installed = install_skill_inner(project_root, name, true, true)?;\n if installed {\n summary.installed_skills.push(name.clone());\n }\n }\n\n Ok(summary)\n}\n\npub fn ensure_default_skills_at(project_root: &Path) -> Result<()> {\n let skills_dir = get_skills_dir_at(project_root);\n fs::create_dir_all(&skills_dir)?;\n\n start::update_gitignore(project_root)?;\n\n let env_dir = skills_dir.join(\"env\");\n let env_file = skill_file_upper(&env_dir);\n let should_write = if env_file.exists() {\n let content = fs::read_to_string(&env_file).unwrap_or_default();\n content.contains(\"source: flow-default\")\n } else {\n true\n };\n\n if should_write {\n fs::create_dir_all(&env_dir)?;\n fs::write(&env_file, DEFAULT_ENV_SKILL)?;\n }\n let _ = normalize_single_skill_file(&env_dir)?;\n\n let quality_dir = skills_dir.join(\"quality-bun-feature-delivery\");\n let quality_file = skill_file_upper(&quality_dir);\n let should_write_quality = if quality_file.exists() {\n let content = fs::read_to_string(&quality_file).unwrap_or_default();\n content.contains(\"source: flow-default\")\n } else {\n true\n };\n if should_write_quality {\n fs::create_dir_all(&quality_dir)?;\n fs::write(&quality_file, DEFAULT_QUALITY_BUN_FEATURE_DELIVERY_SKILL)?;\n }\n let _ = normalize_single_skill_file(&quality_dir)?;\n\n let pr_markdown_dir = skills_dir.join(\"pr-markdown-body-file\");\n let pr_markdown_file = skill_file_upper(&pr_markdown_dir);\n let should_write_pr_markdown = if pr_markdown_file.exists() {\n let content = fs::read_to_string(&pr_markdown_file).unwrap_or_default();\n content.contains(\"source: flow-default\")\n } else {\n true\n };\n if should_write_pr_markdown {\n fs::create_dir_all(&pr_markdown_dir)?;\n fs::write(&pr_markdown_file, DEFAULT_PR_MARKDOWN_BODY_FILE_SKILL)?;\n }\n let _ = normalize_single_skill_file(&pr_markdown_dir)?;\n\n ensure_symlinks_at(project_root)?;\n\n Ok(())\n}\n\npub fn auto_sync_skills() {\n let Ok(cwd) = std::env::current_dir() else {\n return;\n };\n\n let mut current = cwd.clone();\n let flow_toml = loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n break Some(candidate);\n }\n if !current.pop() {\n break None;\n }\n };\n\n let Some(flow_toml) = flow_toml else {\n return;\n };\n let Some(project_root) = flow_toml.parent() else {\n return;\n };\n\n let cfg = match config::load(&flow_toml) {\n Ok(cfg) => Some(cfg),\n Err(err) => {\n tracing::debug!(?err, \"failed to load flow.toml for skills sync\");\n None\n }\n };\n\n if let Err(err) = ensure_default_skills_at(project_root) {\n tracing::debug!(?err, \"failed to auto-sync default skills\");\n }\n\n if let Some(cfg) = cfg {\n if let Err(err) = enforce_skills_from_config(project_root, &cfg) {\n tracing::debug!(?err, \"failed to auto-sync configured skills\");\n }\n }\n}\n\npub fn ensure_project_skills_at(\n project_root: &Path,\n cfg: &config::Config,\n) -> Result<SkillsEnforceSummary> {\n ensure_default_skills_at(project_root)?;\n enforce_skills_from_config(project_root, cfg)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use tempfile::tempdir;\n\n fn sample_task(name: &str, description: Option<&str>) -> config::TaskConfig {\n config::TaskConfig {\n name: name.to_string(),\n command: \"echo hi\".to_string(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: description.map(|v| v.to_string()),\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n }\n }\n\n #[test]\n fn task_openai_yaml_defaults_to_no_implicit_invocation() {\n let task = sample_task(\"deploy-all\", Some(\"Deploy all services safely\"));\n let yaml = render_task_skill_openai_yaml(&task, false);\n assert!(yaml.contains(\"display_name: \\\"Deploy All\\\"\"));\n assert!(yaml.contains(\"allow_implicit_invocation: false\"));\n assert!(\n yaml.contains(\"default_prompt: \\\"Use $deploy-all to Deploy all services safely.\\\"\")\n );\n }\n\n #[test]\n fn task_openai_yaml_can_enable_implicit_invocation() {\n let task = sample_task(\"build-web\", Some(\"Build web assets\"));\n let yaml = render_task_skill_openai_yaml(&task, true);\n assert!(yaml.contains(\"allow_implicit_invocation: true\"));\n }\n\n #[test]\n fn task_skill_frontmatter_quotes_yaml_sensitive_values() {\n let task = sample_task(\n \"ooda-run-qwen3-4b\",\n Some(\"Q4B-baseline: gated confidence fix\"),\n );\n let content = render_task_skill(&task);\n assert!(content.contains(\"name: \\\"ooda-run-qwen3-4b\\\"\"));\n assert!(content.contains(\"description: \\\"Q4B-baseline: gated confidence fix\\\"\"));\n }\n\n #[test]\n fn ensure_default_skills_writes_quality_bun_skill() {\n let dir = tempdir().expect(\"tempdir\");\n ensure_default_skills_at(dir.path()).expect(\"default skills should be written\");\n\n let env = dir.path().join(\".ai/skills/env/SKILL.md\");\n let quality = dir\n .path()\n .join(\".ai/skills/quality-bun-feature-delivery/SKILL.md\");\n let pr_markdown = dir.path().join(\".ai/skills/pr-markdown-body-file/SKILL.md\");\n\n assert!(env.exists(), \"env default skill should exist\");\n assert!(quality.exists(), \"quality skill should exist\");\n assert!(\n pr_markdown.exists(),\n \"pr markdown default skill should exist\"\n );\n\n let quality_content = fs::read_to_string(&quality).expect(\"quality skill readable\");\n assert!(quality_content.contains(\"name: quality-bun-feature-delivery\"));\n assert!(quality_content.contains(\"version: 2\"));\n assert!(quality_content.contains(\"source: flow-default\"));\n\n let pr_markdown_content =\n fs::read_to_string(&pr_markdown).expect(\"pr markdown skill readable\");\n assert!(pr_markdown_content.contains(\"name: pr-markdown-body-file\"));\n assert!(pr_markdown_content.contains(\"version: 1\"));\n assert!(pr_markdown_content.contains(\"source: flow-default\"));\n }\n\n #[test]\n fn ensure_default_skills_merges_into_existing_codex_skills_directory() {\n let dir = tempdir().expect(\"tempdir\");\n let existing_skill_dir = dir.path().join(\".codex/skills/existing-custom-skill\");\n fs::create_dir_all(&existing_skill_dir).expect(\"existing skill dir\");\n fs::write(\n existing_skill_dir.join(\"SKILL.md\"),\n \"---\\nname: existing-custom-skill\\n---\\n\",\n )\n .expect(\"existing skill\");\n\n ensure_default_skills_at(dir.path()).expect(\"default skills should be written\");\n\n let codex_skills_dir = dir.path().join(\".codex/skills\");\n assert!(\n codex_skills_dir.is_dir(),\n \"codex skills directory should remain a directory\"\n );\n assert!(\n codex_skills_dir\n .join(\"existing-custom-skill/SKILL.md\")\n .exists(),\n \"existing codex skill should be preserved\"\n );\n assert!(\n codex_skills_dir.join(\"env/SKILL.md\").exists(),\n \"default env skill should be exposed inside existing codex skills directory\"\n );\n assert!(\n codex_skills_dir\n .join(\"quality-bun-feature-delivery/SKILL.md\")\n .exists(),\n \"default quality skill should be exposed inside existing codex skills directory\"\n );\n assert!(\n codex_skills_dir\n .join(\"pr-markdown-body-file/SKILL.md\")\n .exists(),\n \"default pr markdown skill should be exposed inside existing codex skills directory\"\n );\n }\n\n #[test]\n fn sync_tasks_writes_uppercase_skill_file() {\n let dir = tempdir().expect(\"tempdir\");\n let skills_dir = dir.path().join(\".ai/skills\");\n let tasks = vec![sample_task(\"hello-task\", Some(\"Say hello\"))];\n\n let (created, updated) =\n sync_tasks_to_skills(&skills_dir, &tasks, SkillSyncOptions::default())\n .expect(\"sync should succeed\");\n assert_eq!(created, 1);\n assert_eq!(updated, 0);\n\n let task_dir = skills_dir.join(\"hello-task\");\n assert!(\n has_exact_skill_filename(&task_dir, \"SKILL.md\").expect(\"exact check should succeed\"),\n \"SKILL.md should exist with canonical casing\"\n );\n assert!(\n !has_exact_skill_filename(&task_dir, \"skill.md\").expect(\"exact check should succeed\"),\n \"legacy lowercase filename should not remain\"\n );\n }\n\n #[test]\n fn sync_tasks_migrates_legacy_lowercase_skill_file() {\n let dir = tempdir().expect(\"tempdir\");\n let skills_dir = dir.path().join(\".ai/skills\");\n let task = sample_task(\"migrate-me\", Some(\"Migrate legacy skill case\"));\n let task_dir = skills_dir.join(\"migrate-me\");\n fs::create_dir_all(&task_dir).expect(\"task dir\");\n\n let legacy = skill_file_lower(&task_dir);\n fs::write(&legacy, render_task_skill(&task)).expect(\"legacy skill write\");\n assert!(\n has_exact_skill_filename(&task_dir, \"skill.md\").expect(\"exact check should succeed\"),\n \"test fixture should start with lowercase filename\"\n );\n\n let (created, updated) =\n sync_tasks_to_skills(&skills_dir, &[task], SkillSyncOptions::default())\n .expect(\"sync should succeed\");\n assert_eq!(created, 0);\n assert_eq!(updated, 1, \"case migration should count as an update\");\n assert!(\n has_exact_skill_filename(&task_dir, \"SKILL.md\").expect(\"exact check should succeed\"),\n \"legacy skill should be migrated to uppercase filename\"\n );\n assert!(\n !has_exact_skill_filename(&task_dir, \"skill.md\").expect(\"exact check should succeed\"),\n \"legacy lowercase filename should be removed\"\n );\n }\n}\n" }, { "path": "src/ssh.rs", "content": "use std::fs;\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\nuse serde::{Deserialize, Serialize};\n\nuse crate::config;\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\npub enum SshMode {\n Auto,\n Force,\n Https,\n}\n\npub fn prefer_ssh() -> bool {\n match ssh_mode() {\n SshMode::Https => false,\n SshMode::Force => true,\n SshMode::Auto => has_identities(),\n }\n}\n\npub fn ssh_mode() -> SshMode {\n if env_truthy(\"FLOW_FORCE_HTTPS\") {\n return SshMode::Https;\n }\n if env_truthy(\"FLOW_FORCE_SSH\") {\n return SshMode::Force;\n }\n if let Some(mode) = std::env::var_os(\"FLOW_SSH_MODE\") {\n if let Some(parsed) = parse_mode(&mode.to_string_lossy()) {\n return parsed;\n }\n }\n\n if let Some(parsed) = ssh_mode_from_config() {\n return parsed;\n }\n\n SshMode::Auto\n}\n\npub fn has_identities() -> bool {\n if let Some(sock) = preferred_agent_sock() {\n return agent_has_identities(&sock);\n }\n false\n}\n\npub fn ensure_ssh_env() {\n let env_sock = std::env::var_os(\"SSH_AUTH_SOCK\").map(PathBuf::from);\n let env_sock_valid = env_sock.as_ref().map(|p| p.exists()).unwrap_or(false);\n\n let sock = if env_sock_valid {\n env_sock.clone()\n } else if let Some(flow_sock) = flow_agent_status() {\n Some(flow_sock)\n } else {\n find_1password_sock()\n };\n\n let Some(sock) = sock else {\n return;\n };\n\n // SAFETY: We're setting env vars at startup before spawning threads\n unsafe {\n if !env_sock_valid {\n std::env::set_var(\"SSH_AUTH_SOCK\", &sock);\n }\n\n if std::env::var_os(\"GIT_SSH_COMMAND\").is_none() {\n let escaped = shell_escape(&sock);\n std::env::set_var(\n \"GIT_SSH_COMMAND\",\n format!(\n \"ssh -o IdentityAgent={} -o IdentitiesOnly=yes -o BatchMode=yes\",\n escaped\n ),\n );\n }\n }\n}\n\npub fn ensure_git_ssh_command() -> Result<bool> {\n if !git_config_writable() {\n return Ok(false);\n }\n let Some(sock) = preferred_agent_sock() else {\n return Ok(false);\n };\n\n let desired = format!(\n \"ssh -o IdentityAgent={} -o IdentitiesOnly=yes\",\n shell_escape(&sock)\n );\n\n if let Some(current) = git_config_get(\"core.sshCommand\")? {\n let current = current.trim();\n if current == desired {\n return Ok(false);\n }\n if !current.is_empty() && !current.contains(\"IdentityAgent=\") {\n return Ok(false);\n }\n }\n\n git_config_set(\"core.sshCommand\", &desired)?;\n Ok(true)\n}\n\npub fn ensure_git_ssh_command_for_sock(sock: &Path, force: bool) -> Result<bool> {\n let desired = format!(\n \"ssh -o IdentityAgent={} -o IdentitiesOnly=yes\",\n shell_escape(sock)\n );\n\n if !force {\n if let Some(current) = git_config_get(\"core.sshCommand\")? {\n let current = current.trim();\n if !current.is_empty() && !current.contains(\"IdentityAgent=\") {\n return Ok(false);\n }\n }\n }\n\n git_config_set(\"core.sshCommand\", &desired)?;\n Ok(true)\n}\n\npub fn ensure_git_ssh_command_wrapper(wrapper: &Path, force: bool) -> Result<bool> {\n if !git_config_writable() {\n return Ok(false);\n }\n let desired = shell_escape(wrapper);\n\n if !force {\n if let Some(current) = git_config_get(\"core.sshCommand\")? {\n let current = current.trim();\n if current == desired {\n return Ok(false);\n }\n if !current.is_empty()\n && !current.contains(\"IdentityAgent=\")\n && !current.contains(\"flow-ssh\")\n {\n return Ok(false);\n }\n }\n }\n\n git_config_set(\"core.sshCommand\", &desired)?;\n Ok(true)\n}\n\npub fn ensure_git_https_insteadof() -> Result<bool> {\n if !git_config_writable() {\n return Ok(false);\n }\n let desired = [\"git@github.com:\", \"ssh://git@github.com/\"];\n let mut changed = false;\n\n if add_url_rewrite(\"url.https://github.com/.insteadOf\", &desired)? {\n changed = true;\n }\n if add_url_rewrite(\"url.https://github.com/.pushInsteadOf\", &desired)? {\n changed = true;\n }\n\n Ok(changed)\n}\n\npub fn clear_git_https_insteadof() -> Result<bool> {\n if !git_config_writable() {\n return Ok(false);\n }\n let desired = [\"git@github.com:\", \"ssh://git@github.com/\"];\n let mut changed = false;\n\n if remove_url_rewrite(\"url.https://github.com/.insteadOf\", &desired)? {\n changed = true;\n }\n if remove_url_rewrite(\"url.https://github.com/.pushInsteadOf\", &desired)? {\n changed = true;\n }\n\n Ok(changed)\n}\n\npub fn ensure_flow_agent() -> Result<PathBuf> {\n if let Some(sock) = flow_agent_status() {\n return Ok(sock);\n }\n\n let sock = flow_agent_sock();\n if sock.exists() {\n if probe_agent(&sock) {\n return Ok(sock);\n }\n let _ = fs::remove_file(&sock);\n }\n let state_path = flow_agent_state_path();\n if let Some(parent) = state_path.parent() {\n fs::create_dir_all(parent)?;\n }\n\n let output = Command::new(\"ssh-agent\")\n .args([\"-a\", sock.to_string_lossy().as_ref(), \"-s\"])\n .output()\n .context(\"failed to start ssh-agent\")?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"ssh-agent failed: {}\", stderr.trim());\n }\n\n let stdout = String::from_utf8_lossy(&output.stdout);\n let pid = parse_agent_output(&stdout, \"SSH_AGENT_PID\")\n .and_then(|val| val.parse::<u32>().ok())\n .context(\"failed to parse ssh-agent pid\")?;\n let sock_path = parse_agent_output(&stdout, \"SSH_AUTH_SOCK\")\n .map(PathBuf::from)\n .unwrap_or_else(|| sock.clone());\n\n let state = FlowAgentState {\n pid,\n sock: sock_path.clone(),\n };\n let content = serde_json::to_string_pretty(&state)?;\n fs::write(&state_path, content)?;\n\n Ok(sock_path)\n}\n\npub fn flow_agent_status() -> Option<PathBuf> {\n let sock = flow_agent_sock();\n if !sock.exists() {\n return None;\n }\n\n if let Some(state) = load_flow_agent_state() {\n if !pid_alive(state.pid) {\n return None;\n }\n return Some(state.sock);\n }\n\n if probe_agent(&sock) {\n return Some(sock);\n }\n\n None\n}\n\nfn preferred_agent_sock() -> Option<PathBuf> {\n let env_sock = std::env::var_os(\"SSH_AUTH_SOCK\").map(PathBuf::from);\n if env_sock.as_ref().map(|p| p.exists()).unwrap_or(false) {\n return env_sock;\n }\n if let Some(flow_sock) = flow_agent_status() {\n return Some(flow_sock);\n }\n find_1password_sock()\n}\n\nfn ssh_mode_from_config() -> Option<SshMode> {\n let path = config::default_config_path();\n if !path.exists() {\n return None;\n }\n\n let cfg = config::load(&path).ok()?;\n let ssh = cfg.ssh?;\n ssh.mode.as_deref().and_then(parse_mode)\n}\n\nfn parse_mode(raw: &str) -> Option<SshMode> {\n match raw.trim().to_ascii_lowercase().as_str() {\n \"auto\" => Some(SshMode::Auto),\n \"force\" | \"ssh\" => Some(SshMode::Force),\n \"https\" => Some(SshMode::Https),\n _ => None,\n }\n}\n\n#[derive(Debug, Serialize, Deserialize)]\nstruct FlowAgentState {\n pid: u32,\n sock: PathBuf,\n}\n\nfn flow_agent_sock() -> PathBuf {\n config::global_config_dir().join(\"ssh\").join(\"agent.sock\")\n}\n\npub fn flow_agent_sock_path() -> PathBuf {\n flow_agent_sock()\n}\n\nfn flow_agent_state_path() -> PathBuf {\n config::global_config_dir().join(\"ssh\").join(\"agent.json\")\n}\n\nfn load_flow_agent_state() -> Option<FlowAgentState> {\n let path = flow_agent_state_path();\n let content = fs::read_to_string(&path).ok()?;\n serde_json::from_str(&content).ok()\n}\n\nfn pid_alive(pid: u32) -> bool {\n Command::new(\"kill\")\n .args([\"-0\", &pid.to_string()])\n .status()\n .map(|status| status.success())\n .unwrap_or(false)\n}\n\nfn parse_agent_output(stdout: &str, key: &str) -> Option<String> {\n for part in stdout.split(&[';', '\\n'][..]) {\n let trimmed = part.trim();\n let needle = format!(\"{}=\", key);\n if let Some(rest) = trimmed.strip_prefix(&needle) {\n return Some(rest.trim().to_string());\n }\n }\n None\n}\n\nfn probe_agent(sock: &Path) -> bool {\n let status = match Command::new(\"ssh-add\")\n .args([\"-l\"])\n .env(\"SSH_AUTH_SOCK\", sock)\n .stdin(Stdio::null())\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n {\n Ok(status) => status,\n Err(_) => return false,\n };\n\n match status.code() {\n Some(2) | None => false,\n _ => true,\n }\n}\n\nfn agent_has_identities(sock: &Path) -> bool {\n let status = match Command::new(\"ssh-add\")\n .args([\"-l\"])\n .env(\"SSH_AUTH_SOCK\", sock)\n .stdin(Stdio::null())\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n {\n Ok(status) => status,\n Err(_) => return false,\n };\n\n matches!(status.code(), Some(0))\n}\n\nfn find_1password_sock() -> Option<PathBuf> {\n let candidates = [\n \"~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock\",\n \"~/.1password/agent.sock\",\n ];\n\n for candidate in candidates {\n let path = config::expand_path(candidate);\n if path.exists() {\n return Some(path);\n }\n }\n\n None\n}\n\nfn env_truthy(key: &str) -> bool {\n let Some(value) = std::env::var_os(key) else {\n return false;\n };\n let value = value.to_string_lossy().to_lowercase();\n matches!(value.as_str(), \"1\" | \"true\" | \"yes\" | \"on\")\n}\n\nfn git_config_get(key: &str) -> Result<Option<String>> {\n let output = Command::new(\"git\")\n .args([\"config\", \"--global\", \"--get\", key])\n .output()\n .context(\"failed to run git config\")?;\n\n if !output.status.success() {\n return Ok(None);\n }\n\n let value = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if value.is_empty() {\n return Ok(None);\n }\n Ok(Some(value))\n}\n\nfn git_config_writable() -> bool {\n let home = match std::env::var_os(\"HOME\") {\n Some(val) => PathBuf::from(val),\n None => return false,\n };\n if !home.is_dir() {\n return false;\n }\n\n let path = home.join(\".gitconfig\");\n let meta = match fs::symlink_metadata(&path) {\n Ok(meta) => meta,\n Err(_) => return true,\n };\n if meta.is_dir() {\n return false;\n }\n if meta.file_type().is_symlink() {\n match fs::metadata(&path) {\n Ok(target_meta) => target_meta.is_file(),\n Err(_) => false,\n }\n } else {\n true\n }\n}\n\nfn git_config_get_all(key: &str) -> Result<Vec<String>> {\n let output = Command::new(\"git\")\n .args([\"config\", \"--global\", \"--get-all\", key])\n .output()\n .context(\"failed to run git config\")?;\n\n if !output.status.success() {\n return Ok(Vec::new());\n }\n\n let stdout = String::from_utf8_lossy(&output.stdout);\n Ok(stdout\n .lines()\n .map(|line| line.trim().to_string())\n .filter(|line| !line.is_empty())\n .collect())\n}\n\nfn git_config_set(key: &str, value: &str) -> Result<()> {\n let status = Command::new(\"git\")\n .args([\"config\", \"--global\", key, value])\n .status()\n .context(\"failed to run git config\")?;\n\n if !status.success() {\n anyhow::bail!(\"git config --global {} failed\", key);\n }\n\n Ok(())\n}\n\nfn git_config_add(key: &str, value: &str) -> Result<()> {\n let status = Command::new(\"git\")\n .args([\"config\", \"--global\", \"--add\", key, value])\n .status()\n .context(\"failed to run git config\")?;\n\n if !status.success() {\n anyhow::bail!(\"git config --global --add {} failed\", key);\n }\n\n Ok(())\n}\n\nfn git_config_unset_all(key: &str, value: &str) -> Result<()> {\n let status = Command::new(\"git\")\n .args([\"config\", \"--global\", \"--unset-all\", key, value])\n .status()\n .context(\"failed to run git config\")?;\n\n if !status.success() {\n anyhow::bail!(\"git config --global --unset-all {} failed\", key);\n }\n\n Ok(())\n}\n\nfn add_url_rewrite(key: &str, desired: &[&str]) -> Result<bool> {\n let existing = git_config_get_all(key)?;\n let mut changed = false;\n\n for value in desired {\n if existing.iter().any(|val| val == value) {\n continue;\n }\n git_config_add(key, value)?;\n changed = true;\n }\n\n Ok(changed)\n}\n\nfn remove_url_rewrite(key: &str, desired: &[&str]) -> Result<bool> {\n let existing = git_config_get_all(key)?;\n let mut changed = false;\n\n for value in desired {\n if existing.iter().any(|val| val == value) {\n git_config_unset_all(key, value)?;\n changed = true;\n }\n }\n\n Ok(changed)\n}\n\nfn shell_escape(path: &Path) -> String {\n let raw = path.to_string_lossy();\n let mut escaped = String::with_capacity(raw.len() + 2);\n escaped.push('\\'');\n for ch in raw.chars() {\n if ch == '\\'' {\n escaped.push_str(\"'\\\\''\");\n } else {\n escaped.push(ch);\n }\n }\n escaped.push('\\'');\n escaped\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n struct EnvVarGuard {\n key: &'static str,\n previous: Option<std::ffi::OsString>,\n }\n\n impl EnvVarGuard {\n fn set(key: &'static str, value: &str) -> Self {\n let previous = std::env::var_os(key);\n unsafe {\n std::env::set_var(key, value);\n }\n Self { key, previous }\n }\n }\n\n impl Drop for EnvVarGuard {\n fn drop(&mut self) {\n if let Some(value) = self.previous.take() {\n unsafe {\n std::env::set_var(self.key, value);\n }\n } else {\n unsafe {\n std::env::remove_var(self.key);\n }\n }\n }\n }\n\n #[test]\n fn env_truthy_matches_expected_values() {\n let _guard = EnvVarGuard::set(\"FLOW_TEST_BOOL\", \"true\");\n assert!(env_truthy(\"FLOW_TEST_BOOL\"));\n drop(_guard);\n\n for value in [\"1\", \"yes\", \"on\", \"TRUE\"] {\n let _guard = EnvVarGuard::set(\"FLOW_TEST_BOOL\", value);\n assert!(env_truthy(\"FLOW_TEST_BOOL\"), \"value {}\", value);\n }\n\n let _guard = EnvVarGuard::set(\"FLOW_TEST_BOOL\", \"0\");\n assert!(!env_truthy(\"FLOW_TEST_BOOL\"));\n }\n\n #[test]\n fn prefer_ssh_respects_force_flags() {\n {\n let _https = EnvVarGuard::set(\"FLOW_FORCE_HTTPS\", \"1\");\n let _ssh = EnvVarGuard::set(\"FLOW_FORCE_SSH\", \"1\");\n assert!(!prefer_ssh());\n }\n {\n let _https = EnvVarGuard::set(\"FLOW_FORCE_HTTPS\", \"0\");\n let _ssh = EnvVarGuard::set(\"FLOW_FORCE_SSH\", \"1\");\n assert!(prefer_ssh());\n }\n }\n\n #[test]\n fn ssh_mode_parses_env_override() {\n {\n let _https = EnvVarGuard::set(\"FLOW_SSH_MODE\", \"https\");\n assert_eq!(ssh_mode(), SshMode::Https);\n }\n {\n let _force = EnvVarGuard::set(\"FLOW_SSH_MODE\", \"force\");\n assert_eq!(ssh_mode(), SshMode::Force);\n }\n }\n\n #[test]\n fn shell_escape_handles_single_quotes() {\n let path = Path::new(\"/tmp/has'quote\");\n let escaped = shell_escape(path);\n assert_eq!(escaped, \"'/tmp/has'\\\\''quote'\");\n }\n\n #[test]\n fn parse_agent_output_reads_values() {\n let sample = \"SSH_AUTH_SOCK=/tmp/agent.sock; export SSH_AUTH_SOCK;\\nSSH_AGENT_PID=4242; export SSH_AGENT_PID;\\n\";\n assert_eq!(\n parse_agent_output(sample, \"SSH_AUTH_SOCK\"),\n Some(\"/tmp/agent.sock\".to_string())\n );\n assert_eq!(\n parse_agent_output(sample, \"SSH_AGENT_PID\"),\n Some(\"4242\".to_string())\n );\n }\n}\n" }, { "path": "src/ssh_keys.rs", "content": "use std::fs;\nuse std::io::{IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\nuse base64::{Engine as _, engine::general_purpose::STANDARD};\nuse bs58;\nuse chrono::{DateTime, Local, TimeZone, Utc};\nuse serde::{Deserialize, Serialize};\nuse uuid::Uuid;\n\nuse crate::cli::SshAction;\nuse crate::sealer_crypto::{get_sealer_id, new_x25519_private_key, seal, unseal};\nuse crate::{config, env, ssh};\n\nconst DEFAULT_TTL_HOURS: u64 = 24;\nconst KEY_PRIVATE: &str = \"SSH_PRIVATE_KEY_B64\";\nconst KEY_PRIVATE_SEALED: &str = \"SSH_PRIVATE_KEY_SEALED_B64\";\nconst KEY_PRIVATE_SEALED_NONCE: &str = \"SSH_PRIVATE_KEY_SEALED_NONCE_B64\";\nconst KEY_PRIVATE_SEALER_ID: &str = \"SSH_PRIVATE_KEY_SEALER_ID\";\nconst KEY_PUBLIC: &str = \"SSH_PUBLIC_KEY\";\nconst KEY_FINGERPRINT: &str = \"SSH_FINGERPRINT\";\n\npub(crate) const DEFAULT_KEY_NAME: &str = \"default\";\nconst DEFAULT_SSH_MODE: &str = \"force\";\n\n#[derive(Debug, Serialize, Deserialize)]\nstruct SealerIdentity {\n sealer_secret: String,\n sealer_id: String,\n}\n\nstruct SealedKeyPayload {\n sealed_b64: String,\n nonce_b64: String,\n}\n\n#[derive(Debug, Serialize, Deserialize)]\nstruct SshKeyUnlock {\n expires_at: i64,\n}\n\npub fn run(action: Option<SshAction>) -> Result<()> {\n match action {\n Some(SshAction::Setup { name, no_unlock }) => setup(&name, !no_unlock),\n Some(SshAction::Unlock { name, ttl_hours }) => unlock(&name, ttl_hours),\n Some(SshAction::Status { name }) => status(&name),\n None => status(DEFAULT_KEY_NAME),\n }\n}\n\npub(crate) fn ensure_default_identity(ttl_hours: u64) -> Result<()> {\n if ssh::has_identities() {\n return Ok(());\n }\n\n let key_name = configured_key_name();\n unlock(&key_name, ttl_hours)\n}\n\nfn setup(name: &str, unlock_after: bool) -> Result<()> {\n let key_name = normalize_name(name);\n let tmp_dir = std::env::temp_dir().join(format!(\"flow-ssh-{}\", Uuid::new_v4()));\n fs::create_dir_all(&tmp_dir)?;\n let key_path = tmp_dir.join(\"id_ed25519\");\n\n let comment = format!(\n \"flow@{}\",\n std::env::var(\"USER\").unwrap_or_else(|_| \"flow\".to_string())\n );\n let status = Command::new(\"ssh-keygen\")\n .args([\n \"-t\",\n \"ed25519\",\n \"-N\",\n \"\",\n \"-C\",\n &comment,\n \"-f\",\n key_path.to_string_lossy().as_ref(),\n ])\n .stdin(Stdio::null())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run ssh-keygen\")?;\n if !status.success() {\n bail!(\"ssh-keygen failed\");\n }\n\n let private_key = fs::read_to_string(&key_path)\n .with_context(|| format!(\"failed to read {}\", key_path.display()))?;\n let public_key_path = key_path.with_extension(\"pub\");\n let public_key = fs::read_to_string(&public_key_path)\n .with_context(|| format!(\"failed to read {}\", public_key_path.display()))?;\n\n let identity = load_or_create_sealer_identity()?;\n let sealed = seal_private_key(private_key.as_bytes(), &identity)?;\n let (env_private_plain, env_public, env_fingerprint) = key_env_keys(&key_name);\n let (env_private_sealed, env_private_nonce, env_private_sealer_id) =\n key_env_sealed_keys(&key_name);\n\n env::set_personal_env_var(&env_private_sealed, &sealed.sealed_b64)?;\n env::set_personal_env_var(&env_private_nonce, &sealed.nonce_b64)?;\n env::set_personal_env_var(&env_private_sealer_id, &identity.sealer_id)?;\n env::set_personal_env_var(&env_public, public_key.trim())?;\n\n if let Some(fingerprint) = compute_fingerprint(&public_key_path) {\n let _ = env::set_personal_env_var(&env_fingerprint, &fingerprint);\n }\n\n let _ = fs::remove_dir_all(&tmp_dir);\n\n if let Err(err) = env::delete_personal_env_vars(&[env_private_plain.clone()]) {\n eprintln!(\n \"Warning: failed to delete legacy plaintext key {}: {}\",\n env_private_plain, err\n );\n }\n\n println!(\"Stored SSH key in cloud as '{}' (sealed).\", key_name);\n println!(\"Public key:\\n{}\", public_key.trim());\n println!(\"Add it to GitHub: https://github.com/settings/keys\");\n ensure_global_ssh_config(&key_name)?;\n let wrapper = ensure_flow_ssh_wrapper(&key_name)?;\n let _ = ssh::ensure_git_ssh_command_wrapper(&wrapper, true);\n\n if unlock_after {\n unlock(&key_name, DEFAULT_TTL_HOURS)?;\n }\n\n Ok(())\n}\n\nfn unlock(name: &str, ttl_hours: u64) -> Result<()> {\n let key_name = normalize_name(name);\n require_ssh_key_unlock()?;\n let (env_private_plain, _env_public, _env_fingerprint) = key_env_keys(&key_name);\n let (env_private_sealed, env_private_nonce, env_private_sealer_id) =\n key_env_sealed_keys(&key_name);\n\n let vars = env::fetch_personal_env_vars(&[\n env_private_sealed.clone(),\n env_private_nonce.clone(),\n env_private_sealer_id.clone(),\n env_private_plain.clone(),\n ])?;\n\n let private_key = if vars.contains_key(&env_private_sealed)\n || vars.contains_key(&env_private_nonce)\n {\n let sealed_b64 = vars.get(&env_private_sealed).ok_or_else(|| {\n anyhow::anyhow!(\n \"SSH key sealed payload is missing ({}). Run `f ssh setup` again.\",\n env_private_sealed\n )\n })?;\n let nonce_b64 = vars.get(&env_private_nonce).ok_or_else(|| {\n anyhow::anyhow!(\n \"SSH key sealed nonce is missing ({}). Run `f ssh setup` again.\",\n env_private_nonce\n )\n })?;\n let identity = load_sealer_identity()?.ok_or_else(|| {\n anyhow::anyhow!(\n \"Local SSH seal identity not found. Run `f ssh setup` on this machine first.\"\n )\n })?;\n if let Some(expected_id) = vars.get(&env_private_sealer_id) {\n if expected_id.trim() != identity.sealer_id {\n bail!(\n \"Stored SSH key is sealed for a different device. Run `f ssh setup` to create a new key or copy {} from the original device.\",\n sealer_identity_path()?.display()\n );\n }\n }\n unseal_private_key(sealed_b64, nonce_b64, &identity)?\n } else if let Some(private_b64) = vars.get(&env_private_plain) {\n eprintln!(\n \"Warning: using legacy plaintext SSH key from cloud; run `f ssh setup` to seal it.\"\n );\n STANDARD\n .decode(private_b64.as_bytes())\n .context(\"failed to decode SSH private key\")?\n } else {\n bail!(\"SSH key not found in cloud. Run `f ssh setup` first.\");\n };\n\n let sock = ssh::ensure_flow_agent()?;\n let result = add_key_to_agent(&private_key, &sock, ttl_hours);\n let mut private_key = private_key;\n private_key.fill(0);\n result?;\n\n let wrapper = ensure_flow_ssh_wrapper(&key_name)?;\n let _ = ssh::ensure_git_ssh_command_wrapper(&wrapper, true);\n let _ = ssh::clear_git_https_insteadof();\n println!(\"✓ SSH key unlocked (ttl: {}h)\", ttl_hours);\n\n Ok(())\n}\n\nfn status(name: &str) -> Result<()> {\n let key_name = normalize_name(name);\n let (env_private_plain, env_public, env_fingerprint) = key_env_keys(&key_name);\n let (env_private_sealed, env_private_nonce, env_private_sealer_id) =\n key_env_sealed_keys(&key_name);\n let vars = match env::fetch_personal_env_vars(&[\n env_private_plain.clone(),\n env_public.clone(),\n env_fingerprint.clone(),\n env_private_sealed.clone(),\n env_private_nonce.clone(),\n env_private_sealer_id.clone(),\n ]) {\n Ok(vars) => vars,\n Err(err) => {\n println!(\"Unable to query cloud: {}\", err);\n return Ok(());\n }\n };\n let has_plain = vars.contains_key(&env_private_plain);\n let has_sealed =\n vars.contains_key(&env_private_sealed) && vars.contains_key(&env_private_nonce);\n let has_pub = vars.contains_key(&env_public);\n let fingerprint = vars.get(&env_fingerprint).cloned().unwrap_or_default();\n let sealer_id = vars\n .get(&env_private_sealer_id)\n .cloned()\n .unwrap_or_default();\n let local_identity = load_sealer_identity().ok().flatten();\n\n let agent = ssh::flow_agent_status();\n\n println!(\"Key: {}\", key_name);\n println!(\n \"Stored in cloud (sealed): {}\",\n if has_sealed { \"yes\" } else { \"no\" }\n );\n println!(\n \"Stored in cloud (plaintext): {}\",\n if has_plain { \"yes\" } else { \"no\" }\n );\n println!(\"Public key stored: {}\", if has_pub { \"yes\" } else { \"no\" });\n if !fingerprint.is_empty() {\n println!(\"Fingerprint: {}\", fingerprint);\n }\n if !sealer_id.is_empty() {\n println!(\"Sealer id: {}\", sealer_id);\n }\n println!(\n \"Local seal identity: {}\",\n if local_identity.is_some() {\n \"yes\"\n } else {\n \"no\"\n }\n );\n match agent {\n Some(sock) => println!(\"Flow SSH agent: running ({})\", sock.display()),\n None => println!(\"Flow SSH agent: not running\"),\n }\n Ok(())\n}\n\nfn ensure_global_ssh_config(key_name: &str) -> Result<()> {\n let config_path = config::default_config_path();\n if let Some(parent) = config_path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n\n let contents = if config_path.exists() {\n fs::read_to_string(&config_path)\n .with_context(|| format!(\"failed to read {}\", config_path.display()))?\n } else {\n String::new()\n };\n\n let updated = upsert_ssh_block(&contents, DEFAULT_SSH_MODE, key_name);\n if updated != contents {\n fs::write(&config_path, updated)\n .with_context(|| format!(\"failed to write {}\", config_path.display()))?;\n println!(\n \"Configured Flow to use SSH keys from cloud (mode={}, key={}).\",\n DEFAULT_SSH_MODE, key_name\n );\n }\n\n Ok(())\n}\n\nfn upsert_ssh_block(input: &str, mode: &str, key_name: &str) -> String {\n let mut out: Vec<String> = Vec::new();\n let mut in_ssh = false;\n let mut saw_ssh = false;\n let mut saw_mode = false;\n let mut saw_key = false;\n let ends_with_newline = input.ends_with('\\n');\n\n for line in input.lines() {\n let trimmed = line.trim();\n if trimmed.starts_with('[') && trimmed.ends_with(']') {\n if in_ssh {\n if !saw_mode {\n out.push(format!(\"mode = \\\"{}\\\"\", mode));\n saw_mode = true;\n }\n if !saw_key {\n out.push(format!(\"key_name = \\\"{}\\\"\", key_name));\n saw_key = true;\n }\n }\n\n in_ssh = trimmed == \"[ssh]\";\n if in_ssh {\n saw_ssh = true;\n }\n out.push(line.to_string());\n continue;\n }\n\n if in_ssh {\n if trimmed.starts_with(\"mode\") && trimmed.contains('=') {\n out.push(format!(\"mode = \\\"{}\\\"\", mode));\n saw_mode = true;\n continue;\n }\n if trimmed.starts_with(\"key_name\") && trimmed.contains('=') {\n out.push(format!(\"key_name = \\\"{}\\\"\", key_name));\n saw_key = true;\n continue;\n }\n }\n\n out.push(line.to_string());\n }\n\n if in_ssh {\n if !saw_mode {\n out.push(format!(\"mode = \\\"{}\\\"\", mode));\n }\n if !saw_key {\n out.push(format!(\"key_name = \\\"{}\\\"\", key_name));\n }\n }\n\n if !saw_ssh {\n if !out.is_empty() {\n out.push(String::new());\n }\n out.push(\"[ssh]\".to_string());\n out.push(format!(\"mode = \\\"{}\\\"\", mode));\n out.push(format!(\"key_name = \\\"{}\\\"\", key_name));\n }\n\n let mut rendered = out.join(\"\\n\");\n if ends_with_newline || rendered.is_empty() {\n rendered.push('\\n');\n }\n rendered\n}\n\nfn configured_key_name() -> String {\n let config_path = config::default_config_path();\n if config_path.exists() {\n if let Ok(cfg) = config::load(&config_path) {\n if let Some(ssh_cfg) = cfg.ssh {\n if let Some(name) = ssh_cfg.key_name {\n if !name.trim().is_empty() {\n return name;\n }\n }\n }\n }\n }\n\n DEFAULT_KEY_NAME.to_string()\n}\n\nfn key_env_keys(name: &str) -> (String, String, String) {\n if name == \"default\" {\n (\n format!(\"FLOW_{}\", KEY_PRIVATE),\n format!(\"FLOW_{}\", KEY_PUBLIC),\n format!(\"FLOW_{}\", KEY_FINGERPRINT),\n )\n } else {\n let suffix = sanitize_env_suffix(name);\n (\n format!(\"FLOW_{}_{}\", KEY_PRIVATE, suffix),\n format!(\"FLOW_{}_{}\", KEY_PUBLIC, suffix),\n format!(\"FLOW_{}_{}\", KEY_FINGERPRINT, suffix),\n )\n }\n}\n\nfn key_env_sealed_keys(name: &str) -> (String, String, String) {\n if name == \"default\" {\n (\n format!(\"FLOW_{}\", KEY_PRIVATE_SEALED),\n format!(\"FLOW_{}\", KEY_PRIVATE_SEALED_NONCE),\n format!(\"FLOW_{}\", KEY_PRIVATE_SEALER_ID),\n )\n } else {\n let suffix = sanitize_env_suffix(name);\n (\n format!(\"FLOW_{}_{}\", KEY_PRIVATE_SEALED, suffix),\n format!(\"FLOW_{}_{}\", KEY_PRIVATE_SEALED_NONCE, suffix),\n format!(\"FLOW_{}_{}\", KEY_PRIVATE_SEALER_ID, suffix),\n )\n }\n}\n\nfn normalize_name(name: &str) -> String {\n let trimmed = name.trim();\n if trimmed.is_empty() {\n \"default\".to_string()\n } else {\n trimmed.to_string()\n }\n}\n\nfn sanitize_env_suffix(name: &str) -> String {\n name.chars()\n .map(|ch| {\n if ch.is_ascii_alphanumeric() {\n ch.to_ascii_uppercase()\n } else {\n '_'\n }\n })\n .collect()\n}\n\nfn ensure_ssh_state_dir() -> Result<PathBuf> {\n let base = config::ensure_global_state_dir()?;\n let dir = base.join(\"ssh\");\n fs::create_dir_all(&dir).with_context(|| format!(\"failed to create {}\", dir.display()))?;\n #[cfg(unix)]\n {\n use std::os::unix::fs::PermissionsExt;\n let perms = fs::Permissions::from_mode(0o700);\n fs::set_permissions(&dir, perms)\n .with_context(|| format!(\"failed to chmod {}\", dir.display()))?;\n }\n Ok(dir)\n}\n\nfn ensure_flow_ssh_wrapper(key_name: &str) -> Result<PathBuf> {\n let dir = ensure_ssh_state_dir()?;\n let path = dir.join(\"flow-ssh\");\n let sock = ssh::flow_agent_sock_path();\n let sock_escaped = escape_double_quotes(&sock.to_string_lossy());\n let key_arg = shell_escape_arg(key_name);\n\n let content = format!(\n r#\"#!/usr/bin/env bash\nset -euo pipefail\nSOCK=\"{sock}\"\nif [[ -S \"$SOCK\" ]]; then\n if SSH_AUTH_SOCK=\"$SOCK\" ssh-add -l >/dev/null 2>&1; then\n exec /usr/bin/ssh -o IdentityAgent=\"$SOCK\" -o IdentitiesOnly=yes -o BatchMode=yes \"$@\"\n fi\nfi\nif command -v f >/dev/null 2>&1; then\n f ssh unlock --name {key}\nelif command -v flow >/dev/null 2>&1; then\n flow ssh unlock --name {key}\nfi\nexec /usr/bin/ssh -o IdentityAgent=\"$SOCK\" -o IdentitiesOnly=yes -o BatchMode=yes \"$@\"\n\"#,\n sock = sock_escaped,\n key = key_arg\n );\n\n if !path.exists() || fs::read_to_string(&path).unwrap_or_default() != content {\n write_executable_file(&path, content.as_bytes())?;\n }\n\n Ok(path)\n}\n\nfn sealer_identity_path() -> Result<PathBuf> {\n Ok(ensure_ssh_state_dir()?.join(\"sealer.json\"))\n}\n\nfn ssh_unlock_path() -> Result<PathBuf> {\n Ok(ensure_ssh_state_dir()?.join(\"unlock.json\"))\n}\n\nfn load_ssh_unlock() -> Option<SshKeyUnlock> {\n let path = ssh_unlock_path().ok()?;\n let content = fs::read_to_string(&path).ok()?;\n serde_json::from_str(&content).ok()\n}\n\nfn save_ssh_unlock(expires_at: DateTime<Utc>) -> Result<()> {\n let path = ssh_unlock_path()?;\n let entry = SshKeyUnlock {\n expires_at: expires_at.timestamp(),\n };\n let content = serde_json::to_string_pretty(&entry)?;\n fs::write(&path, content)?;\n Ok(())\n}\n\nfn unlock_expires_at(entry: &SshKeyUnlock) -> Option<DateTime<Utc>> {\n DateTime::<Utc>::from_timestamp(entry.expires_at, 0)\n}\n\nfn next_local_midnight_utc() -> Result<DateTime<Utc>> {\n let now = Local::now();\n let tomorrow = now\n .date_naive()\n .succ_opt()\n .ok_or_else(|| anyhow::anyhow!(\"failed to calculate next day\"))?;\n let naive = tomorrow\n .and_hms_opt(0, 0, 0)\n .ok_or_else(|| anyhow::anyhow!(\"failed to build midnight time\"))?;\n let local_dt = Local\n .from_local_datetime(&naive)\n .single()\n .or_else(|| Local.from_local_datetime(&naive).earliest())\n .ok_or_else(|| anyhow::anyhow!(\"failed to resolve local midnight\"))?;\n Ok(local_dt.with_timezone(&Utc))\n}\n\nfn prompt_touch_id() -> Result<()> {\n if !cfg!(target_os = \"macos\") {\n bail!(\"Touch ID is not available on this OS\");\n }\n if std::env::var(\"FLOW_NO_TOUCH_ID\").is_ok() || !std::io::stdin().is_terminal() {\n bail!(\"Touch ID prompt requires an interactive terminal\");\n }\n\n let reason = \"Flow needs Touch ID to unlock SSH keys.\";\n let reason = reason.replace('\\\\', \"\\\\\\\\\").replace('\"', \"\\\\\\\"\");\n let script = format!(\n r#\"ObjC.import('stdlib');\nObjC.import('Foundation');\nObjC.import('LocalAuthentication');\nconst context = $.LAContext.alloc.init;\nconst policy = $.LAPolicyDeviceOwnerAuthenticationWithBiometrics;\nconst error = Ref();\nif (!context.canEvaluatePolicyError(policy, error)) {{\n $.exit(2);\n}}\nlet ok = false;\nlet done = false;\ncontext.evaluatePolicyLocalizedReasonReply(policy, \"{reason}\", function(success, err) {{\n ok = success;\n done = true;\n}});\nconst runLoop = $.NSRunLoop.currentRunLoop;\nwhile (!done) {{\n runLoop.runUntilDate($.NSDate.dateWithTimeIntervalSinceNow(0.1));\n}}\n$.exit(ok ? 0 : 1);\"#\n );\n\n let status = Command::new(\"osascript\")\n .args([\"-l\", \"JavaScript\", \"-e\", &script])\n .status()\n .context(\"failed to launch Touch ID prompt\")?;\n\n match status.code() {\n Some(0) => Ok(()),\n Some(1) => bail!(\"Touch ID verification failed\"),\n Some(2) => bail!(\"Touch ID is not available on this device\"),\n _ => bail!(\"Touch ID verification failed\"),\n }\n}\n\nfn unlock_ssh_key() -> Result<()> {\n if !cfg!(target_os = \"macos\") {\n println!(\"Touch ID unlock is not available on this OS.\");\n return Ok(());\n }\n\n if let Some(entry) = load_ssh_unlock() {\n if let Some(expires_at) = unlock_expires_at(&entry) {\n if expires_at > Utc::now() {\n let local_expiry = expires_at.with_timezone(&Local);\n println!(\n \"SSH key access already unlocked until {}\",\n local_expiry.format(\"%Y-%m-%d %H:%M %Z\")\n );\n return Ok(());\n }\n }\n }\n\n println!(\"Touch ID required to unlock SSH keys.\");\n prompt_touch_id()?;\n let expires_at = next_local_midnight_utc()?;\n save_ssh_unlock(expires_at)?;\n let local_expiry = expires_at.with_timezone(&Local);\n println!(\n \"✓ SSH key access unlocked until {}\",\n local_expiry.format(\"%Y-%m-%d %H:%M %Z\")\n );\n Ok(())\n}\n\nfn require_ssh_key_unlock() -> Result<()> {\n if !cfg!(target_os = \"macos\") {\n return Ok(());\n }\n\n if let Some(entry) = load_ssh_unlock() {\n if let Some(expires_at) = unlock_expires_at(&entry) {\n if expires_at > Utc::now() {\n return Ok(());\n }\n }\n }\n\n unlock_ssh_key()\n}\n\nfn load_sealer_identity() -> Result<Option<SealerIdentity>> {\n let path = sealer_identity_path()?;\n if !path.exists() {\n return Ok(None);\n }\n\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let mut identity: SealerIdentity =\n serde_json::from_str(&content).context(\"failed to parse SSH sealer identity\")?;\n if identity.sealer_secret.trim().is_empty() {\n bail!(\"SSH sealer identity is missing its secret\");\n }\n\n let derived_id = get_sealer_id(&identity.sealer_secret).context(\"invalid SSH sealer secret\")?;\n if identity.sealer_id != derived_id {\n identity.sealer_id = derived_id;\n let updated = serde_json::to_string_pretty(&identity)?;\n write_private_key(&path, updated.as_bytes())?;\n }\n\n Ok(Some(identity))\n}\n\nfn load_or_create_sealer_identity() -> Result<SealerIdentity> {\n if let Some(identity) = load_sealer_identity()? {\n return Ok(identity);\n }\n\n let identity = create_sealer_identity()?;\n let path = sealer_identity_path()?;\n let content = serde_json::to_string_pretty(&identity)?;\n write_private_key(&path, content.as_bytes())?;\n Ok(identity)\n}\n\nfn create_sealer_identity() -> Result<SealerIdentity> {\n let private_key = new_x25519_private_key();\n let sealer_secret = format!(\"sealerSecret_z{}\", bs58::encode(&private_key).into_string());\n let sealer_id = get_sealer_id(&sealer_secret).context(\"failed to derive SSH sealer id\")?;\n Ok(SealerIdentity {\n sealer_secret,\n sealer_id,\n })\n}\n\nfn seal_private_key(private_key: &[u8], identity: &SealerIdentity) -> Result<SealedKeyPayload> {\n let mut nonce_material = [0u8; 32];\n nonce_material[..16].copy_from_slice(Uuid::new_v4().as_bytes());\n nonce_material[16..].copy_from_slice(Uuid::new_v4().as_bytes());\n\n let sealed = seal(\n private_key,\n &identity.sealer_secret,\n &identity.sealer_id,\n &nonce_material,\n )\n .context(\"failed to seal SSH private key\")?;\n Ok(SealedKeyPayload {\n sealed_b64: STANDARD.encode(sealed),\n nonce_b64: STANDARD.encode(nonce_material),\n })\n}\n\nfn unseal_private_key(\n sealed_b64: &str,\n nonce_b64: &str,\n identity: &SealerIdentity,\n) -> Result<Vec<u8>> {\n let sealed = STANDARD\n .decode(sealed_b64.as_bytes())\n .context(\"failed to decode sealed SSH key\")?;\n let nonce_material = STANDARD\n .decode(nonce_b64.as_bytes())\n .context(\"failed to decode sealed SSH nonce\")?;\n if nonce_material.is_empty() {\n bail!(\"sealed SSH nonce is empty\");\n }\n\n let unsealed = unseal(\n &sealed,\n &identity.sealer_secret,\n &identity.sealer_id,\n &nonce_material,\n )\n .context(\"failed to unseal SSH private key\")?;\n Ok(unsealed)\n}\n\nfn add_key_to_agent(private_key: &[u8], sock: &Path, ttl_hours: u64) -> Result<()> {\n let ttl_seconds = ttl_hours.saturating_mul(3600).to_string();\n let mut child = Command::new(\"ssh-add\")\n .arg(\"-t\")\n .arg(&ttl_seconds)\n .arg(\"-\")\n .env(\"SSH_AUTH_SOCK\", sock)\n .stdin(Stdio::piped())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .spawn()\n .context(\"failed to run ssh-add\")?;\n\n {\n let stdin = child\n .stdin\n .as_mut()\n .context(\"failed to open ssh-add stdin\")?;\n stdin\n .write_all(private_key)\n .context(\"failed to write SSH key to ssh-add\")?;\n }\n\n let status = child.wait().context(\"failed to wait for ssh-add\")?;\n if !status.success() {\n bail!(\"ssh-add failed\");\n }\n\n Ok(())\n}\n\nfn write_private_key(path: &PathBuf, content: &[u8]) -> Result<()> {\n let mut options = fs::OpenOptions::new();\n options.write(true).create(true).truncate(true);\n\n #[cfg(unix)]\n {\n use std::os::unix::fs::OpenOptionsExt;\n options.mode(0o600);\n }\n\n let mut file = options\n .open(path)\n .with_context(|| format!(\"failed to create {}\", path.display()))?;\n\n #[cfg(unix)]\n {\n use std::os::unix::fs::PermissionsExt;\n let perms = fs::Permissions::from_mode(0o600);\n fs::set_permissions(path, perms)\n .with_context(|| format!(\"failed to chmod {}\", path.display()))?;\n }\n\n file.write_all(content)\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n\n Ok(())\n}\n\nfn write_executable_file(path: &PathBuf, content: &[u8]) -> Result<()> {\n let mut options = fs::OpenOptions::new();\n options.write(true).create(true).truncate(true);\n\n #[cfg(unix)]\n {\n use std::os::unix::fs::OpenOptionsExt;\n options.mode(0o700);\n }\n\n let mut file = options\n .open(path)\n .with_context(|| format!(\"failed to create {}\", path.display()))?;\n\n #[cfg(unix)]\n {\n use std::os::unix::fs::PermissionsExt;\n let perms = fs::Permissions::from_mode(0o700);\n fs::set_permissions(path, perms)\n .with_context(|| format!(\"failed to chmod {}\", path.display()))?;\n }\n\n file.write_all(content)\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n\n Ok(())\n}\n\nfn escape_double_quotes(value: &str) -> String {\n value.replace('\\\\', \"\\\\\\\\\").replace('\"', \"\\\\\\\"\")\n}\n\nfn shell_escape_arg(value: &str) -> String {\n if value\n .chars()\n .all(|ch| ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || ch == '.')\n {\n value.to_string()\n } else {\n format!(\"'{}'\", value.replace('\\'', \"'\\\"'\\\"'\"))\n }\n}\n\nfn compute_fingerprint(public_key_path: &PathBuf) -> Option<String> {\n let output = Command::new(\"ssh-keygen\")\n .args([\"-lf\", public_key_path.to_string_lossy().as_ref()])\n .output()\n .ok()?;\n if !output.status.success() {\n return None;\n }\n let stdout = String::from_utf8_lossy(&output.stdout);\n stdout.split_whitespace().nth(1).map(|s| s.to_string())\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn normalize_name_defaults_to_default() {\n assert_eq!(normalize_name(\"\"), \"default\");\n assert_eq!(normalize_name(\" \"), \"default\");\n assert_eq!(normalize_name(\"work\"), \"work\");\n }\n\n #[test]\n fn sanitize_env_suffix_normalizes() {\n assert_eq!(sanitize_env_suffix(\"dev-ops\"), \"DEV_OPS\");\n assert_eq!(sanitize_env_suffix(\"aB9\"), \"AB9\");\n assert_eq!(sanitize_env_suffix(\"with space\"), \"WITH_SPACE\");\n }\n\n #[test]\n fn key_env_keys_uses_expected_prefixes() {\n let (priv_key, pub_key, fp) = key_env_keys(\"default\");\n assert_eq!(priv_key, \"FLOW_SSH_PRIVATE_KEY_B64\");\n assert_eq!(pub_key, \"FLOW_SSH_PUBLIC_KEY\");\n assert_eq!(fp, \"FLOW_SSH_FINGERPRINT\");\n\n let (priv_key, pub_key, fp) = key_env_keys(\"work\");\n assert_eq!(priv_key, \"FLOW_SSH_PRIVATE_KEY_B64_WORK\");\n assert_eq!(pub_key, \"FLOW_SSH_PUBLIC_KEY_WORK\");\n assert_eq!(fp, \"FLOW_SSH_FINGERPRINT_WORK\");\n }\n\n #[test]\n fn key_env_sealed_keys_uses_expected_prefixes() {\n let (sealed, nonce, sealer) = key_env_sealed_keys(\"default\");\n assert_eq!(sealed, \"FLOW_SSH_PRIVATE_KEY_SEALED_B64\");\n assert_eq!(nonce, \"FLOW_SSH_PRIVATE_KEY_SEALED_NONCE_B64\");\n assert_eq!(sealer, \"FLOW_SSH_PRIVATE_KEY_SEALER_ID\");\n\n let (sealed, nonce, sealer) = key_env_sealed_keys(\"work\");\n assert_eq!(sealed, \"FLOW_SSH_PRIVATE_KEY_SEALED_B64_WORK\");\n assert_eq!(nonce, \"FLOW_SSH_PRIVATE_KEY_SEALED_NONCE_B64_WORK\");\n assert_eq!(sealer, \"FLOW_SSH_PRIVATE_KEY_SEALER_ID_WORK\");\n }\n\n #[test]\n fn seal_private_key_roundtrip() {\n let identity = create_sealer_identity().expect(\"identity\");\n let payload = seal_private_key(b\"PRIVATE_KEY\", &identity).expect(\"seal\");\n let unsealed =\n unseal_private_key(&payload.sealed_b64, &payload.nonce_b64, &identity).expect(\"unseal\");\n assert_eq!(unsealed, b\"PRIVATE_KEY\");\n }\n\n #[test]\n fn write_private_key_sets_permissions() {\n let dir = tempfile::tempdir().expect(\"tempdir\");\n let path = dir.path().join(\"id_ed25519_test\");\n write_private_key(&path, b\"PRIVATE\").expect(\"write key\");\n\n let content = fs::read_to_string(&path).expect(\"read key\");\n assert_eq!(content, \"PRIVATE\");\n\n #[cfg(unix)]\n {\n use std::os::unix::fs::PermissionsExt;\n let mode = fs::metadata(&path).expect(\"meta\").permissions().mode() & 0o777;\n assert_eq!(mode, 0o600);\n }\n }\n\n #[test]\n fn upsert_ssh_block_adds_when_missing() {\n let updated = upsert_ssh_block(\"\", \"force\", \"default\");\n assert!(updated.contains(\"[ssh]\"));\n assert!(updated.contains(\"mode = \\\"force\\\"\"));\n assert!(updated.contains(\"key_name = \\\"default\\\"\"));\n }\n\n #[test]\n fn upsert_ssh_block_updates_existing_values() {\n let input = \"[ssh]\\nmode = \\\"auto\\\"\\nkey_name = \\\"work\\\"\\n\";\n let updated = upsert_ssh_block(input, \"force\", \"default\");\n assert!(updated.contains(\"mode = \\\"force\\\"\"));\n assert!(updated.contains(\"key_name = \\\"default\\\"\"));\n assert!(!updated.contains(\"mode = \\\"auto\\\"\"));\n assert!(!updated.contains(\"key_name = \\\"work\\\"\"));\n }\n}\n" }, { "path": "src/start.rs", "content": "//! Project bootstrap and initialization.\n//!\n//! Creates `.ai/` folder structure with tracked, generated, and internal (gitignored) sections.\n//!\n//! Structure:\n//! .ai/\n//! ├── actions/ # TRACKED - fixer/action scripts\n//! ├── skills/ # GITIGNORED - generated skills\n//! ├── tools/ # TRACKED - shared tools\n//! ├── review.md # TRACKED - review instructions\n//! └── internal/ # GITIGNORED - private data\n//! ├── sessions/ # AI session data\n//! ├── checkpoints/\n//! ├── db/\n//! └── *.json # Various state files\n\nuse std::fs;\nuse std::path::{Path, PathBuf};\n\nuse anyhow::{Context, Result};\n\nuse crate::{skills, web};\n\n/// Checkpoint names for tracking completed actions.\npub mod checkpoints {\n pub const AI_FOLDER_CREATED: &str = \"ai_folder_created\";\n pub const GITIGNORE_UPDATED: &str = \"gitignore_updated\";\n pub const DB_SCHEMA_CREATED: &str = \"db_schema_created\";\n}\n\n/// Run the start command to bootstrap the project.\npub fn run() -> Result<()> {\n let project_root = std::env::current_dir()?;\n run_at(&project_root)\n}\n\n/// Bootstrap a project at the provided root path.\npub fn run_at(project_root: &Path) -> Result<()> {\n // Create .ai/ folder structure\n if !has_checkpoint(&project_root, checkpoints::AI_FOLDER_CREATED) {\n create_ai_folder(&project_root)?;\n set_checkpoint(&project_root, checkpoints::AI_FOLDER_CREATED)?;\n println!(\"✓ Created .ai/ folder structure\");\n }\n\n // Add flow entries to .gitignore\n if !has_checkpoint(&project_root, checkpoints::GITIGNORE_UPDATED) {\n update_gitignore(&project_root)?;\n set_checkpoint(&project_root, checkpoints::GITIGNORE_UPDATED)?;\n println!(\"✓ Updated .gitignore\");\n }\n\n // Create database schema\n if !has_checkpoint(&project_root, checkpoints::DB_SCHEMA_CREATED) {\n create_db_schema(&project_root)?;\n set_checkpoint(&project_root, checkpoints::DB_SCHEMA_CREATED)?;\n println!(\"✓ Created .ai/internal/db/ with schema\");\n }\n\n skills::ensure_default_skills_at(&project_root)?;\n\n // Materialize .claude/ and .codex/ from .ai/\n materialize_tool_folders(&project_root)?;\n\n web::ensure_web_ui(&project_root)?;\n\n println!(\"\\n✓ Project ready\");\n println!(\"\\nStructure:\");\n println!(\" .ai/\");\n println!(\" ├── actions/ # Tracked - fixer scripts\");\n println!(\" ├── skills/ # Gitignored - generated skills\");\n println!(\" ├── tools/ # Tracked - shared tools\");\n println!(\" ├── flox/ # Tracked - flox manifest\");\n println!(\" ├── web/ # Gitignored - AI web UI\");\n println!(\" ├── docs/ # Tracked - auto-generated docs\");\n println!(\" ├── agents.md # Tracked - agent instructions\");\n println!(\" └── internal/ # Gitignored - private data\");\n println!(\" .claude/ # Gitignored - symlinks to .ai/\");\n println!(\" .codex/ # Gitignored - symlinks to .ai/\");\n println!(\" .flox/ # Gitignored - symlinks to .ai/flox/\");\n Ok(())\n}\n\npub fn is_bootstrapped(project_root: &Path) -> bool {\n has_checkpoint(project_root, checkpoints::AI_FOLDER_CREATED)\n && has_checkpoint(project_root, checkpoints::GITIGNORE_UPDATED)\n && has_checkpoint(project_root, checkpoints::DB_SCHEMA_CREATED)\n}\n\n/// Check if a checkpoint exists.\npub fn has_checkpoint(project_root: &Path, name: &str) -> bool {\n checkpoint_path(project_root, name).exists()\n}\n\n/// Set a checkpoint (creates an empty file).\npub fn set_checkpoint(project_root: &Path, name: &str) -> Result<()> {\n let path = checkpoint_path(project_root, name);\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n fs::write(&path, \"\")?;\n Ok(())\n}\n\n/// Clear a checkpoint.\n#[allow(dead_code)]\npub fn clear_checkpoint(project_root: &Path, name: &str) -> Result<()> {\n let path = checkpoint_path(project_root, name);\n if path.exists() {\n fs::remove_file(&path)?;\n }\n Ok(())\n}\n\n/// Get the path to a checkpoint file.\nfn checkpoint_path(project_root: &Path, name: &str) -> PathBuf {\n project_root\n .join(\".ai\")\n .join(\"internal\")\n .join(\"checkpoints\")\n .join(name)\n}\n\n/// Create the .ai/ folder structure.\nfn create_ai_folder(project_root: &Path) -> Result<()> {\n let ai_dir = project_root.join(\".ai\");\n let internal_dir = ai_dir.join(\"internal\");\n\n // Public folders (tracked in git or generated)\n let public_dirs = [\n ai_dir.clone(),\n ai_dir.join(\"actions\"),\n ai_dir.join(\"skills\"),\n ai_dir.join(\"tools\"),\n ai_dir.join(\"flox\"),\n ai_dir.join(\"web\"),\n ai_dir.join(\"docs\"),\n ];\n\n // Private folders (gitignored)\n let internal_dirs = [\n internal_dir.clone(),\n internal_dir.join(\"checkpoints\"),\n internal_dir.join(\"sessions\"),\n internal_dir.join(\"db\"),\n internal_dir.join(\"commits\"),\n ];\n\n for dir in public_dirs.iter().chain(internal_dirs.iter()) {\n fs::create_dir_all(dir).with_context(|| format!(\"failed to create {}\", dir.display()))?;\n }\n\n Ok(())\n}\n\n/// Materialize .claude/, .codex/, and .flox/ folders with symlinks to .ai/\nfn materialize_tool_folders(project_root: &Path) -> Result<()> {\n use std::os::unix::fs::symlink;\n\n let ai_dir = project_root.join(\".ai\");\n let agents_source = ai_dir.join(\"agents.md\");\n let skills_source = ai_dir.join(\"skills\");\n\n // Materialize .claude/ and .codex/\n for tool_dir in [\".claude\", \".codex\"] {\n let tool_path = project_root.join(tool_dir);\n fs::create_dir_all(&tool_path)?;\n\n // Symlink skills -> ../.ai/skills\n let skills_link = tool_path.join(\"skills\");\n if !skills_link.exists() && skills_source.exists() {\n let _ = symlink(\"../.ai/skills\", &skills_link);\n }\n\n // Symlink agents.md -> ../.ai/agents.md\n let agents_link = tool_path.join(\"agents.md\");\n if !agents_link.exists() && agents_source.exists() {\n let _ = symlink(\"../.ai/agents.md\", &agents_link);\n }\n }\n\n // Materialize .flox/ from .ai/flox/\n let flox_source = ai_dir.join(\"flox\");\n let manifest_source = flox_source.join(\"manifest.toml\");\n if manifest_source.exists() {\n let flox_dir = project_root.join(\".flox\");\n let flox_env_dir = flox_dir.join(\"env\");\n fs::create_dir_all(&flox_env_dir)?;\n\n // Symlink manifest.toml -> ../../.ai/flox/manifest.toml\n let manifest_link = flox_env_dir.join(\"manifest.toml\");\n if !manifest_link.exists() {\n let _ = symlink(\"../../.ai/flox/manifest.toml\", &manifest_link);\n }\n\n // Create env.json files that flox expects\n let env_json = flox_dir.join(\"env.json\");\n if !env_json.exists() {\n fs::write(\n &env_json,\n r#\"{\n \"version\": 1,\n \"manifest\": \"env/manifest.toml\",\n \"lockfile\": \"env/manifest.lock\"\n}\"#,\n )?;\n }\n\n let env_env_json = flox_env_dir.join(\"env.json\");\n if !env_env_json.exists() {\n let manifest_path = flox_env_dir.join(\"manifest.toml\");\n let lockfile_path = flox_env_dir.join(\"manifest.lock\");\n fs::write(\n &env_env_json,\n format!(\n r#\"{{\n \"version\": 1,\n \"manifest\": \"{}\",\n \"lockfile\": \"{}\"\n}}\"#,\n manifest_path.display(),\n lockfile_path.display()\n ),\n )?;\n }\n }\n\n Ok(())\n}\n\n/// Create the database schema files.\nfn create_db_schema(project_root: &Path) -> Result<()> {\n let db_dir = project_root.join(\".ai/internal/db\");\n fs::create_dir_all(&db_dir)?;\n\n // Create schema.ts with drizzle-orm schema\n let schema_path = db_dir.join(\"schema.ts\");\n if !schema_path.exists() {\n fs::write(&schema_path, SCHEMA_TEMPLATE)?;\n }\n\n // Create index.ts for database connection\n let index_path = db_dir.join(\"index.ts\");\n if !index_path.exists() {\n fs::write(&index_path, DB_INDEX_TEMPLATE)?;\n }\n\n // Create package.json for dependencies\n let package_path = db_dir.join(\"package.json\");\n if !package_path.exists() {\n fs::write(&package_path, DB_PACKAGE_TEMPLATE)?;\n }\n\n Ok(())\n}\n\nconst SCHEMA_TEMPLATE: &str = r#\"// .ai/internal/db/schema.ts\n// Database schema for AI project data using drizzle-orm\nimport { sqliteTable, text, integer, blob } from \"drizzle-orm/sqlite-core\"\n\n// Research notes and findings\nexport const research = sqliteTable(\"research\", {\n id: text(\"id\").primaryKey(),\n title: text(\"title\").notNull(),\n content: text(\"content\").notNull(),\n source: text(\"source\"), // URL, file path, or reference\n tags: text(\"tags\"), // JSON array of tags\n createdAt: integer(\"created_at\", { mode: \"timestamp\" }).notNull(),\n updatedAt: integer(\"updated_at\", { mode: \"timestamp\" }),\n})\n\n// Tasks and todos tracked by agents\nexport const tasks = sqliteTable(\"tasks\", {\n id: text(\"id\").primaryKey(),\n title: text(\"title\").notNull(),\n description: text(\"description\"),\n status: text(\"status\").notNull().default(\"pending\"), // pending, in_progress, completed, blocked\n priority: integer(\"priority\").default(0),\n parentId: text(\"parent_id\"), // for subtasks\n createdAt: integer(\"created_at\", { mode: \"timestamp\" }).notNull(),\n completedAt: integer(\"completed_at\", { mode: \"timestamp\" }),\n})\n\n// Files being tracked or generated\nexport const files = sqliteTable(\"files\", {\n id: text(\"id\").primaryKey(),\n path: text(\"path\").notNull().unique(),\n contentHash: text(\"content_hash\"),\n description: text(\"description\"),\n generatedBy: text(\"generated_by\"), // agent/tool that created it\n createdAt: integer(\"created_at\", { mode: \"timestamp\" }).notNull(),\n updatedAt: integer(\"updated_at\", { mode: \"timestamp\" }),\n})\n\n// Key-value store for agent memory/state\nexport const memory = sqliteTable(\"memory\", {\n key: text(\"key\").primaryKey(),\n value: text(\"value\").notNull(), // JSON serialized\n expiresAt: integer(\"expires_at\", { mode: \"timestamp\" }),\n createdAt: integer(\"created_at\", { mode: \"timestamp\" }).notNull(),\n})\n\n// External service connections and context\nexport const connections = sqliteTable(\"connections\", {\n id: text(\"id\").primaryKey(),\n service: text(\"service\").notNull(), // github, x, linear, etc.\n accountId: text(\"account_id\"),\n metadata: text(\"metadata\"), // JSON with service-specific data\n syncedAt: integer(\"synced_at\", { mode: \"timestamp\" }),\n createdAt: integer(\"created_at\", { mode: \"timestamp\" }).notNull(),\n})\n\"#;\n\nconst DB_INDEX_TEMPLATE: &str = r#\"// .ai/internal/db/index.ts\n// Database connection and utilities\nimport { drizzle } from \"drizzle-orm/bun-sqlite\"\nimport { Database } from \"bun:sqlite\"\nimport * as schema from \"./schema\"\n\nconst sqlite = new Database(\".ai/internal/db/db.sqlite\")\nexport const db = drizzle(sqlite, { schema })\n\n// Re-export schema for convenience\nexport * from \"./schema\"\n\n// Helper to generate IDs\nexport const genId = () => crypto.randomUUID()\n\n// Helper to get current timestamp\nexport const now = () => new Date()\n\"#;\n\nconst DB_PACKAGE_TEMPLATE: &str = r#\"{\n \"name\": \"@ai/db\",\n \"type\": \"module\",\n \"dependencies\": {\n \"drizzle-orm\": \"^0.38.0\"\n },\n \"devDependencies\": {\n \"drizzle-kit\": \"^0.30.0\"\n },\n \"scripts\": {\n \"generate\": \"drizzle-kit generate\",\n \"migrate\": \"drizzle-kit migrate\",\n \"studio\": \"drizzle-kit studio\"\n }\n}\n\"#;\n\n/// Flow gitignore patterns.\nconst FLOW_GITIGNORE_SECTION: &str = \"\\\n# flow\n.ai/internal/\n.ai/web/\n.ai/skills/\n.claude/\n.codex/\n.flox/\n\";\n\n/// Add flow section to .gitignore if not already present.\npub(crate) fn update_gitignore(project_root: &Path) -> Result<()> {\n let gitignore_path = project_root.join(\".gitignore\");\n\n let content = if gitignore_path.exists() {\n fs::read_to_string(&gitignore_path)?\n } else {\n String::new()\n };\n\n let required_entries = [\n \".ai/internal/\",\n \".ai/web/\",\n \".ai/skills/\",\n \".claude/\",\n \".codex/\",\n \".flox/\",\n ];\n\n // If flow section already exists, make sure required entries are present.\n if content.contains(\"# flow\") {\n let mut new_content = content.clone();\n let mut updated = false;\n for entry in required_entries {\n if !content.lines().any(|line| line.trim() == entry) {\n if !new_content.ends_with('\\n') {\n new_content.push('\\n');\n }\n new_content.push_str(entry);\n new_content.push('\\n');\n updated = true;\n }\n }\n if updated {\n fs::write(&gitignore_path, new_content)?;\n }\n return Ok(());\n }\n\n // Also check if all patterns are already present (legacy)\n let has_ai_internal = content.lines().any(|l| l.trim() == \".ai/internal/\");\n let has_web = content.lines().any(|l| l.trim() == \".ai/web/\");\n let has_skills = content.lines().any(|l| l.trim() == \".ai/skills/\");\n let has_claude = content.lines().any(|l| l.trim() == \".claude/\");\n let has_codex = content.lines().any(|l| l.trim() == \".codex/\");\n let has_flox = content.lines().any(|l| l.trim() == \".flox/\");\n\n if has_ai_internal && has_web && has_skills && has_claude && has_codex && has_flox {\n return Ok(());\n }\n\n // Add flow section\n let mut new_content = content;\n if !new_content.is_empty() && !new_content.ends_with('\\n') {\n new_content.push('\\n');\n }\n if !new_content.is_empty() && !new_content.ends_with(\"\\n\\n\") {\n new_content.push('\\n');\n }\n new_content.push_str(FLOW_GITIGNORE_SECTION);\n fs::write(&gitignore_path, new_content)?;\n\n Ok(())\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use tempfile::tempdir;\n\n #[test]\n fn test_checkpoint_lifecycle() {\n let dir = tempdir().unwrap();\n let root = dir.path();\n\n assert!(!has_checkpoint(root, \"test_checkpoint\"));\n\n set_checkpoint(root, \"test_checkpoint\").unwrap();\n assert!(has_checkpoint(root, \"test_checkpoint\"));\n\n clear_checkpoint(root, \"test_checkpoint\").unwrap();\n assert!(!has_checkpoint(root, \"test_checkpoint\"));\n }\n\n #[test]\n fn test_create_ai_folder() {\n let dir = tempdir().unwrap();\n let root = dir.path();\n\n create_ai_folder(root).unwrap();\n\n // Public folders\n assert!(root.join(\".ai\").exists());\n assert!(root.join(\".ai/actions\").exists());\n assert!(root.join(\".ai/skills\").exists());\n assert!(root.join(\".ai/tools\").exists());\n // Internal folders\n assert!(root.join(\".ai/internal\").exists());\n assert!(root.join(\".ai/internal/checkpoints\").exists());\n assert!(root.join(\".ai/internal/sessions\").exists());\n assert!(root.join(\".ai/internal/db\").exists());\n }\n\n #[test]\n fn test_update_gitignore_new_file() {\n let dir = tempdir().unwrap();\n let root = dir.path();\n\n update_gitignore(root).unwrap();\n\n let content = fs::read_to_string(root.join(\".gitignore\")).unwrap();\n assert!(content.contains(\"# flow\"));\n assert!(content.contains(\".ai/internal/\"));\n assert!(content.contains(\".ai/web/\"));\n assert!(content.contains(\".ai/skills/\"));\n assert!(content.contains(\".claude/\"));\n assert!(content.contains(\".codex/\"));\n }\n\n #[test]\n fn test_update_gitignore_existing() {\n let dir = tempdir().unwrap();\n let root = dir.path();\n\n fs::write(root.join(\".gitignore\"), \"node_modules/\\n\").unwrap();\n\n update_gitignore(root).unwrap();\n\n let content = fs::read_to_string(root.join(\".gitignore\")).unwrap();\n assert!(content.contains(\"node_modules/\"));\n assert!(content.contains(\"# flow\"));\n assert!(content.contains(\".ai/internal/\"));\n assert!(content.contains(\".ai/web/\"));\n assert!(content.contains(\".ai/skills/\"));\n assert!(content.contains(\".claude/\"));\n assert!(content.contains(\".codex/\"));\n }\n\n #[test]\n fn test_update_gitignore_already_present() {\n let dir = tempdir().unwrap();\n let root = dir.path();\n\n fs::write(\n root.join(\".gitignore\"),\n \"# flow\\n.ai/internal/\\n.ai/web/\\n.ai/skills/\\n.claude/\\n.codex/\\n.flox/\\n\",\n )\n .unwrap();\n\n update_gitignore(root).unwrap();\n\n let content = fs::read_to_string(root.join(\".gitignore\")).unwrap();\n // Should not duplicate\n assert_eq!(content.matches(\"# flow\").count(), 1);\n assert_eq!(content.matches(\".ai/internal/\").count(), 1);\n assert_eq!(content.matches(\".ai/skills/\").count(), 1);\n }\n\n #[test]\n fn test_update_gitignore_adds_web_when_flow_section_exists() {\n let dir = tempdir().unwrap();\n let root = dir.path();\n\n fs::write(\n root.join(\".gitignore\"),\n \"# flow\\n.ai/internal/\\n.claude/\\n.codex/\\n\",\n )\n .unwrap();\n\n update_gitignore(root).unwrap();\n\n let content = fs::read_to_string(root.join(\".gitignore\")).unwrap();\n assert!(content.contains(\"# flow\"));\n assert!(content.contains(\".ai/internal/\"));\n assert!(content.contains(\".ai/web/\"));\n assert!(content.contains(\".ai/skills/\"));\n assert!(content.contains(\".flox/\"));\n }\n}\n" }, { "path": "src/storage.rs", "content": "use std::fs;\nuse std::io::Read;\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Output, Stdio};\nuse std::thread;\nuse std::time::{Duration, Instant};\n\nuse anyhow::{Context, Result, bail};\nuse shellexpand::tilde;\nuse url::Url;\nuse uuid::Uuid;\n\nuse crate::cli::{DbAction, DbCommand, JazzStorageAction, JazzStorageKind, PostgresAction};\nuse crate::{config, env};\n\nconst DEFAULT_JAZZ_API_KEY_MIRROR: &str = \"jazz-gitedit-prod\";\nconst DEFAULT_JAZZ_SERVER_MIRROR: &str = \"https://cloud.jazz.tools\";\nconst DEFAULT_JAZZ_API_KEY_ENV: &str = \"cloud@myflow.sh\";\nconst DEFAULT_JAZZ_SERVER_ENV: &str = \"https://cloud.jazz.tools\";\nconst DEFAULT_JAZZ_API_KEY_APP: &str = \"cloud@myflow.sh\";\nconst DEFAULT_JAZZ_SERVER_APP: &str = \"https://cloud.jazz.tools\";\nconst DEFAULT_POSTGRES_PROJECT: &str = \"~/org/la/la/server\";\nconst DEFAULT_JAZZ_TOOLS_NPX_SPEC: &str = \"jazz-tools@0.20.14\";\nconst JAZZ_TOOLS_NPX_SPEC_ENV: &str = \"FLOW_JAZZ_TOOLS_PACKAGE_SPEC\";\n\n#[derive(Debug, Clone)]\npub(crate) struct JazzAppCredentials {\n pub(crate) app_id: String,\n pub(crate) backend_secret: String,\n pub(crate) admin_secret: String,\n}\n\npub fn run(cmd: DbCommand) -> Result<()> {\n match cmd.action {\n DbAction::Jazz(jazz) => run_jazz(jazz.action),\n DbAction::Postgres(pg) => run_postgres(pg.action),\n }\n}\n\nfn run_jazz(action: JazzStorageAction) -> Result<()> {\n match action {\n JazzStorageAction::New {\n kind,\n name,\n peer,\n api_key,\n environment,\n } => jazz_new(kind, name, peer, api_key, &environment),\n }\n}\n\nfn run_postgres(action: PostgresAction) -> Result<()> {\n match action {\n PostgresAction::Generate { project } => postgres_generate(project),\n PostgresAction::Migrate {\n project,\n database_url,\n generate,\n } => postgres_migrate(project, database_url, generate),\n }\n}\n\nfn postgres_generate(project: Option<PathBuf>) -> Result<()> {\n let project_dir = resolve_postgres_project(project)?;\n println!(\"Running migrations generate in {}\", project_dir.display());\n run_bun_script(&project_dir, \"db:generate\", None)\n}\n\nfn postgres_migrate(\n project: Option<PathBuf>,\n database_url: Option<String>,\n generate: bool,\n) -> Result<()> {\n let project_dir = resolve_postgres_project(project)?;\n let database_url = resolve_database_url(database_url.as_deref(), &project_dir)?;\n\n if generate {\n println!(\"Generating migrations in {}\", project_dir.display());\n run_bun_script(&project_dir, \"db:generate\", Some(&database_url))?;\n }\n\n println!(\"Applying migrations in {}\", project_dir.display());\n run_bun_script(&project_dir, \"db:migrate\", Some(&database_url))\n}\n\nfn resolve_postgres_project(project: Option<PathBuf>) -> Result<PathBuf> {\n let path = match project {\n Some(path) => path,\n None => PathBuf::from(tilde(DEFAULT_POSTGRES_PROJECT).as_ref()),\n };\n\n if path.exists() {\n return Ok(path);\n }\n\n bail!(\n \"Postgres project path not found: {} (override with --project)\",\n path.display()\n )\n}\n\nfn resolve_database_url(database_url: Option<&str>, project_dir: &Path) -> Result<String> {\n if let Some(url) = database_url {\n let trimmed = url.trim();\n if !trimmed.is_empty() {\n return Ok(trimmed.to_string());\n }\n }\n\n for key in [\n \"DATABASE_URL\",\n \"PLANETSCALE_DATABASE_URL\",\n \"PSCALE_DATABASE_URL\",\n ] {\n if let Ok(url) = std::env::var(key) {\n if !url.trim().is_empty() {\n return Ok(url);\n }\n }\n }\n\n let env_path = project_dir.join(\".env\");\n if let Some(value) = read_env_value(&env_path, \"DATABASE_URL\")? {\n return Ok(value);\n }\n\n bail!(\n \"DATABASE_URL not found (set env, PLANETSCALE_DATABASE_URL, or add it to {})\",\n env_path.display()\n )\n}\n\nfn read_env_value(path: &Path, key: &str) -> Result<Option<String>> {\n if !path.exists() {\n return Ok(None);\n }\n let contents = fs::read_to_string(path)\n .with_context(|| format!(\"failed to read env file {}\", path.display()))?;\n for line in contents.lines() {\n let line = line.trim();\n if line.is_empty() || line.starts_with('#') {\n continue;\n }\n let line = line.strip_prefix(\"export \").unwrap_or(line);\n let Some((name, value)) = line.split_once('=') else {\n continue;\n };\n if name.trim() != key {\n continue;\n }\n let value = strip_quotes(value.trim());\n if !value.is_empty() {\n return Ok(Some(value.to_string()));\n }\n }\n Ok(None)\n}\n\nfn strip_quotes(value: &str) -> &str {\n let trimmed = value.trim();\n trimmed\n .strip_prefix('\"')\n .and_then(|v| v.strip_suffix('\"'))\n .or_else(|| {\n trimmed\n .strip_prefix('\\'')\n .and_then(|v| v.strip_suffix('\\''))\n })\n .unwrap_or(trimmed)\n}\n\nfn run_bun_script(project_dir: &Path, script: &str, database_url: Option<&str>) -> Result<()> {\n let mut cmd = Command::new(\"bun\");\n cmd.args([\"run\", script]);\n cmd.current_dir(project_dir);\n if let Some(url) = database_url {\n cmd.env(\"DATABASE_URL\", url);\n }\n cmd.stdout(Stdio::inherit());\n cmd.stderr(Stdio::inherit());\n let status = cmd.status().with_context(|| {\n format!(\n \"failed to run bun script '{}' in {}\",\n script,\n project_dir.display()\n )\n })?;\n if !status.success() {\n bail!(\"bun run {} failed with status {}\", script, status);\n }\n Ok(())\n}\n\nfn jazz_new(\n kind: JazzStorageKind,\n name: Option<String>,\n peer: Option<String>,\n api_key: Option<String>,\n environment: &str,\n) -> Result<()> {\n let project = get_project_name()?;\n let default_name = match kind {\n JazzStorageKind::Mirror => format!(\"{}-jazz-mirror\", sanitize_name(&project)),\n JazzStorageKind::EnvStore => format!(\"{}-jazz-env\", sanitize_name(&project)),\n JazzStorageKind::AppStore => format!(\"{}-jazz-app\", sanitize_name(&project)),\n };\n let name = name.unwrap_or(default_name);\n\n let default_server_url = match kind {\n JazzStorageKind::Mirror => DEFAULT_JAZZ_SERVER_MIRROR,\n JazzStorageKind::EnvStore => DEFAULT_JAZZ_SERVER_ENV,\n JazzStorageKind::AppStore => DEFAULT_JAZZ_SERVER_APP,\n };\n\n let (server_url, peer_api_key) = match peer {\n Some(peer) => {\n let api_key = extract_api_key(&peer);\n (normalize_server_url(&peer), api_key)\n }\n None => (default_server_url.to_string(), None),\n };\n let effective_api_key = api_key.or(peer_api_key);\n\n let creds = create_jazz_app_credentials(&name)?;\n\n match kind {\n JazzStorageKind::Mirror => {\n env::set_project_env_var(\n \"JAZZ_MIRROR_APP_ID\",\n &creds.app_id,\n environment,\n Some(\"Jazz2 mirror app id\"),\n )?;\n env::set_project_env_var(\n \"JAZZ_MIRROR_BACKEND_SECRET\",\n &creds.backend_secret,\n environment,\n Some(\"Jazz2 mirror backend secret\"),\n )?;\n env::set_project_env_var(\n \"JAZZ_MIRROR_ADMIN_SECRET\",\n &creds.admin_secret,\n environment,\n Some(\"Jazz2 mirror admin secret\"),\n )?;\n }\n JazzStorageKind::EnvStore => {\n env::set_project_env_var(\n \"JAZZ_APP_ID\",\n &creds.app_id,\n environment,\n Some(\"Jazz2 app id\"),\n )?;\n env::set_project_env_var(\n \"JAZZ_BACKEND_SECRET\",\n &creds.backend_secret,\n environment,\n Some(\"Jazz2 backend secret\"),\n )?;\n env::set_project_env_var(\n \"JAZZ_ADMIN_SECRET\",\n &creds.admin_secret,\n environment,\n Some(\"Jazz2 admin secret\"),\n )?;\n }\n JazzStorageKind::AppStore => {\n env::set_project_env_var(\n \"JAZZ_APP_APP_ID\",\n &creds.app_id,\n environment,\n Some(\"Jazz2 app-store app id\"),\n )?;\n env::set_project_env_var(\n \"JAZZ_APP_BACKEND_SECRET\",\n &creds.backend_secret,\n environment,\n Some(\"Jazz2 app-store backend secret\"),\n )?;\n env::set_project_env_var(\n \"JAZZ_APP_ADMIN_SECRET\",\n &creds.admin_secret,\n environment,\n Some(\"Jazz2 app-store admin secret\"),\n )?;\n }\n }\n\n if effective_api_key.is_some() {\n let key = effective_api_key.unwrap_or_else(|| match kind {\n JazzStorageKind::Mirror => DEFAULT_JAZZ_API_KEY_MIRROR.to_string(),\n JazzStorageKind::EnvStore => DEFAULT_JAZZ_API_KEY_ENV.to_string(),\n JazzStorageKind::AppStore => DEFAULT_JAZZ_API_KEY_APP.to_string(),\n });\n env::set_project_env_var(\n \"JAZZ_API_KEY\",\n &key,\n environment,\n Some(\"Jazz2 API key for hosted sync\"),\n )?;\n }\n\n if server_url != default_server_url {\n let (key, desc) = match kind {\n JazzStorageKind::Mirror => (\n \"JAZZ_MIRROR_SERVER_URL\",\n \"Custom Jazz2 server URL for mirror app\",\n ),\n JazzStorageKind::EnvStore => (\"JAZZ_SERVER_URL\", \"Custom Jazz2 server URL\"),\n JazzStorageKind::AppStore => (\n \"JAZZ_APP_SERVER_URL\",\n \"Custom Jazz2 server URL for app-store app\",\n ),\n };\n env::set_project_env_var(key, &server_url, environment, Some(desc))?;\n }\n\n println!(\"✓ Jazz2 storage initialized for {}\", project);\n Ok(())\n}\n\npub(crate) fn create_jazz_app_credentials(name: &str) -> Result<JazzAppCredentials> {\n println!(\n \"Creating Jazz2 app credentials '{}' (this can take a minute)...\",\n name\n );\n\n let output = if let Some(path) = find_in_path(\"jazz-tools\") {\n println!(\"Running: {} create app --name {}\", path.display(), name);\n {\n let mut cmd = Command::new(path);\n cmd.args([\"create\", \"app\", \"--name\", name]);\n run_command_with_output(cmd)\n }\n .context(\"failed to spawn jazz-tools\")?\n } else {\n let package_spec = jazz_tools_package_spec();\n println!(\n \"Running: npx --yes {} create app --name {}\",\n package_spec, name\n );\n {\n let mut cmd = Command::new(\"npx\");\n cmd.args([\"--yes\"]);\n cmd.arg(&package_spec);\n cmd.args([\"create\", \"app\", \"--name\", name]);\n run_command_with_output(cmd)\n }\n .context(\"failed to spawn npx\")?\n };\n\n if !output.status.success() {\n let stdout = String::from_utf8_lossy(&output.stdout);\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\n \"jazz2 app create failed: {}{}\",\n stdout.trim(),\n stderr.trim()\n );\n }\n\n let stdout = String::from_utf8_lossy(&output.stdout);\n let app_id = stdout\n .lines()\n .rev()\n .find(|line| !line.trim().is_empty())\n .map(|line| line.trim().to_string())\n .ok_or_else(|| anyhow::anyhow!(\"jazz-tools did not return an app id\"))?;\n\n Ok(JazzAppCredentials {\n app_id,\n backend_secret: generate_secret(\"backend\"),\n admin_secret: generate_secret(\"admin\"),\n })\n}\n\nfn jazz_tools_package_spec() -> String {\n resolve_jazz_tools_package_spec(std::env::var(JAZZ_TOOLS_NPX_SPEC_ENV).ok().as_deref())\n}\n\nfn resolve_jazz_tools_package_spec(raw: Option<&str>) -> String {\n raw.map(str::trim)\n .filter(|value| !value.is_empty())\n .unwrap_or(DEFAULT_JAZZ_TOOLS_NPX_SPEC)\n .to_string()\n}\n\nfn run_command_with_output(mut cmd: Command) -> Result<Output> {\n let mut child = cmd.stdout(Stdio::piped()).stderr(Stdio::piped()).spawn()?;\n\n let mut stdout = child\n .stdout\n .take()\n .ok_or_else(|| anyhow::anyhow!(\"failed to capture stdout\"))?;\n let mut stderr = child\n .stderr\n .take()\n .ok_or_else(|| anyhow::anyhow!(\"failed to capture stderr\"))?;\n\n let stdout_handle = thread::spawn(move || {\n let mut buf = Vec::new();\n let _ = stdout.read_to_end(&mut buf);\n buf\n });\n let stderr_handle = thread::spawn(move || {\n let mut buf = Vec::new();\n let _ = stderr.read_to_end(&mut buf);\n buf\n });\n\n let start = Instant::now();\n let mut next_log = Duration::from_secs(10);\n let status = loop {\n if let Some(status) = child.try_wait()? {\n break status;\n }\n let elapsed = start.elapsed();\n if elapsed >= next_log {\n println!(\n \"... still creating Jazz worker account ({}s)\",\n elapsed.as_secs()\n );\n next_log += Duration::from_secs(10);\n }\n thread::sleep(Duration::from_millis(200));\n };\n\n let stdout = stdout_handle.join().unwrap_or_default();\n let stderr = stderr_handle.join().unwrap_or_default();\n\n Ok(Output {\n status,\n stdout,\n stderr,\n })\n}\n\nfn normalize_server_url(value: &str) -> String {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n return DEFAULT_JAZZ_SERVER_ENV.to_string();\n }\n if let Ok(mut parsed) = Url::parse(trimmed) {\n match parsed.scheme() {\n \"wss\" => {\n let _ = parsed.set_scheme(\"https\");\n }\n \"ws\" => {\n let _ = parsed.set_scheme(\"http\");\n }\n _ => {}\n }\n parsed.set_query(None);\n parsed.set_fragment(None);\n return parsed.to_string().trim_end_matches('/').to_string();\n }\n trimmed.trim_end_matches('/').to_string()\n}\n\nfn extract_api_key(value: &str) -> Option<String> {\n let parsed = Url::parse(value).ok()?;\n parsed\n .query_pairs()\n .find_map(|(k, v)| (k == \"key\").then(|| v.to_string()))\n}\n\nfn find_in_path(binary: &str) -> Option<PathBuf> {\n let path = std::env::var_os(\"PATH\")?;\n for dir in std::env::split_paths(&path) {\n let candidate = dir.join(binary);\n if candidate.is_file() {\n return Some(candidate);\n }\n }\n None\n}\n\nfn generate_secret(prefix: &str) -> String {\n format!(\n \"{}-{}{}\",\n prefix,\n Uuid::new_v4().as_simple(),\n Uuid::new_v4().as_simple()\n )\n}\n\npub(crate) fn sanitize_name(name: &str) -> String {\n let mut out = String::new();\n let mut last_dash = false;\n for ch in name.chars() {\n let ch = ch.to_ascii_lowercase();\n if ch.is_ascii_alphanumeric() {\n out.push(ch);\n last_dash = false;\n } else if !last_dash {\n out.push('-');\n last_dash = true;\n }\n }\n let trimmed = out.trim_matches('-').to_string();\n if trimmed.is_empty() {\n \"flow-jazz-mirror\".to_string()\n } else {\n trimmed\n }\n}\n\nfn find_flow_toml(start: &PathBuf) -> Option<PathBuf> {\n let mut current = start.clone();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n\npub(crate) fn get_project_name() -> Result<String> {\n let cwd = std::env::current_dir()?;\n if let Some(flow_path) = find_flow_toml(&cwd) {\n if let Ok(cfg) = config::load(&flow_path) {\n if let Some(name) = cfg.project_name {\n return Ok(name);\n }\n if let Some(parent) = flow_path.parent() {\n if let Some(dir_name) = parent.file_name().and_then(|n| n.to_str()) {\n return Ok(dir_name.to_string());\n }\n }\n }\n }\n\n Ok(cwd\n .file_name()\n .and_then(|n| n.to_str())\n .unwrap_or(\"flow\")\n .to_string())\n}\n\n#[cfg(test)]\nmod tests {\n use super::{DEFAULT_JAZZ_TOOLS_NPX_SPEC, resolve_jazz_tools_package_spec, sanitize_name};\n\n #[test]\n fn sanitize_name_keeps_alnum_and_normalizes_separators() {\n assert_eq!(sanitize_name(\"Flow Mirror App\"), \"flow-mirror-app\");\n assert_eq!(sanitize_name(\"___\"), \"flow-jazz-mirror\");\n }\n\n #[test]\n fn resolve_jazz_tools_package_spec_defaults_to_pinned_version() {\n assert_eq!(\n resolve_jazz_tools_package_spec(None),\n DEFAULT_JAZZ_TOOLS_NPX_SPEC\n );\n assert_eq!(\n resolve_jazz_tools_package_spec(Some(\" \")),\n DEFAULT_JAZZ_TOOLS_NPX_SPEC\n );\n }\n\n #[test]\n fn resolve_jazz_tools_package_spec_allows_explicit_override() {\n assert_eq!(\n resolve_jazz_tools_package_spec(Some(\"jazz-tools@0.20.15\")),\n \"jazz-tools@0.20.15\"\n );\n assert_eq!(\n resolve_jazz_tools_package_spec(Some(\" jazz-tools@local \")),\n \"jazz-tools@local\"\n );\n }\n}\n" }, { "path": "src/supervisor.rs", "content": "use std::collections::HashMap;\nuse std::fs;\nuse std::io::{BufRead, BufReader, Write};\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\nuse std::sync::{Arc, Mutex};\nuse std::time::{Duration, Instant};\n\nuse anyhow::{Context, Result, bail};\nuse serde::{Deserialize, Serialize};\n\nuse crate::cli::{DaemonAction, SupervisorAction, SupervisorCommand};\nuse crate::{config, daemon, projects, running};\n\n#[derive(Debug, Serialize, Deserialize)]\npub struct IpcRequest {\n pub action: SupervisorIpcAction,\n}\n\n#[derive(Debug, Serialize, Deserialize)]\n#[serde(tag = \"type\", rename_all = \"snake_case\")]\npub enum SupervisorIpcAction {\n Ping,\n StartDaemon {\n name: String,\n config_path: Option<String>,\n },\n StopDaemon {\n name: String,\n config_path: Option<String>,\n },\n RestartDaemon {\n name: String,\n config_path: Option<String>,\n },\n Status {\n config_path: Option<String>,\n },\n List {\n config_path: Option<String>,\n },\n}\n\n#[derive(Debug, Serialize, Deserialize)]\npub struct IpcResponse {\n pub ok: bool,\n pub message: Option<String>,\n pub daemons: Option<Vec<DaemonStatusView>>,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct DaemonStatusView {\n pub name: String,\n pub running: bool,\n pub pid: Option<u32>,\n #[serde(default)]\n pub healthy: Option<bool>,\n pub health_target: Option<String>,\n pub description: Option<String>,\n}\n\n#[derive(Debug, Clone)]\nstruct ManagedDaemon {\n name: String,\n config_path: Option<PathBuf>,\n restart: config::DaemonRestartPolicy,\n retry_remaining: Option<u32>,\n autostop: bool,\n disabled: bool,\n health_failures: u32,\n restart_attempts: u32,\n next_restart_at: Option<Instant>,\n}\n\n#[derive(Default)]\nstruct SupervisorState {\n managed: HashMap<String, ManagedDaemon>,\n}\n\ntype SharedState = Arc<Mutex<SupervisorState>>;\n\npub fn run(cmd: SupervisorCommand) -> Result<()> {\n let action = cmd.action.unwrap_or(SupervisorAction::Status);\n let socket_path = resolve_socket_path(cmd.socket.as_deref())?;\n\n match action {\n SupervisorAction::Start { boot } => {\n ensure_supervisor_running(&socket_path, true, boot)?;\n Ok(())\n }\n SupervisorAction::Run { boot } => run_server(&socket_path, boot),\n SupervisorAction::Install { boot } => install_launch_agent(&socket_path, boot),\n SupervisorAction::Uninstall => uninstall_launch_agent(&socket_path),\n SupervisorAction::Stop => stop_supervisor(&socket_path),\n SupervisorAction::Status => show_status(&socket_path),\n }\n}\n\npub fn ensure_running(boot: bool, announce: bool) -> Result<()> {\n let socket_path = resolve_socket_path(None)?;\n ensure_supervisor_running(&socket_path, announce, boot)?;\n Ok(())\n}\n\npub fn ensure_daemon_running(name: &str, config_path: Option<&Path>, announce: bool) -> Result<()> {\n let socket_path = resolve_socket_path(None)?;\n ensure_supervisor_running(&socket_path, announce, false)?;\n let request = IpcRequest {\n action: SupervisorIpcAction::StartDaemon {\n name: name.to_string(),\n config_path: config_path.map(|p| p.display().to_string()),\n },\n };\n let response = send_request(&socket_path, &request)?;\n if !response.ok {\n bail!(\n \"{}\",\n response\n .message\n .unwrap_or_else(|| format!(\"failed to start daemon {}\", name))\n );\n }\n if announce {\n if let Some(message) = response.message {\n println!(\"OK {}\", message);\n }\n }\n Ok(())\n}\n\npub fn stop_daemon_managed(name: &str, config_path: Option<&Path>, announce: bool) -> Result<()> {\n let socket_path = resolve_socket_path(None)?;\n ensure_supervisor_running(&socket_path, announce, false)?;\n let request = IpcRequest {\n action: SupervisorIpcAction::StopDaemon {\n name: name.to_string(),\n config_path: config_path.map(|p| p.display().to_string()),\n },\n };\n let response = send_request(&socket_path, &request)?;\n if !response.ok {\n bail!(\n \"{}\",\n response\n .message\n .unwrap_or_else(|| format!(\"failed to stop daemon {}\", name))\n );\n }\n if announce {\n if let Some(message) = response.message {\n println!(\"OK {}\", message);\n }\n }\n Ok(())\n}\n\npub fn is_running() -> bool {\n resolve_socket_path(None)\n .map(|path| supervisor_running(&path))\n .unwrap_or(false)\n}\n\npub fn try_handle_daemon_action(action: &DaemonAction, config_path: Option<&Path>) -> Result<bool> {\n let socket_path = resolve_socket_path(None)?;\n if !supervisor_running(&socket_path) {\n if !ensure_supervisor_running(&socket_path, false, false).unwrap_or(false) {\n return Ok(false);\n }\n }\n\n let request = IpcRequest {\n action: match action {\n DaemonAction::Start { name } => SupervisorIpcAction::StartDaemon {\n name: name.clone(),\n config_path: config_path.map(|p| p.display().to_string()),\n },\n DaemonAction::Stop { name } => SupervisorIpcAction::StopDaemon {\n name: name.clone(),\n config_path: config_path.map(|p| p.display().to_string()),\n },\n DaemonAction::Restart { name } => SupervisorIpcAction::RestartDaemon {\n name: name.clone(),\n config_path: config_path.map(|p| p.display().to_string()),\n },\n DaemonAction::Status { .. } => SupervisorIpcAction::Status {\n config_path: config_path.map(|p| p.display().to_string()),\n },\n DaemonAction::List => SupervisorIpcAction::List {\n config_path: config_path.map(|p| p.display().to_string()),\n },\n },\n };\n\n let response = match send_request(&socket_path, &request) {\n Ok(resp) => resp,\n Err(_) => return Ok(false),\n };\n\n if !response.ok {\n if let Some(message) = response.message {\n eprintln!(\"WARN supervisor error: {}\", message);\n }\n return Ok(false);\n }\n\n if let Some(daemons) = response.daemons {\n match action {\n DaemonAction::Status { name } => print_status_views(&daemons, name.as_deref()),\n DaemonAction::List => print_list_views(&daemons),\n _ => {}\n }\n return Ok(true);\n }\n\n if let Some(message) = response.message {\n println!(\"OK {}\", message);\n }\n\n Ok(true)\n}\n\npub fn resolve_socket_path(override_path: Option<&Path>) -> Result<PathBuf> {\n if let Some(path) = override_path {\n return Ok(config::expand_path(&path.to_string_lossy()));\n }\n let base = config::ensure_global_state_dir()?;\n Ok(base.join(\"supervisor.sock\"))\n}\n\nfn supervisor_pid_path() -> Result<PathBuf> {\n let base = config::ensure_global_state_dir()?;\n Ok(base.join(\"supervisor.pid\"))\n}\n\nfn supervisor_log_path() -> Result<PathBuf> {\n let base = config::ensure_global_state_dir()?;\n Ok(base.join(\"supervisor.log\"))\n}\n\nfn supervisor_running(socket_path: &Path) -> bool {\n if !socket_path.exists() {\n return false;\n }\n\n let request = IpcRequest {\n action: SupervisorIpcAction::Ping,\n };\n send_request(socket_path, &request)\n .map(|resp| resp.ok)\n .unwrap_or(false)\n}\n\nfn ensure_supervisor_running(socket_path: &Path, announce: bool, boot: bool) -> Result<bool> {\n if supervisor_running(socket_path) {\n if announce {\n println!(\"Supervisor already running.\");\n }\n return Ok(true);\n }\n\n if let Some(started) = ensure_supervisor_via_launchd(socket_path, announce, boot)? {\n return Ok(started);\n }\n\n let exe = std::env::current_exe().context(\"failed to resolve flow binary\")?;\n let mut cmd = Command::new(exe);\n cmd.arg(\"supervisor\").arg(\"run\");\n cmd.arg(\"--socket\").arg(socket_path);\n if boot {\n cmd.arg(\"--boot\");\n }\n cmd.stdin(Stdio::null());\n\n let log_path = supervisor_log_path().ok();\n if let Some(path) = &log_path {\n let log_file = fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(path)\n .ok();\n if let Some(file) = log_file {\n let file_err = file.try_clone().ok();\n cmd.stdout(file);\n if let Some(err) = file_err {\n cmd.stderr(err);\n } else {\n cmd.stderr(Stdio::null());\n }\n } else {\n cmd.stdout(Stdio::null()).stderr(Stdio::null());\n }\n } else {\n cmd.stdout(Stdio::null()).stderr(Stdio::null());\n }\n\n #[cfg(unix)]\n {\n use std::os::unix::process::CommandExt;\n cmd.process_group(0);\n }\n\n let child = cmd.spawn().context(\"failed to start supervisor\")?;\n persist_supervisor_pid(child.id())?;\n\n // Give the socket a moment to come up.\n let mut ready = false;\n for _ in 0..20 {\n std::thread::sleep(Duration::from_millis(150));\n if supervisor_running(socket_path) {\n ready = true;\n break;\n }\n }\n\n if ready {\n if announce {\n println!(\"Supervisor started.\");\n }\n return Ok(true);\n }\n\n if announce {\n if let Some(path) = log_path {\n eprintln!(\n \"WARN supervisor did not respond after launch. Check {}\",\n path.display()\n );\n } else {\n eprintln!(\"WARN supervisor did not respond after launch.\");\n }\n }\n Ok(false)\n}\n\nfn show_status(socket_path: &Path) -> Result<()> {\n if supervisor_running(socket_path) {\n println!(\"Supervisor running (socket: {}).\", socket_path.display());\n return Ok(());\n }\n println!(\"Supervisor not running.\");\n Ok(())\n}\n\nfn stop_supervisor(socket_path: &Path) -> Result<()> {\n if let Ok(pid_path) = supervisor_pid_path() {\n if let Ok(Some(pid)) = load_supervisor_pid(&pid_path) {\n if running::process_alive(pid) {\n terminate_process(pid).ok();\n }\n remove_supervisor_pid(&pid_path).ok();\n }\n }\n\n if socket_path.exists() {\n fs::remove_file(socket_path).ok();\n }\n\n println!(\"Supervisor stopped (if it was running).\");\n Ok(())\n}\n\nfn run_server(socket_path: &Path, boot: bool) -> Result<()> {\n if let Some(parent) = socket_path.parent() {\n fs::create_dir_all(parent)?;\n }\n\n if socket_path.exists() {\n if supervisor_running(socket_path) {\n println!(\"Supervisor already running; exiting.\");\n return Ok(());\n }\n fs::remove_file(socket_path).ok();\n }\n\n #[cfg(unix)]\n let listener = std::os::unix::net::UnixListener::bind(socket_path)\n .with_context(|| format!(\"failed to bind {}\", socket_path.display()))?;\n\n #[cfg(not(unix))]\n {\n bail!(\"Supervisor IPC is only supported on unix platforms right now.\");\n }\n\n let state = Arc::new(Mutex::new(SupervisorState::default()));\n let active_path = resolve_active_project_config_path();\n bootstrap_daemons(&state, active_path.as_deref(), boot)?;\n\n let monitor_state = Arc::clone(&state);\n std::thread::spawn(move || {\n if let Err(err) = monitor_daemons(monitor_state) {\n eprintln!(\"WARN supervisor monitor failed: {err}\");\n }\n });\n\n #[cfg(unix)]\n {\n for stream in listener.incoming() {\n match stream {\n Ok(stream) => {\n if let Err(err) = handle_client(stream, &state) {\n eprintln!(\"WARN supervisor request failed: {err}\");\n }\n }\n Err(err) => {\n eprintln!(\"WARN supervisor accept failed: {err}\");\n }\n }\n }\n }\n\n Ok(())\n}\n\nfn ensure_supervisor_via_launchd(\n socket_path: &Path,\n announce: bool,\n boot: bool,\n) -> Result<Option<bool>> {\n #[cfg(target_os = \"macos\")]\n {\n if !launch_agent_installed() {\n return Ok(None);\n }\n\n if boot {\n install_launch_agent(socket_path, true)?;\n }\n\n if announce {\n println!(\"Starting supervisor via launchd...\");\n }\n\n launch_agent_kickstart()?;\n\n let mut ready = false;\n for _ in 0..20 {\n std::thread::sleep(Duration::from_millis(150));\n if supervisor_running(socket_path) {\n ready = true;\n break;\n }\n }\n\n if ready {\n if announce {\n println!(\"Supervisor started (launchd).\");\n }\n return Ok(Some(true));\n }\n\n if announce {\n eprintln!(\"WARN launchd supervisor did not respond.\");\n }\n return Ok(Some(false));\n }\n\n #[cfg(not(target_os = \"macos\"))]\n {\n let _ = socket_path;\n let _ = announce;\n let _ = boot;\n Ok(None)\n }\n}\n\n#[cfg(target_os = \"macos\")]\nfn launch_agent_label() -> &'static str {\n \"io.linsa.flow-supervisor\"\n}\n\n#[cfg(target_os = \"macos\")]\nfn launch_agent_plist_path() -> Result<PathBuf> {\n let dir = config::expand_path(\"~/Library/LaunchAgents\");\n fs::create_dir_all(&dir).with_context(|| format!(\"failed to create {}\", dir.display()))?;\n Ok(dir.join(format!(\"{}.plist\", launch_agent_label())))\n}\n\n#[cfg(target_os = \"macos\")]\nfn launch_agent_installed() -> bool {\n launch_agent_plist_path()\n .map(|p| p.exists())\n .unwrap_or(false)\n}\n\n#[cfg(target_os = \"macos\")]\nfn launch_agent_domain() -> String {\n let uid = unsafe { libc::getuid() };\n format!(\"gui/{}\", uid)\n}\n\n#[cfg(target_os = \"macos\")]\nfn launch_agent_target() -> String {\n format!(\"{}/{}\", launch_agent_domain(), launch_agent_label())\n}\n\n#[cfg(target_os = \"macos\")]\nfn launch_agent_program_args(socket_path: &Path, boot: bool) -> Result<Vec<String>> {\n let exe = std::env::current_exe().context(\"failed to resolve flow binary\")?;\n let mut args = vec![\n exe.to_string_lossy().into_owned(),\n \"supervisor\".to_string(),\n \"run\".to_string(),\n \"--socket\".to_string(),\n socket_path.to_string_lossy().into_owned(),\n ];\n if boot {\n args.push(\"--boot\".to_string());\n }\n Ok(args)\n}\n\n#[cfg(target_os = \"macos\")]\nfn launch_agent_plist(socket_path: &Path, boot: bool, log_path: Option<&Path>) -> Result<String> {\n let args = launch_agent_program_args(socket_path, boot)?;\n let mut buf = String::new();\n buf.push_str(\"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n\");\n buf.push_str(\n \"<!DOCTYPE plist PUBLIC \\\"-//Apple//DTD PLIST 1.0//EN\\\" \\\"http://www.apple.com/DTDs/PropertyList-1.0.dtd\\\">\\n\",\n );\n buf.push_str(\"<plist version=\\\"1.0\\\">\\n<dict>\\n\");\n buf.push_str(\" <key>Label</key>\\n\");\n buf.push_str(&format!(\" <string>{}</string>\\n\", launch_agent_label()));\n buf.push_str(\" <key>ProgramArguments</key>\\n <array>\\n\");\n for arg in args {\n buf.push_str(&format!(\" <string>{}</string>\\n\", xml_escape(&arg)));\n }\n buf.push_str(\" </array>\\n\");\n buf.push_str(\" <key>RunAtLoad</key>\\n <true/>\\n\");\n buf.push_str(\" <key>KeepAlive</key>\\n <dict>\\n\");\n buf.push_str(\" <key>SuccessfulExit</key>\\n <false/>\\n\");\n buf.push_str(\" </dict>\\n\");\n if let Some(path) = log_path {\n let log = path.to_string_lossy();\n buf.push_str(\" <key>StandardOutPath</key>\\n\");\n buf.push_str(&format!(\n \" <string>{}</string>\\n\",\n xml_escape(log.as_ref())\n ));\n buf.push_str(\" <key>StandardErrorPath</key>\\n\");\n buf.push_str(&format!(\n \" <string>{}</string>\\n\",\n xml_escape(log.as_ref())\n ));\n }\n buf.push_str(\"</dict>\\n</plist>\\n\");\n Ok(buf)\n}\n\n#[cfg(target_os = \"macos\")]\nfn install_launch_agent(socket_path: &Path, boot: bool) -> Result<()> {\n let plist_path = launch_agent_plist_path()?;\n let log_path = supervisor_log_path().ok();\n let plist = launch_agent_plist(socket_path, boot, log_path.as_deref())?;\n fs::write(&plist_path, plist)\n .with_context(|| format!(\"failed to write {}\", plist_path.display()))?;\n\n let domain = launch_agent_domain();\n let target = launch_agent_target();\n\n let _ = Command::new(\"launchctl\")\n .args([\"bootout\", &domain, plist_path.to_string_lossy().as_ref()])\n .output();\n\n let output = Command::new(\"launchctl\")\n .args([\"bootstrap\", &domain, plist_path.to_string_lossy().as_ref()])\n .output()\n .context(\"failed to bootstrap launch agent\")?;\n if !output.status.success() {\n bail!(\n \"launchctl bootstrap failed: {}\",\n String::from_utf8_lossy(&output.stderr)\n );\n }\n\n let _ = Command::new(\"launchctl\").args([\"enable\", &target]).output();\n\n let output = Command::new(\"launchctl\")\n .args([\"kickstart\", \"-k\", &target])\n .output()\n .context(\"failed to kickstart launch agent\")?;\n if !output.status.success() {\n bail!(\n \"launchctl kickstart failed: {}\",\n String::from_utf8_lossy(&output.stderr)\n );\n }\n\n println!(\n \"Installed launch agent {} at {}\",\n launch_agent_label(),\n plist_path.display()\n );\n Ok(())\n}\n\n#[cfg(target_os = \"macos\")]\nfn launch_agent_kickstart() -> Result<()> {\n let target = launch_agent_target();\n let output = Command::new(\"launchctl\")\n .args([\"kickstart\", \"-k\", &target])\n .output()\n .context(\"failed to kickstart launch agent\")?;\n if !output.status.success() {\n bail!(\n \"launchctl kickstart failed: {}\",\n String::from_utf8_lossy(&output.stderr)\n );\n }\n Ok(())\n}\n\n#[cfg(target_os = \"macos\")]\nfn uninstall_launch_agent(_socket_path: &Path) -> Result<()> {\n let plist_path = launch_agent_plist_path()?;\n let domain = launch_agent_domain();\n\n let _ = Command::new(\"launchctl\")\n .args([\"bootout\", &domain, plist_path.to_string_lossy().as_ref()])\n .output();\n\n if plist_path.exists() {\n fs::remove_file(&plist_path)\n .with_context(|| format!(\"failed to remove {}\", plist_path.display()))?;\n }\n\n println!(\"Removed launch agent {}\", launch_agent_label());\n Ok(())\n}\n\n#[cfg(not(target_os = \"macos\"))]\nfn install_launch_agent(_socket_path: &Path, _boot: bool) -> Result<()> {\n bail!(\"launch agent install is only supported on macOS\");\n}\n\n#[cfg(not(target_os = \"macos\"))]\nfn uninstall_launch_agent(_socket_path: &Path) -> Result<()> {\n bail!(\"launch agent uninstall is only supported on macOS\");\n}\n\n#[cfg(target_os = \"macos\")]\nfn xml_escape(input: &str) -> String {\n let mut out = String::with_capacity(input.len());\n for ch in input.chars() {\n match ch {\n '&' => out.push_str(\"&\"),\n '<' => out.push_str(\"<\"),\n '>' => out.push_str(\">\"),\n '\"' => out.push_str(\""\"),\n '\\'' => out.push_str(\"'\"),\n _ => out.push(ch),\n }\n }\n out\n}\n#[cfg(unix)]\nfn handle_client(stream: std::os::unix::net::UnixStream, state: &SharedState) -> Result<()> {\n let mut reader = BufReader::new(&stream);\n let mut line = Vec::with_capacity(512);\n reader.read_until(b'\\n', &mut line)?;\n let trimmed = trim_ascii_whitespace(&line);\n if trimmed.is_empty() {\n return Ok(());\n }\n\n let request: IpcRequest = serde_json::from_slice(trimmed)?;\n let response = handle_request(request, state)?;\n\n let mut writer = &stream;\n let payload = serde_json::to_string(&response)?;\n writer.write_all(payload.as_bytes())?;\n writer.write_all(b\"\\n\")?;\n writer.flush()?;\n Ok(())\n}\n\nfn handle_request(request: IpcRequest, state: &SharedState) -> Result<IpcResponse> {\n match request.action {\n SupervisorIpcAction::Ping => Ok(IpcResponse {\n ok: true,\n message: Some(\"pong\".to_string()),\n daemons: None,\n }),\n SupervisorIpcAction::StartDaemon { name, config_path } => {\n let path = resolve_config_path(config_path.as_deref());\n let daemon_cfg = resolve_daemon_config(&name, path.as_deref())?;\n daemon::start_daemon_with_path(&name, path.as_deref())?;\n register_managed_daemon(state, &daemon_cfg, path.as_deref(), false)?;\n Ok(IpcResponse {\n ok: true,\n message: Some(format!(\"{} started\", name)),\n daemons: None,\n })\n }\n SupervisorIpcAction::StopDaemon { name, config_path } => {\n let path = resolve_config_path(config_path.as_deref());\n daemon::stop_daemon_with_path(&name, path.as_deref())?;\n disable_managed_daemon(state, &name, path.as_deref())?;\n Ok(IpcResponse {\n ok: true,\n message: Some(format!(\"{} stopped\", name)),\n daemons: None,\n })\n }\n SupervisorIpcAction::RestartDaemon { name, config_path } => {\n let path = resolve_config_path(config_path.as_deref());\n let daemon_cfg = resolve_daemon_config(&name, path.as_deref())?;\n daemon::stop_daemon_with_path(&name, path.as_deref()).ok();\n std::thread::sleep(Duration::from_millis(300));\n daemon::start_daemon_with_path(&name, path.as_deref())?;\n register_managed_daemon(state, &daemon_cfg, path.as_deref(), false)?;\n Ok(IpcResponse {\n ok: true,\n message: Some(format!(\"{} restarted\", name)),\n daemons: None,\n })\n }\n SupervisorIpcAction::Status { config_path } => {\n let views = build_status_views(resolve_config_path(config_path.as_deref()).as_deref())?;\n Ok(IpcResponse {\n ok: true,\n message: None,\n daemons: Some(views),\n })\n }\n SupervisorIpcAction::List { config_path } => {\n let views = build_status_views(resolve_config_path(config_path.as_deref()).as_deref())?;\n Ok(IpcResponse {\n ok: true,\n message: None,\n daemons: Some(views),\n })\n }\n }\n}\n\nfn build_status_views(config_path: Option<&Path>) -> Result<Vec<DaemonStatusView>> {\n let config = daemon::load_merged_config_with_path(config_path)?;\n let mut views = Vec::new();\n for daemon_cfg in config.daemons {\n let status = daemon::get_daemon_status(&daemon_cfg);\n let name = daemon_cfg.name.clone();\n let description = daemon_cfg.description.clone();\n let health_target = daemon_cfg.health_target_label();\n views.push(DaemonStatusView {\n name,\n running: status.running,\n pid: status.pid,\n healthy: status.healthy,\n health_target,\n description,\n });\n }\n Ok(views)\n}\n\npub fn daemon_status_views(config_path: Option<&Path>) -> Result<Vec<DaemonStatusView>> {\n build_status_views(config_path)\n}\n\nfn resolve_config_path(config_path: Option<&str>) -> Option<PathBuf> {\n config_path.map(|path| config::expand_path(path))\n}\n\nfn resolve_active_project_config_path() -> Option<PathBuf> {\n let name = projects::get_active_project()?;\n let entry = projects::resolve_project(&name).ok().flatten()?;\n Some(entry.config_path)\n}\n\nfn bootstrap_daemons(\n state: &SharedState,\n active_config_path: Option<&Path>,\n boot: bool,\n) -> Result<()> {\n let mut seen = std::collections::HashSet::new();\n\n let global_path = config::default_config_path();\n if global_path.exists() {\n if let Ok(cfg) = config::load(&global_path) {\n let mut all_daemons = cfg.daemons;\n for server in &cfg.servers {\n all_daemons.push(server.to_daemon_config());\n }\n start_daemon_set(state, all_daemons, None, boot, &mut seen)?;\n }\n }\n\n if let Some(path) = active_config_path {\n if path.exists() {\n if let Ok(cfg) = config::load(path) {\n let mut all_daemons = cfg.daemons;\n for server in &cfg.servers {\n all_daemons.push(server.to_daemon_config());\n }\n start_daemon_set(state, all_daemons, Some(path), boot, &mut seen)?;\n }\n }\n }\n\n Ok(())\n}\n\nfn start_daemon_set(\n state: &SharedState,\n daemons: Vec<config::DaemonConfig>,\n config_path: Option<&Path>,\n boot: bool,\n seen: &mut std::collections::HashSet<String>,\n) -> Result<()> {\n for daemon_cfg in daemons {\n if !should_start_daemon(&daemon_cfg, boot) {\n continue;\n }\n\n let key = daemon_key(&daemon_cfg.name, config_path);\n if !seen.insert(key) {\n continue;\n }\n\n match daemon::start_daemon_with_path(&daemon_cfg.name, config_path) {\n Ok(()) => {\n register_managed_daemon(state, &daemon_cfg, config_path, false)?;\n }\n Err(err) => {\n eprintln!(\"WARN failed to autostart {}: {}\", daemon_cfg.name, err);\n }\n }\n }\n Ok(())\n}\n\nfn should_start_daemon(daemon_cfg: &config::DaemonConfig, boot: bool) -> bool {\n if daemon_cfg.autostart {\n return true;\n }\n if boot && daemon_cfg.boot {\n return true;\n }\n false\n}\n\nfn should_restart(entry: &ManagedDaemon) -> bool {\n match entry.restart {\n config::DaemonRestartPolicy::Never => false,\n config::DaemonRestartPolicy::Always => true,\n config::DaemonRestartPolicy::OnFailure => true,\n }\n}\n\nfn reconcile_removed(state: &SharedState, active_config_path: &Option<PathBuf>) {\n // Collect all expected daemon names from current config\n let mut expected: std::collections::HashSet<String> = std::collections::HashSet::new();\n\n let global_path = config::default_config_path();\n if global_path.exists() {\n if let Ok(cfg) = config::load(&global_path) {\n for d in &cfg.daemons {\n expected.insert(d.name.clone());\n }\n for s in &cfg.servers {\n expected.insert(s.name.clone());\n }\n }\n }\n if let Some(path) = active_config_path {\n if path.exists() {\n if let Ok(cfg) = config::load(path) {\n for d in &cfg.daemons {\n expected.insert(d.name.clone());\n }\n for s in &cfg.servers {\n expected.insert(s.name.clone());\n }\n }\n }\n }\n\n // Find managed entries not in expected set and stop them\n let managed: Vec<ManagedDaemon> = {\n let st = state.lock().expect(\"lock\");\n st.managed.values().cloned().collect()\n };\n\n for entry in managed {\n if !expected.contains(&entry.name) {\n daemon::stop_daemon(&entry.name).ok();\n let mut st = state.lock().expect(\"lock\");\n st.managed.remove(&entry.name);\n }\n }\n}\n\nfn monitor_daemons(state: SharedState) -> Result<()> {\n let mut last_active = resolve_active_project_config_path()\n .as_deref()\n .map(normalize_path);\n\n let global_path = config::default_config_path();\n let mut last_global_mtime = std::fs::metadata(&global_path)\n .ok()\n .and_then(|m| m.modified().ok());\n\n loop {\n std::thread::sleep(Duration::from_secs(2));\n let now = Instant::now();\n\n let active_path = resolve_active_project_config_path()\n .as_deref()\n .map(normalize_path);\n\n // Check if global config changed\n let current_global_mtime = std::fs::metadata(&global_path)\n .ok()\n .and_then(|m| m.modified().ok());\n if current_global_mtime != last_global_mtime {\n last_global_mtime = current_global_mtime;\n bootstrap_daemons(&state, active_path.as_deref(), false).ok();\n reconcile_removed(&state, &active_path);\n }\n\n if active_path != last_active {\n bootstrap_daemons(&state, active_path.as_deref(), false).ok();\n reconcile_removed(&state, &active_path);\n last_active = active_path.clone();\n }\n\n let entries: Vec<ManagedDaemon> = {\n let state = state.lock().expect(\"supervisor state lock\");\n state.managed.values().cloned().collect()\n };\n\n let mut to_restart: Vec<(String, Option<PathBuf>)> = Vec::new();\n let mut to_stop: Vec<(String, Option<PathBuf>)> = Vec::new();\n let mut updates: Vec<(String, Option<u32>, bool, u32, u32, Option<Instant>)> = Vec::new();\n\n for entry in entries {\n if entry.disabled {\n continue;\n }\n\n if entry.autostop {\n if let Some(ref path) = entry.config_path {\n if !active_path_matches(&active_path, path) {\n to_stop.push((entry.name.clone(), entry.config_path.clone()));\n updates.push((\n daemon_key(&entry.name, entry.config_path.as_deref()),\n entry.retry_remaining,\n true,\n entry.health_failures,\n entry.restart_attempts,\n entry.next_restart_at,\n ));\n continue;\n }\n }\n }\n\n let config_path = entry.config_path.clone();\n let daemon_cfg = match resolve_daemon_config(&entry.name, config_path.as_deref()) {\n Ok(cfg) => cfg,\n Err(err) => {\n eprintln!(\n \"WARN supervisor missing daemon config for {}: {}\",\n entry.name, err\n );\n continue;\n }\n };\n\n let status = daemon::get_daemon_status(&daemon_cfg);\n if status.running {\n if status.healthy == Some(false) {\n let key = daemon_key(&entry.name, config_path.as_deref());\n let failures = entry.health_failures.saturating_add(1);\n let should_restart_for_health = failures >= 3;\n if should_restart_for_health && should_restart(&entry) {\n if entry\n .next_restart_at\n .map(|deadline| now < deadline)\n .unwrap_or(false)\n {\n updates.push((\n key,\n entry.retry_remaining,\n false,\n failures,\n entry.restart_attempts,\n entry.next_restart_at,\n ));\n continue;\n }\n\n let delay_secs = 2u64\n .saturating_pow(entry.restart_attempts.saturating_add(1))\n .min(60);\n let next_restart_at = Some(now + Duration::from_secs(delay_secs));\n updates.push((\n key,\n entry.retry_remaining,\n false,\n failures,\n entry.restart_attempts.saturating_add(1),\n next_restart_at,\n ));\n to_restart.push((entry.name.clone(), config_path));\n } else {\n updates.push((\n key,\n entry.retry_remaining,\n false,\n failures,\n entry.restart_attempts,\n entry.next_restart_at,\n ));\n }\n } else if entry.health_failures != 0 || entry.restart_attempts != 0 {\n let key = daemon_key(&entry.name, config_path.as_deref());\n updates.push((key, entry.retry_remaining, false, 0, 0, None));\n }\n continue;\n }\n\n let key = daemon_key(&entry.name, config_path.as_deref());\n if !should_restart(&entry) {\n continue;\n }\n if entry\n .next_restart_at\n .map(|deadline| now < deadline)\n .unwrap_or(false)\n {\n updates.push((\n key,\n entry.retry_remaining,\n false,\n entry.health_failures,\n entry.restart_attempts,\n entry.next_restart_at,\n ));\n continue;\n }\n\n let mut retry_remaining = entry.retry_remaining;\n if entry.restart != config::DaemonRestartPolicy::Always {\n if let Some(remaining) = retry_remaining {\n if remaining == 0 {\n continue;\n }\n retry_remaining = Some(remaining.saturating_sub(1));\n }\n }\n\n let delay_secs = 2u64\n .saturating_pow(entry.restart_attempts.saturating_add(1))\n .min(60);\n updates.push((\n key,\n retry_remaining,\n false,\n entry.health_failures.saturating_add(1),\n entry.restart_attempts.saturating_add(1),\n Some(now + Duration::from_secs(delay_secs)),\n ));\n to_restart.push((entry.name.clone(), config_path));\n }\n\n if !updates.is_empty() {\n let mut state = state.lock().expect(\"supervisor state lock\");\n for (\n key,\n retry_remaining,\n disabled,\n health_failures,\n restart_attempts,\n next_restart_at,\n ) in updates\n {\n if let Some(entry) = state.managed.get_mut(&key) {\n entry.retry_remaining = retry_remaining;\n entry.disabled = disabled;\n entry.health_failures = health_failures;\n entry.restart_attempts = restart_attempts;\n entry.next_restart_at = next_restart_at;\n }\n }\n }\n\n for (name, config_path) in to_stop {\n daemon::stop_daemon_with_path(&name, config_path.as_deref()).ok();\n }\n\n for (name, config_path) in to_restart {\n daemon::start_daemon_with_path(&name, config_path.as_deref()).ok();\n }\n }\n}\n\nfn active_path_matches(active: &Option<PathBuf>, candidate: &Path) -> bool {\n match active {\n Some(active_path) => active_path == &normalize_path(candidate),\n None => false,\n }\n}\n\nfn normalize_path(path: &Path) -> PathBuf {\n path.canonicalize().unwrap_or_else(|_| path.to_path_buf())\n}\n\nfn resolve_daemon_config(name: &str, config_path: Option<&Path>) -> Result<config::DaemonConfig> {\n let cfg = daemon::load_merged_config_with_path(config_path)?;\n cfg.daemons\n .into_iter()\n .find(|daemon| daemon.name == name)\n .ok_or_else(|| anyhow::anyhow!(\"daemon '{}' not found in config\", name))\n}\n\nfn register_managed_daemon(\n state: &SharedState,\n daemon_cfg: &config::DaemonConfig,\n config_path: Option<&Path>,\n disabled: bool,\n) -> Result<()> {\n let mut state = state.lock().expect(\"supervisor state lock\");\n let key = daemon_key(&daemon_cfg.name, config_path);\n let entry = ManagedDaemon {\n name: daemon_cfg.name.clone(),\n config_path: config_path.map(|path| path.to_path_buf()),\n restart: daemon::restart_policy_for(daemon_cfg),\n retry_remaining: daemon_cfg.retry,\n autostop: daemon_cfg.autostop,\n disabled,\n health_failures: 0,\n restart_attempts: 0,\n next_restart_at: None,\n };\n state.managed.insert(key, entry);\n Ok(())\n}\n\nfn disable_managed_daemon(\n state: &SharedState,\n name: &str,\n config_path: Option<&Path>,\n) -> Result<()> {\n let mut state = state.lock().expect(\"supervisor state lock\");\n let key = daemon_key(name, config_path);\n if let Some(entry) = state.managed.get_mut(&key) {\n entry.disabled = true;\n return Ok(());\n }\n\n if let Ok(cfg) = resolve_daemon_config(name, config_path) {\n let entry = ManagedDaemon {\n name: cfg.name.clone(),\n config_path: config_path.map(|path| path.to_path_buf()),\n restart: daemon::restart_policy_for(&cfg),\n retry_remaining: cfg.retry,\n autostop: cfg.autostop,\n disabled: true,\n health_failures: 0,\n restart_attempts: 0,\n next_restart_at: None,\n };\n state.managed.insert(key, entry);\n }\n Ok(())\n}\n\nfn daemon_key(name: &str, config_path: Option<&Path>) -> String {\n match config_path {\n Some(path) => format!(\"{}::{}\", name, path.display()),\n None => name.to_string(),\n }\n}\n\nfn print_status_views(daemons: &[DaemonStatusView], filter: Option<&str>) {\n if daemons.is_empty() {\n println!(\"No daemons configured.\");\n return;\n }\n\n let mut matched = false;\n println!(\"Daemon Status:\");\n println!();\n for daemon in daemons {\n if let Some(name) = filter {\n if daemon.name != name {\n continue;\n }\n }\n matched = true;\n let icon = if daemon.running {\n if daemon.healthy == Some(false) {\n \"WARN\"\n } else {\n \"OK\"\n }\n } else {\n \"NO\"\n };\n let state = if daemon.running { \"running\" } else { \"stopped\" };\n print!(\" {} {}: {}\", icon, daemon.name, state);\n if let Some(target) = &daemon.health_target {\n if daemon.running {\n if daemon.healthy == Some(false) {\n print!(\" (unhealthy: {})\", target);\n } else {\n print!(\" ({})\", target);\n }\n }\n }\n if let Some(pid) = daemon.pid {\n print!(\" [PID {}]\", pid);\n }\n println!();\n if let Some(desc) = &daemon.description {\n println!(\" {}\", desc);\n }\n }\n\n if let Some(name) = filter {\n if !matched {\n println!(\"Daemon '{}' not found.\", name);\n }\n }\n}\n\nfn print_list_views(daemons: &[DaemonStatusView]) {\n if daemons.is_empty() {\n println!(\"No daemons configured.\");\n return;\n }\n println!(\"Available daemons:\");\n for daemon in daemons {\n print!(\" {}\", daemon.name);\n if let Some(desc) = &daemon.description {\n print!(\" - {}\", desc);\n }\n println!();\n }\n}\n\n#[inline]\nfn trim_ascii_whitespace(bytes: &[u8]) -> &[u8] {\n let mut start = 0usize;\n let mut end = bytes.len();\n while start < end && bytes[start].is_ascii_whitespace() {\n start += 1;\n }\n while end > start && bytes[end - 1].is_ascii_whitespace() {\n end -= 1;\n }\n &bytes[start..end]\n}\n\npub fn send_request(socket_path: &Path, request: &IpcRequest) -> Result<IpcResponse> {\n #[cfg(unix)]\n {\n let mut stream = std::os::unix::net::UnixStream::connect(socket_path)?;\n let payload = serde_json::to_string(request)?;\n stream.write_all(payload.as_bytes())?;\n stream.write_all(b\"\\n\")?;\n stream.flush()?;\n\n let mut reader = BufReader::new(stream);\n let mut line = Vec::with_capacity(512);\n reader.read_until(b'\\n', &mut line)?;\n let trimmed = trim_ascii_whitespace(&line);\n let response: IpcResponse = serde_json::from_slice(trimmed)?;\n Ok(response)\n }\n #[cfg(not(unix))]\n {\n let _ = socket_path;\n let _ = request;\n bail!(\"Supervisor IPC is only supported on unix platforms right now.\");\n }\n}\n\nfn persist_supervisor_pid(pid: u32) -> Result<()> {\n let path = supervisor_pid_path()?;\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n fs::write(&path, pid.to_string())\n .with_context(|| format!(\"failed to write {}\", path.display()))?;\n Ok(())\n}\n\nfn load_supervisor_pid(path: &Path) -> Result<Option<u32>> {\n if !path.exists() {\n return Ok(None);\n }\n let contents = fs::read_to_string(path)?;\n let pid: u32 = contents.trim().parse().ok().unwrap_or(0);\n if pid == 0 { Ok(None) } else { Ok(Some(pid)) }\n}\n\nfn remove_supervisor_pid(path: &Path) -> Result<()> {\n if path.exists() {\n fs::remove_file(path).ok();\n }\n Ok(())\n}\n\nfn terminate_process(pid: u32) -> Result<()> {\n let status = Command::new(\"kill\").arg(\"-9\").arg(pid.to_string()).status();\n if let Ok(status) = status {\n if status.success() {\n return Ok(());\n }\n }\n bail!(\"failed to stop supervisor process {}\", pid)\n}\n" }, { "path": "src/sync.rs", "content": "//! Git sync command - comprehensive repo synchronization.\n//!\n//! Provides a single command to sync a git repository:\n//! - Pull from tracking/default remote (with rebase)\n//! - Sync upstream if configured (fetch, merge)\n//! - Push to configured git remote (default: origin)\n\nuse std::env;\nuse std::fs;\nuse std::io::Write;\nuse std::path::{Path, PathBuf};\nuse std::process::{Command, Stdio};\nuse std::time::Instant;\nuse std::{cell::RefCell, collections::HashMap, collections::HashSet};\n\nuse anyhow::{Context, Result, bail};\nuse chrono::Utc;\nuse crossterm::{\n event::{self, Event, KeyCode, KeyEventKind},\n terminal,\n};\nuse serde::{Deserialize, Serialize};\n\nuse crate::ai_context;\nuse crate::cli::{CheckoutCommand, SwitchCommand, SyncCommand};\nuse crate::commit;\nuse crate::config;\nuse crate::git_guard;\nuse crate::push;\nuse crate::secret_redact;\nuse crate::todo;\n\n#[derive(Serialize, Clone)]\nstruct SyncEvent {\n at: String,\n stage: String,\n message: String,\n}\n\n#[derive(Serialize)]\nstruct SyncSnapshot {\n timestamp: String,\n duration_ms: u128,\n repo_root: String,\n repo_name: String,\n branch_before: String,\n branch_after: String,\n head_before: String,\n head_after: String,\n upstream_before: Option<String>,\n upstream_after: Option<String>,\n origin_url: Option<String>,\n upstream_url: Option<String>,\n status_before: String,\n status_after: String,\n stashed: bool,\n rebase: bool,\n pushed: bool,\n success: bool,\n error: Option<String>,\n remote_updates: Vec<SyncRemoteUpdate>,\n events: Vec<SyncEvent>,\n}\n\n#[derive(Serialize, Clone)]\nstruct SyncRemoteUpdate {\n remote: String,\n branch: String,\n before_tip: Option<String>,\n after_tip: String,\n commit_count: usize,\n commits: Vec<String>,\n}\n\nstruct SyncRecorder {\n enabled: bool,\n started_at: Instant,\n repo_root: String,\n repo_name: String,\n branch_before: String,\n head_before: String,\n upstream_before: Option<String>,\n origin_url: Option<String>,\n upstream_url: Option<String>,\n status_before: String,\n events: Vec<SyncEvent>,\n stashed: bool,\n rebase: bool,\n pushed: bool,\n remote_updates: Vec<SyncRemoteUpdate>,\n}\n\n// Use the Claude family alias so sync always targets the latest Opus model.\nconst SYNC_CLAUDE_MODEL: &str = \"opus\";\n\nfn sync_should_push(cmd: &SyncCommand) -> bool {\n cmd.push && !cmd.no_push\n}\n\nfn sync_claude_command(prompt: &str) -> Command {\n let mut cmd = Command::new(\"claude\");\n cmd.args([\n \"--print\",\n \"--model\",\n SYNC_CLAUDE_MODEL,\n \"--dangerously-skip-permissions\",\n prompt,\n ]);\n cmd\n}\n\nimpl SyncRecorder {\n fn new(cmd: &SyncCommand) -> Result<Self> {\n let should_push = sync_should_push(cmd);\n let repo_root =\n git_capture(&[\"rev-parse\", \"--show-toplevel\"]).unwrap_or_else(|_| \".\".to_string());\n let repo_root = repo_root.trim().to_string();\n let repo_name = std::path::Path::new(&repo_root)\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(\"repo\")\n .to_string();\n let branch_before = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_default()\n .trim()\n .to_string();\n let head_before = git_capture(&[\"rev-parse\", \"HEAD\"])\n .unwrap_or_default()\n .trim()\n .to_string();\n let upstream_before = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"@{upstream}\"])\n .ok()\n .map(|s| s.trim().to_string());\n let origin_url = git_capture(&[\"remote\", \"get-url\", \"origin\"])\n .ok()\n .map(|s| s.trim().to_string());\n let upstream_url = git_capture(&[\"remote\", \"get-url\", \"upstream\"])\n .ok()\n .map(|s| s.trim().to_string());\n let status_before = git_capture(&[\"status\", \"--porcelain\"]).unwrap_or_default();\n\n let mut recorder = SyncRecorder {\n enabled: true,\n started_at: Instant::now(),\n repo_root,\n repo_name,\n branch_before,\n head_before,\n upstream_before,\n origin_url,\n upstream_url,\n status_before,\n events: Vec::new(),\n stashed: false,\n rebase: cmd.rebase,\n pushed: should_push,\n remote_updates: Vec::new(),\n };\n recorder.record(\n \"start\",\n format!(\n \"sync start (rebase={}, stash={}, push={})\",\n cmd.rebase, cmd.stash, should_push\n ),\n );\n Ok(recorder)\n }\n\n fn disabled() -> Self {\n SyncRecorder {\n enabled: false,\n started_at: Instant::now(),\n repo_root: String::new(),\n repo_name: String::new(),\n branch_before: String::new(),\n head_before: String::new(),\n upstream_before: None,\n origin_url: None,\n upstream_url: None,\n status_before: String::new(),\n events: Vec::new(),\n stashed: false,\n rebase: false,\n pushed: false,\n remote_updates: Vec::new(),\n }\n }\n\n fn record(&mut self, stage: &str, message: impl Into<String>) {\n if !self.enabled {\n return;\n }\n self.events.push(SyncEvent {\n at: Utc::now().to_rfc3339(),\n stage: stage.to_string(),\n message: message.into(),\n });\n }\n\n fn set_stashed(&mut self, stashed: bool) {\n self.stashed = stashed;\n }\n\n fn add_remote_update(&mut self, update: SyncRemoteUpdate) {\n if !self.enabled {\n return;\n }\n if let Some(existing) = self\n .remote_updates\n .iter_mut()\n .find(|item| item.remote == update.remote && item.branch == update.branch)\n {\n *existing = update;\n } else {\n self.remote_updates.push(update);\n }\n }\n\n fn finish(&mut self, error: Option<&anyhow::Error>) {\n if !self.enabled {\n return;\n }\n\n let branch_after = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_default()\n .trim()\n .to_string();\n let head_after = git_capture(&[\"rev-parse\", \"HEAD\"])\n .unwrap_or_default()\n .trim()\n .to_string();\n let upstream_after = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"@{upstream}\"])\n .ok()\n .map(|s| s.trim().to_string());\n let status_after = git_capture(&[\"status\", \"--porcelain\"]).unwrap_or_default();\n\n let snapshot = SyncSnapshot {\n timestamp: Utc::now().to_rfc3339(),\n duration_ms: self.started_at.elapsed().as_millis(),\n repo_root: self.repo_root.clone(),\n repo_name: self.repo_name.clone(),\n branch_before: self.branch_before.clone(),\n branch_after,\n head_before: self.head_before.clone(),\n head_after,\n upstream_before: self.upstream_before.clone(),\n upstream_after,\n origin_url: self.origin_url.clone(),\n upstream_url: self.upstream_url.clone(),\n status_before: self.status_before.clone(),\n status_after,\n stashed: self.stashed,\n rebase: self.rebase,\n pushed: self.pushed,\n success: error.is_none(),\n error: error.map(|e| e.to_string()),\n remote_updates: self.remote_updates.clone(),\n events: self.events.clone(),\n };\n\n if let Err(err) = write_sync_snapshot(&snapshot) {\n eprintln!(\"warn: failed to write sync snapshot: {err}\");\n }\n }\n}\n\n/// Check the review-todo push gate. Returns `true` if push should proceed.\n/// Only P1+P2 items trigger the gate; P3/P4 are non-blocking.\n/// Reads `[commit].review-push-gate` from config: \"warn\" (default) | \"block\" | \"off\".\n/// `--allow-review-issues` overrides any mode.\n/// Fails open if todos can't be loaded.\nfn check_review_todo_push_gate(\n repo_root: &Path,\n allow_review_issues: bool,\n recorder: &mut SyncRecorder,\n) -> bool {\n if allow_review_issues {\n return true;\n }\n\n let (p1, p2, _p3, _p4, _total) = match todo::count_open_review_todos_by_priority(repo_root) {\n Ok(counts) => counts,\n Err(_) => return true, // fail open\n };\n\n let blocking = p1 + p2;\n if blocking == 0 {\n return true;\n }\n\n // Read gate mode from config\n let config_path = repo_root.join(\"flow.toml\");\n let gate_mode = if config_path.exists() {\n config::load(&config_path)\n .ok()\n .and_then(|cfg| cfg.commit)\n .and_then(|c| c.review_push_gate)\n .unwrap_or_else(|| \"warn\".to_string())\n } else {\n \"warn\".to_string()\n };\n\n match gate_mode.as_str() {\n \"off\" => true,\n \"block\" => {\n eprintln!(\n \"✗ Push blocked: {} open review todos (P1:{}, P2:{})\",\n blocking, p1, p2\n );\n eprintln!(\n \" Resolve with `f reviews-todo list` or use --allow-review-issues to override.\"\n );\n recorder.record(\"review-gate\", format!(\"blocked (P1:{}, P2:{})\", p1, p2));\n false\n }\n _ => {\n // \"warn\" (default)\n eprintln!(\n \"⚠ {} open review todos (P1:{}, P2:{}) — consider reviewing before push\",\n blocking, p1, p2\n );\n eprintln!(\" Run `f reviews-todo list` to see details.\");\n recorder.record(\"review-gate\", format!(\"warned (P1:{}, P2:{})\", p1, p2));\n true\n }\n }\n}\n\n/// Run the sync command.\npub fn run(cmd: SyncCommand) -> Result<()> {\n let _git_capture_cache_scope = GitCaptureCacheScope::begin();\n\n // Check we're in a git repo\n if git_capture(&[\"rev-parse\", \"--git-dir\"]).is_err() {\n bail!(\"Not a git repository\");\n }\n\n let mut recorder = SyncRecorder::new(&cmd).unwrap_or_else(|err| {\n eprintln!(\"warn: unable to init sync recorder: {err}\");\n SyncRecorder::disabled()\n });\n\n let result = (|| -> Result<()> {\n // Determine if auto-fix is enabled (--fix is default, --no-fix disables)\n let auto_fix = cmd.fix && !cmd.no_fix;\n let should_push = sync_should_push(&cmd);\n let repo_root = git_capture(&[\"rev-parse\", \"--show-toplevel\"])\n .unwrap_or_else(|_| \".\".to_string())\n .trim()\n .to_string();\n let repo_root_path = Path::new(&repo_root);\n let preferred_remote = config::preferred_git_remote_for_repo(repo_root_path);\n let mut use_jj = should_use_jj(repo_root_path);\n let mut jj_disabled_by_custom_tracking = false;\n if use_jj && preferred_remote != \"origin\" && preferred_remote != \"upstream\" {\n println!(\n \"⚠️ Configured git.remote '{}' detected; using git sync flow.\",\n preferred_remote\n );\n recorder.record(\n \"mode\",\n format!(\"jj bypassed (configured git.remote {})\", preferred_remote),\n );\n use_jj = false;\n }\n if use_jj {\n if let Ok(branch) =\n git_capture_in(repo_root_path, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n {\n let branch = branch.trim();\n if branch != \"HEAD\" {\n if let Some((remote, _)) =\n resolve_tracking_remote_branch_in(repo_root_path, Some(branch))\n {\n if remote != \"origin\" && remote != \"upstream\" {\n println!(\n \"⚠️ Tracking remote '{}' detected; using git sync flow for reliable branch + upstream sync.\",\n remote\n );\n recorder.record(\n \"mode\",\n format!(\"jj bypassed (custom tracking remote {})\", remote),\n );\n use_jj = false;\n jj_disabled_by_custom_tracking = true;\n }\n }\n }\n }\n }\n if repo_root_path.join(\".jj\").exists() && !use_jj && !jj_disabled_by_custom_tracking {\n println!(\"⚠️ jj workspace appears unhealthy; falling back to git sync flow.\");\n println!(\n \" Fix: `jj git import` (or if still broken: `rm -rf .jj && jj git init --colocate`)\"\n );\n recorder.record(\"mode\", \"jj unavailable/unhealthy; fallback to git\");\n }\n let current_branch_for_queue = resolve_sync_branch_for_queue_guard(repo_root_path);\n let queue_present = match current_branch_for_queue.as_deref() {\n Some(branch) => commit::commit_queue_has_entries_on_branch(repo_root_path, branch),\n None => commit::commit_queue_has_entries_reachable_from_head(repo_root_path),\n };\n if queue_present && !cmd.allow_queue && (cmd.rebase || use_jj) {\n recorder.record(\"queue\", \"blocked (commit queue present)\");\n bail!(\n \"Commit queue is not empty. Rebase-based sync can rewrite commit SHAs.\\n\\\nUse `f commit-queue list` to review, or re-run with `--allow-queue`.\"\n );\n }\n\n if use_jj {\n recorder.record(\"mode\", \"using jj sync flow\");\n match run_jj_sync(repo_root_path, &cmd, auto_fix, &mut recorder) {\n Ok(()) => return Ok(()),\n Err(err) if is_jj_corruption_error(&err) => {\n println!(\"⚠️ jj sync failed due workspace/store issues; retrying with git.\");\n println!(\n \" Fix: `jj git import` (or if still broken: `rm -rf .jj && jj git init --colocate`)\"\n );\n recorder.record(\"mode\", \"jj failed (corruption); fallback to git\");\n }\n Err(err) => return Err(err),\n }\n }\n\n // Check for unmerged files (can exist even without active merge/rebase)\n let unmerged = git_capture(&[\"diff\", \"--name-only\", \"--diff-filter=U\"]).unwrap_or_default();\n if !unmerged.trim().is_empty() {\n let unmerged_files: Vec<&str> = unmerged.lines().filter(|l| !l.is_empty()).collect();\n println!(\n \"==> Found {} unmerged files, resolving...\",\n unmerged_files.len()\n );\n recorder.record(\n \"unmerged\",\n format!(\"found {} unmerged files\", unmerged_files.len()),\n );\n\n let should_fix = auto_fix || prompt_for_auto_fix()?;\n if should_fix {\n if try_resolve_conflicts()? {\n let _ = git_run(&[\"add\", \"-A\"]);\n // Check if we're in a merge\n if is_merge_in_progress() {\n let _ = Command::new(\"git\").args([\"commit\", \"--no-edit\"]).output();\n }\n println!(\" ✓ Unmerged files resolved\");\n } else {\n // Couldn't resolve - reset the conflicted files to HEAD\n println!(\" Could not auto-resolve. Resetting unmerged files...\");\n for file in &unmerged_files {\n let _ = Command::new(\"git\")\n .args([\"checkout\", \"HEAD\", \"--\", file])\n .output();\n }\n if is_merge_in_progress() {\n let _ = Command::new(\"git\").args([\"merge\", \"--abort\"]).output();\n }\n }\n } else {\n // User declined - reset the files\n println!(\" Resetting unmerged files...\");\n for file in &unmerged_files {\n let _ = Command::new(\"git\")\n .args([\"checkout\", \"HEAD\", \"--\", file])\n .output();\n }\n if is_merge_in_progress() {\n let _ = Command::new(\"git\").args([\"merge\", \"--abort\"]).output();\n }\n }\n }\n\n // Check for in-progress rebase/merge and handle it\n if is_rebase_in_progress() {\n println!(\"==> Rebase in progress, attempting to resolve...\");\n let should_fix = auto_fix || prompt_for_rebase_action()?;\n if should_fix {\n if try_resolve_rebase_conflicts()? {\n println!(\" ✓ Rebase completed\");\n } else {\n println!(\" Could not auto-resolve. Aborting rebase...\");\n let _ = Command::new(\"git\").args([\"rebase\", \"--abort\"]).output();\n }\n } else {\n println!(\" Aborting rebase...\");\n let _ = Command::new(\"git\").args([\"rebase\", \"--abort\"]).output();\n }\n }\n\n // Check for in-progress merge\n if is_merge_in_progress() {\n println!(\"==> Merge in progress, attempting to resolve...\");\n let should_fix = auto_fix || prompt_for_auto_fix()?;\n if should_fix {\n if try_resolve_conflicts()? {\n let _ = git_run(&[\"add\", \"-A\"]);\n let _ = Command::new(\"git\").args([\"commit\", \"--no-edit\"]).output();\n println!(\" ✓ Merge completed\");\n } else {\n println!(\" Could not auto-resolve. Aborting merge...\");\n let _ = Command::new(\"git\").args([\"merge\", \"--abort\"]).output();\n }\n } else {\n println!(\" Aborting merge...\");\n let _ = Command::new(\"git\").args([\"merge\", \"--abort\"]).output();\n }\n }\n\n let current = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])?;\n let current = current.trim();\n\n // Check for uncommitted changes\n let status = git_capture(&[\"status\", \"--porcelain\"])?;\n let has_changes = !status.trim().is_empty();\n\n if has_changes && !cmd.stash {\n println!(\"You have uncommitted changes. Use --stash to auto-stash them.\");\n recorder.record(\"stash\", \"skipped (uncommitted changes without --stash)\");\n bail!(\"Uncommitted changes\");\n }\n\n // Stash if needed\n let mut stashed = false;\n if has_changes && cmd.stash {\n println!(\"==> Stashing local changes...\");\n let stash_count_before = git_capture(&[\"stash\", \"list\"])\n .map(|s| s.lines().count())\n .unwrap_or(0);\n\n if let Err(err) = git_run(&[\"stash\", \"push\", \"-u\", \"-m\", \"f sync auto-stash\"]) {\n recorder.record(\"stash\", format!(\"stash failed: {}\", err));\n bail!(\n \"Failed to stash local changes: {}. Resolve the issue and re-run sync.\",\n err\n );\n }\n\n let stash_count_after = git_capture(&[\"stash\", \"list\"])\n .map(|s| s.lines().count())\n .unwrap_or(0);\n stashed = stash_count_after > stash_count_before;\n }\n recorder.set_stashed(stashed);\n if has_changes && cmd.stash {\n recorder.record(\"stash\", format!(\"stashed={}\", stashed));\n }\n\n // Resolve remotes for sync.\n let push_remote = preferred_remote.clone();\n let has_push_remote = git_capture(&[\"remote\", \"get-url\", &push_remote]).is_ok();\n\n // Keep explicit origin/upstream detection for fork-sync heuristics.\n let has_origin = git_capture(&[\"remote\", \"get-url\", \"origin\"]).is_ok();\n let has_upstream = git_capture(&[\"remote\", \"get-url\", \"upstream\"]).is_ok();\n\n // Check if remotes are reachable (repo exists on remote)\n let push_remote_reachable = has_push_remote\n && git_capture(&[\"ls-remote\", \"--exit-code\", \"-q\", &push_remote]).is_ok();\n let origin_reachable =\n has_origin && git_capture(&[\"ls-remote\", \"--exit-code\", \"-q\", \"origin\"]).is_ok();\n\n // Step 1: Pull from tracking branch.\n let mut tracking = resolve_tracking_remote_branch_in(repo_root_path, Some(current));\n if current != \"HEAD\" && has_push_remote {\n let should_retarget = tracking\n .as_ref()\n .map(|(remote, _)| remote != &push_remote)\n .unwrap_or(true);\n if should_retarget && remote_branch_exists(repo_root_path, &push_remote, current) {\n let branch_remote_key = format!(\"branch.{}.remote\", current);\n let branch_merge_key = format!(\"branch.{}.merge\", current);\n let merge_ref = format!(\"refs/heads/{}\", current);\n let _ = git_run_in(\n repo_root_path,\n &[\"config\", \"--local\", &branch_remote_key, &push_remote],\n );\n let _ = git_run_in(\n repo_root_path,\n &[\"config\", \"--local\", &branch_merge_key, &merge_ref],\n );\n tracking = Some((push_remote.clone(), current.to_string()));\n }\n }\n\n if let Some((tracking_remote, tracking_branch)) = tracking {\n let tracking_reachable = git_capture_in(\n repo_root_path,\n &[\"ls-remote\", \"--exit-code\", \"-q\", &tracking_remote],\n )\n .is_ok();\n if tracking_reachable {\n println!(\n \"==> Pulling from {}/{}...\",\n tracking_remote, tracking_branch\n );\n recorder.record(\n \"pull\",\n format!(\n \"pulling from {}/{} (rebase={})\",\n tracking_remote, tracking_branch, cmd.rebase\n ),\n );\n if cmd.rebase {\n let pull = Command::new(\"git\")\n .current_dir(repo_root_path)\n .args([\n \"pull\",\n \"--rebase\",\n tracking_remote.as_str(),\n tracking_branch.as_str(),\n ])\n .output()\n .context(\"failed to run git pull --rebase\")?;\n if !pull.status.success() {\n let pull_stdout = String::from_utf8_lossy(&pull.stdout);\n let pull_stderr = String::from_utf8_lossy(&pull.stderr);\n let pull_text = format!(\"{}\\n{}\", pull_stdout, pull_stderr).to_lowercase();\n if pull_text.contains(\"cannot rebase: you have unstaged changes\")\n || pull_text\n .contains(\"cannot pull with rebase: you have unstaged changes\")\n {\n let _ = Command::new(\"git\")\n .current_dir(repo_root_path)\n .args([\"rebase\", \"--abort\"])\n .output();\n restore_stash(repo_root_path, stashed);\n recorder.record(\"pull\", \"blocked by unstaged changes\");\n bail!(\n \"git pull --rebase refused due unstaged changes. \\\nClean local file conflicts/case-only path conflicts, then re-run `f sync`.\"\n );\n }\n // Check if we're in a rebase conflict\n if is_rebase_in_progress() {\n let should_fix = auto_fix || prompt_for_auto_fix()?;\n if should_fix {\n if try_resolve_rebase_conflicts()? {\n println!(\" ✓ Rebase conflicts auto-resolved\");\n recorder.record(\"pull\", \"rebase conflicts auto-resolved\");\n } else {\n restore_stash(repo_root_path, stashed);\n recorder.record(\"pull\", \"rebase conflicts unresolved\");\n bail!(\n \"Rebase conflicts. Resolve manually:\\n git status\\n # fix conflicts\\n git add . && git rebase --continue\"\n );\n }\n } else {\n restore_stash(repo_root_path, stashed);\n recorder.record(\"pull\", \"rebase conflicts unresolved\");\n bail!(\n \"Rebase conflicts. Resolve manually:\\n git status\\n # fix conflicts\\n git add . && git rebase --continue\"\n );\n }\n } else {\n restore_stash(repo_root_path, stashed);\n recorder.record(\"pull\", \"git pull --rebase failed\");\n bail!(\"git pull --rebase failed\");\n }\n }\n } else {\n if let Err(_) = git_run_in(\n repo_root_path,\n &[\n \"pull\",\n \"--no-rebase\",\n \"--no-edit\",\n tracking_remote.as_str(),\n tracking_branch.as_str(),\n ],\n ) {\n // Check for merge conflicts\n let conflicts = git_capture(&[\"diff\", \"--name-only\", \"--diff-filter=U\"])\n .unwrap_or_default();\n if !conflicts.trim().is_empty() {\n let should_fix = auto_fix || prompt_for_auto_fix()?;\n if should_fix {\n if try_resolve_conflicts()? {\n let _ = git_run(&[\"add\", \"-A\"]);\n let _ =\n Command::new(\"git\").args([\"commit\", \"--no-edit\"]).output();\n println!(\" ✓ Merge conflicts auto-resolved\");\n recorder.record(\"pull\", \"merge conflicts auto-resolved\");\n } else {\n restore_stash(repo_root_path, stashed);\n recorder.record(\"pull\", \"merge conflicts unresolved\");\n bail!(\n \"Merge conflicts. Resolve manually:\\n git status\\n # fix conflicts\\n git add . && git commit\"\n );\n }\n } else {\n restore_stash(repo_root_path, stashed);\n recorder.record(\"pull\", \"merge conflicts unresolved\");\n bail!(\n \"Merge conflicts. Resolve manually:\\n git status\\n # fix conflicts\\n git add . && git commit\"\n );\n }\n } else {\n restore_stash(repo_root_path, stashed);\n recorder.record(\"pull\", \"git pull failed\");\n bail!(\"git pull failed\");\n }\n }\n }\n recorder.record(\"pull\", \"pull complete\");\n } else {\n println!(\n \"==> Tracking remote '{}' unreachable, skipping pull\",\n tracking_remote\n );\n recorder.record(\n \"pull\",\n format!(\"skipped (tracking remote unreachable: {})\", tracking_remote),\n );\n }\n } else {\n println!(\"==> No tracking branch, skipping pull\");\n recorder.record(\"pull\", \"skipped (no tracking branch)\");\n }\n\n // Step 2: Sync upstream if it exists. If no upstream remote is configured and we're on\n // a feature branch, fall back to syncing from origin's default branch.\n if has_upstream {\n println!(\"==> Syncing upstream...\");\n recorder.record(\"upstream\", \"syncing upstream\");\n if let Err(e) = sync_upstream_internal(repo_root_path, current, auto_fix, &mut recorder)\n {\n restore_stash(repo_root_path, stashed);\n return Err(e);\n }\n } else if has_origin && origin_reachable {\n if let Some(default_branch) =\n origin_default_branch_for_feature_sync(repo_root_path, current)\n {\n println!(\"==> Syncing origin/{} into {}...\", default_branch, current);\n recorder.record(\n \"upstream\",\n format!(\"syncing origin/{} into {}\", default_branch, current),\n );\n if let Err(e) = sync_origin_default_internal(\n repo_root_path,\n current,\n &default_branch,\n auto_fix,\n &mut recorder,\n ) {\n restore_stash(repo_root_path, stashed);\n return Err(e);\n }\n } else {\n recorder.record(\"upstream\", \"skipped (no upstream remote)\");\n }\n } else {\n recorder.record(\"upstream\", \"skipped (no upstream remote)\");\n }\n\n // Step 3: Push to configured remote (defaults to origin).\n // Fork push override: redirect to private fork remote if configured.\n let (mut push_remote, mut has_push_remote, mut push_remote_reachable) =\n (push_remote, has_push_remote, push_remote_reachable);\n if should_push {\n if let Some((fork_remote, fork_owner, fork_repo)) =\n resolve_fork_push_target(repo_root_path)\n {\n let target_url = push::build_github_ssh_url(&fork_owner, &fork_repo);\n if let Err(e) = push::ensure_remote_points_to_target(\n repo_root_path,\n &fork_remote,\n &target_url,\n None,\n true,\n ) {\n eprintln!(\"Warning: could not set up fork remote: {}\", e);\n } else {\n push::ensure_github_repo_exists(&fork_owner, &fork_repo).ok();\n println!(\n \"==> Fork push enabled: {}/{} (remote: {})\",\n fork_owner, fork_repo, fork_remote\n );\n push_remote = fork_remote;\n has_push_remote = true;\n push_remote_reachable = true;\n }\n }\n }\n\n // Review-todo push gate (git sync path)\n if should_push\n && !check_review_todo_push_gate(repo_root_path, cmd.allow_review_issues, &mut recorder)\n {\n recorder.record(\"push\", \"blocked by review-todo gate\");\n bail!(\"Push blocked by open review todos. Use --allow-review-issues to override.\");\n }\n\n if has_push_remote && should_push {\n // Check if push remote == upstream (read-only clone, no fork)\n let push_remote_url =\n git_capture(&[\"remote\", \"get-url\", &push_remote]).unwrap_or_default();\n let upstream_url = git_capture(&[\"remote\", \"get-url\", \"upstream\"]).unwrap_or_default();\n let is_read_only = has_upstream\n && normalize_git_url(&push_remote_url) == normalize_git_url(&upstream_url);\n\n if is_read_only {\n println!(\n \"==> Skipping push (remote '{}' == upstream, read-only clone)\",\n push_remote\n );\n println!(\" To push, create a fork first: gh repo fork --remote\");\n recorder.record(\"push\", \"skipped (push remote == upstream)\");\n } else if !push_remote_reachable {\n // Remote repo doesn't exist or is unreachable.\n if cmd.create_repo && push_remote == \"origin\" {\n println!(\"==> Creating origin repo...\");\n if try_create_origin_repo()? {\n println!(\"==> Pushing to {}...\", push_remote);\n git_run(&[\"push\", \"-u\", &push_remote, current])?;\n recorder.record(\n \"push\",\n format!(\"created repo and pushed to {}\", push_remote),\n );\n } else {\n println!(\" Could not create repo, skipping push\");\n recorder.record(\"push\", \"skipped (create repo failed)\");\n }\n } else {\n println!(\"==> Remote '{}' unreachable, skipping push\", push_remote);\n println!(\" The remote may be missing, private, or auth/network failed.\");\n if push_remote == \"origin\" {\n println!(\" Use --create-repo if origin does not exist yet.\");\n } else {\n println!(\n \" Create/fix remote '{}' and re-run sync (or set [git].remote).\",\n push_remote\n );\n }\n recorder.record(\n \"push\",\n format!(\"skipped (remote unreachable: {})\", push_remote),\n );\n }\n } else {\n println!(\"==> Pushing to {}...\", push_remote);\n let push_result =\n push_with_autofix(current, &push_remote, auto_fix, cmd.max_fix_attempts);\n if let Err(e) = push_result {\n restore_stash(repo_root_path, stashed);\n recorder.record(\"push\", \"push failed\");\n return Err(e);\n }\n recorder.record(\"push\", \"push complete\");\n }\n } else if cmd.no_push {\n recorder.record(\"push\", \"skipped (--no-push)\");\n } else if has_push_remote {\n recorder.record(\"push\", \"skipped (default; use --push)\");\n } else {\n recorder.record(\"push\", format!(\"skipped (missing remote: {})\", push_remote));\n }\n\n // Restore stash\n restore_stash(repo_root_path, stashed);\n if stashed {\n recorder.record(\"stash\", \"stash restored\");\n }\n\n // Explain new commits if configured\n let head_after_sha = git_capture(&[\"rev-parse\", \"HEAD\"])\n .unwrap_or_default()\n .trim()\n .to_string();\n if recorder.head_before != head_after_sha {\n if let Err(e) =\n crate::explain_commits::maybe_run_after_sync(repo_root_path, &recorder.head_before)\n {\n eprintln!(\"warn: commit explanation failed: {e}\");\n }\n }\n\n println!(\"\\n✓ Sync complete!\");\n recorder.record(\"complete\", \"sync complete\");\n\n Ok(())\n })();\n\n if result.is_ok() {\n let synced_commits = build_synced_commit_list(&recorder);\n if !synced_commits.is_empty() {\n println!(\"\\n==> Synced commits:\");\n for line in &synced_commits {\n println!(\" {}\", line);\n }\n let payload = synced_commits.join(\"\\n\");\n match copy_sync_output_to_clipboard(&payload) {\n Ok(true) => println!(\"Copied synced commit list to clipboard.\"),\n Ok(false) => {}\n Err(err) => {\n eprintln!(\"warn: failed to copy synced commit list to clipboard: {err}\")\n }\n }\n }\n }\n\n recorder.finish(result.as_ref().err());\n result\n}\n\n/// Switch to a branch and align upstream/jj state for flow workflows.\npub fn run_switch(cmd: SwitchCommand) -> Result<()> {\n let _git_capture_cache_scope = GitCaptureCacheScope::begin();\n\n if git_capture(&[\"rev-parse\", \"--git-dir\"]).is_err() {\n bail!(\"Not a git repository\");\n }\n\n let target_input = cmd.branch.trim();\n if target_input.is_empty() {\n bail!(\"Branch name cannot be empty\");\n }\n\n let repo_root = git_capture(&[\"rev-parse\", \"--show-toplevel\"])?\n .trim()\n .to_string();\n let repo_root_path = PathBuf::from(repo_root);\n let resolution = resolve_switch_target(&repo_root_path, target_input)?;\n let target_branch = resolution.branch;\n git_guard::ensure_clean_for_push(&repo_root_path)?;\n\n let stash_enabled = cmd.stash && !cmd.no_stash;\n let has_changes = !git_capture_in(&repo_root_path, &[\"status\", \"--porcelain\"])?\n .trim()\n .is_empty();\n let current_branch = git_capture_in(&repo_root_path, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string())\n .trim()\n .to_string();\n let mut stashed = false;\n\n let preserve_enabled = cmd.preserve && !cmd.no_preserve;\n if preserve_enabled && current_branch != \"HEAD\" && current_branch != target_branch {\n let preserve_reason = switch_preserve_reason(\n &repo_root_path,\n ¤t_branch,\n &target_branch,\n has_changes,\n );\n if let Some(reason) = preserve_reason {\n let snapshot_name = create_switch_safety_snapshot(&repo_root_path, ¤t_branch);\n match snapshot_name {\n Some(snapshot) => {\n println!(\n \"==> Preserved branch '{}' as '{}' ({})\",\n current_branch, snapshot, reason\n );\n }\n None => {\n eprintln!(\n \"warning: failed to create safety snapshot for '{}'; continuing switch\",\n current_branch\n );\n }\n }\n }\n }\n\n if stash_enabled && has_changes {\n let message = format!(\n \"flow-switch-{}-{}\",\n target_branch,\n Utc::now().format(\"%Y%m%d-%H%M%S\")\n );\n println!(\"==> Stashing local changes...\");\n if let Err(err) = git_run_in(&repo_root_path, &[\"stash\", \"push\", \"-u\", \"-m\", &message]) {\n eprintln!(\n \"warning: auto-stash failed, continuing without stash: {}\",\n err\n );\n } else {\n stashed = true;\n }\n }\n\n let mut switched_branch = target_branch.clone();\n let switch_result = (|| -> Result<()> {\n let tracking = resolve_tracking_remote_and_fetch(\n &repo_root_path,\n &switched_branch,\n cmd.remote.as_deref(),\n )?;\n\n if git_ref_exists_in(&repo_root_path, &format!(\"refs/heads/{}\", switched_branch)) {\n println!(\"==> Switching to local branch {}...\", switched_branch);\n git_run_in(&repo_root_path, &[\"switch\", &switched_branch])?;\n } else if let Some(remote) = tracking.remote.as_deref() {\n println!(\n \"==> Creating {} from {}/{}...\",\n switched_branch, remote, switched_branch\n );\n let remote_branch = format!(\"{}/{}\", remote, switched_branch);\n git_run_in(\n &repo_root_path,\n &[\"switch\", \"-c\", &switched_branch, \"--track\", &remote_branch],\n )?;\n } else if let Some(pr_target) = resolution.pr.as_ref() {\n println!(\n \"==> Branch '{}' not found on remotes; checking out {} via gh...\",\n switched_branch, pr_target.display\n );\n ensure_gh_available()?;\n let gh_args =\n build_gh_pr_checkout_args(&pr_target.checkout_target, cmd.remote.as_deref());\n run_gh_in(&repo_root_path, &gh_args)?;\n let checked_out =\n git_capture_in(&repo_root_path, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string())\n .trim()\n .to_string();\n if checked_out.is_empty() || checked_out == \"HEAD\" {\n bail!(\n \"checked out {}, but git is detached; please run `gh pr checkout {}` manually\",\n pr_target.display,\n pr_target.checkout_target\n );\n }\n switched_branch = checked_out;\n } else {\n let searched = if tracking.searched.is_empty() {\n cmd.remote\n .as_deref()\n .unwrap_or(\"upstream/origin\")\n .to_string()\n } else {\n tracking.searched.join(\"/\")\n };\n bail!(\n \"Branch '{}' not found locally or on remotes (searched: {}).\",\n switched_branch,\n searched\n );\n }\n\n if remote_branch_exists(&repo_root_path, \"upstream\", &switched_branch) {\n println!(\n \"==> Updating flow upstream tracking to upstream/{}...\",\n switched_branch\n );\n git_run_in(\n &repo_root_path,\n &[\"config\", \"branch.upstream.remote\", \"upstream\"],\n )?;\n let merge_ref = format!(\"refs/heads/{}\", switched_branch);\n git_run_in(\n &repo_root_path,\n &[\"config\", \"branch.upstream.merge\", &merge_ref],\n )?;\n sync_local_upstream_branch(&repo_root_path, &switched_branch)?;\n }\n\n if should_use_jj(&repo_root_path) {\n println!(\"==> Importing git refs into jj...\");\n jj_run_in(&repo_root_path, &[\"--quiet\", \"git\", \"import\"])?;\n }\n\n Ok(())\n })();\n\n if let Err(err) = switch_result {\n if stashed {\n eprintln!(\"==> Restoring stashed changes after failed switch...\");\n let _ = git_run_in(&repo_root_path, &[\"stash\", \"pop\"]);\n }\n return Err(err);\n }\n\n if stashed {\n println!(\"==> Restoring stashed changes...\");\n if let Err(err) = git_run_in(&repo_root_path, &[\"stash\", \"pop\"]) {\n eprintln!(\n \"warning: failed to restore stash automatically: {}\\nRun `git stash list` and restore manually if needed.\",\n err\n );\n }\n }\n\n println!(\"✓ Switched to {}\", switched_branch);\n\n if cmd.sync {\n println!(\"==> Running sync (default no push)...\");\n if let Err(sync_err) = run(SyncCommand {\n rebase: false,\n push: false,\n no_push: true,\n stash: true,\n stash_commits: false,\n allow_queue: false,\n create_repo: false,\n fix: true,\n no_fix: false,\n max_fix_attempts: 3,\n allow_review_issues: false,\n compact: false,\n }) {\n let _ = ensure_branch_attached(&repo_root_path, &switched_branch);\n return Err(sync_err);\n }\n ensure_branch_attached(&repo_root_path, &switched_branch)?;\n }\n\n Ok(())\n}\n\n#[derive(Debug, Clone)]\nstruct SwitchPrTarget {\n checkout_target: String,\n display: String,\n}\n\n#[derive(Debug, Clone)]\nstruct SwitchTargetResolution {\n branch: String,\n pr: Option<SwitchPrTarget>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct SwitchPrView {\n #[serde(rename = \"headRefName\")]\n head_ref_name: String,\n}\n\nfn resolve_switch_target(repo_root: &Path, target: &str) -> Result<SwitchTargetResolution> {\n let trimmed = target.trim();\n if let Some((repo, number)) = parse_github_pr_url(trimmed) {\n ensure_gh_available()?;\n let branch = resolve_pr_head_branch(repo_root, &number, Some(&repo))?;\n println!(\"==> Resolved PR {repo}#{number} to branch {branch}\");\n return Ok(SwitchTargetResolution {\n branch,\n pr: Some(SwitchPrTarget {\n checkout_target: number.clone(),\n display: format!(\"{repo}#{number}\"),\n }),\n });\n }\n\n let pr_number = if let Some(stripped) = trimmed.strip_prefix('#') {\n stripped.trim()\n } else {\n trimmed\n };\n if !pr_number.is_empty() && pr_number.chars().all(|c| c.is_ascii_digit()) {\n ensure_gh_available()?;\n let branch = resolve_pr_head_branch(repo_root, pr_number, None)?;\n println!(\"==> Resolved PR #{pr_number} to branch {branch}\");\n return Ok(SwitchTargetResolution {\n branch,\n pr: Some(SwitchPrTarget {\n checkout_target: pr_number.to_string(),\n display: format!(\"#{pr_number}\"),\n }),\n });\n }\n\n Ok(SwitchTargetResolution {\n branch: trimmed.to_string(),\n pr: None,\n })\n}\n\nfn resolve_pr_head_branch(repo_root: &Path, number: &str, repo: Option<&str>) -> Result<String> {\n let mut args: Vec<String> = vec![\n \"pr\".to_string(),\n \"view\".to_string(),\n number.to_string(),\n \"--json\".to_string(),\n \"headRefName\".to_string(),\n ];\n if let Some(repo) = repo.map(str::trim).filter(|s| !s.is_empty()) {\n args.push(\"--repo\".to_string());\n args.push(repo.to_string());\n }\n\n let ref_args: Vec<&str> = args.iter().map(String::as_str).collect();\n let out = gh_capture_in(repo_root, &ref_args)?;\n let parsed: SwitchPrView = serde_json::from_str(out.trim())\n .with_context(|| format!(\"failed to parse gh pr view JSON for #{number}\"))?;\n let branch = parsed.head_ref_name.trim();\n if branch.is_empty() {\n bail!(\"PR #{} returned empty head branch\", number);\n }\n Ok(branch.to_string())\n}\n\n/// Checkout a GitHub PR safely while preserving local changes.\npub fn run_checkout(cmd: CheckoutCommand) -> Result<()> {\n let _git_capture_cache_scope = GitCaptureCacheScope::begin();\n\n if git_capture(&[\"rev-parse\", \"--git-dir\"]).is_err() {\n bail!(\"Not a git repository\");\n }\n\n let target = cmd.target.trim();\n if target.is_empty() {\n bail!(\"Checkout target cannot be empty\");\n }\n\n let repo_root = git_capture(&[\"rev-parse\", \"--show-toplevel\"])?\n .trim()\n .to_string();\n let repo_root_path = PathBuf::from(repo_root);\n let stash_enabled = cmd.stash && !cmd.no_stash;\n let has_changes = !git_capture_in(&repo_root_path, &[\"status\", \"--porcelain\"])?\n .trim()\n .is_empty();\n let mut stashed = false;\n\n if stash_enabled && has_changes {\n let message = format!(\n \"flow-checkout-{}-{}\",\n sanitize_checkout_label(target),\n Utc::now().format(\"%Y%m%d-%H%M%S\")\n );\n println!(\"==> Stashing local changes...\");\n if let Err(err) = git_run_in(&repo_root_path, &[\"stash\", \"push\", \"-u\", \"-m\", &message]) {\n eprintln!(\n \"warning: auto-stash failed, continuing without stash: {}\",\n err\n );\n } else {\n stashed = true;\n }\n } else if has_changes && !stash_enabled {\n println!(\"==> Continuing with local changes (auto-stash disabled)...\");\n }\n\n let checkout_result = (|| -> Result<()> {\n ensure_gh_available()?;\n let gh_args = build_gh_pr_checkout_args(target, cmd.remote.as_deref());\n println!(\"==> Running: gh {}\", gh_args.join(\" \"));\n run_gh_in(&repo_root_path, &gh_args)?;\n\n if should_use_jj(&repo_root_path) {\n println!(\"==> Importing git refs into jj...\");\n if let Err(err) = jj_run_preferred_in(&repo_root_path, &[\"--quiet\", \"git\", \"import\"]) {\n eprintln!(\n \"warning: jj import failed after checkout: {}\\nGit checkout succeeded.\",\n err\n );\n }\n }\n\n Ok(())\n })();\n\n if let Err(err) = checkout_result {\n if stashed {\n eprintln!(\"==> Restoring stashed changes after failed checkout...\");\n let _ = git_run_in(&repo_root_path, &[\"stash\", \"pop\"]);\n }\n return Err(err);\n }\n\n if stashed {\n println!(\"==> Restoring stashed changes...\");\n if let Err(err) = git_run_in(&repo_root_path, &[\"stash\", \"pop\"]) {\n eprintln!(\n \"warning: failed to restore stash automatically: {}\\nRun `git stash list` and restore manually if needed.\",\n err\n );\n }\n }\n\n let current = git_capture_in(&repo_root_path, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string())\n .trim()\n .to_string();\n println!(\"✓ Checked out {}\", current);\n Ok(())\n}\n\nfn switch_preserve_reason(\n repo_root: &Path,\n current_branch: &str,\n target_branch: &str,\n has_changes: bool,\n) -> Option<String> {\n if has_changes {\n return Some(\"uncommitted changes present\".to_string());\n }\n\n if switch_branch_has_commits_not_in_target(repo_root, current_branch, target_branch) {\n return Some(format!(\"contains commits not in {}\", target_branch));\n }\n\n if let Some((tracking_remote, tracking_branch)) =\n resolve_tracking_remote_branch_in(repo_root, Some(current_branch))\n {\n let tracking_ref = format!(\"{}/{}\", tracking_remote, tracking_branch);\n let tracking_git_ref = format!(\"refs/remotes/{}\", tracking_ref);\n if !git_ref_exists_in(repo_root, &tracking_git_ref) {\n return Some(format!(\"tracking ref {} not fetched\", tracking_ref));\n }\n\n let ahead = git_capture_in(\n repo_root,\n &[\n \"rev-list\",\n \"--count\",\n &format!(\"{}..{}\", tracking_ref, current_branch),\n ],\n )\n .ok()\n .and_then(|v| v.trim().parse::<u32>().ok())\n .unwrap_or(0);\n\n if ahead > 0 {\n return Some(format!(\n \"ahead of tracking {} by {} commit(s)\",\n tracking_ref, ahead\n ));\n }\n }\n\n None\n}\n\nfn switch_branch_has_commits_not_in_target(\n repo_root: &Path,\n current_branch: &str,\n target_branch: &str,\n) -> bool {\n let target_ref = if git_ref_exists_in(repo_root, &format!(\"refs/heads/{}\", target_branch)) {\n target_branch.to_string()\n } else if git_ref_exists_in(\n repo_root,\n &format!(\"refs/remotes/upstream/{}\", target_branch),\n ) {\n format!(\"upstream/{}\", target_branch)\n } else if git_ref_exists_in(repo_root, &format!(\"refs/remotes/origin/{}\", target_branch)) {\n format!(\"origin/{}\", target_branch)\n } else {\n return true;\n };\n\n git_capture_in(\n repo_root,\n &[\n \"rev-list\",\n \"--count\",\n &format!(\"{}..{}\", target_ref, current_branch),\n ],\n )\n .ok()\n .and_then(|v| v.trim().parse::<u32>().ok())\n .map(|count| count > 0)\n .unwrap_or(true)\n}\n\nfn create_switch_safety_snapshot(repo_root: &Path, current_branch: &str) -> Option<String> {\n let snapshot_base = format!(\n \"f-switch-save/{}-{}\",\n sanitize_checkout_label(current_branch),\n Utc::now().format(\"%Y%m%d-%H%M%S\")\n );\n let use_jj = should_use_jj(repo_root);\n let mut snapshot_name = snapshot_base.clone();\n let mut suffix = 1;\n\n loop {\n let git_exists = git_ref_exists_in(repo_root, &format!(\"refs/heads/{}\", snapshot_name));\n let jj_exists = use_jj && jj_bookmark_exists(repo_root, &snapshot_name);\n if !git_exists && !jj_exists {\n break;\n }\n snapshot_name = format!(\"{}-{}\", snapshot_base, suffix);\n suffix += 1;\n }\n\n if git_run_in(repo_root, &[\"branch\", &snapshot_name, current_branch]).is_err() {\n return None;\n }\n\n if use_jj {\n if let Err(err) = jj_bookmark_create_or_set(repo_root, &snapshot_name, current_branch) {\n eprintln!(\n \"warning: created git snapshot '{}' but failed to create/update jj bookmark: {}\",\n snapshot_name, err\n );\n }\n }\n\n Some(snapshot_name)\n}\n\nfn ensure_branch_attached(repo_root: &Path, target_branch: &str) -> Result<()> {\n let current = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string());\n let current = current.trim();\n\n if current == target_branch {\n return Ok(());\n }\n\n println!(\n \"==> Re-attaching Git checkout to {} (current: {})...\",\n target_branch, current\n );\n git_run_in(repo_root, &[\"switch\", target_branch]).with_context(|| {\n format!(\n \"sync finished but could not switch back to '{}'; run `git switch {}` manually\",\n target_branch, target_branch\n )\n })?;\n Ok(())\n}\n\nstruct SwitchTrackingResolution {\n remote: Option<String>,\n searched: Vec<String>,\n}\n\nfn resolve_tracking_remote_and_fetch(\n repo_root: &Path,\n branch: &str,\n preferred_remote: Option<&str>,\n) -> Result<SwitchTrackingResolution> {\n let mut candidates: Vec<String> = Vec::new();\n let mut seen = HashSet::new();\n let mut push_candidate = |remote: String| {\n let trimmed = remote.trim();\n if trimmed.is_empty() {\n return;\n }\n let key = trimmed.to_string();\n if seen.insert(key.clone()) {\n candidates.push(key);\n }\n };\n\n if let Some(remote) = preferred_remote.map(str::trim).filter(|s| !s.is_empty()) {\n push_candidate(remote.to_string());\n }\n for remote in [\"upstream\", \"origin\"] {\n push_candidate(remote.to_string());\n }\n\n if let Ok(remotes_raw) = git_capture_in(repo_root, &[\"remote\"]) {\n for remote in remotes_raw.lines() {\n push_candidate(remote.to_string());\n }\n }\n\n let mut searched: Vec<String> = Vec::new();\n for remote in candidates {\n if !remote_exists(repo_root, &remote) {\n continue;\n }\n searched.push(remote.clone());\n println!(\"==> Fetching {}...\", remote);\n let args = vec![\"fetch\", remote.as_str(), \"--prune\"];\n if let Err(err) = git_run_in(repo_root, &args) {\n if preferred_remote.map(|r| r.trim()) == Some(remote.as_str()) {\n return Err(err);\n }\n continue;\n }\n if remote_branch_exists(repo_root, &remote, branch) {\n return Ok(SwitchTrackingResolution {\n remote: Some(remote),\n searched,\n });\n }\n }\n\n Ok(SwitchTrackingResolution {\n remote: None,\n searched,\n })\n}\n\nfn sync_local_upstream_branch(repo_root: &Path, branch: &str) -> Result<()> {\n let remote_ref = format!(\"refs/remotes/upstream/{}\", branch);\n if !git_ref_exists_in(repo_root, &remote_ref) {\n return Ok(());\n }\n let upstream_ref = format!(\"upstream/{}\", branch);\n let current = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string());\n if git_ref_exists_in(repo_root, \"refs/heads/upstream\") {\n if current.trim() == \"upstream\" {\n git_run_in(repo_root, &[\"reset\", \"--hard\", &upstream_ref])?;\n } else {\n git_run_in(repo_root, &[\"branch\", \"-f\", \"upstream\", &upstream_ref])?;\n }\n } else {\n git_run_in(repo_root, &[\"branch\", \"upstream\", &upstream_ref])?;\n }\n Ok(())\n}\n\nfn remote_exists(repo_root: &Path, remote: &str) -> bool {\n git_capture_in(repo_root, &[\"remote\", \"get-url\", remote]).is_ok()\n}\n\nfn sanitize_checkout_label(input: &str) -> String {\n let mut out = String::new();\n let mut last_sep = false;\n for ch in input.chars() {\n if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || ch == '.' {\n out.push(ch);\n last_sep = false;\n } else if !last_sep {\n out.push('-');\n last_sep = true;\n }\n }\n let trimmed = out.trim_matches('-');\n if trimmed.is_empty() {\n \"target\".to_string()\n } else {\n trimmed.chars().take(32).collect()\n }\n}\n\nfn parse_github_pr_url(target: &str) -> Option<(String, String)> {\n let raw = target.trim().trim_end_matches('/');\n let rest = raw\n .strip_prefix(\"https://github.com/\")\n .or_else(|| raw.strip_prefix(\"http://github.com/\"))?;\n let parts: Vec<&str> = rest.split('/').collect();\n if parts.len() < 4 {\n return None;\n }\n if parts.get(2).copied() != Some(\"pull\") {\n return None;\n }\n let owner = parts[0].trim();\n let repo = parts[1].trim();\n let number = parts[3].trim();\n if owner.is_empty() || repo.is_empty() || number.is_empty() {\n return None;\n }\n if !number.chars().all(|c| c.is_ascii_digit()) {\n return None;\n }\n Some((format!(\"{}/{}\", owner, repo), number.to_string()))\n}\n\nfn build_gh_pr_checkout_args(target: &str, preferred_remote: Option<&str>) -> Vec<String> {\n let mut args: Vec<String> = vec![\"pr\".to_string(), \"checkout\".to_string()];\n if let Some((repo, number)) = parse_github_pr_url(target) {\n args.push(number);\n args.push(\"--repo\".to_string());\n args.push(repo);\n } else {\n args.push(target.to_string());\n }\n if let Some(remote) = preferred_remote.map(str::trim).filter(|s| !s.is_empty()) {\n args.push(\"--remote\".to_string());\n args.push(remote.to_string());\n }\n args\n}\n\nfn ensure_gh_available() -> Result<()> {\n let status = Command::new(\"gh\")\n .arg(\"--version\")\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .context(\"failed to run gh --version\")?;\n if !status.success() {\n bail!(\"GitHub CLI (`gh`) is required for `f checkout`\");\n }\n Ok(())\n}\n\nfn run_gh_in(repo_root: &Path, args: &[String]) -> Result<()> {\n let status = Command::new(\"gh\")\n .current_dir(repo_root)\n .args(args)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .with_context(|| format!(\"failed to run gh {}\", args.join(\" \")))?;\n if !status.success() {\n bail!(\"gh {} failed with status {}\", args.join(\" \"), status);\n }\n Ok(())\n}\n\nfn gh_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"gh\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run gh {}\", args.join(\" \")))?;\n if !output.status.success() {\n bail!(\n \"gh {} failed: {}\",\n args.join(\" \"),\n String::from_utf8_lossy(&output.stderr).trim()\n );\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nfn remote_branch_exists(repo_root: &Path, remote: &str, branch: &str) -> bool {\n let reference = format!(\"refs/remotes/{}/{}\", remote, branch);\n git_ref_exists_in(repo_root, &reference)\n}\n\nfn git_ref_exists_in(repo_root: &Path, reference: &str) -> bool {\n git_capture_in(repo_root, &[\"rev-parse\", \"--verify\", reference]).is_ok()\n}\n\n#[derive(Clone, Debug)]\nstruct TrackedRemoteRef {\n remote: String,\n branch: String,\n before_tip: Option<String>,\n}\n\nfn track_remote_ref(\n tracked: &mut Vec<TrackedRemoteRef>,\n repo_root: &Path,\n remote: &str,\n branch: &str,\n) {\n if remote.trim().is_empty() || branch.trim().is_empty() {\n return;\n }\n if tracked\n .iter()\n .any(|item| item.remote == remote && item.branch == branch)\n {\n return;\n }\n tracked.push(TrackedRemoteRef {\n remote: remote.to_string(),\n branch: branch.to_string(),\n before_tip: remote_branch_tip(repo_root, remote, branch),\n });\n}\n\nfn remote_branch_tip(repo_root: &Path, remote: &str, branch: &str) -> Option<String> {\n let reference = format!(\"refs/remotes/{}/{}\", remote, branch);\n git_capture_in(repo_root, &[\"rev-parse\", \"--verify\", &reference])\n .ok()\n .map(|out| out.trim().to_string())\n .filter(|sha| !sha.is_empty())\n}\n\nfn short_commit_id(sha: &str) -> &str {\n let trimmed = sha.trim();\n if trimmed.len() <= 8 {\n trimmed\n } else {\n &trimmed[..8]\n }\n}\n\nfn normalize_sync_commit_line(hash: &str, description: &str) -> String {\n let hash = hash.trim();\n let description = description.trim();\n if description.is_empty() {\n format!(\"{hash} (no description)\")\n } else {\n format!(\"{hash} {description}\")\n }\n}\n\nfn build_synced_commit_list(recorder: &SyncRecorder) -> Vec<String> {\n let mut seen_commits: Vec<(String, String)> = Vec::new();\n let mut commits: Vec<String> = Vec::new();\n\n for update in &recorder.remote_updates {\n for line in &update.commits {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n continue;\n }\n let (hash, description) =\n if let Some((hash, rest)) = trimmed.split_once(char::is_whitespace) {\n let hash = hash.trim();\n if hash.is_empty() {\n continue;\n }\n (hash, rest.trim())\n } else {\n (trimmed, \"\")\n };\n let normalized_description = description.to_string();\n let is_duplicate = seen_commits.iter().any(|(seen_hash, seen_description)| {\n seen_description == &normalized_description\n && (seen_hash.starts_with(hash) || hash.starts_with(seen_hash))\n });\n if !is_duplicate {\n seen_commits.push((hash.to_string(), normalized_description));\n commits.push(trimmed.to_string());\n }\n }\n }\n commits\n}\n\nfn jj_resolve_commit_id(repo_root: &Path, revset: &str) -> Option<String> {\n jj_capture_in(\n repo_root,\n &[\n \"log\",\n \"-r\",\n revset,\n \"--limit\",\n \"1\",\n \"--no-graph\",\n \"-T\",\n \"commit_id\",\n ],\n )\n .ok()\n .and_then(|out| out.lines().next().map(str::trim).map(str::to_string))\n .filter(|value| !value.is_empty())\n}\n\nfn jj_collect_sync_destination_commits(\n repo_root: &Path,\n source_revset: &str,\n dest_revset: &str,\n) -> Result<Vec<String>> {\n let revset = format!(\"({})..({})\", source_revset, dest_revset);\n let lines = jj_capture_in(\n repo_root,\n &[\n \"log\",\n \"-r\",\n &revset,\n \"--no-graph\",\n \"--reversed\",\n \"-T\",\n r#\"commit_id.shortest(8) ++ \"\\t\" ++ description.first_line() ++ \"\\n\"\"#,\n ],\n )?;\n\n Ok(lines\n .lines()\n .filter_map(|line| {\n let trimmed = line.trim_end();\n if trimmed.is_empty() {\n return None;\n }\n let (hash, description) = trimmed.split_once('\\t').unwrap_or((trimmed, \"\"));\n Some(normalize_sync_commit_line(hash, description))\n })\n .collect())\n}\n\nfn record_jj_synced_destination_commits(\n repo_root: &Path,\n recorder: &mut SyncRecorder,\n source_revset: &str,\n dest_revset: &str,\n) {\n let commits = match jj_collect_sync_destination_commits(repo_root, source_revset, dest_revset) {\n Ok(commits) => commits,\n Err(_) => return,\n };\n if commits.is_empty() {\n return;\n }\n\n let (branch, remote) = match dest_revset.rsplit_once('@') {\n Some((branch, remote)) if !branch.trim().is_empty() && !remote.trim().is_empty() => {\n (branch.to_string(), format!(\"synced:{remote}\"))\n }\n _ => (\"dest\".to_string(), \"synced\".to_string()),\n };\n\n recorder.add_remote_update(SyncRemoteUpdate {\n remote,\n branch,\n before_tip: jj_resolve_commit_id(repo_root, source_revset),\n after_tip: jj_resolve_commit_id(repo_root, dest_revset).unwrap_or_default(),\n commit_count: commits.len(),\n commits,\n });\n}\n\nfn copy_sync_output_to_clipboard(text: &str) -> Result<bool> {\n if std::env::var(\"FLOW_NO_CLIPBOARD\").is_ok() {\n return Ok(false);\n }\n\n #[cfg(target_os = \"macos\")]\n {\n let mut child = Command::new(\"pbcopy\")\n .stdin(Stdio::piped())\n .spawn()\n .context(\"failed to spawn pbcopy\")?;\n if let Some(stdin) = child.stdin.as_mut() {\n stdin.write_all(text.as_bytes())?;\n }\n child.wait()?;\n return Ok(true);\n }\n\n #[cfg(target_os = \"linux\")]\n {\n let result = Command::new(\"xclip\")\n .arg(\"-selection\")\n .arg(\"clipboard\")\n .stdin(Stdio::piped())\n .spawn();\n\n let mut child = match result {\n Ok(c) => c,\n Err(_) => Command::new(\"xsel\")\n .arg(\"--clipboard\")\n .arg(\"--input\")\n .stdin(Stdio::piped())\n .spawn()\n .context(\"failed to spawn xclip or xsel\")?,\n };\n\n if let Some(stdin) = child.stdin.as_mut() {\n stdin.write_all(text.as_bytes())?;\n }\n child.wait()?;\n return Ok(true);\n }\n\n #[cfg(not(any(target_os = \"macos\", target_os = \"linux\")))]\n {\n bail!(\"clipboard not supported on this platform\");\n }\n}\n\nfn print_fetched_remote_commits(\n repo_root: &Path,\n tracked: &[TrackedRemoteRef],\n recorder: &mut SyncRecorder,\n _compact: bool,\n) {\n for item in tracked {\n let Some(after_tip) = remote_branch_tip(repo_root, &item.remote, &item.branch) else {\n continue;\n };\n if item.before_tip.as_deref() == Some(after_tip.as_str()) {\n continue;\n }\n\n let label = format!(\"{}/{}\", item.remote, item.branch);\n match item.before_tip.as_deref() {\n None => {\n recorder.add_remote_update(SyncRemoteUpdate {\n remote: item.remote.clone(),\n branch: item.branch.clone(),\n before_tip: None,\n after_tip: after_tip.clone(),\n commit_count: 0,\n commits: Vec::new(),\n });\n recorder.record(\n \"jj\",\n format!(\"fetched {} at {}\", label, short_commit_id(&after_tip)),\n );\n }\n Some(before_tip) => {\n let range = format!(\"{}..{}\", before_tip, after_tip);\n let lines = git_capture_in(\n repo_root,\n &[\n \"log\",\n \"--oneline\",\n \"--abbrev=8\",\n \"--no-decorate\",\n \"--reverse\",\n &range,\n ],\n )\n .unwrap_or_default();\n let commits: Vec<&str> = lines\n .lines()\n .map(str::trim)\n .filter(|line| !line.is_empty())\n .collect();\n if commits.is_empty() {\n recorder.add_remote_update(SyncRemoteUpdate {\n remote: item.remote.clone(),\n branch: item.branch.clone(),\n before_tip: Some(before_tip.to_string()),\n after_tip: after_tip.clone(),\n commit_count: 0,\n commits: Vec::new(),\n });\n recorder.record(\n \"jj\",\n format!(\n \"fetched {} {} -> {}\",\n label,\n short_commit_id(before_tip),\n short_commit_id(&after_tip)\n ),\n );\n } else {\n recorder.add_remote_update(SyncRemoteUpdate {\n remote: item.remote.clone(),\n branch: item.branch.clone(),\n before_tip: Some(before_tip.to_string()),\n after_tip: after_tip.clone(),\n commit_count: commits.len(),\n commits: commits.iter().map(|line| (*line).to_string()).collect(),\n });\n recorder.record(\n \"jj\",\n format!(\"fetched {} (+{} commits)\", label, commits.len()),\n );\n }\n }\n }\n }\n}\n\nfn run_jj_sync(\n repo_root: &Path,\n cmd: &SyncCommand,\n auto_fix: bool,\n recorder: &mut SyncRecorder,\n) -> Result<()> {\n // Avoid git operations in progress.\n if is_rebase_in_progress() || is_merge_in_progress() {\n bail!(\"Git operation in progress. Run `f git-repair` first.\");\n }\n let unmerged = git_capture(&[\"diff\", \"--name-only\", \"--diff-filter=U\"]).unwrap_or_default();\n if !unmerged.trim().is_empty() {\n bail!(\"Unmerged files detected. Resolve them before syncing.\");\n }\n\n let head_ref = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_else(|_| \"HEAD\".to_string());\n let head_ref = head_ref.trim();\n let current_branch = if head_ref == \"HEAD\" || head_ref.is_empty() {\n recorder.record(\"jj\", \"detached head (ignored, using default branch)\");\n jj_default_branch(repo_root)\n } else {\n head_ref.to_string()\n };\n\n let push_remote = config::preferred_git_remote_for_repo(repo_root);\n let has_push_remote = git_capture_in(repo_root, &[\"remote\", \"get-url\", &push_remote]).is_ok();\n let push_remote_reachable = has_push_remote\n && git_capture_in(repo_root, &[\"ls-remote\", \"--exit-code\", \"-q\", &push_remote]).is_ok();\n let has_origin = git_capture_in(repo_root, &[\"remote\", \"get-url\", \"origin\"]).is_ok();\n let has_upstream = git_capture_in(repo_root, &[\"remote\", \"get-url\", \"upstream\"]).is_ok();\n let origin_reachable = has_origin\n && git_capture_in(repo_root, &[\"ls-remote\", \"--exit-code\", \"-q\", \"origin\"]).is_ok();\n let should_push = sync_should_push(cmd);\n let origin_default_branch = if !has_upstream && has_origin && origin_reachable {\n origin_default_branch_for_feature_sync(repo_root, ¤t_branch)\n } else {\n None\n };\n\n // Keep jj fetch output small. In most workflows, only the current branch + upstream trunk are\n // needed for a sync/rebase.\n let mut upstream_branch_opt = resolve_upstream_branch_in(repo_root, Some(¤t_branch));\n let upstream_branch_for_fetch = upstream_branch_opt\n .clone()\n .unwrap_or_else(|| jj_default_branch(repo_root));\n\n let mut tracked_refs: Vec<TrackedRemoteRef> = Vec::new();\n if has_origin || has_upstream {\n println!(\"==> Fetching remotes via jj...\");\n let mut fetched_any = false;\n let mut failures: Vec<String> = Vec::new();\n\n if has_origin && origin_reachable {\n track_remote_ref(&mut tracked_refs, repo_root, \"origin\", ¤t_branch);\n recorder.record(\n \"jj\",\n format!(\"jj git fetch --remote origin --branch {}\", current_branch),\n );\n if let Err(err) = jj_run_in(\n repo_root,\n &[\n \"--quiet\",\n \"git\",\n \"fetch\",\n \"--remote\",\n \"origin\",\n \"--branch\",\n ¤t_branch,\n ],\n ) {\n failures.push(format!(\"origin: {}\", err));\n } else {\n fetched_any = true;\n }\n if let Some(default_branch) = origin_default_branch.as_deref() {\n track_remote_ref(&mut tracked_refs, repo_root, \"origin\", default_branch);\n recorder.record(\n \"jj\",\n format!(\"jj git fetch --remote origin --branch {}\", default_branch),\n );\n if let Err(err) = jj_run_in(\n repo_root,\n &[\n \"--quiet\",\n \"git\",\n \"fetch\",\n \"--remote\",\n \"origin\",\n \"--branch\",\n default_branch,\n ],\n ) {\n failures.push(format!(\"origin default {}: {}\", default_branch, err));\n } else {\n fetched_any = true;\n }\n }\n } else if has_origin {\n recorder.record(\"jj\", \"skip origin (unreachable)\");\n }\n\n if has_push_remote\n && push_remote != \"origin\"\n && push_remote != \"upstream\"\n && push_remote_reachable\n {\n track_remote_ref(&mut tracked_refs, repo_root, &push_remote, ¤t_branch);\n recorder.record(\n \"jj\",\n format!(\n \"jj git fetch --remote {} --branch {}\",\n push_remote, current_branch\n ),\n );\n if let Err(err) = jj_run_in(\n repo_root,\n &[\n \"--quiet\",\n \"git\",\n \"fetch\",\n \"--remote\",\n &push_remote,\n \"--branch\",\n ¤t_branch,\n ],\n ) {\n failures.push(format!(\"{}: {}\", push_remote, err));\n } else {\n fetched_any = true;\n }\n } else if has_push_remote\n && push_remote != \"origin\"\n && push_remote != \"upstream\"\n && !push_remote_reachable\n {\n recorder.record(\"jj\", format!(\"skip {} (unreachable)\", push_remote));\n }\n\n if has_upstream {\n track_remote_ref(\n &mut tracked_refs,\n repo_root,\n \"upstream\",\n &upstream_branch_for_fetch,\n );\n recorder.record(\n \"jj\",\n format!(\n \"jj git fetch --remote upstream --branch {}\",\n upstream_branch_for_fetch\n ),\n );\n if let Err(primary_err) = jj_run_in(\n repo_root,\n &[\n \"--quiet\",\n \"git\",\n \"fetch\",\n \"--remote\",\n \"upstream\",\n \"--branch\",\n &upstream_branch_for_fetch,\n ],\n ) {\n recorder.record(\n \"jj\",\n format!(\n \"jj git fetch upstream branch {} failed, retrying full fetch\",\n upstream_branch_for_fetch\n ),\n );\n if let Err(fallback_err) = jj_run_in(\n repo_root,\n &[\"--quiet\", \"git\", \"fetch\", \"--remote\", \"upstream\"],\n ) {\n failures.push(format!(\n \"upstream: {} (fallback failed: {})\",\n primary_err, fallback_err\n ));\n } else {\n fetched_any = true;\n }\n } else {\n fetched_any = true;\n }\n }\n\n if fetched_any {\n recorder.record(\"jj\", \"jj git import\");\n let _ = jj_run_in(repo_root, &[\"--quiet\", \"git\", \"import\"]);\n print_fetched_remote_commits(repo_root, &tracked_refs, recorder, cmd.compact);\n // Re-resolve after fetch/import so we can pick up newly discovered upstream refs.\n upstream_branch_opt = resolve_upstream_branch_in(repo_root, Some(¤t_branch));\n } else if !failures.is_empty() {\n bail!(\"jj git fetch failed: {}\", failures.join(\", \"));\n }\n }\n\n let push_remote_url =\n git_capture_in(repo_root, &[\"remote\", \"get-url\", &push_remote]).unwrap_or_default();\n let upstream_url =\n git_capture_in(repo_root, &[\"remote\", \"get-url\", \"upstream\"]).unwrap_or_default();\n let is_read_only =\n has_upstream && normalize_git_url(&push_remote_url) == normalize_git_url(&upstream_url);\n\n let mut dest_ref: Option<String> = None;\n if has_upstream {\n if let Some(branch) = upstream_branch_opt {\n dest_ref = Some(format!(\"{}@upstream\", branch));\n }\n } else if let Some(default_branch) = origin_default_branch {\n dest_ref = Some(format!(\"{}@origin\", default_branch));\n }\n\n if dest_ref.is_none() && has_push_remote {\n dest_ref = Some(format!(\"{}@{}\", current_branch, push_remote));\n }\n\n let mut did_rebase = false;\n let mut did_stash_commits = false;\n let mut needs_git_export = false;\n if let Some(dest) = dest_ref.clone() {\n let has_branch_bookmark = jj_bookmark_exists(repo_root, ¤t_branch);\n let branch_sync_source = jj_branch_sync_source_rev(repo_root, ¤t_branch);\n\n record_jj_synced_destination_commits(repo_root, recorder, &branch_sync_source, &dest);\n\n if cmd.stash_commits {\n if jj_has_divergence(repo_root, &branch_sync_source, &dest)? {\n let stash_name = jj_stash_commits(repo_root, ¤t_branch, &dest)?;\n println!(\"==> Stashed local JJ commits to {}\", stash_name);\n recorder.record(\"stash\", format!(\"jj stash {}\", stash_name));\n recorder.set_stashed(true);\n did_rebase = true;\n did_stash_commits = true;\n needs_git_export = true;\n }\n }\n\n if !did_stash_commits {\n if has_branch_bookmark {\n if jj_has_divergence(repo_root, &branch_sync_source, &dest)? {\n println!(\n \"==> Rebasing branch {} with jj onto {}...\",\n current_branch, dest\n );\n let preempt_ignore_immutable = branch_tip_matches_remote(\n repo_root,\n ¤t_branch,\n if is_read_only {\n \"upstream\"\n } else {\n &push_remote\n },\n );\n if preempt_ignore_immutable {\n recorder.record(\n \"jj\",\n format!(\n \"branch {} matches {}/{}; preemptively using --ignore-immutable\",\n current_branch, push_remote, current_branch\n ),\n );\n }\n let initial_rebase_args: Vec<&str> = if preempt_ignore_immutable {\n vec![\n \"rebase\",\n \"--ignore-immutable\",\n \"-b\",\n branch_sync_source.as_str(),\n \"-d\",\n &dest,\n ]\n } else {\n vec![\"rebase\", \"-b\", branch_sync_source.as_str(), \"-d\", &dest]\n };\n recorder.record(\n \"jj\",\n if preempt_ignore_immutable {\n format!(\n \"jj rebase --ignore-immutable -b {} -d {}\",\n branch_sync_source, dest\n )\n } else {\n format!(\"jj rebase -b {} -d {}\", branch_sync_source, dest)\n },\n );\n if let Err(err) = jj_run_in(repo_root, &initial_rebase_args) {\n recorder.record(\"jj\", \"jj branch rebase failed\");\n if !preempt_ignore_immutable {\n println!(\n \"==> Rebase blocked by immutable commits; retrying with --ignore-immutable...\"\n );\n recorder.record(\"jj\", \"jj branch rebase retry --ignore-immutable\");\n jj_run_in(\n repo_root,\n &[\n \"rebase\",\n \"--ignore-immutable\",\n \"-b\",\n branch_sync_source.as_str(),\n \"-d\",\n &dest,\n ],\n )?;\n } else {\n return Err(err);\n }\n }\n did_rebase = true;\n needs_git_export = true;\n } else {\n recorder.record(\n \"jj\",\n format!(\"jj bookmark set {} -r {}\", current_branch, dest),\n );\n let ff_output = jj_capture_in(\n repo_root,\n &[\"bookmark\", \"set\", ¤t_branch, \"-r\", &dest],\n )?;\n let ff_trimmed = ff_output.trim();\n if ff_trimmed.is_empty()\n || ff_trimmed.contains(\"Nothing changed\")\n || ff_trimmed.contains(\"nothing changed\")\n {\n println!(\" {} already up to date with {}\", current_branch, dest);\n } else {\n println!(\"==> Fast-forwarded {} to {}\", current_branch, dest);\n }\n needs_git_export = true;\n }\n\n // After syncing the branch bookmark, also rebase the working\n // copy onto the new destination so files reflect latest state.\n recorder.record(\"jj\", format!(\"jj rebase -d {} (working copy)\", dest));\n match jj_capture_in(repo_root, &[\"rebase\", \"-d\", &dest]) {\n Ok(_) => {\n println!(\"==> Rebased working copy onto {}\", dest);\n did_rebase = true;\n }\n Err(_) => {\n // Non-fatal: working copy may already be at destination\n }\n }\n } else {\n println!(\"==> Rebasing with jj onto {}...\", dest);\n recorder.record(\"jj\", format!(\"jj rebase -d {}\", dest));\n if let Err(err) = jj_run_in(repo_root, &[\"rebase\", \"-d\", &dest]) {\n recorder.record(\"jj\", \"jj rebase failed\");\n println!(\n \"==> Rebase blocked by immutable commits; retrying with --ignore-immutable...\"\n );\n recorder.record(\"jj\", \"jj rebase retry --ignore-immutable\");\n if let Err(retry_err) =\n jj_run_in(repo_root, &[\"rebase\", \"--ignore-immutable\", \"-d\", &dest])\n {\n // If even --ignore-immutable fails, return the original error.\n let _ = retry_err;\n return Err(err);\n }\n }\n did_rebase = true;\n }\n\n if commit::commit_queue_has_entries(repo_root) {\n if let Ok(updated) = commit::refresh_commit_queue(repo_root) {\n if updated > 0 {\n recorder.record(\"queue\", format!(\"refreshed {} queued commits\", updated));\n println!(\"==> Updated {} queued commit(s) after rebase\", updated);\n }\n }\n }\n }\n\n if needs_git_export {\n recorder.record(\"jj\", \"jj git export\");\n jj_run_in(repo_root, &[\"--quiet\", \"git\", \"export\"])?;\n\n // After jj git export, git HEAD may be detached (or on a jj/keep/ ref)\n // because the jj working copy commit isn't on any bookmark. Re-attach\n // HEAD to the current branch so the user's shell prompt stays sane.\n let git_head = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .unwrap_or_default();\n let git_head = git_head.trim();\n if git_head == \"HEAD\" || git_head.starts_with(\"jj/keep/\") {\n if git_ref_exists_in(repo_root, &format!(\"refs/heads/{}\", current_branch)) {\n let branch_sha = git_capture_in(\n repo_root,\n &[\"rev-parse\", &format!(\"refs/heads/{}\", current_branch)],\n )\n .unwrap_or_default();\n let branch_sha = branch_sha.trim();\n if !branch_sha.is_empty() {\n // Point HEAD at the branch symbolically, then reset to its tip.\n let _ = git_run_in(\n repo_root,\n &[\n \"symbolic-ref\",\n \"HEAD\",\n &format!(\"refs/heads/{}\", current_branch),\n ],\n );\n let _ = git_run_in(repo_root, &[\"reset\", \"--mixed\", \"--quiet\", branch_sha]);\n recorder.record(\"jj\", format!(\"re-attached HEAD to {}\", current_branch));\n }\n }\n }\n }\n } else {\n println!(\"==> No remotes configured, skipping rebase\");\n recorder.record(\"jj\", \"skipped (no remotes)\");\n }\n\n // Fork push override: redirect to private fork remote if configured.\n let (mut push_remote, mut has_push_remote, mut push_remote_reachable, mut is_read_only) = (\n push_remote,\n has_push_remote,\n push_remote_reachable,\n is_read_only,\n );\n if should_push {\n if let Some((fork_remote, fork_owner, fork_repo)) = resolve_fork_push_target(repo_root) {\n let target_url = push::build_github_ssh_url(&fork_owner, &fork_repo);\n if let Err(e) = push::ensure_remote_points_to_target(\n repo_root,\n &fork_remote,\n &target_url,\n None,\n true,\n ) {\n eprintln!(\"Warning: could not set up fork remote: {}\", e);\n } else {\n push::ensure_github_repo_exists(&fork_owner, &fork_repo).ok();\n // Let jj know about the new remote.\n let _ = jj_capture_in(repo_root, &[\"git\", \"fetch\", \"--remote\", &fork_remote]);\n println!(\n \"==> Fork push enabled: {}/{} (remote: {})\",\n fork_owner, fork_repo, fork_remote\n );\n push_remote = fork_remote;\n has_push_remote = true;\n push_remote_reachable = true;\n is_read_only = false;\n }\n }\n }\n\n // Review-todo push gate (jj sync path)\n if should_push && !check_review_todo_push_gate(repo_root, cmd.allow_review_issues, recorder) {\n recorder.record(\"push\", \"blocked by review-todo gate\");\n bail!(\"Push blocked by open review todos. Use --allow-review-issues to override.\");\n }\n\n if has_push_remote && should_push {\n if is_read_only {\n println!(\n \"==> Skipping push (remote '{}' == upstream, read-only clone)\",\n push_remote\n );\n println!(\" To push, create a fork first: gh repo fork --remote\");\n recorder.record(\"push\", \"skipped (push remote == upstream)\");\n } else if !push_remote_reachable {\n if cmd.create_repo && push_remote == \"origin\" {\n println!(\"==> Creating origin repo...\");\n if try_create_origin_repo()? {\n println!(\"==> Pushing to {}...\", push_remote);\n git_run(&[\"push\", \"-u\", &push_remote, ¤t_branch])?;\n recorder.record(\n \"push\",\n format!(\"created repo and pushed to {}\", push_remote),\n );\n } else {\n println!(\" Could not create repo, skipping push\");\n recorder.record(\"push\", \"skipped (create repo failed)\");\n }\n } else {\n println!(\"==> Remote '{}' unreachable, skipping push\", push_remote);\n println!(\" The remote may be missing, private, or auth/network failed.\");\n if push_remote == \"origin\" {\n println!(\" Use --create-repo if origin does not exist yet.\");\n } else {\n println!(\n \" Create/fix remote '{}' and re-run sync (or set [git].remote).\",\n push_remote\n );\n }\n recorder.record(\n \"push\",\n format!(\"skipped (remote unreachable: {})\", push_remote),\n );\n }\n } else {\n println!(\"==> Pushing to {}...\", push_remote);\n let push_result = if did_rebase {\n push_with_autofix_force(\n ¤t_branch,\n &push_remote,\n auto_fix,\n cmd.max_fix_attempts,\n )\n } else {\n push_with_autofix(\n ¤t_branch,\n &push_remote,\n auto_fix,\n cmd.max_fix_attempts,\n )\n };\n if let Err(e) = push_result {\n recorder.record(\"push\", \"push failed\");\n return Err(e);\n }\n recorder.record(\"push\", \"push complete\");\n }\n } else if cmd.no_push {\n recorder.record(\"push\", \"skipped (--no-push)\");\n } else if has_push_remote {\n recorder.record(\"push\", \"skipped (default; use --push)\");\n } else {\n recorder.record(\"push\", format!(\"skipped (missing remote: {})\", push_remote));\n }\n\n // Check for jj conflicts left after rebase\n let has_conflicts = jj_capture_in(\n repo_root,\n &[\"log\", \"-r\", \"conflicts()\", \"--no-graph\", \"-T\", \"commit_id\"],\n )\n .map(|out| !out.trim().is_empty())\n .unwrap_or(false);\n\n if has_conflicts {\n let conflict_details =\n jj_capture_in(repo_root, &[\"log\", \"-r\", \"conflicts()\", \"--no-graph\"])\n .unwrap_or_default();\n println!(\"\\n⚠ Sync complete (jj) but conflicts remain:\");\n for line in conflict_details.lines().filter(|l| !l.trim().is_empty()) {\n println!(\" {}\", line.trim());\n }\n println!(\"\\nResolve with: jj resolve\");\n recorder.record(\"complete\", \"sync complete (jj) with conflicts\");\n } else {\n println!(\"\\n✓ Sync complete (jj)!\");\n recorder.record(\"complete\", \"sync complete (jj)\");\n }\n Ok(())\n}\n\n/// Sync from upstream remote into current branch.\nfn sync_upstream_internal(\n repo_root: &Path,\n current_branch: &str,\n auto_fix: bool,\n recorder: &mut SyncRecorder,\n) -> Result<()> {\n // Fetch upstream — tolerate case-insensitive ref collisions (macOS)\n let fetch = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"fetch\", \"upstream\", \"--prune\"])\n .output()\n .context(\"failed to run git fetch upstream\")?;\n if !fetch.status.success() {\n let stderr = String::from_utf8_lossy(&fetch.stderr);\n if stderr.contains(\"case-insensitive filesystem\") {\n eprintln!(\n \" Warning: upstream has refs that differ only in case; fetch continued anyway\"\n );\n } else {\n bail!(\"git fetch upstream --prune failed: {}\", stderr.trim());\n }\n }\n recorder.record(\"upstream\", \"fetched upstream\");\n\n // Determine upstream branch\n let upstream_branch = match resolve_upstream_branch_in(repo_root, Some(current_branch)) {\n Some(branch) => branch,\n None => {\n println!(\" Cannot determine upstream branch, skipping upstream sync\");\n recorder.record(\"upstream\", \"skipped (cannot determine upstream branch)\");\n return Ok(());\n }\n };\n\n // Update local upstream branch if it exists\n let local_upstream_exists =\n git_capture_in(repo_root, &[\"rev-parse\", \"--verify\", \"refs/heads/upstream\"]).is_ok();\n if local_upstream_exists {\n let upstream_ref = format!(\"upstream/{}\", upstream_branch);\n git_run_in(repo_root, &[\"branch\", \"-f\", \"upstream\", &upstream_ref])?;\n }\n\n merge_remote_branch_into_current(\n repo_root,\n \"upstream\",\n &upstream_branch,\n current_branch,\n auto_fix,\n recorder,\n \"upstream\",\n )\n}\n\nfn sync_origin_default_internal(\n repo_root: &Path,\n current_branch: &str,\n origin_default_branch: &str,\n auto_fix: bool,\n recorder: &mut SyncRecorder,\n) -> Result<()> {\n let refspec = format!(\n \"+refs/heads/{}:refs/remotes/origin/{}\",\n origin_default_branch, origin_default_branch\n );\n git_run_in(repo_root, &[\"fetch\", \"origin\", \"--prune\", &refspec])?;\n recorder.record(\n \"upstream\",\n format!(\"fetched origin {}\", origin_default_branch),\n );\n\n merge_remote_branch_into_current(\n repo_root,\n \"origin\",\n origin_default_branch,\n current_branch,\n auto_fix,\n recorder,\n \"origin-default\",\n )\n}\n\nfn merge_remote_branch_into_current(\n repo_root: &Path,\n remote: &str,\n remote_branch: &str,\n current_branch: &str,\n auto_fix: bool,\n recorder: &mut SyncRecorder,\n stage: &str,\n) -> Result<()> {\n let remote_ref = format!(\"{}/{}\", remote, remote_branch);\n let behind = git_capture_in(\n repo_root,\n &[\n \"rev-list\",\n \"--count\",\n &format!(\"{}..{}\", current_branch, remote_ref),\n ],\n )\n .ok()\n .and_then(|s| s.trim().parse::<u32>().ok())\n .unwrap_or(0);\n\n if behind == 0 {\n println!(\" Already up to date with {}\", remote_ref);\n recorder.record(stage, format!(\"already up to date with {}\", remote_ref));\n return Ok(());\n }\n\n println!(\" Merging {} commits from {}...\", behind, remote_ref);\n recorder.record(\n stage,\n format!(\"merging {} commits from {}\", behind, remote_ref),\n );\n\n match git_run_in(repo_root, &[\"merge\", \"--ff-only\", &remote_ref]) {\n Ok(()) => {\n recorder.record(stage, format!(\"fast-forwarded to {}\", remote_ref));\n return Ok(());\n }\n Err(err) if is_git_index_lock_error(&err.to_string()) => {\n bail!(\n \"Git index lock detected during merge. Remove stale .git/index.lock (if no git process is running) and re-run.\"\n );\n }\n Err(_) => {}\n }\n\n match git_run_in(repo_root, &[\"merge\", &remote_ref, \"--no-edit\"]) {\n Ok(()) => {\n recorder.record(stage, format!(\"merged {} with commit\", remote_ref));\n return Ok(());\n }\n Err(err) if is_git_index_lock_error(&err.to_string()) => {\n bail!(\n \"Git index lock detected during merge. Remove stale .git/index.lock (if no git process is running) and re-run.\"\n );\n }\n Err(_) => {}\n }\n\n let should_fix = auto_fix || prompt_for_auto_fix()?;\n if should_fix {\n println!(\" Attempting auto-fix...\");\n if try_resolve_conflicts()? {\n let _ = git_run_in(repo_root, &[\"add\", \"-A\"]);\n let _ = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"commit\", \"--no-edit\"])\n .output();\n println!(\" ✓ Conflicts auto-resolved\");\n recorder.record(stage, \"conflicts auto-resolved\");\n return Ok(());\n }\n }\n\n recorder.record(stage, \"merge conflicts unresolved\");\n bail!(\n \"Merge conflicts with {}. Resolve manually:\\n git status\\n # fix conflicts\\n git add . && git commit\",\n remote_ref\n );\n}\n\nfn origin_default_branch_for_feature_sync(\n repo_root: &Path,\n current_branch: &str,\n) -> Option<String> {\n let current = current_branch.trim();\n if current.is_empty() || current == \"HEAD\" {\n return None;\n }\n let default_branch = resolve_remote_default_branch_in(repo_root, \"origin\")?;\n if current == default_branch {\n return None;\n }\n if !remote_branch_exists(repo_root, \"origin\", &default_branch) {\n return None;\n }\n Some(default_branch)\n}\n\nfn resolve_remote_default_branch_in(repo_root: &Path, remote: &str) -> Option<String> {\n let head_ref = format!(\"refs/remotes/{}/HEAD\", remote);\n if let Ok(symbolic) = git_capture_in(repo_root, &[\"symbolic-ref\", &head_ref]) {\n let prefix = format!(\"refs/remotes/{}/\", remote);\n if let Some(branch) = symbolic.trim().strip_prefix(&prefix) {\n if !branch.is_empty() {\n return Some(branch.to_string());\n }\n }\n }\n\n let preferred = jj_default_branch(repo_root);\n if remote_branch_exists(repo_root, remote, &preferred) {\n return Some(preferred);\n }\n for candidate in [\"main\", \"master\", \"dev\", \"trunk\"] {\n if remote_branch_exists(repo_root, remote, candidate) {\n return Some(candidate.to_string());\n }\n }\n\n None\n}\n\nfn is_jj_corruption_error(err: &anyhow::Error) -> bool {\n let msg = err.to_string().to_lowercase();\n msg.contains(\"failed to load short-prefixes index\")\n || msg.contains(\"unexpected error from commit backend\")\n || msg.contains(\"current working-copy commit not found\")\n || msg.contains(\"failed to check out a commit\")\n || (msg.contains(\"object \") && msg.contains(\" not found\"))\n || (msg.contains(\"jj git fetch failed\") && msg.contains(\"object\"))\n}\n\nfn is_git_index_lock_error(message: &str) -> bool {\n let lower = message.to_lowercase();\n lower.contains(\"index.lock\")\n || lower.contains(\"another git process seems to be running\")\n || lower.contains(\"could not write index\")\n}\n\nfn parse_branch_merge_ref(value: &str) -> Option<String> {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n return None;\n }\n Some(trimmed.trim_start_matches(\"refs/heads/\").to_string())\n}\n\nfn parse_tracking_ref(value: &str) -> Option<(String, String)> {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n return None;\n }\n\n let (remote, branch) = trimmed.split_once('/')?;\n if remote.is_empty() || branch.is_empty() {\n return None;\n }\n\n Some((remote.to_string(), branch.to_string()))\n}\n\nfn resolve_tracking_remote_branch_in(\n repo_root: &Path,\n current_branch: Option<&str>,\n) -> Option<(String, String)> {\n let current_branch = current_branch\n .map(str::trim)\n .filter(|value| !value.is_empty() && *value != \"HEAD\");\n\n if let Some(branch) = current_branch {\n if let Ok(remote) = git_capture_in(\n repo_root,\n &[\"config\", \"--get\", &format!(\"branch.{}.remote\", branch)],\n ) {\n let remote = remote.trim();\n if !remote.is_empty() {\n if let Ok(merge_ref) = git_capture_in(\n repo_root,\n &[\"config\", \"--get\", &format!(\"branch.{}.merge\", branch)],\n ) {\n if let Some(merge_branch) = parse_branch_merge_ref(&merge_ref) {\n if !merge_branch.is_empty() {\n return Some((remote.to_string(), merge_branch));\n }\n }\n }\n }\n }\n }\n\n if let Ok(upstream) = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"@{upstream}\"]) {\n return parse_tracking_ref(&upstream);\n }\n\n None\n}\n\nfn list_upstream_remote_branches(repo_root: &Path) -> Vec<String> {\n let output = git_capture_in(\n repo_root,\n &[\n \"for-each-ref\",\n \"--format=%(refname:short)\",\n \"refs/remotes/upstream\",\n ],\n )\n .unwrap_or_default();\n let mut branches = Vec::new();\n for line in output.lines() {\n let value = line.trim();\n if value.is_empty() || value == \"upstream/HEAD\" {\n continue;\n }\n if let Some(rest) = value.strip_prefix(\"upstream/\") {\n if !rest.is_empty() {\n branches.push(rest.to_string());\n }\n }\n }\n branches.sort();\n branches.dedup();\n branches\n}\n\nfn resolve_upstream_branch_in(repo_root: &Path, current_branch: Option<&str>) -> Option<String> {\n let current_branch = current_branch\n .map(str::trim)\n .filter(|value| !value.is_empty());\n\n if let Some(branch) = current_branch {\n if let Ok(remote) = git_capture_in(\n repo_root,\n &[\"config\", \"--get\", &format!(\"branch.{}.remote\", branch)],\n ) {\n if remote.trim() == \"upstream\" {\n if let Ok(merge_ref) = git_capture_in(\n repo_root,\n &[\"config\", \"--get\", &format!(\"branch.{}.merge\", branch)],\n ) {\n if let Some(parsed) = parse_branch_merge_ref(&merge_ref) {\n return Some(parsed);\n }\n }\n }\n }\n }\n\n if let Ok(merge_ref) = git_capture_in(repo_root, &[\"config\", \"--get\", \"branch.upstream.merge\"])\n {\n if let Some(parsed) = parse_branch_merge_ref(&merge_ref) {\n return Some(parsed);\n }\n }\n if let Ok(head_ref) = git_capture_in(repo_root, &[\"symbolic-ref\", \"refs/remotes/upstream/HEAD\"])\n {\n let parsed = head_ref.trim().replace(\"refs/remotes/upstream/\", \"\");\n if !parsed.is_empty() {\n return Some(parsed);\n }\n }\n\n if let Some(branch) = current_branch {\n let reference = format!(\"refs/remotes/upstream/{}\", branch);\n if git_ref_exists_in(repo_root, &reference) {\n return Some(branch.to_string());\n }\n }\n\n let remote_branches = list_upstream_remote_branches(repo_root);\n for candidate in [\"main\", \"master\", \"dev\", \"trunk\"] {\n if remote_branches.iter().any(|b| b == candidate) {\n return Some(candidate.to_string());\n }\n }\n\n remote_branches.into_iter().next()\n}\n\nfn resolve_sync_branch_for_queue_guard(repo_root: &Path) -> Option<String> {\n let head = git_capture_in(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .ok()\n .map(|value| value.trim().to_string())\n .unwrap_or_default();\n if !head.is_empty() && head != \"HEAD\" {\n return Some(head);\n }\n\n if let Some(branch) = resolve_rebase_head_branch(repo_root) {\n return Some(branch);\n }\n\n resolve_branch_containing_head(repo_root)\n}\n\nfn resolve_rebase_head_branch(repo_root: &Path) -> Option<String> {\n let git_dir = git_capture_in(repo_root, &[\"rev-parse\", \"--git-dir\"])\n .ok()\n .map(|value| value.trim().to_string())?;\n let git_dir_path = if Path::new(&git_dir).is_absolute() {\n PathBuf::from(git_dir)\n } else {\n repo_root.join(git_dir)\n };\n\n for rel in [\"rebase-merge/head-name\", \"rebase-apply/head-name\"] {\n let path = git_dir_path.join(rel);\n let Ok(raw) = fs::read_to_string(&path) else {\n continue;\n };\n let branch = raw.trim().trim_start_matches(\"refs/heads/\").trim();\n if !branch.is_empty() && branch != \"HEAD\" {\n return Some(branch.to_string());\n }\n }\n None\n}\n\nfn resolve_branch_containing_head(repo_root: &Path) -> Option<String> {\n let output = git_capture_in(\n repo_root,\n &[\"branch\", \"--format=%(refname:short)\", \"--contains\", \"HEAD\"],\n )\n .ok()?;\n output\n .lines()\n .map(str::trim)\n .find(|value| !value.is_empty() && *value != \"(no branch)\" && *value != \"HEAD\")\n .map(|value| value.to_string())\n}\n\nfn should_use_jj(repo_root: &Path) -> bool {\n has_jj_workspace(repo_root) && jj_cli_available() && jj_workspace_healthy(repo_root)\n}\n\nfn has_jj_workspace(repo_root: &Path) -> bool {\n repo_root.join(\".jj\").exists()\n}\n\nfn jj_cli_available() -> bool {\n let status = Command::new(\"jj\")\n .arg(\"--version\")\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status();\n status.map(|s| s.success()).unwrap_or(false)\n}\n\nfn jj_workspace_healthy(repo_root: &Path) -> bool {\n if env::var(\"FLOW_SYNC_SKIP_JJ_HEALTHCHECK\")\n .ok()\n .map(|v| {\n let t = v.trim();\n t == \"1\" || t.eq_ignore_ascii_case(\"true\")\n })\n .unwrap_or(false)\n {\n return true;\n }\n\n Command::new(\"jj\")\n .current_dir(repo_root)\n .arg(\"status\")\n .stdout(Stdio::null())\n .stderr(Stdio::null())\n .status()\n .map(|s| s.success())\n .unwrap_or(false)\n}\n\nfn jj_default_branch(repo_root: &Path) -> String {\n let local_config = repo_root.join(\"flow.toml\");\n if local_config.exists() {\n if let Ok(cfg) = config::load(&local_config) {\n if let Some(jj_cfg) = cfg.jj {\n if let Some(branch) = jj_cfg.default_branch {\n return branch;\n }\n }\n }\n }\n\n let global_config = config::default_config_path();\n if global_config.exists() {\n if let Ok(cfg) = config::load(&global_config) {\n if let Some(jj_cfg) = cfg.jj {\n if let Some(branch) = jj_cfg.default_branch {\n return branch;\n }\n }\n }\n }\n\n if git_ref_exists(\"refs/heads/main\") || git_ref_exists(\"refs/remotes/origin/main\") {\n return \"main\".to_string();\n }\n if git_ref_exists(\"refs/heads/master\") || git_ref_exists(\"refs/remotes/origin/master\") {\n return \"master\".to_string();\n }\n\n \"main\".to_string()\n}\n\nfn git_ref_exists(reference: &str) -> bool {\n git_capture(&[\"rev-parse\", \"--verify\", reference]).is_ok()\n}\n\nfn jj_run_in(repo_root: &Path, args: &[&str]) -> Result<()> {\n let output = Command::new(\"jj\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run jj {}\", args.join(\" \")))?;\n let stdout = String::from_utf8_lossy(&output.stdout);\n if !stdout.trim().is_empty() {\n print!(\"{}\", stdout);\n }\n let stderr = String::from_utf8_lossy(&output.stderr);\n for line in stderr.lines() {\n if line.contains(\"Refused to snapshot\") {\n continue;\n }\n eprintln!(\"{}\", line);\n }\n if !output.status.success() {\n bail!(\"jj {} failed\", args.join(\" \"));\n }\n Ok(())\n}\n\nfn jj_preferred_binary() -> std::path::PathBuf {\n if let Ok(path) = std::env::var(\"FLOW_JJ_BIN\") {\n let candidate = PathBuf::from(path);\n if candidate.exists() {\n return candidate;\n }\n }\n\n if let Ok(home) = std::env::var(\"HOME\") {\n let local_dev_jj = PathBuf::from(home).join(\"repos/jj-vcs/jj/target/release/jj\");\n if local_dev_jj.exists() {\n return local_dev_jj;\n }\n }\n\n PathBuf::from(\"jj\")\n}\n\nfn jj_run_preferred_in(repo_root: &Path, args: &[&str]) -> Result<()> {\n let jj_bin = jj_preferred_binary();\n let output = Command::new(&jj_bin)\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run {} {}\", jj_bin.display(), args.join(\" \")))?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n let stdout = String::from_utf8_lossy(&output.stdout);\n let concise = stderr\n .lines()\n .chain(stdout.lines())\n .map(str::trim)\n .find(|line| !line.is_empty())\n .unwrap_or(\"jj command failed\");\n bail!(\n \"{} {} failed: {}\",\n jj_bin.display(),\n args.join(\" \"),\n concise\n );\n }\n Ok(())\n}\n\nfn jj_bookmark_exists(repo_root: &Path, name: &str) -> bool {\n let output = jj_capture_in(repo_root, &[\"bookmark\", \"list\"]).unwrap_or_default();\n output\n .lines()\n .any(|line| line.trim_start().starts_with(name))\n}\n\nfn jj_bookmark_create_or_set(repo_root: &Path, name: &str, rev: &str) -> Result<()> {\n if jj_bookmark_exists(repo_root, name) {\n return jj_run_in(repo_root, &[\"bookmark\", \"set\", name, \"-r\", rev]);\n }\n\n match jj_run_in(repo_root, &[\"bookmark\", \"create\", name, \"-r\", rev]) {\n Ok(()) => Ok(()),\n Err(create_err) => {\n if jj_bookmark_exists(repo_root, name) {\n jj_run_in(repo_root, &[\"bookmark\", \"set\", name, \"-r\", rev]).with_context(|| {\n format!(\"create failed ({create_err}); bookmark exists, but set also failed\")\n })\n } else {\n Err(create_err)\n }\n }\n }\n}\n\nfn jj_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"jj\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .with_context(|| format!(\"failed to run jj {}\", args.join(\" \")))?;\n if !output.status.success() {\n bail!(\"jj {} failed\", args.join(\" \"));\n }\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nfn jj_revset_string_literal(value: &str) -> String {\n serde_json::to_string(value).unwrap_or_else(|_| format!(\"\\\"{}\\\"\", value))\n}\n\nfn jj_local_bookmark_revset(name: &str) -> String {\n format!(\n \"bookmarks(exact:{}) & mutable()\",\n jj_revset_string_literal(name)\n )\n}\n\nfn jj_branch_sync_source_rev(repo_root: &Path, branch: &str) -> String {\n if jj_bookmark_exists(repo_root, branch) {\n jj_local_bookmark_revset(branch)\n } else {\n \"@\".to_string()\n }\n}\n\nfn jj_has_divergence(repo_root: &Path, source_revset: &str, dest: &str) -> Result<bool> {\n let revset = format!(\"({})..({})\", dest, source_revset);\n let output = jj_capture_in(\n repo_root,\n &[\"log\", \"-r\", &revset, \"--no-graph\", \"-T\", \"commit_id\"],\n )?;\n Ok(!output.trim().is_empty())\n}\n\nfn branch_tip_matches_remote(repo_root: &Path, branch: &str, remote: &str) -> bool {\n let local_ref = format!(\"refs/heads/{}\", branch);\n let remote_ref = format!(\"refs/remotes/{}/{}\", remote, branch);\n let local_sha = match git_capture_in(repo_root, &[\"rev-parse\", &local_ref]) {\n Ok(value) => value.trim().to_string(),\n Err(_) => return false,\n };\n let remote_sha = match git_capture_in(repo_root, &[\"rev-parse\", &remote_ref]) {\n Ok(value) => value.trim().to_string(),\n Err(_) => return false,\n };\n !local_sha.is_empty() && local_sha == remote_sha\n}\n\nfn jj_stash_commits(repo_root: &Path, current: &str, dest: &str) -> Result<String> {\n let ts = Utc::now().format(\"%Y%m%d-%H%M%S\").to_string();\n let stash_name = format!(\"f-sync-stash/{}/{}\", current, ts);\n let source_revset = jj_branch_sync_source_rev(repo_root, current);\n jj_run_in(\n repo_root,\n &[\"bookmark\", \"create\", &stash_name, \"-r\", &source_revset],\n )?;\n jj_run_in(repo_root, &[\"bookmark\", \"set\", current, \"-r\", dest])?;\n jj_run_in(repo_root, &[\"edit\", current])?;\n Ok(stash_name)\n}\n\n/// Check if a rebase is in progress.\nfn is_rebase_in_progress() -> bool {\n let git_dir = git_capture(&[\"rev-parse\", \"--git-dir\"]).unwrap_or_else(|_| \".git\".to_string());\n let git_dir = git_dir.trim();\n std::path::Path::new(&format!(\"{}/rebase-merge\", git_dir)).exists()\n || std::path::Path::new(&format!(\"{}/rebase-apply\", git_dir)).exists()\n}\n\n/// Check if a merge is in progress.\nfn is_merge_in_progress() -> bool {\n let git_dir = git_capture(&[\"rev-parse\", \"--git-dir\"]).unwrap_or_else(|_| \".git\".to_string());\n let git_dir = git_dir.trim();\n std::path::Path::new(&format!(\"{}/MERGE_HEAD\", git_dir)).exists()\n}\n\n/// Read a single keypress (y/n) without waiting for Enter.\nfn read_yes_no() -> Result<bool> {\n terminal::enable_raw_mode()?;\n let result = loop {\n if event::poll(std::time::Duration::from_millis(100))? {\n if let Event::Key(key) = event::read()? {\n if key.kind == KeyEventKind::Press {\n match key.code {\n KeyCode::Char('y') | KeyCode::Char('Y') => break Ok(true),\n KeyCode::Char('n') | KeyCode::Char('N') | KeyCode::Enter | KeyCode::Esc => {\n break Ok(false);\n }\n _ => {}\n }\n }\n }\n }\n };\n terminal::disable_raw_mode()?;\n println!(); // Move to next line after keypress\n result\n}\n\n/// Prompt user for rebase action.\nfn prompt_for_rebase_action() -> Result<bool> {\n let conflicts = git_capture(&[\"diff\", \"--name-only\", \"--diff-filter=U\"]).unwrap_or_default();\n let conflicted_files: Vec<&str> = conflicts.lines().filter(|l| !l.is_empty()).collect();\n\n if !conflicted_files.is_empty() {\n println!(\"\\n Conflicted files:\");\n for file in &conflicted_files {\n println!(\" - {}\", file);\n }\n println!();\n }\n\n print!(\" Try auto-fix with Claude Opus? [y/N] \");\n std::io::Write::flush(&mut std::io::stdout())?;\n\n read_yes_no()\n}\n\n/// Try to resolve rebase conflicts and continue.\nfn try_resolve_rebase_conflicts() -> Result<bool> {\n loop {\n // Get conflicted files\n let conflicts = git_capture(&[\"diff\", \"--name-only\", \"--diff-filter=U\"])?;\n let conflicted_files: Vec<&str> = conflicts.lines().filter(|l| !l.is_empty()).collect();\n\n if conflicted_files.is_empty() {\n // No more conflicts, try to continue rebase\n let result = Command::new(\"git\")\n .args([\"rebase\", \"--continue\"])\n .env(\"GIT_EDITOR\", \"true\") // Skip commit message editing\n .output();\n\n match result {\n Ok(out) if out.status.success() => return Ok(true),\n Ok(out) => {\n let stderr = String::from_utf8_lossy(&out.stderr);\n // Check if rebase is complete\n if stderr.contains(\"No rebase in progress\") || !is_rebase_in_progress() {\n return Ok(true);\n }\n // Still conflicts, continue loop\n }\n Err(_) => return Ok(false),\n }\n continue;\n }\n\n println!(\" Resolving {} conflicted files...\", conflicted_files.len());\n\n // Try to resolve each conflict\n let mut all_resolved = true;\n for file in &conflicted_files {\n if !try_resolve_single_conflict(file)? {\n all_resolved = false;\n println!(\" ✗ Could not resolve {}\", file);\n }\n }\n\n if !all_resolved {\n return Ok(false);\n }\n\n // Stage resolved files\n let _ = git_run(&[\"add\", \"-A\"]);\n\n // Try to continue rebase\n let result = Command::new(\"git\")\n .args([\"rebase\", \"--continue\"])\n .env(\"GIT_EDITOR\", \"true\")\n .output();\n\n match result {\n Ok(out) if out.status.success() => return Ok(true),\n Ok(_) => {\n // More conflicts from next commit, continue loop\n if !is_rebase_in_progress() {\n return Ok(true);\n }\n }\n Err(_) => return Ok(false),\n }\n }\n}\n\n/// Try to resolve a single conflicted file.\nfn try_resolve_single_conflict(file: &str) -> Result<bool> {\n let filename = file.rsplit('/').next().unwrap_or(file);\n\n // Auto-generated files - accept theirs (upstream/incoming)\n let auto_generated = [\n \"STATS.md\",\n \"stats.md\",\n \"CHANGELOG.md\",\n \"changelog.md\",\n \"package-lock.json\",\n \"yarn.lock\",\n \"bun.lock\",\n \"pnpm-lock.yaml\",\n \"Cargo.lock\",\n \"Gemfile.lock\",\n \"poetry.lock\",\n \"composer.lock\",\n ];\n\n if auto_generated\n .iter()\n .any(|&ag| filename.eq_ignore_ascii_case(ag))\n {\n println!(\" Auto-resolving {} (accepting theirs)\", file);\n let _ = Command::new(\"git\")\n .args([\"checkout\", \"--theirs\", file])\n .output();\n let _ = Command::new(\"git\").args([\"add\", file]).output();\n return Ok(true);\n }\n\n // Try Claude for code conflicts\n let content = std::fs::read_to_string(file).unwrap_or_default();\n if content.contains(\"<<<<<<<\") {\n println!(\" Trying Claude Opus for {}...\", file);\n\n // Load sync context if available\n let context = ai_context::load_command_context(\"sync\").unwrap_or_default();\n let context_section = if !context.is_empty() {\n format!(\"## Context\\n\\n{}\\n\\n\", context)\n } else {\n String::new()\n };\n\n let prompt = format!(\n \"{}This file has git merge conflicts. Resolve them by keeping the best of both versions. Output ONLY the resolved file content, no explanations:\\n\\n{}\",\n context_section,\n if content.len() > 8000 {\n &content[..8000]\n } else {\n &content\n }\n );\n\n let output = sync_claude_command(&prompt).output();\n\n if let Ok(out) = output {\n if out.status.success() {\n let resolved = String::from_utf8_lossy(&out.stdout);\n if !resolved.contains(\"<<<<<<<\") && !resolved.contains(\">>>>>>>\") {\n if std::fs::write(file, resolved.as_ref()).is_ok() {\n let _ = Command::new(\"git\").args([\"add\", file]).output();\n println!(\" ✓ Resolved {}\", file);\n return Ok(true);\n }\n }\n }\n }\n }\n\n Ok(false)\n}\n\n/// Prompt user to try auto-fix for push failures.\nfn prompt_for_push_fix() -> Result<bool> {\n println!();\n print!(\" Try auto-fix with Claude Opus? [y/N] \");\n std::io::Write::flush(&mut std::io::stdout())?;\n read_yes_no()\n}\n\n/// Prompt user to try auto-fix for conflicts.\nfn prompt_for_auto_fix() -> Result<bool> {\n // Get list of conflicted files\n let conflicts = git_capture(&[\"diff\", \"--name-only\", \"--diff-filter=U\"])?;\n let conflicted_files: Vec<&str> = conflicts.lines().filter(|l| !l.is_empty()).collect();\n\n if conflicted_files.is_empty() {\n return Ok(false);\n }\n\n println!(\"\\n Conflicted files:\");\n for file in &conflicted_files {\n println!(\" - {}\", file);\n }\n println!();\n\n print!(\" Try auto-fix with Claude Opus? [y/N] \");\n std::io::Write::flush(&mut std::io::stdout())?;\n read_yes_no()\n}\n\n/// Try to resolve merge conflicts automatically.\nfn try_resolve_conflicts() -> Result<bool> {\n // Get list of conflicted files\n let conflicts = git_capture(&[\"diff\", \"--name-only\", \"--diff-filter=U\"])?;\n let conflicted_files: Vec<&str> = conflicts.lines().filter(|l| !l.is_empty()).collect();\n\n if conflicted_files.is_empty() {\n return Ok(true);\n }\n\n println!(\" Conflicted files: {}\", conflicted_files.join(\", \"));\n\n // Auto-generated files - accept theirs (upstream)\n let auto_generated = [\n \"STATS.md\",\n \"stats.md\",\n \"CHANGELOG.md\",\n \"changelog.md\",\n \"package-lock.json\",\n \"yarn.lock\",\n \"bun.lock\",\n \"pnpm-lock.yaml\",\n \"Cargo.lock\",\n \"Gemfile.lock\",\n \"poetry.lock\",\n \"composer.lock\",\n ];\n\n let mut resolved_count = 0;\n let mut needs_claude = Vec::new();\n\n for file in &conflicted_files {\n let filename = file.rsplit('/').next().unwrap_or(file);\n\n if auto_generated\n .iter()\n .any(|&ag| filename.eq_ignore_ascii_case(ag))\n {\n // Accept theirs for auto-generated files\n println!(\" Auto-resolving {} (accepting upstream)\", file);\n let _ = Command::new(\"git\")\n .args([\"checkout\", \"--theirs\", file])\n .output();\n let _ = Command::new(\"git\").args([\"add\", file]).output();\n resolved_count += 1;\n } else {\n needs_claude.push(*file);\n }\n }\n\n // If all conflicts were auto-generated files, we're done\n if needs_claude.is_empty() {\n return Ok(true);\n }\n\n // Try Claude for remaining conflicts\n println!(\n \" Trying Claude Opus for {} remaining conflicts...\",\n needs_claude.len()\n );\n\n // Load sync context once for all files\n let context = ai_context::load_command_context(\"sync\").unwrap_or_default();\n let context_section = if !context.is_empty() {\n format!(\"## Context\\n\\n{}\\n\\n\", context)\n } else {\n String::new()\n };\n\n for file in &needs_claude {\n let content = std::fs::read_to_string(file).unwrap_or_default();\n if content.contains(\"<<<<<<<\") {\n let prompt = format!(\n \"{}This file has git merge conflicts. Resolve them by keeping the best of both versions. Output ONLY the resolved file content, no explanations:\\n\\n{}\",\n context_section,\n if content.len() > 8000 {\n &content[..8000]\n } else {\n &content\n }\n );\n\n let output = sync_claude_command(&prompt).output();\n\n if let Ok(out) = output {\n if out.status.success() {\n let resolved = String::from_utf8_lossy(&out.stdout);\n // Only use if it doesn't contain conflict markers\n if !resolved.contains(\"<<<<<<<\") && !resolved.contains(\">>>>>>>\") {\n if std::fs::write(file, resolved.as_ref()).is_ok() {\n let _ = Command::new(\"git\").args([\"add\", file]).output();\n resolved_count += 1;\n println!(\" ✓ Resolved {}\", file);\n continue;\n }\n }\n }\n }\n println!(\" ✗ Could not resolve {}\", file);\n }\n }\n\n Ok(resolved_count == conflicted_files.len())\n}\n\nfn restore_stash(repo_root: &Path, stashed: bool) {\n if stashed {\n println!(\"==> Restoring stashed changes...\");\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args([\"stash\", \"pop\"])\n .output();\n match output {\n Ok(out) if out.status.success() => {}\n Ok(out) => {\n let stdout = String::from_utf8_lossy(&out.stdout);\n let stderr = String::from_utf8_lossy(&out.stderr);\n let combined = format!(\"{}\\n{}\", stdout, stderr).to_lowercase();\n if stash_pop_untracked_conflict(&combined) {\n match drop_stash_if_untracked_restored(repo_root) {\n Ok(true) => {\n println!(\n \" ✓ Kept local untracked files and dropped redundant auto-stash\"\n );\n return;\n }\n Ok(false) => {}\n Err(err) => {\n eprintln!(\"warning: stash cleanup failed: {}\", err);\n }\n }\n }\n eprintln!(\n \"warning: failed to restore stash automatically: git stash pop failed\\nRun `git stash list` and restore manually if needed.\"\n );\n }\n Err(err) => {\n eprintln!(\n \"warning: failed to restore stash automatically: {}\\nRun `git stash list` and restore manually if needed.\",\n err\n );\n }\n }\n }\n}\n\nfn stash_pop_untracked_conflict(output: &str) -> bool {\n output.contains(\"could not restore untracked files from stash\")\n || (output.contains(\"already exists, no checkout\") && output.contains(\"stash\"))\n}\n\nfn drop_stash_if_untracked_restored(repo_root: &Path) -> Result<bool> {\n if git_capture_in(repo_root, &[\"rev-parse\", \"--verify\", \"stash@{0}\"]).is_err() {\n return Ok(false);\n }\n\n let has_untracked_parent = git_capture_in(repo_root, &[\"rev-parse\", \"--verify\", \"stash@{0}^3\"]);\n if has_untracked_parent.is_err() {\n return Ok(false);\n }\n\n let files = git_capture_in(repo_root, &[\"ls-tree\", \"-r\", \"--name-only\", \"stash@{0}^3\"])\n .unwrap_or_default();\n let untracked_paths: Vec<String> = files\n .lines()\n .map(str::trim)\n .filter(|line| !line.is_empty())\n .map(|line| line.to_string())\n .collect();\n if untracked_paths.is_empty() {\n return Ok(false);\n }\n\n let all_present = untracked_paths\n .iter()\n .all(|path| repo_root.join(path).exists());\n if !all_present {\n return Ok(false);\n }\n\n git_run_in(repo_root, &[\"stash\", \"drop\", \"stash@{0}\"])?;\n Ok(true)\n}\n\n/// If fork-push is enabled in config, resolve the target remote name, owner, and fork repo name.\n///\n/// Returns `Some((remote_name, owner, fork_repo_name))` when fork push should be used.\nfn resolve_fork_push_target(repo_root: &Path) -> Option<(String, String, String)> {\n // Check local config first, then global.\n let cfg = {\n let local = repo_root.join(\"flow.toml\");\n if local.exists() {\n config::load(&local).ok()\n } else {\n None\n }\n .or_else(|| {\n let global = config::default_config_path();\n if global.exists() {\n config::load(&global).ok()\n } else {\n None\n }\n })\n };\n let git_cfg = cfg.as_ref().and_then(|c| c.git.as_ref());\n if git_cfg.map(|g| g.fork_push.unwrap_or(false)) != Some(true) {\n return None;\n }\n let git_cfg = git_cfg.unwrap();\n\n let owner = push::resolve_fork_owner(git_cfg.fork_push_owner.as_deref()).ok()?;\n let suffix = git_cfg.fork_push_suffix.as_deref().unwrap_or(\"-i\");\n\n // Derive base repo name from upstream or origin URL.\n let upstream_url = git_capture_in(repo_root, &[\"remote\", \"get-url\", \"upstream\"])\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty());\n let origin_url = git_capture_in(repo_root, &[\"remote\", \"get-url\", \"origin\"])\n .ok()\n .map(|s| s.trim().to_string())\n .filter(|s| !s.is_empty());\n let base_name =\n push::derive_repo_name(repo_root, upstream_url.as_deref(), origin_url.as_deref()).ok()?;\n\n let fork_repo = format!(\"{}{}\", base_name, suffix);\n let remote_name = format!(\"fork{}\", suffix);\n Some((remote_name, owner, fork_repo))\n}\n\n/// Normalize a git URL for comparison (handle ssh vs https, trailing .git).\nfn normalize_git_url(url: &str) -> String {\n let url = url.trim();\n // Convert SSH to HTTPS format for comparison\n let url = if url.starts_with(\"git@github.com:\") {\n url.replace(\"git@github.com:\", \"github.com/\")\n } else if url.starts_with(\"https://github.com/\") {\n url.replace(\"https://github.com/\", \"github.com/\")\n } else {\n url.to_string()\n };\n // Remove trailing .git\n url.trim_end_matches(\".git\").to_lowercase()\n}\n\n#[derive(Default)]\nstruct GitCaptureCacheState {\n depth: usize,\n entries: HashMap<String, String>,\n}\n\nthread_local! {\n static GIT_CAPTURE_CACHE: RefCell<GitCaptureCacheState> = RefCell::new(GitCaptureCacheState::default());\n}\n\nstruct GitCaptureCacheScope;\n\nimpl GitCaptureCacheScope {\n fn begin() -> Self {\n GIT_CAPTURE_CACHE.with(|state| {\n let mut state = state.borrow_mut();\n if state.depth == 0 {\n state.entries.clear();\n }\n state.depth += 1;\n });\n Self\n }\n}\n\nimpl Drop for GitCaptureCacheScope {\n fn drop(&mut self) {\n GIT_CAPTURE_CACHE.with(|state| {\n let mut state = state.borrow_mut();\n state.depth = state.depth.saturating_sub(1);\n if state.depth == 0 {\n state.entries.clear();\n }\n });\n }\n}\n\nfn git_capture_cacheable(args: &[&str]) -> bool {\n args == [\"rev-parse\", \"--show-toplevel\"]\n || args == [\"rev-parse\", \"--git-dir\"]\n || (args.len() == 3 && args[0] == \"remote\" && args[1] == \"get-url\")\n}\n\nfn git_capture_cache_key(repo_root: Option<&Path>, args: &[&str]) -> Option<String> {\n if !git_capture_cacheable(args) {\n return None;\n }\n\n let cwd = repo_root\n .map(|p| p.to_string_lossy().into_owned())\n .unwrap_or_default();\n Some(format!(\"{cwd}|{}\", args.join(\"\\x1f\")))\n}\n\nfn git_capture_cached_lookup(key: &str) -> Option<String> {\n GIT_CAPTURE_CACHE.with(|state| {\n let state = state.borrow();\n if state.depth == 0 {\n return None;\n }\n state.entries.get(key).cloned()\n })\n}\n\nfn git_capture_cached_store(key: String, value: String) {\n GIT_CAPTURE_CACHE.with(|state| {\n let mut state = state.borrow_mut();\n if state.depth > 0 {\n state.entries.insert(key, value);\n }\n });\n}\n\n/// Run a git command and capture stdout.\nfn git_capture(args: &[&str]) -> Result<String> {\n if let Some(key) = git_capture_cache_key(None, args) {\n if let Some(cached) = git_capture_cached_lookup(&key) {\n return Ok(cached);\n }\n }\n\n let output = Command::new(\"git\")\n .args(args)\n .output()\n .context(\"failed to run git\")?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"git {} failed: {}\", args.join(\" \"), stderr.trim());\n }\n\n let out = String::from_utf8_lossy(&output.stdout).to_string();\n if let Some(key) = git_capture_cache_key(None, args) {\n git_capture_cached_store(key, out.clone());\n }\n Ok(out)\n}\n\n/// Run a git command in a specific repository and capture stdout.\nfn git_capture_in(repo_root: &Path, args: &[&str]) -> Result<String> {\n if let Some(key) = git_capture_cache_key(Some(repo_root), args) {\n if let Some(cached) = git_capture_cached_lookup(&key) {\n return Ok(cached);\n }\n }\n\n let output = Command::new(\"git\")\n .current_dir(repo_root)\n .args(args)\n .output()\n .context(\"failed to run git\")?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"git {} failed: {}\", args.join(\" \"), stderr.trim());\n }\n\n let out = String::from_utf8_lossy(&output.stdout).to_string();\n if let Some(key) = git_capture_cache_key(Some(repo_root), args) {\n git_capture_cached_store(key, out.clone());\n }\n Ok(out)\n}\n\n/// Run a git command with inherited stdio.\nfn git_run(args: &[&str]) -> Result<()> {\n let status = Command::new(\"git\")\n .args(args)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run git\")?;\n\n if !status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n\n Ok(())\n}\n\n/// Run a git command in a specific repository with inherited stdio.\nfn git_run_in(repo_root: &Path, args: &[&str]) -> Result<()> {\n let status = Command::new(\"git\")\n .current_dir(repo_root)\n .args(args)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run git\")?;\n\n if !status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n\n Ok(())\n}\n\n/// Push to a remote with optional auto-fix on failure.\nfn push_with_autofix(branch: &str, remote: &str, auto_fix: bool, max_attempts: u32) -> Result<()> {\n let mut attempts = 0;\n\n loop {\n // Try push and capture output\n let output = Command::new(\"git\")\n .args([\"push\", remote, branch])\n .output()\n .context(\"failed to run git push\")?;\n\n if output.status.success() {\n return Ok(());\n }\n\n attempts += 1;\n let stderr = String::from_utf8_lossy(&output.stderr);\n let stdout = String::from_utf8_lossy(&output.stdout);\n let combined = format!(\"{}\\n{}\", stdout, stderr);\n\n // Check if this looks like a pre-push hook failure\n let is_hook_failure = combined.contains(\"pre-push\")\n || combined.contains(\"husky\")\n || combined.contains(\"typecheck\")\n || combined.contains(\"error TS\")\n || combined.contains(\"eslint\")\n || combined.contains(\"error:\")\n || combined.contains(\"failed to push\");\n\n // Prompt user if not already in auto-fix mode\n let should_fix = if auto_fix {\n true\n } else if is_hook_failure && attempts == 1 {\n println!(\"{}\", combined);\n prompt_for_push_fix()?\n } else {\n false\n };\n\n if !should_fix || attempts > max_attempts {\n if !should_fix {\n println!(\"{}\", combined);\n }\n bail!(\"git push {} {} failed\", remote, branch);\n }\n\n println!(\n \"\\n==> Push failed (attempt {}/{}), attempting auto-fix with Claude Opus...\",\n attempts, max_attempts\n );\n\n // Run Claude to fix the errors (fallback to opencode glm if Claude fails)\n let mut fixed = try_claude_fix(&combined)?;\n if !fixed {\n println!(\" Claude fix failed; trying opencode glm...\");\n fixed = try_opencode_fix(&combined)?;\n }\n if !fixed {\n println!(\"{}\", combined);\n bail!(\"Auto-fix failed. Run manually:\\n claude 'fix these errors: ...'\");\n }\n\n // Stage and commit the fix\n let status = git_capture(&[\"status\", \"--porcelain\"])?;\n if !status.trim().is_empty() {\n println!(\"==> Committing auto-fix...\");\n let _ = git_run(&[\"add\", \"-A\"]);\n let commit_msg = format!(\"fix: auto-fix sync errors (attempt {})\", attempts);\n let _ = Command::new(\"git\")\n .args([\"commit\", \"-m\", &commit_msg, \"--no-verify\"])\n .output();\n }\n\n println!(\"==> Retrying push...\");\n }\n}\n\n/// Push to a remote with --force-with-lease, with optional auto-fix on failure.\nfn push_with_autofix_force(\n branch: &str,\n remote: &str,\n auto_fix: bool,\n max_attempts: u32,\n) -> Result<()> {\n let mut attempts = 0;\n\n loop {\n let output = Command::new(\"git\")\n .args([\"push\", \"--force-with-lease\", remote, branch])\n .output()\n .context(\"failed to run git push --force-with-lease\")?;\n\n if output.status.success() {\n return Ok(());\n }\n\n attempts += 1;\n let stderr = String::from_utf8_lossy(&output.stderr);\n let stdout = String::from_utf8_lossy(&output.stdout);\n let combined = format!(\"{}\\n{}\", stdout, stderr);\n\n let is_hook_failure = combined.contains(\"pre-push\")\n || combined.contains(\"husky\")\n || combined.contains(\"typecheck\")\n || combined.contains(\"error TS\")\n || combined.contains(\"eslint\")\n || combined.contains(\"error:\")\n || combined.contains(\"failed to push\");\n\n let should_fix = if auto_fix {\n true\n } else if is_hook_failure && attempts == 1 {\n println!(\"{}\", combined);\n prompt_for_push_fix()?\n } else {\n false\n };\n\n if !should_fix || attempts > max_attempts {\n if !should_fix {\n println!(\"{}\", combined);\n }\n bail!(\"git push --force-with-lease {} {} failed\", remote, branch);\n }\n\n println!(\n \"\\n==> Push failed (attempt {}/{}), attempting auto-fix with Claude Opus...\",\n attempts, max_attempts\n );\n\n let mut fixed = try_claude_fix(&combined)?;\n if !fixed {\n println!(\" Claude fix failed; trying opencode glm...\");\n fixed = try_opencode_fix(&combined)?;\n }\n\n if fixed {\n println!(\" Changes applied. Retrying push...\");\n } else {\n bail!(\"auto-fix failed; push still failing\");\n }\n }\n}\n\n/// Try to fix errors using Claude CLI.\nfn try_claude_fix(error_output: &str) -> Result<bool> {\n // Check if claude is available\n let claude_check = Command::new(\"which\").arg(\"claude\").output();\n\n if claude_check.is_err() || !claude_check.unwrap().status.success() {\n println!(\" Claude CLI not found. Install with: npm i -g @anthropic-ai/claude-code\");\n return Ok(false);\n }\n\n let prompt = build_fix_prompt(error_output);\n\n // Run claude with the fix prompt\n let status = sync_claude_command(&prompt)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run claude\")?;\n\n Ok(status.success())\n}\n\nfn try_opencode_fix(error_output: &str) -> Result<bool> {\n let opencode_check = Command::new(\"which\").arg(\"opencode\").output();\n if opencode_check.is_err() || !opencode_check.unwrap().status.success() {\n println!(\" opencode CLI not found. Install with: npm i -g opencode\");\n return Ok(false);\n }\n\n let prompt = build_fix_prompt(error_output);\n let mut child = Command::new(\"opencode\")\n .args([\"run\", \"-m\", \"opencode/glm-4.7-free\", \"-\"])\n .stdin(Stdio::piped())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .spawn()\n .context(\"failed to run opencode\")?;\n\n if let Some(stdin) = child.stdin.as_mut() {\n use std::io::Write;\n stdin\n .write_all(prompt.as_bytes())\n .context(\"failed to write opencode prompt\")?;\n }\n\n let status = child.wait().context(\"failed to wait on opencode\")?;\n Ok(status.success())\n}\n\nfn build_fix_prompt(error_output: &str) -> String {\n let excerpt = if error_output.len() > 4000 {\n &error_output[error_output.len() - 4000..]\n } else {\n error_output\n };\n format!(\n \"Fix these errors so the code compiles/passes checks. Make minimal changes. Do not explain, just fix:\\n\\n{}\",\n excerpt\n )\n}\n\n/// Try to create the origin repo on GitHub if it doesn't exist.\nfn try_create_origin_repo() -> Result<bool> {\n let origin_url = match git_capture(&[\"remote\", \"get-url\", \"origin\"]) {\n Ok(url) => url.trim().to_string(),\n Err(_) => return Ok(false),\n };\n\n let repo_path = if origin_url.starts_with(\"git@github.com:\") {\n origin_url\n .strip_prefix(\"git@github.com:\")\n .and_then(|s| s.strip_suffix(\".git\").or(Some(s)))\n } else if origin_url.contains(\"github.com/\") {\n origin_url\n .split(\"github.com/\")\n .nth(1)\n .and_then(|s| s.strip_suffix(\".git\").or(Some(s)))\n } else {\n None\n };\n\n let Some(repo_path) = repo_path else {\n println!(\"Cannot parse origin URL for auto-creation: {}\", origin_url);\n return Ok(false);\n };\n\n println!(\"\\nOrigin repo doesn't exist. Creating: {}\", repo_path);\n\n let status = Command::new(\"gh\")\n .args([\"repo\", \"create\", repo_path, \"--private\", \"--source=.\"])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status();\n\n match status {\n Ok(s) if s.success() => {\n println!(\"✓ Created GitHub repo: {}\", repo_path);\n Ok(true)\n }\n Ok(_) => {\n println!(\"Failed to create repo. Is `gh` installed and authenticated?\");\n Ok(false)\n }\n Err(e) => {\n println!(\"Failed to run gh CLI: {}\", e);\n Ok(false)\n }\n }\n}\n\nfn sync_log_dirs() -> Vec<PathBuf> {\n let mut dirs = Vec::new();\n if let Some(home) = dirs::home_dir() {\n dirs.push(home.join(\"code\").join(\"org\").join(\"linsa\").join(\"base\"));\n dirs.push(home.join(\"repos\").join(\"garden-co\").join(\"jazz2\"));\n dirs.push(home.join(\"code\").join(\"org\").join(\"1f\").join(\"jazz2\"));\n }\n dirs\n}\n\nfn write_sync_snapshot(snapshot: &SyncSnapshot) -> Result<()> {\n let mut value = serde_json::to_value(snapshot)?;\n secret_redact::redact_json_value(&mut value);\n let payload = serde_json::to_string(&value)?;\n for base in sync_log_dirs() {\n let target_dir = base.join(\"sync\");\n if !target_dir.exists() {\n if let Err(err) = fs::create_dir_all(&target_dir) {\n eprintln!(\n \"warn: unable to create sync log dir {}: {}\",\n target_dir.display(),\n err\n );\n continue;\n }\n }\n let log_path = target_dir.join(\"flow-sync.jsonl\");\n let mut file = fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(&log_path)\n .with_context(|| format!(\"open sync log {}\", log_path.display()))?;\n writeln!(file, \"{}\", payload)?;\n }\n Ok(())\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn parse_branch_merge_ref_strips_heads_prefix() {\n assert_eq!(\n parse_branch_merge_ref(\"refs/heads/feature/socket-command\"),\n Some(\"feature/socket-command\".to_string())\n );\n assert_eq!(parse_branch_merge_ref(\"main\"), Some(\"main\".to_string()));\n }\n\n #[test]\n fn parse_tracking_ref_parses_remote_and_branch() {\n assert_eq!(\n parse_tracking_ref(\"fork/socket-command\"),\n Some((\"fork\".to_string(), \"socket-command\".to_string()))\n );\n assert_eq!(\n parse_tracking_ref(\"origin/feature/latency/tune\"),\n Some((\"origin\".to_string(), \"feature/latency/tune\".to_string()))\n );\n }\n\n #[test]\n fn parse_tracking_ref_rejects_invalid_values() {\n assert_eq!(parse_tracking_ref(\"\"), None);\n assert_eq!(parse_tracking_ref(\"origin\"), None);\n assert_eq!(parse_tracking_ref(\"/main\"), None);\n assert_eq!(parse_tracking_ref(\"origin/\"), None);\n }\n\n #[test]\n fn jj_local_bookmark_revset_uses_exact_mutable_selector() {\n assert_eq!(\n jj_local_bookmark_revset(\"main\"),\n r#\"bookmarks(exact:\"main\") & mutable()\"#\n );\n assert_eq!(\n jj_local_bookmark_revset(\"feature/sync-fix\"),\n r#\"bookmarks(exact:\"feature/sync-fix\") & mutable()\"#\n );\n }\n\n #[test]\n fn normalize_sync_commit_line_fills_missing_description() {\n assert_eq!(\n normalize_sync_commit_line(\"abc12345\", \"Fix sync output\"),\n \"abc12345 Fix sync output\"\n );\n assert_eq!(\n normalize_sync_commit_line(\"abc12345\", \"\"),\n \"abc12345 (no description)\"\n );\n }\n\n #[test]\n fn build_synced_commit_list_dedupes_hash_width_variants() {\n let cmd = SyncCommand {\n rebase: false,\n push: false,\n no_push: true,\n stash: false,\n stash_commits: false,\n allow_queue: false,\n create_repo: false,\n fix: false,\n no_fix: true,\n max_fix_attempts: 0,\n allow_review_issues: false,\n compact: false,\n };\n let mut recorder = SyncRecorder::new(&cmd).expect(\"sync recorder\");\n recorder.add_remote_update(SyncRemoteUpdate {\n remote: \"origin\".to_string(),\n branch: \"main\".to_string(),\n before_tip: Some(\"before\".to_string()),\n after_tip: \"after\".to_string(),\n commit_count: 1,\n commits: vec![\"8e258eb3f feat: persist latest model\".to_string()],\n });\n recorder.add_remote_update(SyncRemoteUpdate {\n remote: \"synced:upstream\".to_string(),\n branch: \"main\".to_string(),\n before_tip: Some(\"before\".to_string()),\n after_tip: \"after\".to_string(),\n commit_count: 1,\n commits: vec![\"8e258eb3 feat: persist latest model\".to_string()],\n });\n\n assert_eq!(\n build_synced_commit_list(&recorder),\n vec![\"8e258eb3f feat: persist latest model\".to_string()]\n );\n }\n\n #[test]\n fn sync_claude_command_uses_latest_opus_alias() {\n let cmd = sync_claude_command(\"resolve this\");\n let args: Vec<String> = cmd\n .get_args()\n .map(|arg| arg.to_string_lossy().into_owned())\n .collect();\n\n assert_eq!(\n args,\n vec![\n \"--print\",\n \"--model\",\n \"opus\",\n \"--dangerously-skip-permissions\",\n \"resolve this\",\n ]\n );\n }\n}\n" }, { "path": "src/task_failure_agents.rs", "content": "use std::collections::HashMap;\nuse std::fs;\nuse std::io::IsTerminal;\nuse std::path::Path;\nuse std::process::{Command, Stdio};\n\nuse anyhow::Result;\nuse serde::Deserialize;\n\nuse crate::config;\n\n#[derive(Debug, Clone)]\nstruct TaskFailureSettings {\n enabled: bool,\n tool: String,\n max_lines: usize,\n max_chars: usize,\n max_agents: usize,\n}\n\nimpl Default for TaskFailureSettings {\n fn default() -> Self {\n Self {\n enabled: false,\n tool: \"hive\".to_string(),\n max_lines: 80,\n max_chars: 8000,\n max_agents: 2,\n }\n }\n}\n\n#[derive(Debug, Deserialize)]\nstruct HiveConfig {\n agents: Option<HashMap<String, HiveAgentSpec>>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct HiveAgentSpec {\n #[serde(rename = \"matchedOn\")]\n matched_on: Option<Vec<String>>,\n}\n\nfn load_settings() -> TaskFailureSettings {\n let mut settings = TaskFailureSettings::default();\n if let Some(ts_config) = config::load_ts_config() {\n if let Some(flow) = ts_config.flow {\n if let Some(task_failure) = flow.task_failure_agents {\n if let Some(enabled) = task_failure.enabled {\n settings.enabled = enabled;\n }\n if let Some(tool) = task_failure.tool {\n if !tool.trim().is_empty() {\n settings.tool = tool;\n }\n }\n if let Some(max_lines) = task_failure.max_lines {\n settings.max_lines = max_lines.max(1);\n }\n if let Some(max_chars) = task_failure.max_chars {\n settings.max_chars = max_chars.max(100);\n }\n if let Some(max_agents) = task_failure.max_agents {\n settings.max_agents = max_agents.max(1);\n }\n }\n }\n }\n settings\n}\n\nfn load_hive_config() -> Option<HiveConfig> {\n let path = dirs::home_dir()?.join(\".hive/config.json\");\n let content = fs::read_to_string(path).ok()?;\n serde_json::from_str(&content).ok()\n}\n\nfn truncate_output(output: &str, max_lines: usize, max_chars: usize) -> String {\n let mut lines: Vec<&str> = output.lines().collect();\n if lines.len() > max_lines {\n lines = lines[lines.len().saturating_sub(max_lines)..].to_vec();\n }\n let mut joined = lines.join(\"\\n\");\n if joined.len() > max_chars {\n let start = joined.len().saturating_sub(max_chars);\n joined = format!(\"...{}\", &joined[start..]);\n }\n joined\n}\n\nfn matches_agent(haystack: &str, spec: &HiveAgentSpec) -> bool {\n let Some(terms) = &spec.matched_on else {\n return false;\n };\n terms.iter().any(|term| {\n let needle = term.to_lowercase();\n !needle.is_empty() && haystack.contains(&needle)\n })\n}\n\nfn run_hive_agent(agent: &str, prompt: &str) -> Result<()> {\n let status = Command::new(\"hive\")\n .arg(\"agent\")\n .arg(agent)\n .arg(prompt)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()?;\n if !status.success() {\n eprintln!(\n \"⚠ hive agent '{}' exited with status {:?}\",\n agent,\n status.code()\n );\n }\n Ok(())\n}\n\npub fn maybe_run_task_failure_agents(\n task_name: &str,\n command: &str,\n workdir: &Path,\n output: &str,\n status: Option<i32>,\n) {\n if let Ok(value) = std::env::var(\"FLOW_TASK_FAILURE_AGENTS\") {\n let lowered = value.trim().to_lowercase();\n if lowered == \"0\" || lowered == \"false\" || lowered == \"off\" {\n return;\n }\n }\n if std::env::var(\"FLOW_DISABLE_TASK_FAILURE_AGENTS\").is_ok() {\n return;\n }\n\n let settings = load_settings();\n if !settings.enabled {\n return;\n }\n if settings.tool != \"hive\" {\n eprintln!(\n \"⚠ task-failure agents: unsupported tool '{}'\",\n settings.tool\n );\n return;\n }\n if !std::io::stdin().is_terminal() {\n return;\n }\n if which::which(\"hive\").is_err() {\n eprintln!(\"⚠ task-failure agents: hive not found on PATH\");\n return;\n }\n\n let Some(config) = load_hive_config() else {\n eprintln!(\"⚠ task-failure agents: ~/.hive/config.json not found\");\n return;\n };\n\n let truncated = truncate_output(output, settings.max_lines, settings.max_chars);\n let mut haystack = String::new();\n haystack.push_str(&format!(\n \"task: {}\\ncommand: {}\\nstatus: {}\\nworkdir: {}\\noutput:\\n{}\",\n task_name,\n command,\n status.unwrap_or(-1),\n workdir.display(),\n truncated\n ));\n let haystack_lower = haystack.to_lowercase();\n\n let mut matches: Vec<String> = Vec::new();\n if let Some(agents) = config.agents {\n for (name, spec) in agents {\n if matches_agent(&haystack_lower, &spec) {\n matches.push(name);\n }\n }\n }\n\n if matches.is_empty() {\n return;\n }\n\n matches.truncate(settings.max_agents);\n for agent in matches {\n println!(\"Running agent '{}' for task failure...\", agent);\n if let Err(err) = run_hive_agent(&agent, &haystack) {\n eprintln!(\"⚠ failed to run hive agent '{}': {}\", agent, err);\n }\n }\n}\n" }, { "path": "src/task_match.rs", "content": "//! Match user query to a task using LM Studio.\n\nuse std::io::{self, Write};\nuse std::path::PathBuf;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::Cli;\nuse crate::{\n cli::TaskRunOpts, config, discover::DiscoveredTask, lmstudio,\n project_snapshot::ProjectSnapshot, tasks,\n};\nuse clap::{CommandFactory, Parser};\n\n/// Options for the match command.\n#[derive(Debug, Clone)]\npub struct MatchOpts {\n /// The user's query as separate arguments (preserves quoting from shell).\n pub args: Vec<String>,\n /// LM Studio model to use.\n pub model: Option<String>,\n /// LM Studio API port.\n pub port: Option<u16>,\n /// Whether to actually run the matched task.\n pub execute: bool,\n}\n\n/// Result of matching a query to a task.\n#[derive(Debug)]\npub struct MatchResult {\n pub task_name: String,\n pub config_path: PathBuf,\n pub relative_dir: String,\n}\n\n// Built-in commands that can be run directly if no task matches\nconst BUILTIN_COMMANDS: &[(&str, &[&str])] = &[(\"commit\", &[\"commit\", \"c\"])];\n\nfn cli_subcommands() -> Vec<String> {\n let mut names = Vec::new();\n let cmd = Cli::command();\n for sub in cmd.get_subcommands() {\n names.push(sub.get_name().to_string());\n for alias in sub.get_all_aliases() {\n names.push(alias.to_string());\n }\n }\n names.extend([\"help\", \"-h\", \"--help\"].iter().map(|s| s.to_string()));\n names\n}\n\nfn run_builtin(name: &str, execute: bool) -> Result<()> {\n match name {\n \"commit\" => {\n println!(\"Running: commit\");\n if execute {\n let queue = crate::commit::resolve_commit_queue_mode(false, false);\n let push = true;\n crate::commit::run(push, queue, false, &[])?;\n }\n }\n _ => bail!(\"Unknown built-in: {}\", name),\n }\n Ok(())\n}\n\nfn find_builtin(query: &str) -> Option<&'static str> {\n let q = query.trim().to_lowercase();\n for (name, aliases) in BUILTIN_COMMANDS {\n if aliases.iter().any(|a| *a == q) {\n return Some(name);\n }\n }\n None\n}\n\n/// Check if the first arg is a CLI subcommand that needs pass-through\nfn is_cli_subcommand(args: &[String]) -> bool {\n let Some(first) = args.first() else {\n return false;\n };\n let first_lower = first.to_ascii_lowercase();\n cli_subcommands()\n .iter()\n .any(|cmd| cmd.eq_ignore_ascii_case(&first_lower))\n}\n\nfn should_passthrough_cli(args: &[String]) -> bool {\n if args.is_empty() {\n return false;\n }\n if args[0].eq_ignore_ascii_case(\"match\") {\n return false;\n }\n\n let mut argv = Vec::with_capacity(args.len() + 1);\n argv.push(\"f\".to_string());\n argv.extend(args.iter().cloned());\n Cli::try_parse_from(argv).is_ok() || is_cli_subcommand(args)\n}\n\n/// Re-invoke the CLI with the original arguments (bypassing match)\nfn passthrough_to_cli(args: &[String]) -> Result<()> {\n use std::process::Command;\n\n let exe = std::env::current_exe().context(\"failed to get current executable\")?;\n\n let status = Command::new(&exe)\n .args(args)\n .status()\n .with_context(|| format!(\"failed to run: {} {}\", exe.display(), args.join(\" \")))?;\n\n if !status.success() {\n std::process::exit(status.code().unwrap_or(1));\n }\n Ok(())\n}\n\n/// Match a user query to a task and optionally execute it.\npub fn run(opts: MatchOpts) -> Result<()> {\n let root = std::env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\"));\n let snapshot = ProjectSnapshot::from_root_tasks_only(&root)?;\n run_with_tasks(opts, snapshot.discovery.tasks, true)\n}\n\n/// Match a user query to a global task and optionally execute it.\npub fn run_global(opts: MatchOpts) -> Result<()> {\n let config_path = config::default_config_path();\n if !config_path.exists() {\n bail!(\"global flow config not found at {}\", config_path.display());\n }\n\n let cfg = config::load(&config_path).with_context(|| {\n format!(\n \"failed to load global flow config at {}\",\n config_path.display()\n )\n })?;\n\n let tasks = cfg\n .tasks\n .iter()\n .map(|task| DiscoveredTask {\n task: task.clone(),\n config_path: config_path.clone(),\n relative_dir: \"global\".to_string(),\n depth: 0,\n scope: \"global\".to_string(),\n scope_aliases: vec![\"global\".to_string()],\n })\n .collect();\n\n run_with_tasks(opts, tasks, false)\n}\n\nfn run_with_tasks(\n opts: MatchOpts,\n tasks: Vec<DiscoveredTask>,\n allow_passthrough: bool,\n) -> Result<()> {\n // Check if this is a CLI subcommand that should bypass matching\n if allow_passthrough && should_passthrough_cli(&opts.args) {\n return passthrough_to_cli(&opts.args);\n }\n\n // Join args for display/LLM purposes (but task execution uses the preserved args)\n let query_display = opts.args.join(\" \");\n\n // Try direct match first (exact name, shortcut, or abbreviation) - no LLM needed\n let (task_name, task_args, was_direct_match) = if let Some(direct) =\n try_direct_match(&opts.args, &tasks)\n {\n (direct.task_name, direct.args, true)\n } else if let Some(builtin) = find_builtin(&query_display) {\n // No task match, but matches a built-in command\n return run_builtin(builtin, opts.execute);\n } else if tasks.is_empty() {\n if allow_passthrough {\n // No tasks and no built-in match: behave like `f <args>`\n return passthrough_to_cli(&opts.args);\n }\n bail!(\"No global tasks available to match.\");\n } else if allow_passthrough && opts.args.len() == 1 {\n // Single-token queries should behave like `f <arg>` if no direct match.\n return passthrough_to_cli(&opts.args);\n } else {\n // No direct match, use LM Studio\n let prompt = build_matching_prompt(&query_display, &tasks);\n\n // Query LM Studio (will fail with clear error if not running)\n let response = match lmstudio::quick_prompt(&prompt, opts.model.as_deref(), opts.port) {\n Ok(r) if !r.trim().is_empty() => r,\n Ok(_) => {\n // Empty response - check for built-in before failing\n if let Some(builtin) = find_builtin(&query_display) {\n return run_builtin(builtin, opts.execute);\n }\n let task_list: Vec<_> = tasks.iter().map(|t| t.task.name.as_str()).collect();\n bail!(\n \"No match for '{}'. LM Studio returned empty response.\\n\\nAvailable tasks:\\n {}\",\n query_display,\n task_list.join(\"\\n \")\n );\n }\n Err(e) => {\n // LM Studio error - fall back to built-in if available\n if let Some(builtin) = find_builtin(&query_display) {\n return run_builtin(builtin, opts.execute);\n }\n let task_list: Vec<_> = tasks.iter().map(|t| t.task.name.as_str()).collect();\n bail!(\n \"No direct match for '{}'. LM Studio error: {}\\n\\nAvailable tasks:\\n {}\",\n query_display,\n e,\n task_list.join(\"\\n \")\n );\n }\n };\n\n // Parse the response to get the task name (no args for LLM matches)\n (extract_task_name(&response, &tasks)?, Vec::new(), false)\n };\n\n // Find the matched task\n let matched = tasks\n .iter()\n .find(|t| t.task.name.eq_ignore_ascii_case(&task_name))\n .ok_or_else(|| anyhow::anyhow!(\"LM Studio returned unknown task: {}\", task_name))?;\n\n // Show what was matched\n if matched.relative_dir.is_empty() {\n println!(\"Matched: {} – {}\", matched.task.name, matched.task.command);\n } else {\n println!(\n \"Matched: {} ({}) – {}\",\n matched.task.name, matched.relative_dir, matched.task.command\n );\n }\n\n if opts.execute {\n // Check if confirmation is needed (only for LLM matches on tasks with confirm_on_match)\n let needs_confirm = !was_direct_match && matched.task.confirm_on_match;\n\n if needs_confirm {\n print!(\"Press Enter to confirm, Ctrl+C to cancel: \");\n io::stdout().flush()?;\n let mut input = String::new();\n io::stdin().read_line(&mut input)?;\n }\n\n // Execute the matched task\n let run_opts = TaskRunOpts {\n config: matched.config_path.clone(),\n delegate_to_hub: false,\n hub_host: \"127.0.0.1\".parse().unwrap(),\n hub_port: 9050,\n name: matched.task.name.clone(),\n args: task_args.clone(),\n };\n tasks::run(run_opts)?;\n }\n\n Ok(())\n}\n\n/// Normalize a string by removing hyphens, underscores, and lowercasing\nfn normalize_name(s: &str) -> String {\n s.chars()\n .filter(|c| *c != '-' && *c != '_')\n .collect::<String>()\n .to_ascii_lowercase()\n}\n\n/// Result of a direct match attempt - includes task name and any extra args\nstruct DirectMatchResult {\n task_name: String,\n args: Vec<String>,\n}\n\n/// Try to match query directly to a task name, shortcut, or abbreviation.\n/// Returns the task name and any remaining arguments.\nfn try_direct_match(args: &[String], tasks: &[DiscoveredTask]) -> Option<DirectMatchResult> {\n if args.is_empty() {\n return None;\n }\n\n let first = args[0].trim();\n let rest: Vec<String> = args[1..].to_vec();\n\n // Exact name match (case-insensitive)\n if let Some(task) = tasks\n .iter()\n .find(|t| t.task.name.eq_ignore_ascii_case(first))\n {\n return Some(DirectMatchResult {\n task_name: task.task.name.clone(),\n args: rest,\n });\n }\n\n // Shortcut match\n if let Some(task) = tasks.iter().find(|t| {\n t.task\n .shortcuts\n .iter()\n .any(|s| s.eq_ignore_ascii_case(first))\n }) {\n return Some(DirectMatchResult {\n task_name: task.task.name.clone(),\n args: rest,\n });\n }\n\n // Normalized match (ignoring hyphens/underscores, only if unambiguous)\n let normalized_query = normalize_name(first);\n let mut normalized_matches: Vec<_> = tasks\n .iter()\n .filter(|t| normalize_name(&t.task.name) == normalized_query)\n .collect();\n if normalized_matches.len() == 1 {\n return Some(DirectMatchResult {\n task_name: normalized_matches.remove(0).task.name.clone(),\n args: rest,\n });\n }\n\n // Abbreviation match (only if unambiguous)\n let needle = first.to_ascii_lowercase();\n if needle.len() >= 2 {\n let mut matches = tasks.iter().filter(|t| {\n generate_abbreviation(&t.task.name)\n .map(|abbr| abbr == needle)\n .unwrap_or(false)\n });\n\n if let Some(first_match) = matches.next() {\n if matches.next().is_none() {\n return Some(DirectMatchResult {\n task_name: first_match.task.name.clone(),\n args: rest,\n });\n }\n }\n }\n\n // Prefix match (only if unambiguous) - e.g., \"prime\" matches \"primes\"\n if needle.len() >= 2 {\n let mut prefix_matches: Vec<_> = tasks\n .iter()\n .filter(|t| t.task.name.to_ascii_lowercase().starts_with(&needle))\n .collect();\n if prefix_matches.len() == 1 {\n return Some(DirectMatchResult {\n task_name: prefix_matches.remove(0).task.name.clone(),\n args: rest,\n });\n }\n }\n\n None\n}\n\nfn generate_abbreviation(name: &str) -> Option<String> {\n let mut abbr = String::new();\n let mut new_segment = true;\n for ch in name.chars() {\n if ch.is_ascii_alphanumeric() {\n if new_segment {\n abbr.push(ch.to_ascii_lowercase());\n new_segment = false;\n }\n } else {\n new_segment = true;\n }\n }\n if abbr.len() >= 2 { Some(abbr) } else { None }\n}\n\nfn build_matching_prompt(query: &str, tasks: &[DiscoveredTask]) -> String {\n let mut prompt = String::new();\n\n prompt.push_str(\n \"You are a task matcher. Given a user query, select the most appropriate task from the list below.\\n\\n\",\n );\n\n prompt.push_str(\"Available tasks:\\n\");\n for task in tasks {\n let location = if task.relative_dir.is_empty() {\n String::new()\n } else {\n format!(\" (in {})\", task.relative_dir)\n };\n\n let desc = task\n .task\n .description\n .as_deref()\n .unwrap_or(&task.task.command);\n\n prompt.push_str(&format!(\"- {}{}: {}\\n\", task.task.name, location, desc));\n }\n\n prompt.push_str(\"\\nRespond with ONLY the exact task name, nothing else. No explanation.\\n\");\n prompt.push_str(&format!(\"\\nUser query: {}\\n\", query));\n prompt.push_str(\"\\nTask name:\");\n\n prompt\n}\n\nfn extract_task_name(response: &str, tasks: &[DiscoveredTask]) -> Result<String> {\n let response = response.trim();\n\n // Try exact match first\n for task in tasks {\n if task.task.name.eq_ignore_ascii_case(response) {\n return Ok(task.task.name.clone());\n }\n }\n\n // Try to find a task name within the response\n for task in tasks {\n if response\n .to_lowercase()\n .contains(&task.task.name.to_lowercase())\n {\n return Ok(task.task.name.clone());\n }\n }\n\n // Clean up common LLM artifacts\n let cleaned = response\n .trim_start_matches(|c: char| !c.is_alphanumeric())\n .trim_end_matches(|c: char| !c.is_alphanumeric() && c != '-' && c != '_')\n .to_string();\n\n for task in tasks {\n if task.task.name.eq_ignore_ascii_case(&cleaned) {\n return Ok(task.task.name.clone());\n }\n }\n\n bail!(\n \"Could not parse task name from LM response: '{}'\\nAvailable tasks: {}\",\n response,\n tasks\n .iter()\n .map(|t| t.task.name.as_str())\n .collect::<Vec<_>>()\n .join(\", \")\n )\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use crate::config::TaskConfig;\n\n fn make_discovered(name: &str, desc: Option<&str>) -> DiscoveredTask {\n DiscoveredTask {\n task: TaskConfig {\n name: name.to_string(),\n command: format!(\"echo {}\", name),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: desc.map(|s| s.to_string()),\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n },\n config_path: PathBuf::from(\"flow.toml\"),\n relative_dir: String::new(),\n depth: 0,\n scope: \"root\".to_string(),\n scope_aliases: vec![\"root\".to_string()],\n }\n }\n\n #[test]\n fn extracts_exact_task_name() {\n let tasks = vec![\n make_discovered(\"build\", Some(\"Build the project\")),\n make_discovered(\"test\", Some(\"Run tests\")),\n ];\n\n assert_eq!(extract_task_name(\"build\", &tasks).unwrap(), \"build\");\n assert_eq!(extract_task_name(\"BUILD\", &tasks).unwrap(), \"build\");\n assert_eq!(extract_task_name(\" test \", &tasks).unwrap(), \"test\");\n }\n\n #[test]\n fn extracts_task_name_from_response() {\n let tasks = vec![\n make_discovered(\"build\", None),\n make_discovered(\"deploy-prod\", None),\n ];\n\n assert_eq!(\n extract_task_name(\"The task is: build\", &tasks).unwrap(),\n \"build\"\n );\n assert_eq!(\n extract_task_name(\"deploy-prod.\", &tasks).unwrap(),\n \"deploy-prod\"\n );\n }\n}\n" }, { "path": "src/tasks.rs", "content": "use std::{\n borrow::Cow,\n collections::{BTreeMap, HashMap, hash_map::DefaultHasher},\n env,\n fs::{self, File, OpenOptions},\n hash::{Hash, Hasher},\n io::{IsTerminal, Read, Write},\n net::IpAddr,\n path::{Path, PathBuf},\n process::{Command, ExitStatus, Stdio},\n sync::{\n Arc, Mutex,\n atomic::{AtomicBool, Ordering},\n },\n thread,\n time::{Duration, Instant, SystemTime, UNIX_EPOCH},\n};\n\nuse portable_pty::{CommandBuilder, NativePtySystem, PtySize, PtySystem};\n\nuse anyhow::{Context, Result, bail};\nuse reqwest::blocking::Client;\nuse serde_json::json;\nuse shell_words;\nuse which::which;\n\nuse crate::{\n ai_taskd, ai_tasks,\n cli::{\n FastRunOpts, GlobalAction, GlobalCommand, HubAction, HubCommand, HubOpts, TaskActivateOpts,\n TaskRunOpts, TasksAction, TasksBuildAiOpts, TasksCommand, TasksDaemonAction,\n TasksDaemonCommand, TasksDupesOpts, TasksInitAiOpts, TasksListOpts, TasksOpts,\n TasksRunAiOpts,\n },\n config::{self, Config, FloxInstallSpec, TaskConfig, TaskResolutionConfig},\n discover,\n flox::{self, FloxEnv},\n history::{self, InvocationRecord},\n hub, init, jazz_state,\n project_snapshot::{self, AiTaskSnapshot, ProjectSnapshot},\n projects,\n running::{self, RunningProcess},\n secret_redact, task_failure_agents, task_match,\n};\n\n/// Fire-and-forget log ingester that batches output lines and POSTs them to the\n/// Flow daemon's `/logs/ingest` endpoint on a background thread.\nstruct LogIngester {\n tx: std::sync::mpsc::Sender<String>,\n}\n\nimpl LogIngester {\n fn new(project: &str, service: &str) -> Self {\n let (tx, rx) = std::sync::mpsc::channel::<String>();\n let project = project.to_string();\n let service = service.to_string();\n thread::spawn(move || {\n let client = match crate::http_client::blocking_with_timeout(Duration::from_secs(2)) {\n Ok(c) => c,\n Err(_) => return,\n };\n let mut batch: Vec<serde_json::Value> = Vec::new();\n let flush_interval = Duration::from_millis(500);\n let mut last_flush = Instant::now();\n\n loop {\n match rx.recv_timeout(flush_interval) {\n Ok(line) => {\n batch.push(json!({\n \"project\": project,\n \"content\": line,\n \"timestamp\": running::now_ms() as i64,\n \"type\": \"log\",\n \"service\": service,\n \"format\": \"text\",\n }));\n // Flush if batch is large enough or interval has passed\n if batch.len() >= 50 || last_flush.elapsed() >= flush_interval {\n let _ = client\n .post(\"http://127.0.0.1:9050/logs/ingest\")\n .json(&batch)\n .send();\n batch.clear();\n last_flush = Instant::now();\n }\n }\n Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {\n if !batch.is_empty() {\n let _ = client\n .post(\"http://127.0.0.1:9050/logs/ingest\")\n .json(&batch)\n .send();\n batch.clear();\n last_flush = Instant::now();\n }\n }\n Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {\n if !batch.is_empty() {\n let _ = client\n .post(\"http://127.0.0.1:9050/logs/ingest\")\n .json(&batch)\n .send();\n }\n break;\n }\n }\n }\n });\n Self { tx }\n }\n\n fn send(&self, line: &str) {\n let _ = self.tx.send(secret_redact::redact_text(line));\n }\n}\n\n/// Flag set by the SIGWINCH signal handler when the terminal is resized.\nstatic SIGWINCH_RECEIVED: AtomicBool = AtomicBool::new(false);\n\n/// Tracks whether raw mode is currently active so the ctrlc handler can restore\n/// the terminal before exiting.\nstatic RAW_MODE_ACTIVE: AtomicBool = AtomicBool::new(false);\n\n#[cfg(unix)]\nunsafe extern \"C\" fn sigwinch_handler(_sig: libc::c_int) {\n SIGWINCH_RECEIVED.store(true, Ordering::SeqCst);\n}\n\n/// RAII guard that disables raw mode and clears the global flag on drop,\n/// ensuring the terminal is always restored even on early returns or panics.\nstruct RawModeGuard;\n\nimpl Drop for RawModeGuard {\n fn drop(&mut self) {\n RAW_MODE_ACTIVE.store(false, Ordering::SeqCst);\n let _ = crossterm::terminal::disable_raw_mode();\n }\n}\n\n/// Global state for cancel cleanup handler.\nstatic CANCEL_HANDLER_SET: AtomicBool = AtomicBool::new(false);\nstatic FISHX_WARNED: AtomicBool = AtomicBool::new(false);\n\n/// Cleanup state shared with the signal handler.\nstruct CleanupState {\n command: Option<String>,\n workdir: PathBuf,\n pid: Option<u32>,\n pgid: Option<u32>,\n}\n\nstatic CLEANUP_STATE: std::sync::OnceLock<Mutex<CleanupState>> = std::sync::OnceLock::new();\n\n/// Run the cleanup command if one is set.\nfn run_cleanup() {\n let state = CLEANUP_STATE.get_or_init(|| {\n Mutex::new(CleanupState {\n command: None,\n workdir: PathBuf::from(\".\"),\n pid: None,\n pgid: None,\n })\n });\n\n if let Ok(guard) = state.lock() {\n terminate_tracked_process(&guard);\n if let Some(ref cmd) = guard.command {\n eprintln!(\"\\nRunning cleanup: {}\", cmd);\n let _ = Command::new(\"/bin/sh\")\n .arg(\"-c\")\n .arg(cmd)\n .current_dir(&guard.workdir)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status();\n }\n }\n}\n\n/// Set up the cleanup handler for Ctrl+C.\nfn setup_cancel_handler(on_cancel: Option<&str>, workdir: &Path) {\n let state = CLEANUP_STATE.get_or_init(|| {\n Mutex::new(CleanupState {\n command: None,\n workdir: PathBuf::from(\".\"),\n pid: None,\n pgid: None,\n })\n });\n\n // Update the cleanup state\n if let Ok(mut guard) = state.lock() {\n guard.command = on_cancel.map(|s| s.to_string());\n guard.workdir = workdir.to_path_buf();\n guard.pid = None;\n guard.pgid = None;\n }\n\n // Only set up the handler once\n if !CANCEL_HANDLER_SET.swap(true, Ordering::SeqCst) {\n let _ = ctrlc::set_handler(move || {\n run_cleanup();\n if RAW_MODE_ACTIVE.load(Ordering::SeqCst) {\n let _ = crossterm::terminal::disable_raw_mode();\n }\n std::process::exit(130); // 128 + SIGINT (2)\n });\n }\n}\n\n/// Clear the cleanup handler (called after task completes normally).\nfn clear_cancel_handler() {\n let state = CLEANUP_STATE.get_or_init(|| {\n Mutex::new(CleanupState {\n command: None,\n workdir: PathBuf::from(\".\"),\n pid: None,\n pgid: None,\n })\n });\n\n if let Ok(mut guard) = state.lock() {\n guard.command = None;\n guard.pid = None;\n guard.pgid = None;\n }\n}\n\nfn set_cleanup_process(pid: u32, pgid: u32) {\n let state = CLEANUP_STATE.get_or_init(|| {\n Mutex::new(CleanupState {\n command: None,\n workdir: PathBuf::from(\".\"),\n pid: None,\n pgid: None,\n })\n });\n\n if let Ok(mut guard) = state.lock() {\n guard.pid = Some(pid);\n guard.pgid = Some(pgid);\n }\n}\n\nfn terminate_tracked_process(state: &CleanupState) {\n #[cfg(unix)]\n {\n let self_pgid = running::get_pgid(std::process::id()).unwrap_or(0);\n if let Some(pgid) = state.pgid {\n if pgid != 0 && pgid != self_pgid {\n let _ = Command::new(\"kill\")\n .arg(\"-TERM\")\n .arg(format!(\"-{}\", pgid))\n .status();\n return;\n }\n }\n\n if let Some(pid) = state.pid {\n let _ = Command::new(\"kill\")\n .arg(\"-TERM\")\n .arg(pid.to_string())\n .status();\n }\n }\n\n #[cfg(windows)]\n {\n if let Some(pid) = state.pid {\n let _ = Command::new(\"taskkill\")\n .args([\"/PID\", &pid.to_string(), \"/T\", \"/F\"])\n .status();\n }\n }\n}\n\n/// Context for registering a running task process\n#[derive(Debug, Clone)]\npub struct TaskContext {\n pub task_name: String,\n pub command: String,\n pub config_path: PathBuf,\n pub project_root: PathBuf,\n pub used_flox: bool,\n pub project_name: Option<String>,\n pub log_path: Option<PathBuf>,\n pub interactive: bool,\n}\n\n/// Check if a command needs interactive mode (TTY passthrough).\n/// Auto-detects commands that typically require user input.\nfn needs_interactive_mode(command: &str) -> bool {\n // Check each line of the command (for multi-line scripts)\n for line in command.lines() {\n let line = line.trim();\n\n // Skip empty lines and comments\n if line.is_empty() || line.starts_with('#') {\n continue;\n }\n\n // Commands that need interactive mode when they start a line\n let interactive_prefixes = [\n \"sudo \",\n \"sudo\\t\",\n \"su \",\n \"ssh \",\n \"docker run -it\",\n \"docker run -ti\",\n \"docker exec -it\",\n \"docker exec -ti\",\n \"kubectl exec -it\",\n \"kubectl exec -ti\",\n ];\n\n for prefix in &interactive_prefixes {\n if line.starts_with(prefix) {\n return true;\n }\n }\n\n // Also check if line is exactly \"sudo\" followed by something\n if line == \"sudo\" || line.starts_with(\"sudo \") {\n return true;\n }\n }\n\n // Check for sudo anywhere in piped/chained commands\n if command.contains(\"| sudo\") || command.contains(\"&& sudo\") || command.contains(\"; sudo\") {\n return true;\n }\n\n // Standalone interactive commands (check first line's first word)\n let interactive_commands = [\n \"vim\",\n \"nvim\",\n \"nano\",\n \"emacs\",\n \"htop\",\n \"top\",\n \"btop\",\n \"less\",\n \"more\",\n \"psql\",\n \"mysql\",\n \"sqlite3\",\n \"node\",\n \"python\",\n \"python3\",\n \"irb\",\n \"ghci\",\n \"lazygit\",\n \"lazydocker\",\n // Package managers can have interactive prompts (corepack, license confirmations, etc.)\n \"pnpm\",\n \"npm\",\n \"yarn\",\n \"bun\",\n ];\n\n let first_line = command.lines().next().unwrap_or(\"\").trim();\n let first_word = first_line.split_whitespace().next().unwrap_or(\"\");\n let base_cmd = first_word.rsplit('/').next().unwrap_or(first_word);\n\n interactive_commands.contains(&base_cmd)\n}\n\n/// Handle `f tasks` command: fuzzy search history or list tasks.\npub fn run_tasks_command(cmd: TasksCommand) -> Result<()> {\n match cmd.action {\n Some(TasksAction::List(opts)) => list_tasks(opts),\n Some(TasksAction::Dupes(opts)) => list_task_duplicates(opts),\n Some(TasksAction::InitAi(opts)) => init_ai_tasks(opts),\n Some(TasksAction::BuildAi(opts)) => build_ai_task(opts),\n Some(TasksAction::RunAi(opts)) => run_ai_task(opts),\n Some(TasksAction::Daemon(cmd)) => run_ai_task_daemon_command(cmd),\n None => fuzzy_search_task_history(),\n }\n}\n\npub fn run_fast(opts: FastRunOpts) -> Result<()> {\n let root = project_snapshot::canonicalize_root(&opts.root)?;\n let selector = opts.name.trim();\n if !selector.to_ascii_lowercase().starts_with(\"ai:\") {\n bail!(\n \"f fast expects an AI task selector (for example: ai:flow/dev-check), got '{}'\",\n opts.name\n );\n }\n\n if let Some(()) = run_via_fast_client(&root, selector, &opts.args, opts.no_cache)? {\n return Ok(());\n }\n\n run_via_daemon_with_lazy_start(&root, selector, &opts.args, opts.no_cache)\n}\n\nfn run_ai_task_daemon_command(cmd: TasksDaemonCommand) -> Result<()> {\n match cmd.action {\n TasksDaemonAction::Start => ai_taskd::start(),\n TasksDaemonAction::Stop => ai_taskd::stop(),\n TasksDaemonAction::Status => ai_taskd::status(),\n TasksDaemonAction::Serve => ai_taskd::serve(),\n }\n}\n\nfn build_ai_task(opts: TasksBuildAiOpts) -> Result<()> {\n let snapshot = AiTaskSnapshot::from_root(&opts.root)?;\n let task = ai_tasks::select_task(&snapshot.tasks, &opts.name)?.with_context(|| {\n format!(\n \"AI task '{}' not found in {}\",\n opts.name,\n snapshot.root.display()\n )\n })?;\n let artifact = ai_tasks::build_task_cached(task, &snapshot.root, opts.force)?;\n println!(\n \"ai task cached: {}\\n key: {}\\n binary: {}\\n rebuilt: {}\",\n task.id,\n artifact.cache_key,\n artifact.binary_path.display(),\n artifact.rebuilt\n );\n Ok(())\n}\n\nfn run_ai_task(opts: TasksRunAiOpts) -> Result<()> {\n let root = project_snapshot::canonicalize_root(&opts.root)?;\n let mut policy = AiTaskExecutionPolicy::from_env();\n if opts.daemon {\n policy.use_daemon = true;\n }\n if opts.no_cache {\n policy.no_cache = true;\n }\n if !execute_ai_task_by_selector(&root, &opts.name, &opts.args, &policy)? {\n bail!(\"AI task '{}' not found in {}\", opts.name, root.display());\n }\n Ok(())\n}\n\n#[derive(Debug, Clone, Copy)]\nstruct AiTaskExecutionPolicy {\n use_daemon: bool,\n no_cache: bool,\n}\n\nimpl AiTaskExecutionPolicy {\n fn from_env() -> Self {\n let runtime = std::env::var(\"FLOW_AI_TASK_RUNTIME\")\n .ok()\n .unwrap_or_default()\n .to_ascii_lowercase();\n Self {\n use_daemon: env_flag_is_true(\"FLOW_AI_TASK_DAEMON\"),\n no_cache: runtime == \"moon-run\" || runtime == \"moon\",\n }\n }\n}\n\nfn env_flag_is_true(name: &str) -> bool {\n match std::env::var(name) {\n Ok(raw) => matches!(\n raw.trim().to_ascii_lowercase().as_str(),\n \"1\" | \"true\" | \"yes\" | \"on\"\n ),\n Err(_) => false,\n }\n}\n\nfn should_prefer_fast_client(root: &Path, selector: &str) -> bool {\n if !env_flag_is_true(\"FLOW_AI_TASK_FAST_CLIENT\") {\n return false;\n }\n if !selector.trim().to_ascii_lowercase().starts_with(\"ai:\") {\n return false;\n }\n\n if let Ok(raw) = std::env::var(\"FLOW_AI_TASK_FAST_SELECTORS\")\n && selector_matches_patterns(selector, &raw)\n {\n return true;\n }\n\n if let Ok(Some(task)) = ai_tasks::resolve_task_fast(root, selector) {\n return task.tags.iter().any(|tag| {\n matches!(\n tag.trim().to_ascii_lowercase().as_str(),\n \"fast\" | \"latency\" | \"hot\" | \"hotkey\"\n )\n });\n }\n\n false\n}\n\nfn selector_matches_patterns(selector: &str, patterns_csv: &str) -> bool {\n let selector = selector.trim();\n for raw in patterns_csv.split(',') {\n let p = raw.trim();\n if p.is_empty() {\n continue;\n }\n if p == \"*\" {\n return true;\n }\n if p.starts_with('*') && p.ends_with('*') && p.len() >= 3 {\n let needle = &p[1..p.len() - 1];\n if selector.contains(needle) {\n return true;\n }\n continue;\n }\n if let Some(prefix) = p.strip_suffix('*') {\n if selector.starts_with(prefix) {\n return true;\n }\n continue;\n }\n if let Some(suffix) = p.strip_prefix('*') {\n if selector.ends_with(suffix) {\n return true;\n }\n continue;\n }\n if selector.eq_ignore_ascii_case(p) {\n return true;\n }\n }\n false\n}\n\nfn fast_client_binary_path(root: &Path) -> Option<PathBuf> {\n if let Ok(raw) = std::env::var(\"FLOW_AI_TASK_FAST_CLIENT_BIN\") {\n let p = PathBuf::from(raw.trim());\n if p.is_file() {\n return Some(p);\n }\n }\n\n if let Some(home) = dirs::home_dir() {\n let fai = home.join(\".local\").join(\"bin\").join(\"fai\");\n if fai.is_file() {\n return Some(fai);\n }\n }\n\n let release_local = root.join(\"target\").join(\"release\").join(\"ai-taskd-client\");\n if release_local.is_file() {\n return Some(release_local);\n }\n\n let debug_local = root.join(\"target\").join(\"debug\").join(\"ai-taskd-client\");\n if debug_local.is_file() {\n return Some(debug_local);\n }\n\n which(\"ai-taskd-client\").ok()\n}\n\nfn run_via_fast_client(\n root: &Path,\n selector: &str,\n args: &[String],\n no_cache: bool,\n) -> Result<Option<()>> {\n let Some(bin) = fast_client_binary_path(root) else {\n return Ok(None);\n };\n\n fn invoke(\n bin: &Path,\n root: &Path,\n selector: &str,\n args: &[String],\n no_cache: bool,\n ) -> Result<std::process::Output> {\n let mut cmd = Command::new(bin);\n cmd.arg(\"--root\").arg(root);\n if no_cache {\n cmd.arg(\"--no-cache\");\n }\n cmd.arg(selector);\n if !args.is_empty() {\n cmd.arg(\"--\");\n cmd.args(args);\n }\n cmd.output().with_context(|| {\n format!(\n \"failed to run fast ai client '{}' for selector '{}'\",\n bin.display(),\n selector\n )\n })\n }\n\n let mut output = invoke(&bin, root, selector, args, no_cache)?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr).to_ascii_lowercase();\n let unavailable = stderr.contains(\"failed to connect\")\n || stderr.contains(\"connection refused\")\n || stderr.contains(\"no such file or directory\");\n if unavailable {\n ai_taskd::start()?;\n output = invoke(&bin, root, selector, args, no_cache)?;\n }\n }\n\n if !output.stdout.is_empty() {\n print!(\"{}\", String::from_utf8_lossy(&output.stdout));\n }\n if !output.stderr.is_empty() {\n eprint!(\"{}\", String::from_utf8_lossy(&output.stderr));\n }\n\n if output.status.success() {\n Ok(Some(()))\n } else {\n let code = output.status.code().unwrap_or(1);\n bail!(\"fast ai client failed for '{}': exit {}\", selector, code);\n }\n}\n\nfn execute_ai_task_by_selector(\n root: &Path,\n selector: &str,\n args: &[String],\n policy: &AiTaskExecutionPolicy,\n) -> Result<bool> {\n if policy.use_daemon {\n if should_prefer_fast_client(root, selector)\n && run_via_fast_client(root, selector, args, policy.no_cache)?.is_some()\n {\n return Ok(true);\n }\n\n match run_via_daemon_with_lazy_start(root, selector, args, policy.no_cache) {\n Ok(()) => return Ok(true),\n Err(error) => {\n let msg = format!(\"{error:#}\").to_ascii_lowercase();\n if msg.contains(\"not found\") {\n return Ok(false);\n }\n return Err(error);\n }\n }\n }\n\n if let Some(ai_task) = ai_tasks::resolve_task_fast(root, selector)? {\n execute_ai_task(root, &ai_task.id, &ai_task, args, policy)?;\n return Ok(true);\n }\n\n let snapshot = AiTaskSnapshot::from_canonical_root(root.to_path_buf())?;\n let Some(ai_task) = ai_tasks::select_task(&snapshot.tasks, selector)? else {\n return Ok(false);\n };\n\n execute_ai_task(root, &ai_task.id, ai_task, args, policy)?;\n Ok(true)\n}\n\nfn execute_ai_task(\n root: &Path,\n selector: &str,\n task: &ai_tasks::DiscoveredAiTask,\n args: &[String],\n policy: &AiTaskExecutionPolicy,\n) -> Result<()> {\n if policy.use_daemon {\n return run_via_daemon_with_lazy_start(root, selector, args, policy.no_cache);\n }\n\n if policy.no_cache {\n ai_tasks::run_task_via_moon(task, root, args)\n } else {\n // Auto runtime policy currently resolves to cache-first with safe moon-run fallback.\n ai_tasks::run_task(task, root, args)\n }\n}\n\nfn run_via_daemon_with_lazy_start(\n root: &Path,\n selector: &str,\n args: &[String],\n no_cache: bool,\n) -> Result<()> {\n match ai_taskd::run_via_daemon(root, selector, args, no_cache) {\n Ok(()) => Ok(()),\n Err(first_error) => {\n let msg = format!(\"{first_error:#}\").to_ascii_lowercase();\n let daemon_unavailable = msg.contains(\"failed to connect to ai-taskd\")\n || msg.contains(\"connection refused\")\n || msg.contains(\"no such file or directory\");\n if !daemon_unavailable {\n return Err(first_error);\n }\n ai_taskd::start()?;\n ai_taskd::run_via_daemon(root, selector, args, no_cache)\n }\n }\n}\n\n/// Fuzzy search through task history (most recent first).\nfn fuzzy_search_task_history() -> Result<()> {\n let records = history::load_unique_task_records()?;\n\n if records.is_empty() {\n println!(\"No task history found.\");\n return Ok(());\n }\n\n // Format for fzf: \"task_name project_path\"\n let lines: Vec<String> = records\n .iter()\n .map(|r| {\n let project = r\n .project_root\n .strip_prefix(\n &dirs::home_dir()\n .unwrap_or_default()\n .to_string_lossy()\n .to_string(),\n )\n .map(|p| format!(\"~{}\", p))\n .unwrap_or_else(|| r.project_root.clone());\n format!(\"{}\\t{}\", r.task_name, project)\n })\n .collect();\n\n let input = lines.join(\"\\n\");\n\n // Run fzf\n let mut fzf = Command::new(\"fzf\")\n .args([\n \"--height=50%\",\n \"--reverse\",\n \"--prompt=Task: \",\n \"--delimiter=\\t\",\n \"--with-nth=1,2\",\n \"--tabstop=4\",\n ])\n .stdin(Stdio::piped())\n .stdout(Stdio::piped())\n .spawn()\n .context(\"failed to spawn fzf\")?;\n\n fzf.stdin.as_mut().unwrap().write_all(input.as_bytes())?;\n\n let output = fzf.wait_with_output()?;\n if !output.status.success() {\n return Ok(()); // User cancelled\n }\n\n let selected = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if selected.is_empty() {\n return Ok(());\n }\n\n // Parse selection: \"task_name\\tproject_path\"\n let parts: Vec<&str> = selected.split('\\t').collect();\n if parts.is_empty() {\n return Ok(());\n }\n\n let task_name = parts[0].trim();\n let project_path = if parts.len() > 1 {\n let p = parts[1].trim();\n if p.starts_with(\"~/\") {\n dirs::home_dir()\n .unwrap_or_default()\n .join(&p[2..])\n .to_string_lossy()\n .to_string()\n } else {\n p.to_string()\n }\n } else {\n std::env::current_dir()?.to_string_lossy().to_string()\n };\n\n // Run the task in that project\n println!(\"Running '{}' in {}\", task_name, project_path);\n let project_root = PathBuf::from(&project_path);\n let config_path = project_root.join(\"flow.toml\");\n\n run(TaskRunOpts {\n config: config_path,\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: task_name.to_string(),\n args: vec![],\n })\n}\n\n/// List tasks from flow.toml (moved from `f tasks` to `f tasks list`).\nfn list_tasks(opts: TasksListOpts) -> Result<()> {\n let snapshot = ProjectSnapshot::from_task_config(&opts.config, true)?;\n if opts.dupes {\n return print_duplicate_tasks(&snapshot.discovery.tasks);\n }\n\n if !snapshot.has_any_tasks() {\n println!(\n \"No tasks defined in {} or subdirectories\",\n snapshot.root.display()\n );\n return Ok(());\n }\n\n println!(\"Tasks (root: {}):\", snapshot.root.display());\n for line in format_discovered_task_lines(&snapshot.discovery.tasks, &snapshot.ai_tasks) {\n println!(\"{line}\");\n }\n\n Ok(())\n}\n\nfn list_task_duplicates(opts: TasksDupesOpts) -> Result<()> {\n let snapshot = ProjectSnapshot::from_task_config_tasks_only(&opts.config, true)?;\n print_duplicate_tasks(&snapshot.discovery.tasks)\n}\n\nfn init_ai_tasks(opts: TasksInitAiOpts) -> Result<()> {\n let root = if opts.root.is_absolute() {\n opts.root\n } else {\n std::env::current_dir()?.join(opts.root)\n };\n let task_dir = root.join(\".ai\").join(\"tasks\");\n std::fs::create_dir_all(&task_dir)\n .with_context(|| format!(\"failed to create {}\", task_dir.display()))?;\n\n let starter_path = task_dir.join(\"starter.mbt\");\n if starter_path.exists() && !opts.force {\n println!(\"AI task starter already exists: {}\", starter_path.display());\n println!(\"Use --force to overwrite.\");\n return Ok(());\n }\n\n std::fs::write(&starter_path, AI_TASK_STARTER)\n .with_context(|| format!(\"failed to write {}\", starter_path.display()))?;\n println!(\"Created AI task starter: {}\", starter_path.display());\n println!(\"Run it with: f starter\");\n Ok(())\n}\n\npub fn list(opts: TasksOpts) -> Result<()> {\n let snapshot = ProjectSnapshot::from_task_config(&opts.config, true)?;\n\n if !snapshot.has_any_tasks() {\n println!(\n \"No tasks defined in {} or subdirectories\",\n snapshot.root.display()\n );\n return Ok(());\n }\n\n println!(\"Tasks (root: {}):\", snapshot.root.display());\n for line in format_discovered_task_lines(&snapshot.discovery.tasks, &snapshot.ai_tasks) {\n println!(\"{line}\");\n }\n\n Ok(())\n}\n\n/// Run tasks from the global flow config (~/.config/flow/flow.toml).\npub fn run_global(opts: GlobalCommand) -> Result<()> {\n let config_path = config::default_config_path();\n if !config_path.exists() {\n bail!(\"global flow config not found at {}\", config_path.display());\n }\n\n if let Some(action) = opts.action {\n match action {\n GlobalAction::List => {\n return list(TasksOpts {\n config: config_path,\n });\n }\n GlobalAction::Run { task, args } => {\n return run(TaskRunOpts {\n config: config_path,\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: task,\n args,\n });\n }\n GlobalAction::Match(opts) => {\n return task_match::run_global(task_match::MatchOpts {\n args: opts.query,\n model: opts.model,\n port: Some(opts.port),\n execute: !opts.dry_run,\n });\n }\n }\n }\n\n if opts.list {\n return list(TasksOpts {\n config: config_path,\n });\n }\n\n if let Some(task) = opts.task {\n return run(TaskRunOpts {\n config: config_path,\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: task,\n args: opts.args,\n });\n }\n\n list(TasksOpts {\n config: config_path,\n })\n}\n\n/// Run a task, searching nested flow.toml files if not found in root.\npub fn run_with_discovery(task_name: &str, args: Vec<String>) -> Result<()> {\n let snapshot = ProjectSnapshot::from_current_dir(true)?;\n if !snapshot.has_any_tasks() {\n bail!(\n \"No tasks defined in {} or subdirectories\",\n snapshot.root.display()\n );\n }\n\n let discovered = select_discovered_task(&snapshot.discovery, task_name)?;\n if let Some(discovered) = discovered {\n return run(TaskRunOpts {\n config: discovered.config_path.clone(),\n delegate_to_hub: false,\n hub_host: std::net::IpAddr::from([127, 0, 0, 1]),\n hub_port: 9050,\n name: discovered.task.name.clone(),\n args,\n });\n }\n\n let ai_policy = AiTaskExecutionPolicy::from_env();\n if execute_ai_task_by_selector(&snapshot.root, task_name, &args, &ai_policy)? {\n return Ok(());\n }\n\n // List available tasks in error message\n let available: Vec<_> = snapshot\n .discovery\n .tasks\n .iter()\n .map(task_reference)\n .collect();\n let mut available_all = available;\n available_all.extend(snapshot.ai_tasks.iter().map(ai_tasks::task_reference));\n bail!(\n \"task '{}' not found.\\nAvailable tasks: {}\",\n task_name,\n available_all.join(\", \")\n );\n}\n\nfn select_discovered_task<'a>(\n discovery: &'a discover::DiscoveryResult,\n task_name: &str,\n) -> Result<Option<&'a discover::DiscoveredTask>> {\n let mut scoped_not_found: Option<(String, String, Vec<String>)> = None;\n if let Some((scope, scoped_task)) = parse_scoped_selector(task_name) {\n let scope_exists = discovery.tasks.iter().any(|d| d.matches_scope(&scope));\n if scope_exists {\n let scoped_matches: Vec<&discover::DiscoveredTask> = discovery\n .tasks\n .iter()\n .filter(|d| d.matches_scope(&scope))\n .filter(|d| task_matches_selector(d, &scoped_task))\n .collect();\n\n let selected = if scoped_matches.is_empty() {\n let needle = scoped_task.to_ascii_lowercase();\n if needle.len() < 2 {\n None\n } else {\n let mut matches = discovery.tasks.iter().filter(|d| {\n d.matches_scope(&scope)\n && generate_abbreviation(&d.task.name)\n .map(|abbr| abbr == needle)\n .unwrap_or(false)\n });\n let first = matches.next();\n if first.is_some() && matches.next().is_none() {\n first\n } else {\n None\n }\n }\n } else if scoped_matches.len() == 1 {\n Some(scoped_matches[0])\n } else {\n return Err(ambiguous_task_error(task_name, &scoped_matches));\n };\n\n if let Some(discovered) = selected {\n return Ok(Some(discovered));\n }\n\n let scoped_available: Vec<String> = discovery\n .tasks\n .iter()\n .filter(|d| d.matches_scope(&scope))\n .map(task_reference)\n .collect();\n scoped_not_found = Some((scope, scoped_task, scoped_available));\n }\n }\n\n let exact_matches: Vec<&discover::DiscoveredTask> = discovery\n .tasks\n .iter()\n .filter(|d| task_matches_selector(d, task_name))\n .collect();\n\n let discovered = if exact_matches.is_empty() {\n let needle = task_name.to_ascii_lowercase();\n if needle.len() < 2 {\n None\n } else {\n let mut matches = discovery.tasks.iter().filter(|d| {\n generate_abbreviation(&d.task.name)\n .map(|abbr| abbr == needle)\n .unwrap_or(false)\n });\n if let Some(first) = matches.next() {\n if matches.next().is_some() {\n None\n } else {\n Some(first)\n }\n } else {\n None\n }\n }\n } else if exact_matches.len() == 1 {\n Some(exact_matches[0])\n } else {\n Some(resolve_ambiguous_task_match(\n task_name,\n &exact_matches,\n discovery.root_task_resolution.as_ref(),\n )?)\n };\n\n if let Some(discovered) = discovered {\n return Ok(Some(discovered));\n }\n\n if let Some((scope, scoped_task, scoped_available)) = scoped_not_found {\n bail!(\n \"task '{}' not found in scope '{}'.\\nAvailable in scope: {}\",\n scoped_task,\n scope,\n if scoped_available.is_empty() {\n \"(none)\".to_string()\n } else {\n scoped_available.join(\", \")\n }\n );\n }\n\n Ok(None)\n}\n\nfn parse_scoped_selector(selector: &str) -> Option<(String, String)> {\n let trimmed = selector.trim();\n if let Some((scope, task)) = trimmed.split_once(':') {\n let scope = scope.trim();\n let task = task.trim();\n if !scope.is_empty() && !task.is_empty() {\n return Some((scope.to_string(), task.to_string()));\n }\n }\n if let Some((scope, task)) = trimmed.split_once('/') {\n let scope = scope.trim();\n let task = task.trim();\n if !scope.is_empty() && !task.is_empty() {\n return Some((scope.to_string(), task.to_string()));\n }\n }\n None\n}\n\nfn task_matches_selector(task: &discover::DiscoveredTask, needle: &str) -> bool {\n task.task.name.eq_ignore_ascii_case(needle)\n || task\n .task\n .shortcuts\n .iter()\n .any(|s| s.eq_ignore_ascii_case(needle))\n}\n\nfn task_reference(task: &discover::DiscoveredTask) -> String {\n let mut out = format!(\"{}:{}\", task.scope, task.task.name);\n if !task.relative_dir.is_empty() {\n out.push_str(&format!(\" ({})\", task.relative_dir));\n }\n out\n}\n\nfn ambiguous_task_error(task_name: &str, matches: &[&discover::DiscoveredTask]) -> anyhow::Error {\n let mut msg = String::new();\n msg.push_str(&format!(\"task '{}' is ambiguous.\\n\", task_name));\n msg.push_str(\"Discovered matches:\\n\");\n for task in matches {\n msg.push_str(&format!(\" - {}\\n\", task_reference(task)));\n }\n msg.push_str(\"Try one of:\\n\");\n for task in matches {\n msg.push_str(&format!(\n \" f {}:{}\\n f run --config {} {}\\n\",\n task.scope,\n task.task.name,\n task.config_path.display(),\n task.task.name\n ));\n }\n anyhow::anyhow!(msg.trim_end().to_string())\n}\n\nfn resolve_ambiguous_task_match<'a>(\n query: &str,\n matches: &[&'a discover::DiscoveredTask],\n task_resolution: Option<&TaskResolutionConfig>,\n) -> Result<&'a discover::DiscoveredTask> {\n let Some(policy) = task_resolution else {\n return Err(ambiguous_task_error(query, matches));\n };\n\n let mut route_scope: Option<&str> = None;\n for (task, scope) in &policy.routes {\n if task.eq_ignore_ascii_case(query)\n || matches\n .iter()\n .any(|m| m.task.name.eq_ignore_ascii_case(task))\n {\n route_scope = Some(scope.as_str());\n break;\n }\n }\n if let Some(scope) = route_scope {\n let routed: Vec<&discover::DiscoveredTask> = matches\n .iter()\n .copied()\n .filter(|m| m.matches_scope(scope))\n .collect();\n if routed.len() == 1 {\n if policy.warn_on_implicit_scope.unwrap_or(false) {\n eprintln!(\n \"note: routed '{}' to scope '{}' via [task_resolution.routes].\",\n query, scope\n );\n }\n return Ok(routed[0]);\n }\n if routed.len() > 1 {\n return Err(ambiguous_task_error(query, &routed));\n }\n }\n\n for scope in &policy.preferred_scopes {\n let preferred: Vec<&discover::DiscoveredTask> = matches\n .iter()\n .copied()\n .filter(|m| m.matches_scope(scope))\n .collect();\n if preferred.len() == 1 {\n if policy.warn_on_implicit_scope.unwrap_or(false) {\n eprintln!(\n \"note: selected '{}' from preferred scope '{}'.\",\n query, scope\n );\n }\n return Ok(preferred[0]);\n }\n if preferred.len() > 1 {\n return Err(ambiguous_task_error(query, &preferred));\n }\n }\n\n Err(ambiguous_task_error(query, matches))\n}\n\npub fn run(opts: TaskRunOpts) -> Result<()> {\n let config_path_for_deps = opts.config.clone();\n let (config_path, cfg) = load_project_config(opts.config)?;\n let project_name = cfg.project_name.clone();\n let workdir = config_path.parent().unwrap_or(Path::new(\".\"));\n\n maybe_warn_non_fishx();\n\n // Set active project when running a task\n if let Some(ref name) = project_name {\n let _ = projects::set_active_project(name);\n }\n\n let ai_policy = AiTaskExecutionPolicy::from_env();\n let task = if let Some(task) = find_task(&cfg, &opts.name) {\n task\n } else {\n if execute_ai_task_by_selector(workdir, &opts.name, &opts.args, &ai_policy)? {\n return Ok(());\n }\n bail!(\n \"task '{}' not found in {}\",\n opts.name,\n config_path.display()\n );\n };\n\n // Build user_input early so we can record failures\n let quoted_args: Vec<String> = opts\n .args\n .iter()\n .map(|arg| shell_words::quote(arg).into_owned())\n .collect();\n let user_input = if opts.args.is_empty() {\n task.name.clone()\n } else {\n format!(\"{} {}\", task.name, quoted_args.join(\" \"))\n };\n let base_command = task.command.trim().to_string();\n let display_command = if opts.args.is_empty() {\n base_command.clone()\n } else {\n format!(\"{} {}\", base_command, quoted_args.join(\" \"))\n };\n\n // Helper to record a failed invocation\n let record_failure = |error_msg: &str| {\n let mut record = InvocationRecord::new(\n workdir.display().to_string(),\n config_path.display().to_string(),\n project_name.as_deref(),\n &task.name,\n &display_command,\n &user_input,\n false,\n );\n record.success = false;\n record.status = Some(1);\n record.output = error_msg.to_string();\n if let Err(err) = history::record(record) {\n tracing::warn!(?err, \"failed to write task history\");\n }\n };\n\n // Resolve dependencies and record failure if it fails\n let resolved = match resolve_task_dependencies(task, &cfg) {\n Ok(r) => r,\n Err(err) => {\n record_failure(&err.to_string());\n return Err(err);\n }\n };\n\n // Run task dependencies first (tasks that must complete before this one)\n if !resolved.task_deps.is_empty() {\n for dep_task_name in &resolved.task_deps {\n println!(\"Running dependency task '{}'...\", dep_task_name);\n let dep_opts = TaskRunOpts {\n config: config_path_for_deps.clone(),\n delegate_to_hub: false,\n hub_host: opts.hub_host,\n hub_port: opts.hub_port,\n name: dep_task_name.clone(),\n args: vec![],\n };\n if let Err(err) = run(dep_opts) {\n record_failure(&format!(\n \"dependency task '{}' failed: {}\",\n dep_task_name, err\n ));\n bail!(\"dependency task '{}' failed: {}\", dep_task_name, err);\n }\n println!();\n }\n }\n\n let should_delegate = opts.delegate_to_hub || task.delegate_to_hub;\n if should_delegate {\n match delegate_task_to_hub(\n task,\n &resolved,\n workdir,\n opts.hub_host,\n opts.hub_port,\n &display_command,\n ) {\n Ok(()) => {\n let mut record = InvocationRecord::new(\n workdir.display().to_string(),\n config_path.display().to_string(),\n project_name.as_deref(),\n &task.name,\n &display_command,\n &user_input,\n false,\n );\n record.success = true;\n record.status = Some(0);\n record.output = format!(\"delegated to hub at {}:{}\", opts.hub_host, opts.hub_port);\n if let Err(err) = history::record(record) {\n tracing::warn!(?err, \"failed to write task history\");\n }\n return Ok(());\n }\n Err(err) => {\n println!(\n \"⚠️ Failed to delegate task '{}' to hub ({}); falling back to local execution.\",\n task.name, err\n );\n }\n }\n }\n\n let flox_pkgs = collect_flox_packages(&cfg, &resolved.flox);\n let mut preamble = String::new();\n let flox_disabled_env = std::env::var_os(\"FLOW_DISABLE_FLOX\").is_some();\n let flox_disabled_marker = flox_disabled_marker(workdir).exists();\n let flox_enabled = !flox_pkgs.is_empty() && !flox_disabled_env && !flox_disabled_marker;\n\n if flox_enabled {\n log_and_capture(\n &mut preamble,\n &format!(\n \"Skipping host PATH checks; using managed deps [{}]\",\n flox_pkgs\n .iter()\n .map(|(name, _)| name.as_str())\n .collect::<Vec<_>>()\n .join(\", \")\n ),\n );\n } else {\n if flox_disabled_env {\n log_and_capture(\n &mut preamble,\n \"FLOW_DISABLE_FLOX is set; running on host PATH\",\n );\n }\n if let Err(err) = ensure_command_dependencies_available(&resolved.commands) {\n record_failure(&err.to_string());\n return Err(err);\n }\n }\n execute_task(\n task,\n &config_path,\n workdir,\n preamble,\n project_name.as_deref(),\n &flox_pkgs,\n flox_enabled,\n &base_command,\n &opts.args,\n &user_input,\n )\n}\n\npub fn activate(opts: TaskActivateOpts) -> Result<()> {\n let (config_path, cfg) = load_project_config(opts.config)?;\n let workdir = config_path.parent().unwrap_or(Path::new(\".\"));\n let project_name = cfg.project_name.clone();\n\n let tasks: Vec<&TaskConfig> = cfg\n .tasks\n .iter()\n .filter(|task| task.activate_on_cd_to_root)\n .collect();\n\n if tasks.is_empty() {\n return Ok(());\n }\n\n let mut combined = ResolvedDependencies::default();\n for task in &tasks {\n let resolved = resolve_task_dependencies(task, &cfg)?;\n combined.commands.extend(resolved.commands);\n combined.flox.extend(resolved.flox);\n }\n\n let flox_pkgs = collect_flox_packages(&cfg, &combined.flox);\n let mut preamble = String::new();\n if flox_pkgs.is_empty() {\n ensure_command_dependencies_available(&combined.commands)?;\n } else {\n log_and_capture(\n &mut preamble,\n &format!(\n \"Skipping host PATH checks; using managed deps [{}]\",\n flox_pkgs\n .iter()\n .map(|(name, _)| name.as_str())\n .collect::<Vec<_>>()\n .join(\", \")\n ),\n );\n }\n for task in tasks {\n let flox_disabled_env = std::env::var_os(\"FLOW_DISABLE_FLOX\").is_some();\n let flox_disabled_marker = flox_disabled_marker(workdir).exists();\n let flox_enabled = !flox_pkgs.is_empty() && !flox_disabled_env && !flox_disabled_marker;\n let command = task.command.trim().to_string();\n let empty_args: Vec<String> = Vec::new();\n execute_task(\n task,\n &config_path,\n workdir,\n preamble.clone(),\n project_name.as_deref(),\n &flox_pkgs,\n flox_enabled,\n &command,\n &empty_args,\n &task.name,\n )?;\n }\n\n Ok(())\n}\n\npub(crate) fn load_project_config(path: PathBuf) -> Result<(PathBuf, Config)> {\n let mut config_path = resolve_path(path)?;\n if !config_path.exists() {\n let is_default = project_snapshot::is_default_flow_config(&config_path);\n if is_default {\n if let Some(found) = project_snapshot::find_flow_toml_upwards(\n config_path.parent().unwrap_or_else(|| Path::new(\".\")),\n ) {\n config_path = found;\n } else {\n init::write_template(&config_path)?;\n println!(\"Created starter flow.toml at {}\", config_path.display());\n }\n }\n }\n let cfg = config::load(&config_path).with_context(|| {\n format!(\n \"failed to load flow tasks configuration at {}\",\n config_path.display()\n )\n })?;\n if let Some(name) = cfg.project_name.as_deref() {\n if let Err(err) = projects::register_project(name, &config_path) {\n tracing::debug!(?err, \"failed to register project name\");\n }\n }\n Ok((config_path, cfg))\n}\n\nfn resolve_path(path: PathBuf) -> Result<PathBuf> {\n if path.is_absolute() {\n Ok(path)\n } else {\n Ok(std::env::current_dir()?.join(path))\n }\n}\n\nfn log_and_capture(buf: &mut String, msg: &str) {\n println!(\"{msg}\");\n buf.push_str(msg);\n if !msg.ends_with('\\n') {\n buf.push('\\n');\n }\n}\n\nfn log_dir() -> PathBuf {\n std::env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\".config/flow/logs\")\n}\n\nfn sanitize_component(raw: &str) -> String {\n let mut s = String::with_capacity(raw.len());\n for ch in raw.chars() {\n if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' {\n s.push(ch);\n } else {\n s.push('-');\n }\n }\n s.trim_matches('-').to_lowercase()\n}\n\nfn short_hash(input: &str) -> String {\n let mut hasher = DefaultHasher::new();\n input.hash(&mut hasher);\n format!(\"{:x}\", hasher.finish())\n}\n\nfn task_log_path(ctx: &TaskContext) -> Option<PathBuf> {\n let base = log_dir();\n let project_root_key = ctx.project_root.display().to_string();\n let project_root_hash = short_hash(&project_root_key);\n let slug = if let Some(name) = ctx.project_name.as_deref() {\n let clean = sanitize_component(name);\n if clean.is_empty() {\n format!(\"proj-{project_root_hash}\")\n } else {\n format!(\"{clean}-{project_root_hash}\")\n }\n } else {\n format!(\"proj-{project_root_hash}\")\n };\n\n let task = {\n let clean = sanitize_component(&ctx.task_name);\n if clean.is_empty() {\n \"task\".to_string()\n } else {\n clean\n }\n };\n\n Some(base.join(slug).join(format!(\"{task}.log\")))\n}\n\nfn task_output_path(raw: &str, workdir: &Path) -> PathBuf {\n let expanded = config::expand_path(raw);\n if expanded.is_absolute() {\n expanded\n } else {\n workdir.join(expanded)\n }\n}\n\nfn execute_task(\n task: &TaskConfig,\n config_path: &Path,\n workdir: &Path,\n mut preamble: String,\n project_name: Option<&str>,\n flox_pkgs: &[(String, FloxInstallSpec)],\n flox_enabled: bool,\n command: &str,\n args: &[String],\n user_input: &str,\n) -> Result<()> {\n if command.is_empty() {\n bail!(\"task '{}' has an empty command\", task.name);\n }\n\n log_and_capture(\n &mut preamble,\n &format!(\"Running task '{}': {}\", task.name, command),\n );\n\n // Create context for PID tracking\n let canonical_config = config_path\n .canonicalize()\n .unwrap_or_else(|_| config_path.to_path_buf());\n let canonical_workdir = workdir\n .canonicalize()\n .unwrap_or_else(|_| workdir.to_path_buf());\n\n // Auto-detect interactive mode if not explicitly set\n let interactive = task.interactive || needs_interactive_mode(command);\n\n let task_ctx = TaskContext {\n task_name: task.name.clone(),\n command: command.to_string(),\n config_path: canonical_config,\n project_root: canonical_workdir.clone(),\n used_flox: flox_enabled && !flox_pkgs.is_empty(),\n project_name: project_name.map(|s| s.to_string()),\n log_path: None,\n interactive,\n };\n\n // Set up cancel handler if on_cancel is defined\n setup_cancel_handler(task.on_cancel.as_deref(), workdir);\n\n let mut record = InvocationRecord::new(\n workdir.display().to_string(),\n config_path.display().to_string(),\n project_name,\n &task.name,\n command,\n user_input,\n !flox_pkgs.is_empty(),\n );\n let started = Instant::now();\n let mut combined_output = preamble;\n let status: ExitStatus;\n\n let flox_disabled = flox_disabled_marker(workdir).exists();\n\n if flox_pkgs.is_empty() || flox_disabled || !flox_enabled {\n let (st, out) = run_host_command(workdir, command, args, Some(task_ctx.clone()))?;\n status = st;\n combined_output.push_str(&out);\n } else {\n log_and_capture(\n &mut combined_output,\n &format!(\n \"Skipping host PATH checks; using managed deps [{}]\",\n flox_pkgs\n .iter()\n .map(|(name, _)| name.as_str())\n .collect::<Vec<_>>()\n .join(\", \")\n ),\n );\n match flox_health_check(workdir, flox_pkgs) {\n Ok(true) => {\n match run_flox_with_reset(flox_pkgs, workdir, command, args, Some(task_ctx.clone()))\n {\n Ok(Some((st, out))) => {\n combined_output.push_str(&out);\n if st.success() {\n status = st;\n } else {\n log_and_capture(\n &mut combined_output,\n &format!(\n \"flox activate failed (status {:?}); retrying on host PATH\",\n st.code()\n ),\n );\n let (host_status, host_out) =\n run_host_command(workdir, command, args, Some(task_ctx.clone()))?;\n combined_output\n .push_str(\"\\n[flox activate failed; retried on host PATH]\\n\");\n combined_output.push_str(&host_out);\n status = host_status;\n }\n }\n Ok(None) => {\n log_and_capture(\n &mut combined_output,\n \"flox disabled after repeated errors; using host PATH\",\n );\n combined_output.push_str(\"[flox disabled after errors]\\n\");\n let (host_status, host_out) =\n run_host_command(workdir, command, args, Some(task_ctx.clone()))?;\n combined_output.push_str(&host_out);\n status = host_status;\n }\n Err(err) => {\n log_and_capture(\n &mut combined_output,\n &format!(\"flox activate failed ({err}); retrying on host PATH\"),\n );\n let (host_status, host_out) =\n run_host_command(workdir, command, args, Some(task_ctx.clone()))?;\n combined_output\n .push_str(\"\\n[flox activate failed; retried on host PATH]\\n\");\n combined_output.push_str(&host_out);\n status = host_status;\n }\n }\n }\n Ok(false) => {\n log_and_capture(\n &mut combined_output,\n \"flox disabled after health check; using host PATH\",\n );\n combined_output.push_str(\"[flox disabled after health check]\\n\");\n let (host_status, host_out) =\n run_host_command(workdir, command, args, Some(task_ctx.clone()))?;\n combined_output.push_str(&host_out);\n status = host_status;\n }\n Err(err) => {\n log_and_capture(\n &mut combined_output,\n &format!(\"flox health check failed ({err}); using host PATH\"),\n );\n combined_output.push_str(\"[flox health check failed; using host PATH]\\n\");\n let (host_status, host_out) =\n run_host_command(workdir, command, args, Some(task_ctx))?;\n combined_output.push_str(&host_out);\n status = host_status;\n }\n }\n }\n\n record.duration_ms = started.elapsed().as_millis();\n record.status = status.code();\n record.success = status.success();\n record.output = combined_output;\n let output = record.output.clone();\n\n if let Some(output_file) = task.output_file.as_deref() {\n let path = task_output_path(output_file, workdir);\n if let Some(parent) = path.parent() {\n let _ = fs::create_dir_all(parent);\n }\n if let Err(err) = fs::write(&path, record.output.as_bytes()) {\n tracing::warn!(?err, path = %path.display(), \"failed to write task output file\");\n }\n }\n\n // Record to jazz2 first (borrows), then history (takes ownership)\n if let Err(err) = jazz_state::record_task_run(&record) {\n tracing::warn!(?err, \"failed to write jazz2 task run\");\n }\n if let Err(err) = history::record(record) {\n tracing::warn!(?err, \"failed to write task history\");\n }\n\n // Clear cancel handler since task completed normally\n clear_cancel_handler();\n\n if status.success() {\n Ok(())\n } else {\n write_failure_bundle(\n &task.name,\n command,\n workdir,\n config_path,\n project_name,\n &output,\n status.code(),\n );\n task_failure_agents::maybe_run_task_failure_agents(\n &task.name,\n command,\n workdir,\n &output,\n status.code(),\n );\n maybe_run_task_failure_hook(&task.name, command, workdir, &output, status.code());\n bail!(\n \"task '{}' exited with status {}\",\n task.name,\n status.code().unwrap_or(-1)\n );\n }\n}\n\n#[cfg(test)]\nfn format_task_lines(tasks: &[TaskConfig]) -> Vec<String> {\n let mut lines = Vec::new();\n for (idx, task) in tasks.iter().enumerate() {\n let shortcut_display = if task.shortcuts.is_empty() {\n String::new()\n } else {\n format!(\" [{}]\", task.shortcuts.join(\", \"))\n };\n lines.push(format!(\n \"{:>2}. {}{} – {}\",\n idx + 1,\n task.name,\n shortcut_display,\n task.command\n ));\n if let Some(desc) = &task.description {\n lines.push(format!(\" {desc}\"));\n }\n }\n lines\n}\n\nfn format_discovered_task_lines(\n tasks: &[discover::DiscoveredTask],\n ai_tasks_list: &[ai_tasks::DiscoveredAiTask],\n) -> Vec<String> {\n let mut lines = Vec::new();\n for (idx, discovered) in tasks.iter().enumerate() {\n let task = &discovered.task;\n let shortcut_display = if task.shortcuts.is_empty() {\n String::new()\n } else {\n format!(\" [{}]\", task.shortcuts.join(\", \"))\n };\n\n // Keep relative path visible for debugging where each selector resolves.\n let path_suffix = if let Some(path_label) = discovered.path_label() {\n format!(\" ({})\", path_label)\n } else {\n String::new()\n };\n\n lines.push(format!(\n \"{:>2}. {}:{}{}{} – {}\",\n idx + 1,\n discovered.scope,\n task.name,\n shortcut_display,\n path_suffix,\n task.command\n ));\n if let Some(desc) = &task.description {\n lines.push(format!(\" {desc}\"));\n }\n }\n\n let base = lines.len();\n for (idx, task) in ai_tasks_list.iter().enumerate() {\n let tags = if task.tags.is_empty() {\n String::new()\n } else {\n format!(\" [{}]\", task.tags.join(\",\"))\n };\n lines.push(format!(\n \"{:>2}. {}{} ({}) – moon run {}\",\n base + idx + 1,\n task.id,\n tags,\n task.relative_path,\n task.path.display()\n ));\n if !task.description.trim().is_empty() {\n lines.push(format!(\" {}\", task.description.trim()));\n }\n }\n\n lines\n}\n\nfn print_duplicate_tasks(tasks: &[discover::DiscoveredTask]) -> Result<()> {\n let mut by_name: BTreeMap<String, Vec<&discover::DiscoveredTask>> = BTreeMap::new();\n for task in tasks {\n by_name\n .entry(task.task.name.to_ascii_lowercase())\n .or_default()\n .push(task);\n }\n\n let mut duplicates: Vec<(String, Vec<&discover::DiscoveredTask>)> = by_name\n .into_iter()\n .filter_map(|(name, mut entries)| {\n if entries.len() < 2 {\n return None;\n }\n entries.sort_by(|a, b| {\n a.scope\n .cmp(&b.scope)\n .then_with(|| a.relative_dir.cmp(&b.relative_dir))\n });\n Some((name, entries))\n })\n .collect();\n duplicates.sort_by(|a, b| a.0.cmp(&b.0));\n\n if duplicates.is_empty() {\n println!(\"No duplicate task names found.\");\n return Ok(());\n }\n\n println!(\"Duplicate task names:\");\n for (name, entries) in duplicates {\n println!();\n println!(\" {} ({})\", name, entries.len());\n for entry in entries {\n println!(\n \" - {}:{} [{}]\",\n entry.scope,\n entry.task.name,\n entry.config_path.display()\n );\n }\n }\n Ok(())\n}\n\nconst AI_TASK_STARTER: &str = r#\"// title: Starter AI Task\n// description: Example MoonBit task under .ai/tasks.\n// tags: [ai, moonbit, task]\n//\n// Run with:\n// f starter\n// or:\n// f ai:starter\n\nfn main {\n println(\"starter ai task: ok\")\n}\n\"#;\n\npub(crate) fn find_task<'a>(cfg: &'a Config, needle: &str) -> Option<&'a TaskConfig> {\n let normalized = needle.trim();\n if normalized.is_empty() {\n return None;\n }\n\n let index = lookup_index_for(cfg);\n let normalized = normalized.to_ascii_lowercase();\n\n if let Some(idx) = index.by_name.get(&normalized).copied() {\n return cfg.tasks.get(idx);\n }\n\n if let Some(idx) = index.by_shortcut.get(&normalized).copied() {\n return cfg.tasks.get(idx);\n }\n\n if normalized.len() < 2 {\n return None;\n }\n\n let maybe_idx = index.by_abbreviation.get(&normalized).copied().flatten()?;\n cfg.tasks.get(maybe_idx)\n}\n\nfn generate_abbreviation(name: &str) -> Option<String> {\n let mut abbr = String::new();\n let mut new_segment = true;\n for ch in name.chars() {\n if ch.is_ascii_alphanumeric() {\n if new_segment {\n abbr.push(ch.to_ascii_lowercase());\n new_segment = false;\n }\n } else {\n new_segment = true;\n }\n }\n\n if abbr.len() >= 2 { Some(abbr) } else { None }\n}\n\n#[derive(Clone, Debug, Default)]\nstruct TaskLookupIndex {\n task_count: usize,\n first_name: String,\n last_name: String,\n by_name: HashMap<String, usize>,\n by_shortcut: HashMap<String, usize>,\n by_abbreviation: HashMap<String, Option<usize>>,\n}\n\nimpl TaskLookupIndex {\n fn build(tasks: &[TaskConfig]) -> Self {\n let mut by_name = HashMap::with_capacity(tasks.len());\n let mut by_shortcut = HashMap::new();\n let mut by_abbreviation = HashMap::new();\n\n for (idx, task) in tasks.iter().enumerate() {\n by_name.entry(task.name.to_ascii_lowercase()).or_insert(idx);\n\n for alias in &task.shortcuts {\n let normalized = alias.trim().to_ascii_lowercase();\n if !normalized.is_empty() {\n by_shortcut.entry(normalized).or_insert(idx);\n }\n }\n\n if let Some(abbr) = generate_abbreviation(&task.name) {\n match by_abbreviation.entry(abbr) {\n std::collections::hash_map::Entry::Vacant(entry) => {\n entry.insert(Some(idx));\n }\n std::collections::hash_map::Entry::Occupied(mut entry) => {\n entry.insert(None);\n }\n }\n }\n }\n\n Self {\n task_count: tasks.len(),\n first_name: tasks.first().map(|t| t.name.clone()).unwrap_or_default(),\n last_name: tasks.last().map(|t| t.name.clone()).unwrap_or_default(),\n by_name,\n by_shortcut,\n by_abbreviation,\n }\n }\n\n fn looks_like(&self, tasks: &[TaskConfig]) -> bool {\n if self.task_count != tasks.len() {\n return false;\n }\n let first = tasks.first().map(|t| t.name.as_str()).unwrap_or_default();\n let last = tasks.last().map(|t| t.name.as_str()).unwrap_or_default();\n self.first_name == first && self.last_name == last\n }\n}\n\nfn task_lookup_cache() -> &'static Mutex<HashMap<usize, TaskLookupIndex>> {\n static CACHE: std::sync::OnceLock<Mutex<HashMap<usize, TaskLookupIndex>>> =\n std::sync::OnceLock::new();\n CACHE.get_or_init(|| Mutex::new(HashMap::new()))\n}\n\nfn lookup_index_for(cfg: &Config) -> TaskLookupIndex {\n let cache_key = cfg as *const Config as usize;\n let tasks = &cfg.tasks;\n\n let Ok(mut cache) = task_lookup_cache().lock() else {\n return TaskLookupIndex::build(tasks);\n };\n\n if let Some(existing) = cache.get(&cache_key)\n && existing.looks_like(tasks)\n {\n return existing.clone();\n }\n\n let index = TaskLookupIndex::build(tasks);\n cache.insert(cache_key, index.clone());\n index\n}\n\n/// Check if command already references shell positional args ($@, $*, $1, etc.)\nfn command_references_args(command: &str) -> bool {\n // Look for $@, $*, $1-$9, ${1}, ${@}, etc.\n let mut chars = command.chars().peekable();\n while let Some(c) = chars.next() {\n if c == '$' {\n match chars.peek() {\n Some('@') | Some('*') | Some('1'..='9') => return true,\n Some('{') => {\n // Check for ${1}, ${@}, ${*}, etc.\n chars.next();\n match chars.peek() {\n Some('@') | Some('*') | Some('1'..='9') => return true,\n _ => {}\n }\n }\n _ => {}\n }\n }\n }\n false\n}\n\nfn has_tty_access() -> bool {\n if std::io::stdin().is_terminal() {\n return true;\n }\n #[cfg(unix)]\n {\n std::fs::File::open(\"/dev/tty\").is_ok()\n }\n #[cfg(not(unix))]\n {\n false\n }\n}\n\nfn fishx_enabled() -> bool {\n match env::var(\"FISHX\") {\n Ok(value) => {\n let value = value.trim().to_lowercase();\n value == \"1\" || value == \"true\" || value == \"yes\" || value == \"on\"\n }\n Err(_) => false,\n }\n}\n\nfn maybe_warn_non_fishx() {\n if !std::io::stdin().is_terminal() {\n return;\n }\n if fishx_enabled() {\n return;\n }\n if env::var_os(\"FLOW_ALLOW_NON_FISHX\").is_some() {\n return;\n }\n if FISHX_WARNED.swap(true, Ordering::Relaxed) {\n return;\n }\n // Only warn if fishx is installed but not active — contributors who\n // never installed fishx shouldn't see a confusing warning.\n if which::which(\"fishx\").is_err() {\n return;\n }\n eprintln!(\n \"⚠️ fishx is installed but not active. Flow runs best under fishx for error capture and AI hints.\\n\\\n Tip: run `f deploy-login` in the fishx repo or set FLOW_ALLOW_NON_FISHX=1 to hide this warning.\"\n );\n}\n\nfn failure_bundle_path() -> Option<PathBuf> {\n if let Ok(path) = env::var(\"FISHX_FAILURE_PATH\") {\n let trimmed = path.trim();\n if !trimmed.is_empty() {\n return Some(PathBuf::from(trimmed));\n }\n }\n if let Ok(path) = env::var(\"FLOW_FAILURE_BUNDLE_PATH\") {\n let trimmed = path.trim();\n if !trimmed.is_empty() {\n return Some(PathBuf::from(trimmed));\n }\n }\n dirs::cache_dir().map(|dir| dir.join(\"flow\").join(\"last-task-failure.json\"))\n}\n\nfn resolve_task_failure_hook() -> Option<String> {\n if let Ok(value) = env::var(\"FLOW_TASK_FAILURE_HOOK\") {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n }\n }\n let config = config::load_ts_config()?;\n let flow = config.flow?;\n let hook = flow.task_failure_hook?;\n let trimmed = hook.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n }\n}\n\nfn truncate_output_for_hook(output: &str, max_lines: usize, max_chars: usize) -> String {\n let mut lines: Vec<&str> = output.lines().collect();\n if lines.len() > max_lines {\n lines = lines[lines.len().saturating_sub(max_lines)..].to_vec();\n }\n let mut joined = lines.join(\"\\n\");\n if joined.len() > max_chars {\n let start = joined.len().saturating_sub(max_chars);\n joined = format!(\"...{}\", &joined[start..]);\n }\n joined\n}\n\nfn maybe_run_task_failure_hook(\n task_name: &str,\n command: &str,\n workdir: &Path,\n output: &str,\n status: Option<i32>,\n) {\n if env::var_os(\"FLOW_DISABLE_TASK_FAILURE_HOOK\").is_some() {\n return;\n }\n let Some(hook) = resolve_task_failure_hook() else {\n return;\n };\n if !std::io::stdin().is_terminal() {\n return;\n }\n let mut hook = hook;\n if env::var_os(\"FLOW_TASK_FAILURE_HOOK_ALLOW_OPEN\").is_none() {\n let hook_lower = hook.to_ascii_lowercase();\n if hook_lower.contains(\"rise work\") {\n hook = sanitize_rise_work_hook_no_open(&hook);\n }\n }\n let mut cmd = Command::new(\"sh\");\n cmd.arg(\"-c\")\n .arg(&hook)\n .current_dir(workdir)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit());\n cmd.env(\"FLOW_TASK_NAME\", task_name);\n cmd.env(\"FLOW_TASK_COMMAND\", secret_redact::redact_text(command));\n cmd.env(\"FLOW_TASK_WORKDIR\", workdir.display().to_string());\n cmd.env(\"FLOW_TASK_STATUS\", status.unwrap_or(-1).to_string());\n if let Some(path) = failure_bundle_path() {\n cmd.env(\"FLOW_FAILURE_BUNDLE_PATH\", path.display().to_string());\n }\n let tail = truncate_output_for_hook(output, 120, 12000);\n if !tail.is_empty() {\n cmd.env(\"FLOW_TASK_OUTPUT_TAIL\", secret_redact::redact_text(&tail));\n }\n match cmd.status() {\n Ok(status) if status.success() => {}\n Ok(status) => {\n eprintln!(\"⚠ task failure hook exited with status {:?}\", status.code());\n }\n Err(err) => {\n eprintln!(\"⚠ failed to run task failure hook: {}\", err);\n }\n }\n}\n\nfn sanitize_rise_work_hook_no_open(hook: &str) -> String {\n let tokens = match shell_words::split(hook) {\n Ok(tokens) => tokens,\n Err(_) => {\n let mut fallback = hook.to_string();\n let lower = fallback.to_ascii_lowercase();\n if !lower.contains(\"--no-open\") {\n fallback.push_str(\" --no-open\");\n }\n return fallback;\n }\n };\n\n let mut cleaned: Vec<String> = Vec::new();\n let mut skip_next = false;\n for token in tokens {\n if skip_next {\n skip_next = false;\n continue;\n }\n let lower = token.to_ascii_lowercase();\n if lower == \"--focus\" {\n continue;\n }\n if lower == \"--focus-app\" || lower == \"--app\" || lower == \"--target\" {\n skip_next = true;\n continue;\n }\n if lower.starts_with(\"--focus-app=\")\n || lower.starts_with(\"--app=\")\n || lower.starts_with(\"--target=\")\n {\n continue;\n }\n cleaned.push(token);\n }\n\n let mut rebuilt = shell_words::join(cleaned);\n let lower = rebuilt.to_ascii_lowercase();\n if !lower.contains(\"--no-open\") {\n if !rebuilt.is_empty() {\n rebuilt.push(' ');\n }\n rebuilt.push_str(\"--no-open\");\n }\n rebuilt\n}\n\nfn truncate_for_bundle(output: &str, max_chars: usize) -> String {\n if output.len() <= max_chars {\n return output.to_string();\n }\n let start = output.len().saturating_sub(max_chars);\n format!(\"...{}\", &output[start..])\n}\n\nfn write_failure_bundle(\n task_name: &str,\n command: &str,\n workdir: &Path,\n config_path: &Path,\n project_name: Option<&str>,\n output: &str,\n status: Option<i32>,\n) {\n let Some(path) = failure_bundle_path() else {\n return;\n };\n\n let ts = SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|d| d.as_millis() as u64)\n .unwrap_or(0);\n\n let payload = json!({\n \"task\": task_name,\n \"command\": secret_redact::redact_text(command),\n \"workdir\": workdir.display().to_string(),\n \"config\": config_path.display().to_string(),\n \"project\": project_name,\n \"status\": status.unwrap_or(-1),\n \"output\": secret_redact::redact_text(&truncate_for_bundle(output, 20_000)),\n \"fishx\": fishx_enabled(),\n \"ts\": ts,\n });\n\n if let Some(parent) = path.parent() {\n let _ = fs::create_dir_all(parent);\n }\n if let Err(err) = fs::write(&path, payload.to_string().as_bytes()) {\n tracing::warn!(?err, path = %path.display(), \"failed to write task failure bundle\");\n return;\n }\n\n if std::io::stdin().is_terminal() {\n eprintln!(\"🧩 failure bundle: {}\", path.display());\n if which(\"fx-failure\").is_ok() {\n eprintln!(\" Tip: run `fx-failure` or `last-error` for a quick fix prompt.\");\n }\n }\n}\n\nfn run_host_command(\n workdir: &Path,\n command: &str,\n args: &[String],\n ctx: Option<TaskContext>,\n) -> Result<(ExitStatus, String)> {\n // For interactive tasks, run directly with inherited stdio\n // This ensures proper TTY handling for readline, prompts, etc.\n let interactive = ctx.as_ref().map(|c| c.interactive).unwrap_or(false);\n let is_tty = has_tty_access();\n\n if interactive && is_tty {\n return run_command_with_pty(workdir, command, args, ctx);\n }\n\n let mut cmd = Command::new(\"/bin/sh\");\n\n // If args are provided and command doesn't already reference them ($@ or $1, $2, etc.),\n // append \"$@\" to pass them through properly\n let full_command = if args.is_empty() || command_references_args(command) {\n command.to_string()\n } else {\n format!(\"{} \\\"$@\\\"\", command)\n };\n\n cmd.arg(\"-c\").arg(&full_command);\n if !args.is_empty() {\n cmd.arg(\"sh\"); // $0 placeholder\n for arg in args {\n cmd.arg(arg);\n }\n }\n cmd.current_dir(workdir);\n inject_global_env(&mut cmd);\n run_command_with_tee(cmd, ctx).with_context(|| \"failed to spawn command without managed env\")\n}\n\nfn run_flox_with_reset(\n flox_pkgs: &[(String, FloxInstallSpec)],\n workdir: &Path,\n command: &str,\n args: &[String],\n ctx: Option<TaskContext>,\n) -> Result<Option<(ExitStatus, String)>> {\n let mut combined_output = String::new();\n let mut reset_done = false;\n\n loop {\n let env = flox::ensure_env(workdir, flox_pkgs)?;\n match run_flox_command(&env, workdir, command, args, ctx.clone()) {\n Ok((status, out)) => {\n combined_output.push_str(&out);\n if status.success() {\n return Ok(Some((status, combined_output)));\n }\n if !reset_done {\n reset_flox_env(workdir)?;\n combined_output\n .push_str(\"\\n[flox activate failed; reset .flox and retrying]\\n\");\n reset_done = true;\n continue;\n }\n mark_flox_disabled(workdir, \"flox activate repeatedly failed\")?;\n return Ok(None);\n }\n Err(err) => {\n combined_output.push_str(&format!(\"[flox activate error: {err}]\\n\"));\n if !reset_done {\n reset_flox_env(workdir)?;\n combined_output.push_str(\"[reset .flox and retrying]\\n\");\n reset_done = true;\n continue;\n }\n mark_flox_disabled(workdir, \"flox activate error after reset\")?;\n return Ok(None);\n }\n }\n }\n}\n\nfn flox_health_check(project_root: &Path, flox_pkgs: &[(String, FloxInstallSpec)]) -> Result<bool> {\n let env = flox::ensure_env(project_root, flox_pkgs)?;\n let flox_bin = which(\"flox\").context(\"flox is required to run tasks with flox deps\")?;\n let mut cmd = Command::new(flox_bin);\n cmd.arg(\"activate\")\n .arg(\"-d\")\n .arg(&env.project_root)\n .arg(\"--\")\n .arg(\"/bin/sh\")\n .arg(\"-c\")\n .arg(\":\")\n .current_dir(project_root)\n .stdout(Stdio::null())\n .stderr(Stdio::null());\n\n match cmd.status() {\n Ok(status) if status.success() => Ok(true),\n _ => {\n mark_flox_disabled(project_root, \"flox health check failed\")?;\n Ok(false)\n }\n }\n}\n\nfn run_flox_command(\n env: &FloxEnv,\n workdir: &Path,\n command: &str,\n args: &[String],\n ctx: Option<TaskContext>,\n) -> Result<(ExitStatus, String)> {\n // For interactive tasks, run directly with inherited stdio\n let interactive = ctx.as_ref().map(|c| c.interactive).unwrap_or(false);\n\n if interactive && has_tty_access() {\n // Build a single command string that wraps the user command inside\n // `flox activate`, then hand it to the PTY path for full interactivity\n // + output capture.\n let flox_bin = which(\"flox\").context(\"flox is required to run tasks with flox deps\")?;\n let inner = if args.is_empty() || command_references_args(command) {\n command.to_string()\n } else {\n format!(\"{} \\\"$@\\\"\", command)\n };\n let flox_cmd = format!(\n \"{} activate -d {} -- /bin/sh -c {}\",\n shell_words::quote(&flox_bin.to_string_lossy()),\n shell_words::quote(&env.project_root.to_string_lossy()),\n shell_words::quote(&inner),\n );\n return run_command_with_pty(workdir, &flox_cmd, args, ctx);\n }\n\n let flox_bin = which(\"flox\").context(\"flox is required to run tasks with flox deps\")?;\n\n // If args are provided and command doesn't already reference them,\n // append \"$@\" to pass them through properly\n let full_command = if args.is_empty() || command_references_args(command) {\n command.to_string()\n } else {\n format!(\"{} \\\"$@\\\"\", command)\n };\n\n let mut cmd = Command::new(flox_bin);\n cmd.arg(\"activate\")\n .arg(\"-d\")\n .arg(&env.project_root)\n .arg(\"--\")\n .arg(\"/bin/sh\")\n .arg(\"-c\")\n .arg(&full_command);\n if !args.is_empty() {\n cmd.arg(\"sh\"); // $0 placeholder\n for arg in args {\n cmd.arg(arg);\n }\n }\n cmd.current_dir(workdir);\n inject_global_env(&mut cmd);\n run_command_with_tee(cmd, ctx).with_context(|| \"failed to spawn flox activate for task\")\n}\n\nfn run_command_with_tee(\n mut cmd: Command,\n ctx: Option<TaskContext>,\n) -> Result<(ExitStatus, String)> {\n inject_global_env(&mut cmd);\n // Interactive commands are now caught upstream by run_host_command /\n // run_flox_command and routed through run_command_with_pty, so this\n // always delegates to the pipe-based path.\n run_command_with_pipes(cmd, ctx)\n}\n\nfn inject_global_env(cmd: &mut Command) {\n let keys = config::global_env_keys();\n if keys.is_empty() {\n return;\n }\n\n let missing: Vec<String> = keys\n .into_iter()\n .filter(|key| std::env::var_os(key).is_none())\n .collect();\n\n if missing.is_empty() {\n return;\n }\n\n // If not logged in to cloud, silently try local env store and skip.\n // This avoids prompting \"Not logged in to cloud...\" for contributors\n // who don't need cloud env vars (e.g. web-only dev).\n if !crate::env::has_cloud_auth_token() {\n match crate::env::fetch_local_personal_env_vars(&missing) {\n Ok(vars) => {\n for (key, value) in vars {\n if !value.is_empty() {\n cmd.env(key, value);\n }\n }\n }\n Err(err) => {\n tracing::debug!(?err, \"failed to read local env vars\");\n }\n }\n return;\n }\n\n match crate::env::fetch_personal_env_vars(&missing) {\n Ok(vars) => {\n for (key, value) in vars {\n if !value.is_empty() {\n cmd.env(key, value);\n }\n }\n }\n Err(err) => {\n tracing::debug!(?err, \"failed to fetch global env vars\");\n }\n }\n}\n\n/// Inject global env vars into a `portable_pty::CommandBuilder`.\nfn inject_global_env_pty(cmd: &mut CommandBuilder) {\n let keys = config::global_env_keys();\n if keys.is_empty() {\n return;\n }\n\n let missing: Vec<String> = keys\n .into_iter()\n .filter(|key| std::env::var_os(key).is_none())\n .collect();\n\n if missing.is_empty() {\n return;\n }\n\n if !crate::env::has_cloud_auth_token() {\n match crate::env::fetch_local_personal_env_vars(&missing) {\n Ok(vars) => {\n for (key, value) in vars {\n if !value.is_empty() {\n cmd.env(key, value);\n }\n }\n }\n Err(err) => {\n tracing::debug!(?err, \"failed to read local env vars\");\n }\n }\n return;\n }\n\n match crate::env::fetch_personal_env_vars(&missing) {\n Ok(vars) => {\n for (key, value) in vars {\n if !value.is_empty() {\n cmd.env(key, value);\n }\n }\n }\n Err(err) => {\n tracing::debug!(?err, \"failed to fetch global env vars\");\n }\n }\n}\n\n/// Run a command inside a PTY with full interactivity, color support, and output\n/// capture. Enables raw mode so keystrokes pass through unbuffered, installs a\n/// SIGWINCH handler to propagate terminal resizes, and uses `poll(2)` on stdin\n/// so the forwarding thread exits promptly when the child terminates.\nfn run_command_with_pty(\n workdir: &Path,\n command: &str,\n args: &[String],\n ctx: Option<TaskContext>,\n) -> Result<(ExitStatus, String)> {\n let pty_system = NativePtySystem::default();\n\n // Get terminal size or use defaults\n let size = crossterm::terminal::size()\n .map(|(cols, rows)| PtySize {\n rows,\n cols,\n pixel_width: 0,\n pixel_height: 0,\n })\n .unwrap_or(PtySize {\n rows: 24,\n cols: 80,\n pixel_width: 0,\n pixel_height: 0,\n });\n\n let pair = pty_system\n .openpty(size)\n .map_err(|e| anyhow::anyhow!(\"failed to open pty: {}\", e))?;\n\n // Build the shell command, appending \"$@\" for positional args if needed\n let full_command = if args.is_empty() || command_references_args(command) {\n command.to_string()\n } else {\n format!(\"{} \\\"$@\\\"\", command)\n };\n\n let mut pty_cmd = CommandBuilder::new(\"/bin/sh\");\n pty_cmd.arg(\"-c\");\n pty_cmd.arg(&full_command);\n if !args.is_empty() {\n pty_cmd.arg(\"sh\"); // $0 placeholder\n for arg in args {\n pty_cmd.arg(arg);\n }\n }\n pty_cmd.cwd(workdir);\n\n // Enable full color support in child processes\n pty_cmd.env(\"TERM\", \"xterm-256color\");\n pty_cmd.env(\"COLORTERM\", \"truecolor\");\n\n inject_global_env_pty(&mut pty_cmd);\n\n let mut child = pair\n .slave\n .spawn_command(pty_cmd)\n .map_err(|e| anyhow::anyhow!(\"failed to spawn command in pty: {}\", e))?;\n\n // Drop the slave side in the parent\n drop(pair.slave);\n\n let pid = child.process_id().unwrap_or(0);\n set_cleanup_process(pid, pid);\n\n // Register the process if we have task context\n if let Some(ref task_ctx) = ctx {\n let entry = RunningProcess {\n pid,\n pgid: pid, // PTY processes are their own group\n task_name: task_ctx.task_name.clone(),\n command: task_ctx.command.clone(),\n started_at: running::now_ms(),\n config_path: task_ctx.config_path.clone(),\n project_root: task_ctx.project_root.clone(),\n used_flox: task_ctx.used_flox,\n project_name: task_ctx.project_name.clone(),\n };\n if let Err(err) = running::register_process(entry) {\n tracing::warn!(?err, \"failed to register running process\");\n }\n }\n\n // Install SIGWINCH handler for terminal resize propagation\n #[cfg(unix)]\n unsafe {\n libc::signal(\n libc::SIGWINCH,\n sigwinch_handler as *const () as libc::sighandler_t,\n );\n }\n\n // Enable raw mode so every keystroke reaches the child unbuffered\n crossterm::terminal::enable_raw_mode()\n .map_err(|e| anyhow::anyhow!(\"failed to enable raw mode: {}\", e))?;\n RAW_MODE_ACTIVE.store(true, Ordering::SeqCst);\n let _raw_guard = RawModeGuard;\n\n let output = Arc::new(Mutex::new(String::new()));\n\n // Set up optional log file\n let log_file = ctx.as_ref().and_then(|c| {\n let path = task_log_path(c)?;\n if let Some(parent) = path.parent() {\n let _ = fs::create_dir_all(parent);\n }\n match OpenOptions::new().create(true).append(true).open(&path) {\n Ok(mut file) => {\n let header = format!(\n \"\\n--- {} | task:{} | cmd:{} ---\\n\",\n running::now_ms(),\n c.task_name,\n c.command\n );\n let _ = file.write_all(header.as_bytes());\n Some(Arc::new(Mutex::new(file)))\n }\n Err(_) => None,\n }\n });\n\n // Get reader/writer for PTY master\n let mut reader = pair\n .master\n .try_clone_reader()\n .map_err(|e| anyhow::anyhow!(\"failed to clone pty reader: {}\", e))?;\n\n // Keep the master alive so SIGWINCH can resize it; take_writer for stdin\n let master = pair.master;\n let mut pty_writer = master\n .take_writer()\n .map_err(|e| anyhow::anyhow!(\"failed to take pty writer: {}\", e))?;\n\n // Shared flag so the stdin thread knows when to stop\n let child_done = Arc::new(AtomicBool::new(false));\n\n // Thread to forward stdin to PTY using poll(2) with 100ms timeout\n let stdin_handle = {\n let child_done = child_done.clone();\n thread::spawn(move || {\n let stdin_fd = libc::STDIN_FILENO;\n let mut buf = [0u8; 1024];\n loop {\n if child_done.load(Ordering::SeqCst) {\n break;\n }\n // Use poll(2) so we can periodically check if the child has exited\n let mut pfd = libc::pollfd {\n fd: stdin_fd,\n events: libc::POLLIN,\n revents: 0,\n };\n let ret = unsafe { libc::poll(&mut pfd, 1, 100) };\n if ret <= 0 {\n // timeout or error — loop back and check child_done\n continue;\n }\n if pfd.revents & libc::POLLIN != 0 {\n let n = unsafe {\n libc::read(stdin_fd, buf.as_mut_ptr() as *mut libc::c_void, buf.len())\n };\n if n <= 0 {\n break;\n }\n if pty_writer.write_all(&buf[..n as usize]).is_err() {\n break;\n }\n let _ = pty_writer.flush();\n }\n if pfd.revents & (libc::POLLHUP | libc::POLLERR) != 0 {\n break;\n }\n }\n })\n };\n\n // Create log ingester for fire-and-forget streaming to daemon\n let ingester = ctx.as_ref().map(|c| {\n Arc::new(LogIngester::new(\n c.project_name.as_deref().unwrap_or(\"unknown\"),\n &c.task_name,\n ))\n });\n\n // Thread to read PTY output, tee to stdout, capture, and handle SIGWINCH\n let output_clone = output.clone();\n let log_file_clone = log_file.clone();\n let ingester_clone = ingester.clone();\n let child_done_output = child_done.clone();\n let output_handle = thread::spawn(move || {\n let mut stdout = std::io::stdout();\n let mut buf = [0u8; 8192];\n let mut line_buf = String::with_capacity(2048);\n let preferred_url = lifecycle_preferred_url();\n let mut preferred_url_hint_emitted = false;\n loop {\n // Check for SIGWINCH and propagate resize to the PTY\n if SIGWINCH_RECEIVED.swap(false, Ordering::SeqCst) {\n if let Ok((cols, rows)) = crossterm::terminal::size() {\n let new_size = PtySize {\n rows,\n cols,\n pixel_width: 0,\n pixel_height: 0,\n };\n let _ = master.resize(new_size);\n }\n }\n\n match reader.read(&mut buf) {\n Ok(0) => break,\n Ok(n) => {\n let _ = stdout.write_all(&buf[..n]);\n let _ = stdout.flush();\n\n if let Some(ref file) = log_file_clone {\n if let Ok(mut f) = file.lock() {\n let _ = f.write_all(&buf[..n]);\n let _ = f.flush();\n }\n }\n\n let text = String::from_utf8_lossy(&buf[..n]);\n\n if let Ok(mut out) = output_clone.lock() {\n out.push_str(&text);\n }\n\n if let Some(ref ing) = ingester_clone {\n line_buf.push_str(&text);\n for_each_complete_line(&mut line_buf, |line| {\n maybe_emit_lifecycle_preferred_url_hint(\n &preferred_url,\n line,\n &mut preferred_url_hint_emitted,\n );\n ing.send(line);\n });\n } else {\n line_buf.push_str(&text);\n for_each_complete_line(&mut line_buf, |line| {\n maybe_emit_lifecycle_preferred_url_hint(\n &preferred_url,\n line,\n &mut preferred_url_hint_emitted,\n );\n });\n }\n }\n Err(_) => break,\n }\n\n // If child already exited, drain remaining output then stop\n if child_done_output.load(Ordering::SeqCst) {\n // One more non-blocking drain attempt\n break;\n }\n }\n // Flush remaining partial line\n if !line_buf.is_empty() {\n maybe_emit_lifecycle_preferred_url_hint(\n &preferred_url,\n &line_buf,\n &mut preferred_url_hint_emitted,\n );\n if let Some(ref ing) = ingester_clone {\n ing.send(&line_buf);\n }\n }\n });\n\n // Wait for the child process\n let exit_status = child\n .wait()\n .map_err(|e| anyhow::anyhow!(\"failed to wait on child: {}\", e))?;\n\n // Signal threads that the child is done\n child_done.store(true, Ordering::SeqCst);\n\n // Wait for output thread (stdin thread will exit via poll + child_done flag)\n let _ = output_handle.join();\n let _ = stdin_handle.join();\n\n // _raw_guard drops here, restoring the terminal\n\n // Unregister the process\n if ctx.is_some() {\n if let Err(err) = running::unregister_process(pid) {\n tracing::debug!(?err, \"failed to unregister process\");\n }\n }\n\n let collected = output\n .lock()\n .map(|s| s.clone())\n .unwrap_or_else(|_| String::new());\n\n // Convert portable_pty ExitStatus to std::process::ExitStatus\n let code = exit_status.exit_code();\n let status = std::process::Command::new(\"sh\")\n .arg(\"-c\")\n .arg(format!(\"exit {}\", code))\n .status()\n .unwrap_or_else(|_| std::process::ExitStatus::default());\n\n Ok((status, collected))\n}\n\nfn run_command_with_pipes(\n mut cmd: Command,\n ctx: Option<TaskContext>,\n) -> Result<(ExitStatus, String)> {\n let interactive = ctx.as_ref().map(|c| c.interactive).unwrap_or(false);\n\n // Interactive mode: inherit all stdio for TTY passthrough\n // NOTE: Do NOT create a new process group for interactive commands.\n // The child must remain in the foreground process group to read from the terminal.\n if interactive {\n let mut child = cmd\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .spawn()\n .with_context(|| \"failed to spawn interactive command\")?;\n\n let pid = child.id();\n let pgid = running::get_pgid(pid).unwrap_or(pid);\n set_cleanup_process(pid, pgid);\n\n // Register the process\n if let Some(ref task_ctx) = ctx {\n let entry = RunningProcess {\n pid,\n pgid,\n task_name: task_ctx.task_name.clone(),\n command: task_ctx.command.clone(),\n started_at: running::now_ms(),\n config_path: task_ctx.config_path.clone(),\n project_root: task_ctx.project_root.clone(),\n used_flox: task_ctx.used_flox,\n project_name: task_ctx.project_name.clone(),\n };\n if let Err(err) = running::register_process(entry) {\n tracing::warn!(?err, \"failed to register running process\");\n }\n }\n\n let status = child.wait().with_context(|| \"failed to wait on child\")?;\n\n // Unregister on exit\n if let Err(err) = running::unregister_process(pid) {\n tracing::debug!(?err, \"failed to unregister process\");\n }\n\n return Ok((status, String::new()));\n }\n\n // Create new process group on Unix for reliable child process management\n // (only for non-interactive commands)\n #[cfg(unix)]\n {\n use std::os::unix::process::CommandExt;\n cmd.process_group(0);\n }\n\n let mut child = cmd\n .stdin(Stdio::inherit()) // Allow user input for prompts\n .stdout(Stdio::piped())\n .stderr(Stdio::piped())\n .spawn()\n .with_context(|| \"failed to spawn command\")?;\n\n let pid = child.id();\n let pgid = running::get_pgid(pid).unwrap_or(pid);\n set_cleanup_process(pid, pgid);\n\n // Register the process if we have task context\n if let Some(ref task_ctx) = ctx {\n let entry = RunningProcess {\n pid,\n pgid,\n task_name: task_ctx.task_name.clone(),\n command: task_ctx.command.clone(),\n started_at: running::now_ms(),\n config_path: task_ctx.config_path.clone(),\n project_root: task_ctx.project_root.clone(),\n used_flox: task_ctx.used_flox,\n project_name: task_ctx.project_name.clone(),\n };\n if let Err(err) = running::register_process(entry) {\n tracing::warn!(?err, \"failed to register running process\");\n }\n }\n\n let output = Arc::new(Mutex::new(String::new()));\n // Set up optional log file for streaming output\n let (ctx, log_file) = match ctx {\n Some(mut c) => {\n let path = task_log_path(&c);\n if let Some(path) = path {\n if let Some(parent) = path.parent() {\n let _ = fs::create_dir_all(parent);\n }\n match OpenOptions::new().create(true).append(true).open(&path) {\n Ok(mut file) => {\n let header = format!(\n \"\\n--- {} | task:{} | cmd:{} ---\\n\",\n running::now_ms(),\n c.task_name,\n c.command\n );\n let _ = file.write_all(header.as_bytes());\n c.log_path = Some(path.clone());\n (Some(c), Some(Arc::new(Mutex::new(file))))\n }\n Err(err) => {\n if let Ok(mut buf) = output.lock() {\n buf.push_str(&format!(\"failed to open log file: {err}\\n\"));\n }\n (Some(c), None)\n }\n }\n } else {\n (Some(c), None)\n }\n }\n None => (None, None),\n };\n\n // Create log ingester for fire-and-forget streaming to daemon\n let ingester = ctx.as_ref().map(|c| {\n Arc::new(LogIngester::new(\n c.project_name.as_deref().unwrap_or(\"unknown\"),\n &c.task_name,\n ))\n });\n\n let mut handles = Vec::new();\n\n if let Some(stdout) = child.stdout.take() {\n handles.push(tee_stream(\n stdout,\n std::io::stdout(),\n output.clone(),\n log_file.clone(),\n ingester.clone(),\n ));\n }\n if let Some(stderr) = child.stderr.take() {\n handles.push(tee_stream(\n stderr,\n std::io::stderr(),\n output.clone(),\n log_file.clone(),\n ingester.clone(),\n ));\n }\n\n for handle in handles {\n let _ = handle.join();\n }\n\n let status = child\n .wait()\n .with_context(|| \"failed to wait for command completion\")?;\n\n // Unregister the process\n if ctx.is_some() {\n if let Err(err) = running::unregister_process(pid) {\n tracing::warn!(?err, \"failed to unregister process\");\n }\n }\n\n let collected = output\n .lock()\n .map(|s| s.clone())\n .unwrap_or_else(|_| String::new());\n\n Ok((status, collected))\n}\n\nfn lifecycle_preferred_url() -> Option<String> {\n crate::lifecycle::runtime_preferred_url()\n}\n\nfn is_service_ready_line(line: &str) -> bool {\n let lower: Cow<'_, str> = if line.bytes().any(|b| b.is_ascii_uppercase()) {\n Cow::Owned(line.to_ascii_lowercase())\n } else {\n Cow::Borrowed(line)\n };\n (lower.contains(\"local:\") && lower.contains(\"http://\"))\n || lower.contains(\"ready on http://\")\n || lower.contains(\"listening on http://\")\n || lower.contains(\"listening at http://\")\n}\n\nfn maybe_emit_lifecycle_preferred_url_hint(\n preferred_url: &Option<String>,\n line: &str,\n emitted: &mut bool,\n) {\n if *emitted {\n return;\n }\n if !is_service_ready_line(line) {\n return;\n }\n let Some(url) = preferred_url.as_deref() else {\n return;\n };\n println!(\"[flow][up] preferred URL: {url}\");\n *emitted = true;\n}\n\nfn for_each_complete_line(line_buf: &mut String, mut on_line: impl FnMut(&str)) {\n let mut start = 0usize;\n let mut drain_until = 0usize;\n while let Some(relative) = line_buf[start..].find('\\n') {\n let end = start + relative;\n on_line(&line_buf[start..end]);\n start = end + 1;\n drain_until = start;\n }\n if drain_until > 0 {\n line_buf.drain(..drain_until);\n }\n}\n\nfn tee_stream<R, W>(\n mut reader: R,\n mut writer: W,\n buffer: Arc<Mutex<String>>,\n log_file: Option<Arc<Mutex<File>>>,\n ingester: Option<Arc<LogIngester>>,\n) -> thread::JoinHandle<()>\nwhere\n R: Read + Send + 'static,\n W: Write + Send + 'static,\n{\n thread::spawn(move || {\n let mut chunk = [0u8; 4096];\n let mut line_buf = String::with_capacity(2048);\n let preferred_url = lifecycle_preferred_url();\n let mut preferred_url_hint_emitted = false;\n loop {\n let read = match reader.read(&mut chunk) {\n Ok(0) => break,\n Ok(n) => n,\n Err(_) => break,\n };\n\n let _ = writer.write_all(&chunk[..read]);\n let _ = writer.flush();\n\n if let Some(file) = log_file.as_ref() {\n if let Ok(mut f) = file.lock() {\n let _ = f.write_all(&chunk[..read]);\n let _ = f.flush();\n }\n }\n\n let text = String::from_utf8_lossy(&chunk[..read]);\n\n if let Ok(mut buf) = buffer.lock() {\n buf.push_str(&text);\n }\n\n line_buf.push_str(&text);\n for_each_complete_line(&mut line_buf, |line| {\n maybe_emit_lifecycle_preferred_url_hint(\n &preferred_url,\n line,\n &mut preferred_url_hint_emitted,\n );\n if let Some(ref ing) = ingester {\n ing.send(line);\n }\n });\n }\n // Flush remaining partial line\n if !line_buf.is_empty() {\n maybe_emit_lifecycle_preferred_url_hint(\n &preferred_url,\n &line_buf,\n &mut preferred_url_hint_emitted,\n );\n if let Some(ref ing) = ingester {\n ing.send(&line_buf);\n }\n }\n })\n}\n\nfn reset_flox_env(project_root: &Path) -> Result<()> {\n let dir = project_root.join(\".flox\");\n if dir.exists() {\n fs::remove_dir_all(&dir)\n .with_context(|| format!(\"failed to remove flox env at {}\", dir.display()))?;\n }\n Ok(())\n}\n\nfn flox_disabled_marker(project_root: &Path) -> PathBuf {\n project_root.join(\".flox.disabled\")\n}\n\nfn mark_flox_disabled(project_root: &Path, reason: &str) -> Result<()> {\n let marker = flox_disabled_marker(project_root);\n fs::write(&marker, reason).with_context(|| {\n format!(\n \"failed to write flox disable marker at {}\",\n marker.display()\n )\n })\n}\n\n#[derive(Debug, Default)]\nstruct ResolvedDependencies {\n commands: Vec<String>,\n flox: Vec<(String, FloxInstallSpec)>,\n /// Task names that must run before this task.\n task_deps: Vec<String>,\n}\n\nfn resolve_task_dependencies(task: &TaskConfig, cfg: &Config) -> Result<ResolvedDependencies> {\n if task.dependencies.is_empty() {\n return Ok(ResolvedDependencies::default());\n }\n\n let mut missing = Vec::new();\n let mut resolved = ResolvedDependencies::default();\n for dep_name in &task.dependencies {\n // First check if it's a [deps] entry\n if let Some(spec) = cfg.dependencies.get(dep_name) {\n match spec {\n config::DependencySpec::Single(cmd) => {\n // If value looks like a URL/path, use the key as binary name\n if cmd.contains('/') {\n resolved.commands.push(dep_name.clone());\n } else {\n resolved.commands.push(cmd.clone());\n }\n }\n config::DependencySpec::Multiple(cmds) => resolved.commands.extend(cmds.clone()),\n config::DependencySpec::Flox(pkg) => {\n resolved.flox.push((dep_name.clone(), pkg.clone()));\n }\n }\n continue;\n }\n\n // Check if it's a flox install\n if let Some(flox) = cfg.flox.as_ref().and_then(|f| f.install.get(dep_name)) {\n resolved.flox.push((dep_name.clone(), flox.clone()));\n continue;\n }\n\n // Check if it's a task name (for task ordering)\n if cfg.tasks.iter().any(|t| t.name == *dep_name) {\n resolved.task_deps.push(dep_name.clone());\n continue;\n }\n\n missing.push(dep_name.as_str());\n }\n\n if !missing.is_empty() {\n bail!(\n \"task '{}' references unknown dependencies: {} (define them under [deps], [flox.install], or as a task name)\",\n task.name,\n missing.join(\", \")\n );\n }\n\n Ok(resolved)\n}\n\nfn ensure_command_dependencies_available(commands: &[String]) -> Result<()> {\n if commands.is_empty() {\n return Ok(());\n }\n\n for command in commands {\n which::which(command).with_context(|| dependency_error(command))?;\n }\n\n Ok(())\n}\n\nfn dependency_error(command: &str) -> String {\n let mut msg = format!(\n \"dependency '{}' not found in PATH. Install it or adjust the [dependencies] config.\",\n command\n );\n if let Some(extra) = dependency_help(command) {\n msg.push('\\n');\n msg.push_str(extra);\n }\n msg\n}\n\nfn dependency_help(command: &str) -> Option<&'static str> {\n match command {\n \"fast\" => {\n Some(\"Get the fast CLI from https://github.com/nikivdev/fast and ensure it is on PATH.\")\n }\n _ => None,\n }\n}\n\nfn collect_flox_packages(\n cfg: &Config,\n deps: &[(String, FloxInstallSpec)],\n) -> Vec<(String, FloxInstallSpec)> {\n let mut merged = std::collections::BTreeMap::new();\n if let Some(flox) = &cfg.flox {\n for (name, spec) in &flox.install {\n merged.insert(name.clone(), spec.clone());\n }\n }\n\n for (name, spec) in deps {\n merged.insert(name.clone(), spec.clone());\n }\n\n merged.into_iter().collect()\n}\n\nfn delegate_task_to_hub(\n task: &TaskConfig,\n deps: &ResolvedDependencies,\n workdir: &Path,\n host: IpAddr,\n port: u16,\n command: &str,\n) -> Result<()> {\n ensure_hub_running(host, port)?;\n let url = format_task_submit_url(host, port);\n let client = Client::builder()\n .timeout(Duration::from_secs(5))\n .build()\n .context(\"failed to construct HTTP client for hub delegation\")?;\n\n let flox_specs: Vec<_> = deps\n .flox\n .iter()\n .map(|(name, spec)| json!({ \"name\": name, \"spec\": spec }))\n .collect();\n\n let payload = json!({\n \"task\": {\n \"name\": task.name,\n \"command\": command,\n \"dependencies\": {\n \"commands\": deps.commands,\n \"flox\": flox_specs,\n },\n },\n \"cwd\": workdir.to_string_lossy(),\n \"flow_version\": env!(\"CARGO_PKG_VERSION\"),\n });\n\n let resp = client.post(&url).json(&payload).send().with_context(|| {\n format!(\n \"failed to submit task to hub at {}\",\n format_addr(host, port)\n )\n })?;\n\n let status = resp.status();\n if status.is_success() {\n println!(\n \"Delegated task '{}' to hub at {}\",\n task.name,\n format_addr(host, port)\n );\n Ok(())\n } else {\n let body = resp.text().unwrap_or_default();\n bail!(\n \"hub returned {} while delegating task '{}': {}\",\n status,\n task.name,\n body\n );\n }\n}\n\nfn ensure_hub_running(host: IpAddr, port: u16) -> Result<()> {\n let opts = HubOpts {\n host,\n port,\n config: None,\n no_ui: true,\n docs_hub: false,\n };\n let cmd = HubCommand {\n opts,\n action: Some(HubAction::Start),\n };\n hub::run(cmd)\n}\n\nfn format_addr(host: IpAddr, port: u16) -> String {\n match host {\n IpAddr::V4(_) => format!(\"http://{host}:{port}\"),\n IpAddr::V6(_) => format!(\"http://[{host}]:{port}\"),\n }\n}\n\nfn format_task_submit_url(host: IpAddr, port: u16) -> String {\n match host {\n IpAddr::V4(_) => format!(\"http://{host}:{port}/tasks/run\"),\n IpAddr::V6(_) => format!(\"http://[{host}]:{port}/tasks/run\"),\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use crate::config::{DependencySpec, FloxConfig, TaskResolutionConfig};\n use std::collections::HashMap;\n use std::path::Path;\n\n #[test]\n fn formats_task_lines_with_descriptions() {\n let tasks = vec![\n TaskConfig {\n name: \"lint\".to_string(),\n command: \"golangci-lint run\".to_string(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: Some(\"Run lint checks\".to_string()),\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n },\n TaskConfig {\n name: \"test\".to_string(),\n command: \"gotestsum ./...\".to_string(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n },\n ];\n\n let lines = format_task_lines(&tasks);\n assert_eq!(\n lines,\n vec![\n \" 1. lint – golangci-lint run\".to_string(),\n \" Run lint checks\".to_string(),\n \" 2. test – gotestsum ./...\".to_string(),\n ]\n );\n }\n\n fn discovered_task(scope: &str, relative_dir: &str, name: &str) -> discover::DiscoveredTask {\n discover::DiscoveredTask {\n task: TaskConfig {\n name: name.to_string(),\n command: format!(\"echo {}\", name),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n },\n config_path: PathBuf::from(format!(\"{}/flow.toml\", scope)),\n relative_dir: relative_dir.to_string(),\n depth: if relative_dir.is_empty() { 0 } else { 1 },\n scope: scope.to_string(),\n scope_aliases: vec![scope.to_ascii_lowercase()],\n }\n }\n\n #[test]\n fn parse_scoped_selector_supports_colon_and_slash() {\n assert_eq!(\n parse_scoped_selector(\"mobile:dev\"),\n Some((\"mobile\".to_string(), \"dev\".to_string()))\n );\n assert_eq!(\n parse_scoped_selector(\"mobile/dev\"),\n Some((\"mobile\".to_string(), \"dev\".to_string()))\n );\n assert!(parse_scoped_selector(\"dev\").is_none());\n }\n\n #[test]\n fn resolve_ambiguous_task_match_uses_route_then_preferred_scope() {\n let mobile = discovered_task(\"mobile\", \"mobile\", \"dev\");\n let root = discovered_task(\"root\", \"\", \"dev\");\n let matches = vec![&mobile, &root];\n\n let mut cfg = Config::default();\n cfg.task_resolution = Some(TaskResolutionConfig {\n preferred_scopes: vec![\"root\".to_string()],\n routes: HashMap::from([(String::from(\"dev\"), String::from(\"mobile\"))]),\n warn_on_implicit_scope: Some(false),\n });\n\n let selected = resolve_ambiguous_task_match(\"dev\", &matches, cfg.task_resolution.as_ref())\n .expect(\"route should pick\");\n assert_eq!(selected.scope, \"mobile\");\n\n cfg.task_resolution = Some(TaskResolutionConfig {\n preferred_scopes: vec![\"root\".to_string()],\n routes: HashMap::new(),\n warn_on_implicit_scope: Some(false),\n });\n let selected = resolve_ambiguous_task_match(\"dev\", &matches, cfg.task_resolution.as_ref())\n .expect(\"preferred scope should pick\");\n assert_eq!(selected.scope, \"root\");\n }\n\n #[test]\n fn select_discovered_task_allows_exact_names_with_scope_delimiters() {\n let scoped = discovered_task(\"mobile\", \"mobile\", \"run\");\n let exact = discovered_task(\"root\", \"\", \"mobile:dev\");\n let discovery = discover::DiscoveryResult {\n tasks: vec![scoped, exact],\n root_config: None,\n root_task_resolution: None,\n };\n\n let selected = select_discovered_task(&discovery, \"mobile:dev\")\n .expect(\"selection should succeed\")\n .expect(\"exact task should resolve\");\n assert_eq!(selected.scope, \"root\");\n assert_eq!(selected.task.name, \"mobile:dev\");\n }\n\n #[test]\n fn format_discovered_task_lines_prefixes_scope() {\n let entries = vec![discovered_task(\"mobile\", \"mobile\", \"dev\")];\n let ai_entries: Vec<ai_tasks::DiscoveredAiTask> = Vec::new();\n let lines = format_discovered_task_lines(&entries, &ai_entries);\n assert!(lines[0].contains(\"mobile:dev\"));\n }\n\n #[test]\n fn run_rejects_empty_commands() {\n let task = TaskConfig {\n name: \"empty\".into(),\n command: \"\".into(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n };\n let empty_args: Vec<String> = Vec::new();\n let err = execute_task(\n &task,\n Path::new(\"flow.toml\"),\n Path::new(\".\"),\n String::new(),\n None,\n &[],\n false,\n \"\",\n &empty_args,\n &task.name,\n )\n .unwrap_err();\n assert!(\n err.to_string().contains(\"empty command\"),\n \"unexpected error: {err:?}\"\n );\n }\n\n #[test]\n fn collects_dependency_commands() {\n let mut cfg = Config::default();\n cfg.dependencies\n .insert(\"fast\".into(), DependencySpec::Single(\"fast\".into()));\n cfg.dependencies.insert(\n \"toolkit\".into(),\n DependencySpec::Multiple(vec![\"rg\".into(), \"fd\".into()]),\n );\n\n let task = TaskConfig {\n name: \"ci\".into(),\n command: \"ci\".into(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: vec![\"fast\".into(), \"toolkit\".into()],\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n };\n\n let resolved = resolve_task_dependencies(&task, &cfg).expect(\"dependencies should resolve\");\n assert_eq!(\n resolved.commands,\n vec![\"fast\".to_string(), \"rg\".to_string(), \"fd\".to_string()]\n );\n assert!(resolved.flox.is_empty());\n }\n\n #[test]\n fn collects_flox_dependencies_from_dependency_table() {\n let mut cfg = Config::default();\n cfg.dependencies.insert(\n \"ripgrep\".into(),\n DependencySpec::Flox(FloxInstallSpec {\n pkg_path: \"ripgrep\".into(),\n pkg_group: None,\n version: None,\n systems: None,\n priority: None,\n }),\n );\n\n let task = TaskConfig {\n name: \"search\".into(),\n command: \"rg TODO\".into(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: vec![\"ripgrep\".into()],\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n };\n\n let resolved = resolve_task_dependencies(&task, &cfg).expect(\"dependencies should resolve\");\n assert!(resolved.commands.is_empty());\n assert_eq!(resolved.flox.len(), 1);\n assert_eq!(resolved.flox[0].0, \"ripgrep\");\n assert_eq!(resolved.flox[0].1.pkg_path, \"ripgrep\");\n }\n\n #[test]\n fn collects_flox_dependencies_from_flox_config() {\n let mut cfg = Config::default();\n let mut install = std::collections::HashMap::new();\n install.insert(\n \"node\".to_string(),\n FloxInstallSpec {\n pkg_path: \"nodejs\".into(),\n pkg_group: None,\n version: None,\n systems: None,\n priority: None,\n },\n );\n cfg.flox = Some(FloxConfig { install });\n\n let task = TaskConfig {\n name: \"dev\".into(),\n command: \"npm start\".into(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: vec![\"node\".into()],\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n };\n\n let resolved = resolve_task_dependencies(&task, &cfg).expect(\"dependencies should resolve\");\n assert!(resolved.commands.is_empty());\n assert_eq!(resolved.flox.len(), 1);\n assert_eq!(resolved.flox[0].0, \"node\");\n assert_eq!(resolved.flox[0].1.pkg_path, \"nodejs\");\n }\n\n #[test]\n fn errors_on_missing_dependencies() {\n let cfg = Config::default();\n let task = TaskConfig {\n name: \"ci\".into(),\n command: \"ci\".into(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: vec![\"unknown\".into()],\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n };\n\n let err = resolve_task_dependencies(&task, &cfg).unwrap_err();\n assert!(\n err.to_string().contains(\"references unknown dependencies\"),\n \"unexpected error: {err:?}\"\n );\n }\n\n #[test]\n fn errors_when_dependency_not_declared_in_table() {\n let mut cfg = Config::default();\n cfg.dependencies\n .insert(\"fast\".into(), DependencySpec::Single(\"fast\".into()));\n let task = TaskConfig {\n name: \"ci\".into(),\n command: \"ci\".into(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: vec![\"unknown\".into()],\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n };\n\n let err = resolve_task_dependencies(&task, &cfg).unwrap_err();\n assert!(\n err.to_string().contains(\"references unknown dependencies\"),\n \"unexpected error: {err:?}\"\n );\n }\n\n #[test]\n fn find_task_matches_shortcuts_and_abbreviations() {\n let mut cfg = Config::default();\n cfg.tasks = vec![\n TaskConfig {\n name: \"deploy-cli-release\".into(),\n command: \"echo deploy\".into(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: None,\n shortcuts: vec![\"dcr-alias\".into()],\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n },\n TaskConfig {\n name: \"dev-hub\".into(),\n command: \"echo dev\".into(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n },\n ];\n\n let task = find_task(&cfg, \"dcr-alias\").expect(\"shortcut should resolve\");\n assert_eq!(task.name, \"deploy-cli-release\");\n\n let task = find_task(&cfg, \"dcr\").expect(\"abbreviation should resolve\");\n assert_eq!(task.name, \"deploy-cli-release\");\n\n let task = find_task(&cfg, \"dev-hub\").expect(\"exact match should resolve\");\n assert_eq!(task.name, \"dev-hub\");\n\n let task = find_task(&cfg, \"DH\").expect(\"case-insensitive match should resolve\");\n assert_eq!(task.name, \"dev-hub\");\n }\n\n #[test]\n fn ambiguous_abbreviations_do_not_match() {\n let mut cfg = Config::default();\n cfg.tasks = vec![\n TaskConfig {\n name: \"deploy-cli-release\".into(),\n command: \"echo deploy\".into(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n },\n TaskConfig {\n name: \"deploy-core-runner\".into(),\n command: \"echo runner\".into(),\n delegate_to_hub: false,\n activate_on_cd_to_root: false,\n dependencies: Vec::new(),\n description: None,\n shortcuts: Vec::new(),\n interactive: false,\n confirm_on_match: false,\n on_cancel: None,\n output_file: None,\n },\n ];\n\n assert!(\n find_task(&cfg, \"dcr\").is_none(),\n \"abbreviation should be ambiguous\"\n );\n }\n\n #[test]\n fn detects_command_arg_references() {\n // Should detect $@, $*, $1, $2, etc.\n assert!(command_references_args(\"echo $@\"));\n assert!(command_references_args(\"echo $*\"));\n assert!(command_references_args(\"echo $1\"));\n assert!(command_references_args(\"echo $9\"));\n assert!(command_references_args(\"bash -c 'echo $@' --\"));\n assert!(command_references_args(\"script.sh \\\"$1\\\" \\\"$2\\\"\"));\n assert!(command_references_args(\"echo ${1}\"));\n assert!(command_references_args(\"echo ${@}\"));\n\n // Should not detect other $ variables\n assert!(!command_references_args(\"echo $HOME\"));\n assert!(!command_references_args(\"echo $0\")); // $0 is script name, not arg\n assert!(!command_references_args(\"echo ${HOME}\"));\n assert!(!command_references_args(\"echo $$\")); // PID\n assert!(!command_references_args(\"echo $?\")); // exit code\n assert!(!command_references_args(\n \"source .env && bun script.ts --delete\"\n ));\n }\n}\n" }, { "path": "src/terminal.rs", "content": "use std::{\n env, fs,\n path::{Path, PathBuf},\n process::Command,\n};\n\nuse anyhow::{Context, Result, bail};\nuse which::which;\n\nuse crate::config::OptionsConfig;\n\n#[cfg(unix)]\nuse std::os::unix::fs::PermissionsExt;\n\nconst LOG_DIR_SUFFIX: &str = \".flow/tmux-logs\";\nconst META_DIR_SUFFIX: &str = \".flow/tty-meta\";\nconst SCRIPT_PATH_SUFFIX: &str = \".config/flow/tmux-enable-tracing.sh\";\nconst FISH_CONF_SUFFIX: &str = \".config/fish/conf.d/flow-trace.fish\";\n\npub fn maybe_enable_terminal_tracing(options: &OptionsConfig) {\n if !options.trace_terminal_io {\n return;\n }\n\n if let Err(err) = enforce_tmux_logging() {\n tracing::warn!(?err, \"failed to enable tmux-based terminal tracing\");\n }\n\n if let Err(err) = install_fish_hooks() {\n tracing::warn!(?err, \"failed to install fish tracing hooks\");\n }\n}\n\nfn enforce_tmux_logging() -> Result<()> {\n if which(\"tmux\").is_err() {\n tracing::info!(\"tmux not found on PATH; skipping terminal IO tracing\");\n return Ok(());\n }\n\n let home = home_dir();\n let log_dir = home.join(LOG_DIR_SUFFIX);\n fs::create_dir_all(&log_dir)\n .with_context(|| format!(\"failed to create tmux log dir {}\", log_dir.display()))?;\n\n let script_path = home.join(SCRIPT_PATH_SUFFIX);\n write_enable_script(&script_path, &log_dir)?;\n\n run_tmux(&[\"start-server\"], \"start tmux server for tracing\")?;\n install_hooks(&script_path)?;\n prime_existing_panes(&script_path)?;\n\n tracing::info!(dir = %log_dir.display(), \"tmux terminal tracing enabled\");\n Ok(())\n}\n\nfn install_fish_hooks() -> Result<()> {\n if which(\"fish\").is_err() {\n tracing::debug!(\"fish not found on PATH; skipping fish hook installation\");\n return Ok(());\n }\n\n let home = home_dir();\n let meta_dir = home.join(META_DIR_SUFFIX);\n fs::create_dir_all(&meta_dir)\n .with_context(|| format!(\"failed to create fish meta dir {}\", meta_dir.display()))?;\n\n let conf_path = home.join(FISH_CONF_SUFFIX);\n write_fish_conf(&conf_path, &meta_dir)?;\n Ok(())\n}\n\nfn install_hooks(script_path: &Path) -> Result<()> {\n let script_cmd = format!(\"run-shell {}\", sh_quote(script_path));\n for hook in [\"pane-add\", \"client-session-changed\", \"session-created\"] {\n run_tmux(\n &[\"set-hook\", \"-g\", hook, &script_cmd],\n \"install tmux tracing hook\",\n )?;\n }\n Ok(())\n}\n\nfn prime_existing_panes(script_path: &Path) -> Result<()> {\n let output = Command::new(\"tmux\")\n .args([\"list-panes\", \"-a\", \"-F\", \"#{pane_id}\"])\n .output();\n\n let output = match output {\n Ok(out) if out.status.success() => out,\n Ok(_) => return Ok(()), // No panes yet; hooks will handle future ones.\n Err(err) => {\n tracing::warn!(?err, \"unable to list tmux panes for tracing bootstrap\");\n return Ok(());\n }\n };\n\n let script_cmd = sh_quote(script_path);\n for pane in String::from_utf8_lossy(&output.stdout).lines() {\n let pane = pane.trim();\n if pane.is_empty() {\n continue;\n }\n let run_shell_cmd = format!(\"{script_cmd} {pane}\");\n run_tmux(&[\"run-shell\", &run_shell_cmd], \"prime tmux pane tracing\")?;\n }\n\n Ok(())\n}\n\nfn write_enable_script(script_path: &Path, log_dir: &Path) -> Result<()> {\n if let Some(parent) = script_path.parent() {\n fs::create_dir_all(parent).with_context(|| {\n format!(\n \"failed to create directory for tmux tracing script {}\",\n parent.display()\n )\n })?;\n }\n\n let contents = format!(\n r#\"#!/bin/sh\nset -e\nLOG_DIR={log_dir}\nmkdir -p \"$LOG_DIR\"\nTARGET=\"${{1:-!}}\"\ntmux pipe-pane -o -t \"$TARGET\" \"cat >>${{LOG_DIR}}/pane-#{{session_name}}-#{{window_index}}-#{{pane_index}}.log\"\n\"#,\n log_dir = sh_quote(log_dir)\n );\n fs::write(script_path, contents).with_context(|| {\n format!(\n \"failed to write tmux tracing helper to {}\",\n script_path.display()\n )\n })?;\n\n #[cfg(unix)]\n fs::set_permissions(script_path, fs::Permissions::from_mode(0o755)).with_context(|| {\n format!(\n \"failed to mark tmux tracing script executable at {}\",\n script_path.display()\n )\n })?;\n\n Ok(())\n}\n\nfn write_fish_conf(conf_path: &Path, meta_dir: &Path) -> Result<()> {\n const CONTENTS: &str = r#\"if status --is-interactive\n if not set -q TMUX\n if not set -q FLOW_SKIP_AUTO_TMUX\n if type -q tmux\n set -l __flow_trace_tmux_session \"flow\"\n if set -q FLOW_AUTO_TMUX_SESSION\n set __flow_trace_tmux_session $FLOW_AUTO_TMUX_SESSION\n end\n exec tmux new-session -A -s $__flow_trace_tmux_session\n end\n end\n end\nend\n\nset -g __flow_trace_meta_dir \"%META_DIR%\"\nmkdir -p $__flow_trace_meta_dir\n\nfunction __flow_trace_preexec --on-event fish_preexec\n set -l id (uuidgen)\n set -gx FLOW_CMD_ID $id\n set -l ts (date -Ins)\n set -l cmd (string join ' ' $argv)\n set -l pane (set -q TMUX_PANE; and echo $TMUX_PANE; or echo \"nopane\")\n set -l cwd (pwd)\n set -l cwd_b64 (printf \"%s\" $cwd | base64)\n set -l cmd_b64 (printf \"%s\" $cmd | base64)\n printf \"\\e]133;A;flow-cmd-start;%s\\a\" $id\n printf \"start %s %s %s %s\\n\" $ts $id $cwd_b64 $cmd_b64 >> $__flow_trace_meta_dir/$pane.log\nend\n\nfunction __flow_trace_postexec --on-event fish_postexec\n set -l ts (date -Ins)\n set -l pane (set -q TMUX_PANE; and echo $TMUX_PANE; or echo \"nopane\")\n printf \"\\e]133;B;flow-cmd-end;%s;%s\\a\" $FLOW_CMD_ID $status\n printf \"end %s %s %s\\n\" $ts $FLOW_CMD_ID $status >> $__flow_trace_meta_dir/$pane.log\nend\n\"#;\n\n let rendered = CONTENTS.replace(\"%META_DIR%\", &meta_dir.to_string_lossy());\n if let Some(parent) = conf_path.parent() {\n fs::create_dir_all(parent).with_context(|| {\n format!(\n \"failed to create directory for fish tracing conf {}\",\n parent.display()\n )\n })?;\n }\n\n // Avoid rewriting if unchanged to keep user shells happy.\n if let Ok(existing) = fs::read_to_string(conf_path) {\n if existing == rendered {\n return Ok(());\n }\n }\n\n fs::write(conf_path, rendered).with_context(|| {\n format!(\n \"failed to write fish tracing hooks to {}\",\n conf_path.display()\n )\n })\n}\n\nfn run_tmux(args: &[&str], context: &str) -> Result<()> {\n let status = Command::new(\"tmux\")\n .args(args)\n .status()\n .with_context(|| format!(\"failed to execute tmux to {context}\"))?;\n if status.success() {\n Ok(())\n } else {\n bail!(\n \"tmux exited with status {} while attempting to {context}\",\n status.code().unwrap_or(-1)\n );\n }\n}\n\nfn sh_quote(path: &Path) -> String {\n let value = path.to_string_lossy();\n let escaped = value.replace('\\'', r\"'\\''\");\n format!(\"'{escaped}'\")\n}\n\nfn home_dir() -> PathBuf {\n env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n}\n" }, { "path": "src/todo.rs", "content": "use std::fs;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\nuse chrono::Utc;\nuse serde::{Deserialize, Serialize};\nuse sha1::{Digest, Sha1};\nuse uuid::Uuid;\n\nuse crate::ai;\nuse crate::cli::{TodoAction, TodoCommand, TodoStatusArg};\n\n#[derive(Debug, Serialize, Deserialize, Clone)]\npub(crate) struct TodoItem {\n pub id: String,\n pub title: String,\n pub status: String,\n pub created_at: String,\n pub updated_at: Option<String>,\n pub note: Option<String>,\n pub session: Option<String>,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub external_ref: Option<String>,\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n pub priority: Option<String>,\n}\n\npub fn run(cmd: TodoCommand) -> Result<()> {\n match cmd.action {\n None | Some(TodoAction::Bike) => open_bike(),\n Some(TodoAction::Add {\n title,\n note,\n session,\n no_session,\n status,\n }) => add(\n &title,\n note.as_deref(),\n session.as_deref(),\n no_session,\n status,\n ),\n Some(TodoAction::List { all }) => list(all),\n Some(TodoAction::Done { id }) => set_status(&id, TodoStatusArg::Completed),\n Some(TodoAction::Edit {\n id,\n title,\n status,\n note,\n }) => edit(&id, title.as_deref(), status, note),\n Some(TodoAction::Remove { id }) => remove(&id),\n }\n}\n\nfn open_bike() -> Result<()> {\n let root = project_root();\n let project_name = root\n .file_name()\n .and_then(|name| name.to_str())\n .map(|name| name.to_string())\n .filter(|name| !name.trim().is_empty())\n .unwrap_or_else(|| \"project\".to_string());\n\n let dir = root.join(\".ai\").join(\"todos\");\n let path = dir.join(format!(\"{}.bike\", project_name));\n fs::create_dir_all(&dir)?;\n let needs_init = match fs::read_to_string(&path) {\n Ok(content) => !looks_like_bike(&content),\n Err(_) => true,\n };\n if needs_init {\n let content = render_bike_template(&project_name);\n fs::write(&path, content)?;\n }\n\n let bike_app = Path::new(\"/System/Volumes/Data/Applications/Bike.app\");\n if !bike_app.exists() {\n bail!(\"Bike.app not found at {}\", bike_app.display());\n }\n\n let status = Command::new(\"open\")\n .arg(\"-a\")\n .arg(bike_app)\n .arg(&path)\n .status()\n .context(\"failed to launch Bike.app\")?;\n if !status.success() {\n bail!(\"Bike.app failed to open {}\", path.display());\n }\n\n Ok(())\n}\n\nfn looks_like_bike(content: &str) -> bool {\n let trimmed = content.trim_start();\n if !trimmed.starts_with(\"<?xml\") {\n return false;\n }\n let lower = trimmed.to_ascii_lowercase();\n lower.contains(\"<html\") && lower.contains(\"<body\") && lower.contains(\"<ul\")\n}\n\nfn render_bike_template(project_name: &str) -> String {\n let now = Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true);\n let ul_id = format!(\"_{}\", Uuid::new_v4().simple());\n let li_id = Uuid::new_v4().simple().to_string();\n format!(\n \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n<html>\\n <head>\\n <meta charset=\\\"utf-8\\\"/>\\n </head>\\n <body>\\n <ul id=\\\"{}\\\" data-created=\\\"{}\\\" data-modified=\\\"{}\\\">\\n <li id=\\\"{}\\\" data-created=\\\"{}\\\" data-modified=\\\"{}\\\">\\n <p>{}</p>\\n </li>\\n </ul>\\n </body>\\n</html>\\n\",\n ul_id, now, now, li_id, now, now, project_name\n )\n}\n\nfn add(\n title: &str,\n note: Option<&str>,\n session: Option<&str>,\n no_session: bool,\n status: TodoStatusArg,\n) -> Result<()> {\n let trimmed = title.trim();\n if trimmed.is_empty() {\n bail!(\"todo title cannot be empty\");\n }\n let (path, mut items) = load_items()?;\n let session_ref = resolve_session_ref(session, no_session)?;\n let now = Utc::now().to_rfc3339();\n let item = TodoItem {\n id: Uuid::new_v4().simple().to_string(),\n title: trimmed.to_string(),\n status: status_to_string(status).to_string(),\n created_at: now,\n updated_at: None,\n note: note.map(|n| n.trim().to_string()).filter(|n| !n.is_empty()),\n session: session_ref,\n external_ref: None,\n priority: None,\n };\n items.push(item.clone());\n save_items(&path, &items)?;\n println!(\"✓ Added {} [{}]\", item.id, item.title);\n Ok(())\n}\n\nfn list(show_all: bool) -> Result<()> {\n let (_path, items) = load_items()?;\n if items.is_empty() {\n println!(\"No todos yet.\");\n return Ok(());\n }\n\n let mut count = 0;\n for item in &items {\n if !show_all && item.status == status_to_string(TodoStatusArg::Completed) {\n continue;\n }\n count += 1;\n println!(\"[{}] {} {}\", item.status, item.id, item.title);\n if let Some(note) = &item.note {\n println!(\" - {}\", note);\n }\n if let Some(session) = &item.session {\n println!(\" @ {}\", session);\n }\n }\n if count == 0 {\n println!(\"No active todos.\");\n }\n Ok(())\n}\n\nfn edit(\n id: &str,\n title: Option<&str>,\n status: Option<TodoStatusArg>,\n note: Option<String>,\n) -> Result<()> {\n let (path, mut items) = load_items()?;\n let idx = find_item_index(&items, id)?;\n let item_id = {\n let item = &mut items[idx];\n\n if let Some(title) = title {\n let title = title.trim();\n if !title.is_empty() {\n item.title = title.to_string();\n }\n }\n\n if let Some(status) = status {\n item.status = status_to_string(status).to_string();\n }\n\n if let Some(note) = note {\n let note = note.trim().to_string();\n item.note = if note.is_empty() { None } else { Some(note) };\n }\n\n item.updated_at = Some(Utc::now().to_rfc3339());\n item.id.clone()\n };\n save_items(&path, &items)?;\n println!(\"✓ Updated {}\", item_id);\n Ok(())\n}\n\nfn set_status(id: &str, status: TodoStatusArg) -> Result<()> {\n let (path, mut items) = load_items()?;\n let idx = find_item_index(&items, id)?;\n let (item_id, item_status) = {\n let item = &mut items[idx];\n item.status = status_to_string(status).to_string();\n item.updated_at = Some(Utc::now().to_rfc3339());\n (item.id.clone(), item.status.clone())\n };\n save_items(&path, &items)?;\n println!(\"✓ {} -> {}\", item_id, item_status);\n Ok(())\n}\n\nfn remove(id: &str) -> Result<()> {\n let (path, mut items) = load_items()?;\n let idx = find_item_index(&items, id)?;\n let item = items.remove(idx);\n save_items(&path, &items)?;\n println!(\"✓ Removed {}\", item.id);\n Ok(())\n}\n\nfn status_to_string(status: TodoStatusArg) -> &'static str {\n match status {\n TodoStatusArg::Pending => \"pending\",\n TodoStatusArg::InProgress => \"in_progress\",\n TodoStatusArg::Completed => \"completed\",\n TodoStatusArg::Blocked => \"blocked\",\n }\n}\n\nfn load_items() -> Result<(PathBuf, Vec<TodoItem>)> {\n let root = project_root();\n let dir = root.join(\".ai\").join(\"todos\");\n let path = dir.join(\"todos.json\");\n\n if !path.exists() {\n return Ok((path, Vec::new()));\n }\n\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n if content.trim().is_empty() {\n return Ok((path, Vec::new()));\n }\n let items = serde_json::from_str(&content)\n .with_context(|| format!(\"failed to parse {}\", path.display()))?;\n Ok((path, items))\n}\n\npub(crate) fn load_items_at_root(root: &Path) -> Result<(PathBuf, Vec<TodoItem>)> {\n let dir = root.join(\".ai\").join(\"todos\");\n let path = dir.join(\"todos.json\");\n\n if !path.exists() {\n return Ok((path, Vec::new()));\n }\n\n let content =\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n if content.trim().is_empty() {\n return Ok((path, Vec::new()));\n }\n let items = serde_json::from_str(&content)\n .with_context(|| format!(\"failed to parse {}\", path.display()))?;\n Ok((path, items))\n}\n\npub(crate) fn save_items(path: &Path, items: &[TodoItem]) -> Result<()> {\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n let content = serde_json::to_string_pretty(items)?;\n fs::write(path, content)?;\n Ok(())\n}\n\nfn todo_title_compact(title: &str) -> String {\n let trimmed = title.trim().trim_start_matches('-').trim();\n let max_len = 120;\n let mut out = String::new();\n let mut count = 0;\n for ch in trimmed.chars() {\n if count >= max_len {\n out.push_str(\"...\");\n break;\n }\n out.push(ch);\n count += 1;\n }\n if out.is_empty() {\n \"todo\".to_string()\n } else {\n out\n }\n}\n\nfn external_ref_for_review_issue(commit_sha: &str, issue: &str) -> String {\n let mut hasher = Sha1::new();\n hasher.update(commit_sha.trim().as_bytes());\n hasher.update(b\":\");\n hasher.update(issue.trim().as_bytes());\n let hex = hex::encode(hasher.finalize());\n let short = hex.get(..12).unwrap_or(&hex);\n format!(\"flow-review-issue-{}\", short)\n}\n\n/// Infer priority from issue text using keyword heuristics.\npub(crate) fn parse_priority_from_issue(issue: &str) -> String {\n let lower = issue.to_lowercase();\n if lower.contains(\"secret\")\n || lower.contains(\"credential\")\n || lower.contains(\"api key\")\n || lower.contains(\"injection\")\n || lower.contains(\"vulnerability\")\n || lower.contains(\"security\")\n {\n return \"P1\".to_string();\n }\n if lower.contains(\"crash\")\n || lower.contains(\"data loss\")\n || lower.contains(\"race condition\")\n || lower.contains(\"memory leak\")\n || lower.contains(\"buffer overflow\")\n {\n return \"P2\".to_string();\n }\n if lower.contains(\"bug\")\n || lower.contains(\"error handling\")\n || lower.contains(\"panic\")\n || lower.contains(\"unwrap\")\n || lower.contains(\"missing validation\")\n {\n return \"P3\".to_string();\n }\n \"P4\".to_string()\n}\n\n/// Load only review todos (those with external_ref starting with \"flow-review-issue-\").\npub(crate) fn load_review_todos(repo_root: &Path) -> Result<Vec<TodoItem>> {\n let (_path, items) = load_items_at_root(repo_root)?;\n Ok(items\n .into_iter()\n .filter(|item| {\n item.external_ref\n .as_deref()\n .map(|r| r.starts_with(\"flow-review-issue-\"))\n .unwrap_or(false)\n })\n .collect())\n}\n\n/// Count open (non-completed) review todos by priority.\n/// Returns (p1, p2, p3, p4, total).\npub(crate) fn count_open_review_todos_by_priority(\n repo_root: &Path,\n) -> Result<(usize, usize, usize, usize, usize)> {\n let items = load_review_todos(repo_root)?;\n let (mut p1, mut p2, mut p3, mut p4) = (0, 0, 0, 0);\n for item in &items {\n if item.status == \"completed\" {\n continue;\n }\n match item.priority.as_deref().unwrap_or(\"P4\") {\n \"P1\" => p1 += 1,\n \"P2\" => p2 += 1,\n \"P3\" => p3 += 1,\n _ => p4 += 1,\n }\n }\n let total = p1 + p2 + p3 + p4;\n Ok((p1, p2, p3, p4, total))\n}\n\n/// Record review issues as project-scoped todos under `.ai/todos/todos.json`.\n/// Returns ids for created items (deduplicated by `external_ref`).\npub fn record_review_issues_as_todos(\n repo_root: &Path,\n commit_sha: &str,\n issues: &[String],\n summary: Option<&str>,\n model_label: &str,\n) -> Result<Vec<String>> {\n if issues.is_empty() {\n return Ok(Vec::new());\n }\n\n let (path, mut items) = load_items_at_root(repo_root)?;\n let mut existing_refs = std::collections::HashSet::new();\n for item in &items {\n if let Some(r) = item\n .external_ref\n .as_deref()\n .map(|s| s.trim())\n .filter(|s| !s.is_empty())\n {\n existing_refs.insert(r.to_string());\n }\n }\n\n let mut created_ids = Vec::new();\n let now = Utc::now().to_rfc3339();\n let summary = summary.map(|s| s.trim()).filter(|s| !s.is_empty());\n\n for issue in issues {\n let ext = external_ref_for_review_issue(commit_sha, issue);\n if existing_refs.contains(&ext) {\n continue;\n }\n\n let title = todo_title_compact(issue);\n let mut note = String::new();\n note.push_str(\"Source: flow review\\n\");\n note.push_str(\"Commit: \");\n note.push_str(commit_sha.trim());\n note.push('\\n');\n note.push_str(\"Model: \");\n note.push_str(model_label.trim());\n note.push('\\n');\n if let Some(summary) = summary {\n note.push_str(\"Review summary: \");\n note.push_str(summary);\n note.push('\\n');\n }\n note.push('\\n');\n note.push_str(issue.trim());\n\n let id = Uuid::new_v4().simple().to_string();\n let priority = parse_priority_from_issue(issue);\n items.push(TodoItem {\n id: id.clone(),\n title,\n status: status_to_string(TodoStatusArg::Pending).to_string(),\n created_at: now.clone(),\n updated_at: None,\n note: Some(note),\n session: None,\n external_ref: Some(ext.clone()),\n priority: Some(priority),\n });\n existing_refs.insert(ext);\n created_ids.push(id);\n }\n\n if !created_ids.is_empty() {\n save_items(&path, &items)?;\n }\n\n Ok(created_ids)\n}\n\n/// Mark review-timeout follow-up todos as completed for the given todo ids.\n/// Returns number of todos updated.\npub fn complete_review_timeout_todos(repo_root: &Path, ids: &[String]) -> Result<usize> {\n if ids.is_empty() {\n return Ok(0);\n }\n\n let targets: std::collections::HashSet<String> = ids\n .iter()\n .map(|id| id.trim().to_string())\n .filter(|id| !id.is_empty())\n .collect();\n if targets.is_empty() {\n return Ok(0);\n }\n\n let (path, mut items) = load_items_at_root(repo_root)?;\n let mut updated = 0usize;\n let now = Utc::now().to_rfc3339();\n\n for item in &mut items {\n if !targets.contains(&item.id) {\n continue;\n }\n if !is_review_timeout_followup(item) {\n continue;\n }\n if item.status == status_to_string(TodoStatusArg::Completed) {\n continue;\n }\n item.status = status_to_string(TodoStatusArg::Completed).to_string();\n item.updated_at = Some(now.clone());\n updated += 1;\n }\n\n if updated > 0 {\n save_items(&path, &items)?;\n }\n\n Ok(updated)\n}\n\n/// Count review todos by ids that are still not completed.\npub fn count_open_todos(repo_root: &Path, ids: &[String]) -> Result<usize> {\n if ids.is_empty() {\n return Ok(0);\n }\n let targets: std::collections::HashSet<String> = ids\n .iter()\n .map(|id| id.trim().to_string())\n .filter(|id| !id.is_empty())\n .collect();\n if targets.is_empty() {\n return Ok(0);\n }\n\n let (_path, items) = load_items_at_root(repo_root)?;\n let mut open = 0usize;\n for item in items {\n if !targets.contains(&item.id) {\n continue;\n }\n if item.status != status_to_string(TodoStatusArg::Completed) {\n open += 1;\n }\n }\n Ok(open)\n}\n\nfn is_review_timeout_followup(item: &TodoItem) -> bool {\n let title = item.title.trim().to_lowercase();\n if title.starts_with(\"re-run review:\") || title.contains(\"review timed out\") {\n return true;\n }\n item.note\n .as_deref()\n .map(|n| n.to_lowercase().contains(\"review timed out\"))\n .unwrap_or(false)\n}\n\npub(crate) fn find_item_index(items: &[TodoItem], id: &str) -> Result<usize> {\n let mut matches = Vec::new();\n for (idx, item) in items.iter().enumerate() {\n if item.id == id || item.id.starts_with(id) {\n matches.push(idx);\n }\n }\n\n match matches.len() {\n 0 => bail!(\"Todo '{}' not found\", id),\n 1 => Ok(matches[0]),\n _ => bail!(\"Todo id '{}' is ambiguous\", id),\n }\n}\n\nfn resolve_session_ref(session: Option<&str>, no_session: bool) -> Result<Option<String>> {\n if no_session {\n return Ok(None);\n }\n\n if let Some(session) = session {\n let trimmed = session.trim();\n return Ok(if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n });\n }\n\n let root = project_root();\n match ai::get_latest_session_ref_for_path(&root)? {\n Some(latest) => Ok(Some(latest)),\n None => Ok(None),\n }\n}\n\npub(crate) fn project_root() -> PathBuf {\n let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from(\".\"));\n if let Some(flow_path) = find_flow_toml(&cwd) {\n return flow_path.parent().unwrap_or(&cwd).to_path_buf();\n }\n cwd\n}\n\nfn find_flow_toml(start: &PathBuf) -> Option<PathBuf> {\n let mut current = start.clone();\n loop {\n let candidate = current.join(\"flow.toml\");\n if candidate.exists() {\n return Some(candidate);\n }\n if !current.pop() {\n return None;\n }\n }\n}\n" }, { "path": "src/tools.rs", "content": "//! AI tools management - execute TypeScript tools via localcode/bun.\n//!\n//! Tools are stored in .ai/tools/<name>.ts\n\nuse std::fs;\nuse std::path::PathBuf;\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::{ToolsAction, ToolsCommand};\n\n/// Run the tools subcommand.\npub fn run(cmd: ToolsCommand) -> Result<()> {\n let action = cmd.action.unwrap_or(ToolsAction::List);\n\n match action {\n ToolsAction::List => list_tools()?,\n ToolsAction::Run { name, args } => run_tool(&name, args)?,\n ToolsAction::New {\n name,\n description,\n ai,\n } => new_tool(&name, description.as_deref(), ai)?,\n ToolsAction::Edit { name } => edit_tool(&name)?,\n ToolsAction::Remove { name } => remove_tool(&name)?,\n }\n\n Ok(())\n}\n\n/// Get the tools directory for the current project.\nfn get_tools_dir() -> Result<PathBuf> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n Ok(cwd.join(\".ai\").join(\"tools\"))\n}\n\n/// Find the localcode binary (our opencode fork).\nfn find_localcode() -> Option<PathBuf> {\n // Check ~/.local/bin/localcode first\n if let Some(home) = dirs::home_dir() {\n let local_bin = home.join(\".local/bin/localcode\");\n if local_bin.exists() {\n return Some(local_bin);\n }\n }\n\n // Fall back to PATH\n which::which(\"localcode\").ok()\n}\n\n/// List all tools in the project.\nfn list_tools() -> Result<()> {\n let tools_dir = get_tools_dir()?;\n\n if !tools_dir.exists() {\n println!(\"No tools found. Create one with: f tools new <name>\");\n return Ok(());\n }\n\n let entries = fs::read_dir(&tools_dir).context(\"failed to read tools directory\")?;\n\n let mut tools: Vec<(String, Option<String>)> = Vec::new();\n\n for entry in entries {\n let entry = entry?;\n let path = entry.path();\n\n if path.extension().map_or(false, |e| e == \"ts\") {\n let name = path\n .file_stem()\n .and_then(|n| n.to_str())\n .unwrap_or(\"\")\n .to_string();\n\n let description = parse_tool_description(&path);\n tools.push((name, description));\n }\n }\n\n if tools.is_empty() {\n println!(\"No tools found. Create one with: f tools new <name>\");\n return Ok(());\n }\n\n tools.sort_by(|a, b| a.0.cmp(&b.0));\n\n println!(\"Tools in .ai/tools/:\\n\");\n for (name, desc) in tools {\n if let Some(d) = desc {\n println!(\" {} - {}\", name, d);\n } else {\n println!(\" {}\", name);\n }\n }\n\n println!(\"\\nRun with: f tools run <name>\");\n\n Ok(())\n}\n\n/// Parse description from first comment line in a .ts file.\nfn parse_tool_description(path: &PathBuf) -> Option<String> {\n let content = fs::read_to_string(path).ok()?;\n\n for line in content.lines() {\n let trimmed = line.trim();\n if trimmed.starts_with(\"// \") {\n return Some(trimmed.trim_start_matches(\"// \").to_string());\n }\n if trimmed.starts_with(\"///\") {\n return Some(trimmed.trim_start_matches(\"///\").trim().to_string());\n }\n // Skip empty lines at the top\n if !trimmed.is_empty() && !trimmed.starts_with(\"//\") {\n break;\n }\n }\n\n None\n}\n\n/// Run a tool via bun.\nfn run_tool(name: &str, args: Vec<String>) -> Result<()> {\n let tools_dir = get_tools_dir()?;\n let tool_file = tools_dir.join(format!(\"{}.ts\", name));\n\n if !tool_file.exists() {\n bail!(\n \"Tool '{}' not found. Create it with: f tools new {}\",\n name,\n name\n );\n }\n\n let status = Command::new(\"bun\")\n .arg(\"run\")\n .arg(&tool_file)\n .args(&args)\n .status()\n .context(\"failed to run bun\")?;\n\n if !status.success() {\n bail!(\"Tool '{}' exited with status: {}\", name, status);\n }\n\n Ok(())\n}\n\n/// Create a new tool.\nfn new_tool(name: &str, description: Option<&str>, use_ai: bool) -> Result<()> {\n let tools_dir = get_tools_dir()?;\n fs::create_dir_all(&tools_dir).context(\"failed to create tools directory\")?;\n\n let tool_file = tools_dir.join(format!(\"{}.ts\", name));\n\n if tool_file.exists() {\n bail!(\"Tool '{}' already exists\", name);\n }\n\n if use_ai {\n // Use localcode to generate the tool\n let localcode = find_localcode();\n if localcode.is_none() {\n bail!(\n \"localcode not found. Install it with:\\n \\\n cd <opencode-repo> && flow link\"\n );\n }\n\n let desc = description.unwrap_or(name);\n let prompt = format!(\n \"Create a TypeScript tool for Bun called '{}' that: {}\\n\\n\\\n Requirements:\\n\\\n - Use Bun APIs (Bun.$, Bun.file, etc.)\\n\\\n - Add a description comment at the top\\n\\\n - Handle CLI args via Bun.argv\\n\\\n - Save to: {}\",\n name,\n desc,\n tool_file.display()\n );\n\n println!(\"Generating tool '{}' with AI...\\n\", name);\n\n let status = Command::new(localcode.unwrap())\n .arg(\"--print\")\n .arg(&prompt)\n .status()\n .context(\"failed to run localcode\")?;\n\n if !status.success() {\n bail!(\"AI generation failed with status: {}\", status);\n }\n\n if tool_file.exists() {\n println!(\"\\nCreated tool: {}\", tool_file.display());\n println!(\"Run it with: f tools run {}\", name);\n }\n } else {\n // Create template\n let desc = description.unwrap_or(\"TODO: Add description\");\n let content = format!(\n r#\"// {desc}\n\nimport {{ $ }} from \"bun\"\n\nconst args = Bun.argv.slice(2)\n\n// TODO: Implement tool logic\nconsole.log(\"{name} tool running with args:\", args)\n\"#,\n desc = desc,\n name = name\n );\n\n fs::write(&tool_file, content).context(\"failed to write tool file\")?;\n\n println!(\"Created tool: {}\", tool_file.display());\n println!(\"\\nEdit it with: f tools edit {}\", name);\n println!(\"Run it with: f tools run {}\", name);\n }\n\n Ok(())\n}\n\n/// Edit a tool in the user's editor.\nfn edit_tool(name: &str) -> Result<()> {\n let tools_dir = get_tools_dir()?;\n let tool_file = tools_dir.join(format!(\"{}.ts\", name));\n\n if !tool_file.exists() {\n bail!(\n \"Tool '{}' not found. Create it with: f tools new {}\",\n name,\n name\n );\n }\n\n let editor = std::env::var(\"EDITOR\").unwrap_or_else(|_| \"vim\".to_string());\n\n Command::new(&editor)\n .arg(&tool_file)\n .status()\n .with_context(|| format!(\"failed to open editor: {}\", editor))?;\n\n Ok(())\n}\n\n/// Remove a tool.\nfn remove_tool(name: &str) -> Result<()> {\n let tools_dir = get_tools_dir()?;\n let tool_file = tools_dir.join(format!(\"{}.ts\", name));\n\n if !tool_file.exists() {\n bail!(\"Tool '{}' not found\", name);\n }\n\n fs::remove_file(&tool_file).context(\"failed to remove tool file\")?;\n\n println!(\"Removed tool: {}\", name);\n\n Ok(())\n}\n" }, { "path": "src/trace.rs", "content": "use std::{\n collections::HashMap,\n fs::{self, File},\n io::{BufRead, BufReader, Seek, SeekFrom},\n path::{Path, PathBuf},\n sync::mpsc,\n time::Duration,\n};\n\nuse anyhow::{Context, Result, bail};\nuse base64::{Engine, engine::general_purpose};\nuse notify::{RecursiveMode, Watcher};\n\nuse crate::cli::TraceOpts;\n\nconst META_DIR_SUFFIX: &str = \".flow/tty-meta\";\nconst TTY_LOG_DIR_SUFFIX: &str = \".flow/tmux-logs\";\n\npub fn run(opts: TraceOpts) -> Result<()> {\n if opts.last_command {\n return print_last_command();\n }\n stream_operations()\n}\n\nfn stream_operations() -> Result<()> {\n let meta_dir = meta_dir();\n if !meta_dir.exists() {\n bail!(\n \"no meta dir at {}; enable trace_terminal_io and open a new terminal\",\n meta_dir.display()\n );\n }\n\n let mut positions = HashMap::new();\n bootstrap_existing(&meta_dir, &mut positions)?;\n\n let (tx, rx) = mpsc::channel();\n let mut watcher = notify::recommended_watcher(move |res| {\n let _ = tx.send(res);\n })\n .context(\"failed to start watcher on tty meta dir\")?;\n watcher\n .watch(&meta_dir, RecursiveMode::NonRecursive)\n .with_context(|| format!(\"failed to watch {}\", meta_dir.display()))?;\n\n println!(\"# streaming command events (Ctrl+C to stop)\");\n loop {\n match rx.recv_timeout(Duration::from_millis(500)) {\n Ok(Ok(event)) => {\n for path in event.paths {\n if path.extension().and_then(|s| s.to_str()) != Some(\"log\") {\n continue;\n }\n let _ = print_new_lines(&path, &mut positions);\n }\n }\n Ok(Err(err)) => {\n eprintln!(\"watch error: {err}\");\n }\n Err(mpsc::RecvTimeoutError::Timeout) => {\n // poll for new files\n let _ = bootstrap_existing(&meta_dir, &mut positions);\n }\n Err(mpsc::RecvTimeoutError::Disconnected) => break,\n }\n }\n\n Ok(())\n}\n\nfn bootstrap_existing(meta_dir: &Path, positions: &mut HashMap<PathBuf, u64>) -> Result<()> {\n for entry in\n fs::read_dir(meta_dir).with_context(|| format!(\"failed to read {}\", meta_dir.display()))?\n {\n let entry = entry?;\n let path = entry.path();\n if path.extension().and_then(|s| s.to_str()) != Some(\"log\") {\n continue;\n }\n if !positions.contains_key(&path) {\n positions.insert(path.clone(), 0);\n print_new_lines(&path, positions)?;\n }\n }\n Ok(())\n}\n\nfn print_new_lines(path: &Path, positions: &mut HashMap<PathBuf, u64>) -> Result<()> {\n let mut file =\n File::open(path).with_context(|| format!(\"failed to open {}\", path.display()))?;\n let pos = positions.entry(path.to_path_buf()).or_insert(0);\n file.seek(SeekFrom::Start(*pos))\n .with_context(|| format!(\"failed to seek {}\", path.display()))?;\n\n let mut reader = BufReader::new(file);\n let mut buf = String::new();\n while reader.read_line(&mut buf)? != 0 {\n *pos += buf.len() as u64;\n if let Some(evt) = parse_meta_line(buf.trim_end()) {\n println!(\"{}\", format_event(evt, path));\n }\n buf.clear();\n }\n\n Ok(())\n}\n\nfn print_last_command() -> Result<()> {\n let meta_dir = meta_dir();\n let tty_dir = tty_dir();\n if !meta_dir.exists() {\n bail!(\n \"no meta data found at {}; enable trace_terminal_io and run commands inside tmux\",\n meta_dir.display()\n );\n }\n\n if !tty_dir.exists() {\n bail!(\n \"no tmux logs at {}; ensure shells run inside tmux\",\n tty_dir.display()\n );\n }\n\n let (last_evt, start_map) = latest_event(&meta_dir)?;\n let Some(evt) = last_evt else {\n bail!(\"no commands recorded yet\");\n };\n let cmd = start_map.get(&evt.id).cloned();\n\n let output = extract_command_output(&evt.id, &tty_dir)\n .with_context(|| format!(\"failed to find output for command {}\", evt.id))?;\n\n if let Some(start) = cmd {\n println!(\n \"command: {}\",\n start.cmd.unwrap_or_else(|| \"<unknown>\".to_string())\n );\n if let Some(cwd) = start.cwd {\n println!(\"cwd: {cwd}\");\n }\n } else {\n println!(\"command: <unknown>\");\n }\n if let Some(status) = evt.status {\n println!(\"status: {status}\");\n }\n println!(\"--- output ---\");\n print!(\"{output}\");\n Ok(())\n}\n\nfn extract_command_output(id: &str, tty_dir: &Path) -> Result<String> {\n let start_marker = format!(\"flow-cmd-start;{id}\");\n let end_marker = format!(\"flow-cmd-end;{id}\");\n\n for entry in\n fs::read_dir(tty_dir).with_context(|| format!(\"failed to read {}\", tty_dir.display()))?\n {\n let entry = entry?;\n let path = entry.path();\n if path.extension().and_then(|s| s.to_str()) != Some(\"log\") {\n continue;\n }\n let content = fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read tty log {}\", path.display()))?;\n\n if let Some(start_pos) = content.find(&start_marker) {\n let after_start = content[start_pos..]\n .find('\\x07')\n .map(|idx| start_pos + idx + 1)\n .unwrap_or(start_pos);\n if let Some(end_pos) = content[after_start..].find(&end_marker) {\n let end_idx = after_start + end_pos;\n let slice = &content[after_start..end_idx];\n return Ok(slice.trim_matches(|c| c == '\\n' || c == '\\r').to_string());\n }\n }\n }\n\n bail!(\"command id {id} not found in tty logs; ensure command ran inside tmux\")\n}\n\n#[derive(Clone)]\nstruct MetaEvent {\n ts: String,\n id: String,\n kind: MetaKind,\n cmd: Option<String>,\n cwd: Option<String>,\n status: Option<i32>,\n}\n\n#[derive(Clone)]\nenum MetaKind {\n Start,\n End,\n}\n\nfn parse_meta_line(line: &str) -> Option<MetaEvent> {\n let mut parts = line.split_whitespace();\n let kind = parts.next()?;\n let ts = parts.next()?.to_string();\n\n match kind {\n \"start\" => {\n let id = parts.next()?.to_string();\n let cwd_b64 = parts.next().unwrap_or(\"\");\n let cmd_b64 = parts.next().unwrap_or(\"\");\n Some(MetaEvent {\n ts,\n id,\n kind: MetaKind::Start,\n cwd: decode_b64(cwd_b64),\n cmd: decode_b64(cmd_b64),\n status: None,\n })\n }\n \"end\" => {\n let id = parts.next()?.to_string();\n let status = parts.next().and_then(|s| s.parse::<i32>().ok());\n Some(MetaEvent {\n ts,\n id,\n kind: MetaKind::End,\n cmd: None,\n cwd: None,\n status,\n })\n }\n _ => None,\n }\n}\n\nfn format_event(evt: MetaEvent, path: &Path) -> String {\n match evt.kind {\n MetaKind::Start => format!(\n \"[{} {}] start {} (cwd: {})\",\n path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"pane\"),\n evt.ts,\n evt.cmd.unwrap_or_else(|| \"<unknown>\".to_string()),\n evt.cwd.unwrap_or_else(|| \"?\".to_string())\n ),\n MetaKind::End => format!(\n \"[{} {}] end status={}\",\n path.file_stem().and_then(|s| s.to_str()).unwrap_or(\"pane\"),\n evt.ts,\n evt.status\n .map(|s| s.to_string())\n .unwrap_or_else(|| \"?\".to_string())\n ),\n }\n}\n\nfn latest_event(meta_dir: &Path) -> Result<(Option<MetaEvent>, HashMap<String, MetaEvent>)> {\n let mut last: Option<MetaEvent> = None;\n let mut starts: HashMap<String, MetaEvent> = HashMap::new();\n\n for entry in\n fs::read_dir(meta_dir).with_context(|| format!(\"failed to read {}\", meta_dir.display()))?\n {\n let entry = entry?;\n let path = entry.path();\n if path.extension().and_then(|s| s.to_str()) != Some(\"log\") {\n continue;\n }\n let file =\n File::open(&path).with_context(|| format!(\"failed to open {}\", path.display()))?;\n let reader = BufReader::new(file);\n for line in reader.lines() {\n let line = match line {\n Ok(l) => l,\n Err(_) => continue,\n };\n if let Some(evt) = parse_meta_line(&line) {\n if matches!(evt.kind, MetaKind::Start) {\n starts.insert(evt.id.clone(), evt.clone());\n }\n if last.as_ref().map_or(true, |prev| evt.ts > prev.ts) {\n last = Some(evt);\n }\n }\n }\n }\n\n Ok((last, starts))\n}\n\nfn decode_b64(input: &str) -> Option<String> {\n general_purpose::STANDARD\n .decode(input.as_bytes())\n .ok()\n .and_then(|bytes| String::from_utf8(bytes).ok())\n}\n\nfn meta_dir() -> PathBuf {\n home_dir().join(META_DIR_SUFFIX)\n}\n\nfn tty_dir() -> PathBuf {\n home_dir().join(TTY_LOG_DIR_SUFFIX)\n}\n\nfn home_dir() -> PathBuf {\n std::env::var_os(\"HOME\")\n .map(PathBuf::from)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n}\n" }, { "path": "src/traces.rs", "content": "use std::env;\nuse std::path::{Path, PathBuf};\nuse std::sync::Arc;\nuse std::time::{Duration, UNIX_EPOCH};\n\nuse anyhow::{Context, Result, bail};\nuse groove::ObjectId;\nuse groove::sql::{Database, RowValue};\nuse groove_rocksdb::RocksEnvironment;\n\nuse crate::ai;\nuse crate::cli::{TraceSessionOpts, TraceSource, TracesOpts};\nuse crate::jazz_state;\n\nconst DEFAULT_LIMIT: usize = 40;\nconst DETAIL_LIMIT: usize = 120;\nconst FOLLOW_POLL_MS: u64 = 400;\n\npub fn run(opts: TracesOpts) -> Result<()> {\n let flow_path = jazz_state::state_dir();\n let flow_db = open_db_at(&flow_path)?;\n let ai_db = open_ai_db(&flow_path);\n let limit = if opts.limit == 0 {\n DEFAULT_LIMIT\n } else {\n opts.limit\n };\n\n if opts.follow {\n follow_traces(&flow_db, ai_db.as_ref(), &opts, limit)\n } else {\n let mut items = fetch_all(&flow_db, ai_db.as_ref(), &opts, 0, limit, false)?;\n items.sort_by_key(|item| item.timestamp_ms);\n for item in items {\n println!(\"{}\", format_item(&item));\n }\n Ok(())\n }\n}\n\npub fn run_session(opts: TraceSessionOpts) -> Result<()> {\n let mut path = opts.path;\n if path.is_relative() {\n let cwd = env::current_dir().context(\"read current dir\")?;\n path = cwd.join(path);\n }\n let path = path.canonicalize().unwrap_or(path);\n let history = ai::get_latest_session_history_for_path(&path)?;\n let Some(history) = history else {\n println!(\"No AI sessions found for {}\", path.display());\n return Ok(());\n };\n\n let id_short = &history.session_id[..8.min(history.session_id.len())];\n println!(\"# session {}:{}\", history.provider, id_short);\n println!(\"# path {}\", path.display());\n if let Some(ts) = history.started_at.as_deref() {\n println!(\"# started_at {ts}\");\n }\n if let Some(ts) = history.last_message_at.as_deref() {\n println!(\"# last_message_at {ts}\");\n }\n\n for message in history.messages {\n println!();\n println!(\"[{}]\", message.role);\n println!(\"{}\", message.content);\n }\n\n Ok(())\n}\n\nfn follow_traces(\n flow_db: &Database,\n ai_db: Option<&Database>,\n opts: &TracesOpts,\n limit: usize,\n) -> Result<()> {\n let mut since = 0u64;\n let mut initial = fetch_all(flow_db, ai_db, opts, 0, limit, true)?;\n initial.sort_by_key(|item| item.timestamp_ms);\n for item in &initial {\n println!(\"{}\", format_item(item));\n since = since.max(item.timestamp_ms);\n }\n\n loop {\n std::thread::sleep(Duration::from_millis(FOLLOW_POLL_MS));\n let mut items = fetch_all(flow_db, ai_db, opts, since, limit, true)?;\n items.sort_by_key(|item| item.timestamp_ms);\n for item in &items {\n if item.timestamp_ms > since {\n println!(\"{}\", format_item(item));\n since = since.max(item.timestamp_ms);\n }\n }\n }\n}\n\nfn fetch_all(\n flow_db: &Database,\n ai_db: Option<&Database>,\n opts: &TracesOpts,\n since: u64,\n limit: usize,\n ascending: bool,\n) -> Result<Vec<TraceItem>> {\n let mut items = Vec::new();\n match opts.source {\n TraceSource::All => {\n items.extend(fetch_task_runs(\n flow_db,\n opts.project.as_deref(),\n since,\n limit,\n ascending,\n )?);\n let agent_db = ai_db.unwrap_or(flow_db);\n items.extend(fetch_agent_events(\n agent_db,\n opts.project.as_deref(),\n since,\n limit,\n ascending,\n )?);\n }\n TraceSource::Tasks => {\n items.extend(fetch_task_runs(\n flow_db,\n opts.project.as_deref(),\n since,\n limit,\n ascending,\n )?);\n }\n TraceSource::Ai => {\n let agent_db = ai_db.unwrap_or(flow_db);\n items.extend(fetch_agent_events(\n agent_db,\n opts.project.as_deref(),\n since,\n limit,\n ascending,\n )?);\n }\n }\n Ok(items)\n}\n\nfn fetch_task_runs(\n db: &Database,\n project_filter: Option<&str>,\n since: u64,\n limit: usize,\n ascending: bool,\n) -> Result<Vec<TraceItem>> {\n let order = if ascending { \"ASC\" } else { \"DESC\" };\n let sql = format!(\n \"SELECT task, command, success, status, duration_ms, timestamp_ms, output, project_root \\\n FROM flow_task_runs WHERE timestamp_ms > {} ORDER BY timestamp_ms {} LIMIT {}\",\n since, order, limit\n );\n\n let rows = db.query(&sql).unwrap_or_default();\n let mut items = Vec::new();\n for (_, row) in rows {\n let task = match row.get_by_name(\"task\") {\n Some(RowValue::String(s)) => s.to_string(),\n _ => continue,\n };\n let project = match row.get_by_name(\"project_root\") {\n Some(RowValue::String(s)) => s.to_string(),\n _ => String::new(),\n };\n if let Some(filter) = project_filter {\n if !project.contains(filter) {\n continue;\n }\n }\n let success = matches!(row.get_by_name(\"success\"), Some(RowValue::Bool(true)));\n let timestamp_ms = match row.get_by_name(\"timestamp_ms\") {\n Some(RowValue::I64(ts)) => ts as u64,\n _ => 0,\n };\n let duration_ms = match row.get_by_name(\"duration_ms\") {\n Some(RowValue::I64(d)) => d as u64,\n _ => 0,\n };\n let status = match row.get_by_name(\"status\") {\n Some(RowValue::I64(s)) => Some(s),\n _ => None,\n };\n let output = match row.get_by_name(\"output\") {\n Some(RowValue::String(s)) => s.to_string(),\n _ => String::new(),\n };\n let command = match row.get_by_name(\"command\") {\n Some(RowValue::String(s)) => s.to_string(),\n _ => String::new(),\n };\n\n let kind = if success { \"task_ok\" } else { \"task_fail\" };\n let detail = if success {\n format!(\"{}ms\", duration_ms)\n } else {\n let status_str = status.map(|s| format!(\"exit {}\", s)).unwrap_or_default();\n let last_line = output.lines().last().unwrap_or(\"\").trim();\n if last_line.is_empty() {\n status_str\n } else {\n format!(\"{} | {}\", status_str, last_line)\n }\n };\n\n items.push(TraceItem {\n timestamp_ms,\n source: \"task\",\n kind: kind.to_string(),\n summary: task,\n detail,\n project,\n extra: command,\n });\n }\n Ok(items)\n}\n\nfn fetch_agent_events(\n db: &Database,\n project_filter: Option<&str>,\n since: u64,\n limit: usize,\n ascending: bool,\n) -> Result<Vec<TraceItem>> {\n let order = if ascending { \"ASC\" } else { \"DESC\" };\n let sql = format!(\n \"SELECT event_kind, summary, detail, timestamp_ms, project_root \\\n FROM ai_agent_events WHERE timestamp_ms > {} ORDER BY timestamp_ms {} LIMIT {}\",\n since, order, limit\n );\n\n let rows = db.query(&sql).unwrap_or_default();\n let mut items = Vec::new();\n for (_, row) in rows {\n let kind = match row.get_by_name(\"event_kind\") {\n Some(RowValue::String(s)) => s.to_string(),\n _ => continue,\n };\n let summary = match row.get_by_name(\"summary\") {\n Some(RowValue::String(s)) => s.to_string(),\n _ => String::new(),\n };\n let detail = match row.get_by_name(\"detail\") {\n Some(RowValue::String(s)) => s.to_string(),\n _ => String::new(),\n };\n let timestamp_ms = match row.get_by_name(\"timestamp_ms\") {\n Some(RowValue::I64(ts)) => ts as u64,\n _ => 0,\n };\n let project = match row.get_by_name(\"project_root\") {\n Some(RowValue::String(s)) => s.to_string(),\n _ => String::new(),\n };\n if let Some(filter) = project_filter {\n if !project.contains(filter) {\n continue;\n }\n }\n\n items.push(TraceItem {\n timestamp_ms,\n source: \"ai\",\n kind,\n summary,\n detail,\n project,\n extra: String::new(),\n });\n }\n Ok(items)\n}\n\n#[derive(Clone)]\nstruct TraceItem {\n timestamp_ms: u64,\n source: &'static str,\n kind: String,\n summary: String,\n detail: String,\n project: String,\n extra: String,\n}\n\nfn format_item(item: &TraceItem) -> String {\n let time = format_timestamp(item.timestamp_ms);\n let project = project_label(&item.project);\n let detail = truncate(&item.detail, DETAIL_LIMIT);\n let summary = if item.summary.is_empty() {\n item.kind.clone()\n } else {\n item.summary.clone()\n };\n let extra = if item.extra.is_empty() {\n String::new()\n } else {\n format!(\" | {}\", truncate(&item.extra, 60))\n };\n\n format!(\n \"{} {:>4} {:<10} {} ({}) | {}{}\",\n time, item.source, item.kind, summary, project, detail, extra\n )\n}\n\nfn format_timestamp(timestamp_ms: u64) -> String {\n let system_time = UNIX_EPOCH + Duration::from_millis(timestamp_ms);\n let dt: chrono::DateTime<chrono::Local> = system_time.into();\n dt.format(\"%H:%M:%S%.3f\").to_string()\n}\n\nfn project_label(project: &str) -> String {\n project.rsplit('/').next().unwrap_or(project).to_string()\n}\n\nfn truncate(value: &str, limit: usize) -> String {\n if value.len() <= limit {\n return value.to_string();\n }\n let mut end = limit;\n while end > 0 && !value.is_char_boundary(end) {\n end -= 1;\n }\n format!(\"{}…\", &value[..end])\n}\n\nfn open_db_at(path: &Path) -> Result<Database> {\n use groove::Environment;\n\n if !path.exists() {\n bail!(\"jazz2 state not found at {}\", path.display());\n }\n\n let env: Arc<dyn Environment> =\n Arc::new(RocksEnvironment::open(&path).context(\"open rocksdb\")?);\n let catalog_id = load_catalog_id(&path).context(\"load catalog id\")?;\n let db = futures::executor::block_on(Database::from_env(env, catalog_id))\n .context(\"load jazz2 catalog\")?;\n Ok(db)\n}\n\nfn open_ai_db(flow_path: &Path) -> Option<Database> {\n let path = if let Ok(path) = env::var(\"AI_JAZZ2_PATH\") {\n PathBuf::from(path)\n } else {\n flow_path.join(\"ai\")\n };\n if path == flow_path || !path.exists() {\n return None;\n }\n open_db_at(&path).ok()\n}\n\nfn load_catalog_id(base: &Path) -> Result<ObjectId> {\n let path = base.join(\"catalog.id\");\n let contents =\n std::fs::read_to_string(&path).with_context(|| format!(\"read {}\", path.display()))?;\n let trimmed = contents.trim();\n let id = trimmed\n .parse::<ObjectId>()\n .with_context(|| format!(\"parse catalog id {}\", trimmed))?;\n Ok(id)\n}\n" }, { "path": "src/traces_stub.rs", "content": "use anyhow::{Result, bail};\n\nuse crate::base_tool;\nuse crate::cli::{TraceSessionOpts, TraceSource, TracesOpts};\n\npub fn run(opts: TracesOpts) -> Result<()> {\n let Some(bin) = base_tool::resolve_bin() else {\n bail!(\n \"traces require the base tool (FLOW_BASE_BIN).\\n\\\n Install it, then retry.\\n\\\n (Expected `base` or `db` on PATH, or set FLOW_BASE_BIN=/path/to/base)\"\n );\n };\n\n let mut args: Vec<String> = vec![\n \"trace\".to_string(),\n \"--limit\".to_string(),\n opts.limit.to_string(),\n ];\n if opts.follow {\n args.push(\"--follow\".to_string());\n }\n if let Some(project) = opts\n .project\n .as_deref()\n .map(|s| s.trim())\n .filter(|s| !s.is_empty())\n {\n args.push(\"--project\".to_string());\n args.push(project.to_string());\n }\n args.push(\"--source\".to_string());\n args.push(\n match opts.source {\n TraceSource::All => \"all\",\n TraceSource::Tasks => \"tasks\",\n TraceSource::Ai => \"ai\",\n }\n .to_string(),\n );\n\n base_tool::run_inherit_stdio(&bin, &args)\n}\n\npub fn run_session(_opts: TraceSessionOpts) -> Result<()> {\n let Some(bin) = base_tool::resolve_bin() else {\n bail!(\n \"trace session requires the base tool (FLOW_BASE_BIN).\\n\\\n Install it, then retry.\\n\\\n (Expected `base` or `db` on PATH, or set FLOW_BASE_BIN=/path/to/base)\"\n );\n };\n\n // Keep behavior compatible with Flow's old implementation: always show full session history.\n let mut args: Vec<String> = vec![\"session\".to_string()];\n args.push(_opts.path.display().to_string());\n base_tool::run_inherit_stdio(&bin, &args)\n}\n\npub fn trace_source_from_str(_value: &str) -> TraceSource {\n TraceSource::Tasks\n}\n" }, { "path": "src/undo.rs", "content": "//! Undo system for flow actions.\n//!\n//! Tracks undoable actions (commit, push, etc.) and provides undo functionality.\n\nuse anyhow::{Context, Result, bail};\nuse serde::{Deserialize, Serialize};\nuse std::fs;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\nuse tracing::{debug, info};\n\nuse crate::cli::{UndoAction, UndoCommand};\n\n/// Run the undo command.\npub fn run(cmd: UndoCommand) -> Result<()> {\n let cwd = std::env::current_dir()?;\n\n // Find repository root\n let repo_root = find_repo_root(&cwd)?;\n\n match cmd.action {\n Some(UndoAction::Show) => {\n show_last(&repo_root)?;\n }\n Some(UndoAction::List { limit }) => {\n list_actions(&repo_root, limit)?;\n }\n None => {\n // Default action: undo the last action\n let opts = UndoOpts {\n dry_run: cmd.dry_run,\n force: cmd.force,\n };\n\n match undo_last(&repo_root, &opts) {\n Ok(result) => {\n if !cmd.dry_run {\n if result.force_pushed {\n println!(\"\\nAction undone. Remote has been updated.\");\n } else {\n println!(\"\\nAction undone.\");\n }\n }\n }\n Err(e) => {\n bail!(\"{}\", e);\n }\n }\n }\n }\n\n Ok(())\n}\n\n/// Find the git repository root from a path.\nfn find_repo_root(start: &Path) -> Result<PathBuf> {\n let output = Command::new(\"git\")\n .args([\"rev-parse\", \"--show-toplevel\"])\n .current_dir(start)\n .output()\n .context(\"failed to find git repository\")?;\n\n if !output.status.success() {\n bail!(\"Not in a git repository\");\n }\n\n let path = String::from_utf8_lossy(&output.stdout).trim().to_string();\n Ok(PathBuf::from(path))\n}\n\n/// Action types that can be undone.\n#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]\n#[serde(rename_all = \"snake_case\")]\npub enum ActionType {\n /// Git commit (can be undone with reset)\n Commit,\n /// Git push (can be undone with force push)\n Push,\n /// Commit + push together\n CommitPush,\n}\n\nimpl std::fmt::Display for ActionType {\n fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {\n match self {\n ActionType::Commit => write!(f, \"commit\"),\n ActionType::Push => write!(f, \"push\"),\n ActionType::CommitPush => write!(f, \"commit+push\"),\n }\n }\n}\n\n/// Record of an undoable action.\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct UndoRecord {\n /// Timestamp when action was performed (ISO 8601)\n pub timestamp: String,\n /// Type of action\n pub action: ActionType,\n /// Git commit SHA before the action (for reverting)\n pub before_sha: String,\n /// Git commit SHA after the action\n pub after_sha: String,\n /// Branch name\n pub branch: String,\n /// Whether the action included a push\n pub pushed: bool,\n /// Remote name (if pushed)\n pub remote: Option<String>,\n /// Commit message (for display)\n pub message: Option<String>,\n}\n\n/// Get the undo log path for a repository.\nfn undo_log_path(repo_root: &Path) -> PathBuf {\n repo_root\n .join(\".ai\")\n .join(\"internal\")\n .join(\"undo-log.jsonl\")\n}\n\n/// Record an undoable action.\npub fn record_action(\n repo_root: &Path,\n action: ActionType,\n before_sha: &str,\n after_sha: &str,\n branch: &str,\n pushed: bool,\n remote: Option<&str>,\n message: Option<&str>,\n) -> Result<()> {\n let log_path = undo_log_path(repo_root);\n\n // Ensure parent directory exists\n if let Some(parent) = log_path.parent() {\n fs::create_dir_all(parent)?;\n }\n\n let record = UndoRecord {\n timestamp: chrono::Utc::now().to_rfc3339(),\n action,\n before_sha: before_sha.to_string(),\n after_sha: after_sha.to_string(),\n branch: branch.to_string(),\n pushed,\n remote: remote.map(|s| s.to_string()),\n message: message.map(|s| s.to_string()),\n };\n\n let line = serde_json::to_string(&record)?;\n\n // Append to log file\n let mut file = fs::OpenOptions::new()\n .create(true)\n .append(true)\n .open(&log_path)?;\n\n use std::io::Write;\n writeln!(file, \"{}\", line)?;\n\n debug!(\n action = %record.action,\n before = %record.before_sha,\n after = %record.after_sha,\n \"recorded undo action\"\n );\n\n Ok(())\n}\n\n/// Get the last undoable action for the current repository.\npub fn get_last_action(repo_root: &Path) -> Result<Option<UndoRecord>> {\n let log_path = undo_log_path(repo_root);\n\n if !log_path.exists() {\n return Ok(None);\n }\n\n let content = fs::read_to_string(&log_path)?;\n let lines: Vec<&str> = content.lines().filter(|l| !l.trim().is_empty()).collect();\n\n if lines.is_empty() {\n return Ok(None);\n }\n\n // Get the last line\n let last_line = lines.last().unwrap();\n let record: UndoRecord =\n serde_json::from_str(last_line).context(\"failed to parse last undo record\")?;\n\n Ok(Some(record))\n}\n\n/// Remove the last action from the undo log.\nfn remove_last_action(repo_root: &Path) -> Result<()> {\n let log_path = undo_log_path(repo_root);\n\n if !log_path.exists() {\n return Ok(());\n }\n\n let content = fs::read_to_string(&log_path)?;\n let mut lines: Vec<&str> = content.lines().filter(|l| !l.trim().is_empty()).collect();\n\n if lines.is_empty() {\n return Ok(());\n }\n\n // Remove last line\n lines.pop();\n\n // Rewrite file\n let new_content = if lines.is_empty() {\n String::new()\n } else {\n lines.join(\"\\n\") + \"\\n\"\n };\n\n fs::write(&log_path, new_content)?;\n\n Ok(())\n}\n\n/// Options for undo operation.\n#[derive(Debug, Default)]\npub struct UndoOpts {\n /// Dry run - show what would be done without doing it\n pub dry_run: bool,\n /// Force undo even if it requires force push\n pub force: bool,\n}\n\n/// Result of an undo operation.\n#[derive(Debug)]\npub struct UndoResult {\n pub action_type: ActionType,\n pub before_sha: String,\n pub after_sha: String,\n pub force_pushed: bool,\n}\n\n/// Undo the last action.\npub fn undo_last(repo_root: &Path, opts: &UndoOpts) -> Result<UndoResult> {\n let record =\n get_last_action(repo_root)?.ok_or_else(|| anyhow::anyhow!(\"No actions to undo\"))?;\n\n // Check if we're on the same branch\n let current_branch = git_capture(repo_root, &[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])?;\n if current_branch.trim() != record.branch {\n bail!(\n \"Currently on branch '{}', but last action was on '{}'. Switch branches first.\",\n current_branch.trim(),\n record.branch\n );\n }\n\n // Check if HEAD matches the after_sha\n let current_sha = git_capture(repo_root, &[\"rev-parse\", \"HEAD\"])?;\n if !current_sha\n .trim()\n .starts_with(&record.after_sha[..7.min(record.after_sha.len())])\n {\n // Try short comparison\n let current_short = ¤t_sha.trim()[..7.min(current_sha.len())];\n let record_short = &record.after_sha[..7.min(record.after_sha.len())];\n if current_short != record_short {\n bail!(\n \"HEAD ({}) doesn't match the recorded action ({}). \\\n The repository state has changed since the action was recorded.\",\n current_short,\n record_short\n );\n }\n }\n\n if opts.dry_run {\n println!(\n \"Would undo: {} ({})\",\n record.action,\n short_sha(&record.after_sha)\n );\n println!(\" Reset to: {}\", short_sha(&record.before_sha));\n if record.pushed {\n println!(\" Would force push to remote\");\n }\n return Ok(UndoResult {\n action_type: record.action.clone(),\n before_sha: record.before_sha.clone(),\n after_sha: record.after_sha.clone(),\n force_pushed: false,\n });\n }\n\n // Perform the undo based on action type\n match &record.action {\n ActionType::Commit => {\n undo_commit(repo_root, &record)?;\n }\n ActionType::Push => {\n if !opts.force {\n bail!(\"Undoing a push requires --force flag (this will force push to remote)\");\n }\n undo_push(repo_root, &record)?;\n }\n ActionType::CommitPush => {\n if record.pushed && !opts.force {\n bail!(\"This action was pushed to remote. Use --force to undo (will force push)\");\n }\n undo_commit_push(repo_root, &record, opts.force)?;\n }\n }\n\n // Remove from undo log after successful undo\n remove_last_action(repo_root)?;\n\n let force_pushed = record.pushed\n && (record.action == ActionType::Push || record.action == ActionType::CommitPush);\n\n Ok(UndoResult {\n action_type: record.action,\n before_sha: record.before_sha,\n after_sha: record.after_sha,\n force_pushed,\n })\n}\n\n/// Undo a commit (reset --soft to keep changes staged).\nfn undo_commit(repo_root: &Path, record: &UndoRecord) -> Result<()> {\n info!(sha = %record.after_sha, \"undoing commit\");\n\n // Use --soft to keep changes staged\n git_run(repo_root, &[\"reset\", \"--soft\", &record.before_sha])?;\n\n println!(\"✓ Undid commit {}\", short_sha(&record.after_sha));\n println!(\" Changes are still staged\");\n\n Ok(())\n}\n\n/// Undo a push (force push the previous state).\nfn undo_push(repo_root: &Path, record: &UndoRecord) -> Result<()> {\n let remote = record.remote.as_deref().unwrap_or(\"origin\");\n\n info!(\n sha = %record.after_sha,\n remote = %remote,\n branch = %record.branch,\n \"undoing push with force push\"\n );\n\n // Force push the before_sha to the branch\n git_run(\n repo_root,\n &[\n \"push\",\n \"--force\",\n remote,\n &format!(\"{}:{}\", record.before_sha, record.branch),\n ],\n )?;\n\n println!(\n \"✓ Force pushed {} to {}/{}\",\n short_sha(&record.before_sha),\n remote,\n record.branch\n );\n\n Ok(())\n}\n\n/// Undo a commit+push operation.\nfn undo_commit_push(repo_root: &Path, record: &UndoRecord, force: bool) -> Result<()> {\n info!(sha = %record.after_sha, pushed = record.pushed, \"undoing commit+push\");\n\n // First, reset the local commit\n git_run(repo_root, &[\"reset\", \"--soft\", &record.before_sha])?;\n println!(\"✓ Undid commit {}\", short_sha(&record.after_sha));\n\n // If it was pushed, force push to revert remote\n if record.pushed && force {\n let remote = record.remote.as_deref().unwrap_or(\"origin\");\n git_run(repo_root, &[\"push\", \"--force\", remote, &record.branch])?;\n println!(\"✓ Force pushed to {}/{}\", remote, record.branch);\n }\n\n println!(\" Changes are still staged\");\n\n Ok(())\n}\n\n/// Show the last undoable action without undoing it.\npub fn show_last(repo_root: &Path) -> Result<()> {\n match get_last_action(repo_root)? {\n Some(record) => {\n println!(\"Last undoable action:\");\n println!(\" Type: {}\", record.action);\n println!(\" Time: {}\", record.timestamp);\n println!(\" Branch: {}\", record.branch);\n println!(\" Before: {}\", short_sha(&record.before_sha));\n println!(\" After: {}\", short_sha(&record.after_sha));\n if record.pushed {\n println!(\n \" Pushed: yes (to {})\",\n record.remote.as_deref().unwrap_or(\"origin\")\n );\n }\n if let Some(msg) = &record.message {\n let short_msg = if msg.len() > 60 {\n format!(\"{}...\", &msg[..57])\n } else {\n msg.clone()\n };\n println!(\" Message: {}\", short_msg);\n }\n }\n None => {\n println!(\"No undoable actions recorded for this repository.\");\n }\n }\n\n Ok(())\n}\n\n/// List recent undoable actions.\npub fn list_actions(repo_root: &Path, limit: usize) -> Result<()> {\n let log_path = undo_log_path(repo_root);\n\n if !log_path.exists() {\n println!(\"No undo history for this repository.\");\n return Ok(());\n }\n\n let content = fs::read_to_string(&log_path)?;\n let lines: Vec<&str> = content.lines().filter(|l| !l.trim().is_empty()).collect();\n\n if lines.is_empty() {\n println!(\"No undo history for this repository.\");\n return Ok(());\n }\n\n println!(\"Recent actions (newest first):\");\n println!();\n\n let start = if lines.len() > limit {\n lines.len() - limit\n } else {\n 0\n };\n\n for (i, line) in lines[start..].iter().rev().enumerate() {\n if let Ok(record) = serde_json::from_str::<UndoRecord>(line) {\n let pushed_indicator = if record.pushed { \" [pushed]\" } else { \"\" };\n let msg_short = record\n .message\n .as_ref()\n .map(|m| {\n if m.len() > 40 {\n format!(\"{:.40}...\", m)\n } else {\n m.clone()\n }\n })\n .unwrap_or_default();\n\n if i == 0 {\n println!(\n \" → {} {} {}{} {}\",\n short_sha(&record.after_sha),\n record.action,\n record.branch,\n pushed_indicator,\n msg_short\n );\n } else {\n println!(\n \" {} {} {}{} {}\",\n short_sha(&record.after_sha),\n record.action,\n record.branch,\n pushed_indicator,\n msg_short\n );\n }\n }\n }\n\n println!();\n println!(\"Use 'f undo' to undo the most recent action (→)\");\n\n Ok(())\n}\n\n// Helper functions\n\nfn short_sha(sha: &str) -> &str {\n &sha[..7.min(sha.len())]\n}\n\nfn git_capture(repo_root: &Path, args: &[&str]) -> Result<String> {\n let output = Command::new(\"git\")\n .args(args)\n .current_dir(repo_root)\n .output()\n .context(\"failed to run git command\")?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"git {} failed: {}\", args.join(\" \"), stderr);\n }\n\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\nfn git_run(repo_root: &Path, args: &[&str]) -> Result<()> {\n let status = Command::new(\"git\")\n .args(args)\n .current_dir(repo_root)\n .status()\n .context(\"failed to run git command\")?;\n\n if !status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n\n Ok(())\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn test_action_type_display() {\n assert_eq!(format!(\"{}\", ActionType::Commit), \"commit\");\n assert_eq!(format!(\"{}\", ActionType::Push), \"push\");\n assert_eq!(format!(\"{}\", ActionType::CommitPush), \"commit+push\");\n }\n\n #[test]\n fn test_short_sha() {\n assert_eq!(short_sha(\"abc1234567890\"), \"abc1234\");\n assert_eq!(short_sha(\"abc\"), \"abc\");\n }\n}\n" }, { "path": "src/upgrade.rs", "content": "//! Self-upgrade functionality for flow.\n//!\n//! Similar to Deno's upgrade system:\n//! - Fetches latest version from GitHub releases\n//! - Downloads and replaces the current binary\n//! - Background version checking with caching\n\nuse std::env;\nuse std::fs::{self, File};\nuse std::io::Write;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\nuse std::time::{Duration, SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result, bail};\nuse reqwest::blocking::Client;\nuse serde::Deserialize;\nuse sha2::{Digest, Sha256};\n\nuse crate::cli::UpgradeOpts;\n\nconst UPGRADE_CHECK_INTERVAL_HOURS: u64 = 24;\n\nfn env_truthy(key: &str) -> bool {\n match env::var(key)\n .ok()\n .map(|v| v.trim().to_ascii_lowercase())\n .as_deref()\n {\n Some(\"1\") | Some(\"true\") | Some(\"yes\") | Some(\"y\") => true,\n _ => false,\n }\n}\n\nfn upgrade_repo() -> Result<(String, String)> {\n if let Ok(value) = env::var(\"FLOW_UPGRADE_REPO\") {\n if let Some((owner, repo)) = value.trim().split_once('/') {\n if !owner.trim().is_empty() && !repo.trim().is_empty() {\n return Ok((owner.trim().to_string(), repo.trim().to_string()));\n }\n }\n }\n\n if let (Ok(owner), Ok(repo)) = (env::var(\"FLOW_GITHUB_OWNER\"), env::var(\"FLOW_GITHUB_REPO\")) {\n let owner = owner.trim();\n let repo = repo.trim();\n if !owner.is_empty() && !repo.is_empty() {\n return Ok((owner.to_string(), repo.to_string()));\n }\n }\n\n if let Some((owner, repo)) = parse_github_owner_repo(env!(\"CARGO_PKG_REPOSITORY\")) {\n return Ok((owner, repo));\n }\n\n bail!(\n \"upgrade source repo not configured.\\nSet FLOW_UPGRADE_REPO=owner/repo (recommended) or FLOW_GITHUB_OWNER/FLOW_GITHUB_REPO.\"\n );\n}\n\n#[derive(Debug, Deserialize)]\nstruct GitHubRelease {\n tag_name: String,\n assets: Vec<GitHubAsset>,\n html_url: String,\n}\n\n#[derive(Debug, Deserialize)]\nstruct GitHubAsset {\n name: String,\n browser_download_url: String,\n}\n\n/// Version check cache stored in ~/.cache/flow/upgrade_check.txt\n#[derive(Debug)]\nstruct VersionCache {\n last_checked: u64,\n latest_version: String,\n current_version: String,\n}\n\nimpl VersionCache {\n fn cache_path() -> PathBuf {\n dirs::cache_dir()\n .unwrap_or_else(|| PathBuf::from(\".\"))\n .join(\"flow\")\n .join(\"upgrade_check.txt\")\n }\n\n fn load() -> Option<Self> {\n let path = Self::cache_path();\n let content = fs::read_to_string(&path).ok()?;\n let parts: Vec<&str> = content.trim().split('!').collect();\n if parts.len() >= 3 {\n Some(Self {\n last_checked: parts[0].parse().ok()?,\n latest_version: parts[1].to_string(),\n current_version: parts[2].to_string(),\n })\n } else {\n None\n }\n }\n\n fn save(&self) -> Result<()> {\n let path = Self::cache_path();\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n let content = format!(\n \"{}!{}!{}\",\n self.last_checked, self.latest_version, self.current_version\n );\n fs::write(&path, content)?;\n Ok(())\n }\n\n fn now_timestamp() -> u64 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|d| d.as_secs())\n .unwrap_or(0)\n }\n\n fn should_check(&self) -> bool {\n let now = Self::now_timestamp();\n let elapsed_hours = (now.saturating_sub(self.last_checked)) / 3600;\n elapsed_hours >= UPGRADE_CHECK_INTERVAL_HOURS\n }\n}\n\n/// Get current version from Cargo.toml embedded at compile time.\npub fn current_version() -> &'static str {\n env!(\"CARGO_PKG_VERSION\")\n}\n\n/// Detect the current platform (os, arch).\nfn detect_release_target() -> Result<&'static str> {\n if cfg!(target_os = \"macos\") {\n if cfg!(target_arch = \"x86_64\") {\n return Ok(\"x86_64-apple-darwin\");\n }\n if cfg!(target_arch = \"aarch64\") {\n return Ok(\"aarch64-apple-darwin\");\n }\n bail!(\"Unsupported macOS architecture\");\n }\n if cfg!(target_os = \"linux\") {\n if cfg!(target_arch = \"x86_64\") {\n return Ok(\"x86_64-unknown-linux-gnu\");\n }\n if cfg!(target_arch = \"aarch64\") {\n return Ok(\"aarch64-unknown-linux-gnu\");\n }\n bail!(\"Unsupported Linux architecture\");\n }\n\n bail!(\"Unsupported operating system for self-upgrade (only macOS/Linux supported)\");\n}\n\nfn detect_legacy_platform() -> Result<(&'static str, &'static str)> {\n let os = if cfg!(target_os = \"macos\") {\n \"darwin\"\n } else if cfg!(target_os = \"linux\") {\n \"linux\"\n } else {\n bail!(\"Unsupported operating system for self-upgrade (only macOS/Linux supported)\");\n };\n\n let arch = if cfg!(target_arch = \"aarch64\") {\n \"arm64\"\n } else if cfg!(target_arch = \"x86_64\") {\n \"amd64\"\n } else {\n bail!(\"Unsupported architecture\");\n };\n\n Ok((os, arch))\n}\n\n/// Fetch the latest release info from GitHub.\nfn fetch_latest_release(client: &Client) -> Result<GitHubRelease> {\n let (owner, repo) = upgrade_repo()?;\n let url = format!(\n \"https://api.github.com/repos/{}/{}/releases/latest\",\n owner, repo\n );\n\n let mut request = client\n .get(&url)\n .header(\"User-Agent\", format!(\"flow/{}\", current_version()))\n .header(\"Accept\", \"application/vnd.github.v3+json\")\n .timeout(Duration::from_secs(30));\n\n if let Some(token) = github_token() {\n request = request.bearer_auth(token);\n }\n\n let response = request\n .send()\n .context(\"Failed to fetch release info from GitHub\")?;\n\n if !response.status().is_success() {\n bail!(\n \"GitHub API returned status {}: {}\",\n response.status(),\n response.text().unwrap_or_default()\n );\n }\n\n response\n .json::<GitHubRelease>()\n .context(\"Failed to parse GitHub release response\")\n}\n\n/// Fetch a release by tag (e.g. \"v0.1.0\") from GitHub.\nfn fetch_release_by_tag(client: &Client, tag: &str) -> Result<GitHubRelease> {\n let (owner, repo) = upgrade_repo()?;\n let url = format!(\n \"https://api.github.com/repos/{}/{}/releases/tags/{}\",\n owner, repo, tag\n );\n\n let mut request = client\n .get(&url)\n .header(\"User-Agent\", format!(\"flow/{}\", current_version()))\n .header(\"Accept\", \"application/vnd.github.v3+json\")\n .timeout(Duration::from_secs(30));\n\n if let Some(token) = github_token() {\n request = request.bearer_auth(token);\n }\n\n let response = request\n .send()\n .context(\"Failed to fetch release info from GitHub\")?;\n\n if response.status() == reqwest::StatusCode::NOT_FOUND {\n bail!(\n \"Release tag '{}' not found in {}/{}.\\n\\\n If you meant canary: wait for the canary workflow to publish it (GitHub release tag: canary).\",\n tag,\n owner,\n repo\n );\n }\n if !response.status().is_success() {\n bail!(\n \"GitHub API returned status {}: {}\",\n response.status(),\n response.text().unwrap_or_default()\n );\n }\n\n response\n .json::<GitHubRelease>()\n .context(\"Failed to parse GitHub release response\")\n}\n\n/// Parse version string, stripping 'v' prefix if present.\nfn parse_version(version: &str) -> &str {\n version.strip_prefix('v').unwrap_or(version)\n}\n\n/// Compare two semver-like versions. Returns true if `latest` is newer than `current`.\nfn is_newer_version(current: &str, latest: &str) -> bool {\n let current = parse_version(current);\n let latest = parse_version(latest);\n\n let parse_parts = |v: &str| -> Vec<u32> {\n v.split(|c: char| c == '.' || c == '-')\n .filter_map(|s| s.parse().ok())\n .collect()\n };\n\n let current_parts = parse_parts(current);\n let latest_parts = parse_parts(latest);\n\n for (c, l) in current_parts.iter().zip(latest_parts.iter()) {\n if l > c {\n return true;\n }\n if l < c {\n return false;\n }\n }\n\n latest_parts.len() > current_parts.len()\n}\n\n/// Download a file with progress indication.\nfn download_with_progress(client: &Client, url: &str, dest: &Path) -> Result<()> {\n let response = client\n .get(url)\n .header(\"User-Agent\", format!(\"flow/{}\", current_version()))\n .timeout(Duration::from_secs(300))\n .send()\n .context(\"Failed to start download\")?;\n\n if !response.status().is_success() {\n bail!(\"Download failed with status {}\", response.status());\n }\n\n let total_size = response.content_length();\n let mut file = File::create(dest).context(\"Failed to create temp file\")?;\n\n let bytes = response.bytes().context(\"Failed to read response\")?;\n\n if let Some(total) = total_size {\n println!(\"Downloading {} bytes...\", total);\n }\n\n file.write_all(&bytes)?;\n Ok(())\n}\n\nfn github_token() -> Option<String> {\n for key in [\"GITHUB_TOKEN\", \"GH_TOKEN\", \"FLOW_GITHUB_TOKEN\"] {\n if let Ok(value) = env::var(key) {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Some(trimmed.to_string());\n }\n }\n }\n None\n}\n\nfn parse_github_owner_repo(url: &str) -> Option<(String, String)> {\n let trimmed = url.trim().trim_end_matches('/');\n if trimmed.is_empty() {\n return None;\n }\n\n let rest = if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n rest\n } else if let Some(rest) = trimmed.strip_prefix(\"https://github.com/\") {\n rest\n } else {\n return None;\n };\n\n let rest = rest.trim_end_matches(\".git\");\n let mut parts = rest.split('/');\n let owner = parts.next()?.trim();\n let repo = parts.next()?.trim();\n if owner.is_empty() || repo.is_empty() {\n return None;\n }\n Some((owner.to_string(), repo.to_string()))\n}\n\nfn normalize_tag(input: &str) -> String {\n let trimmed = input.trim();\n if trimmed.starts_with('v') {\n trimmed.to_string()\n } else {\n format!(\"v{}\", trimmed)\n }\n}\n\nfn parse_sha256_from_checksums(checksums: &str, filename: &str) -> Option<String> {\n for line in checksums.lines() {\n let mut parts = line.split_whitespace();\n let hash = parts.next()?;\n let file = parts.next()?;\n if file.trim() == filename {\n return Some(hash.trim().to_string());\n }\n }\n None\n}\n\nfn sha256_file(path: &Path) -> Result<String> {\n let bytes = fs::read(path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let mut hasher = Sha256::new();\n hasher.update(&bytes);\n Ok(hex::encode(hasher.finalize()))\n}\n\n/// Extract tarball and find the binary.\nfn extract_binary(tarball: &Path, binary_name: &str) -> Result<PathBuf> {\n let temp_dir = tempfile::tempdir().context(\"Failed to create temp directory\")?;\n let temp_path = temp_dir.path();\n\n // Extract tarball\n let status = Command::new(\"tar\")\n .args([\n \"-xzf\",\n tarball.to_str().unwrap(),\n \"-C\",\n temp_path.to_str().unwrap(),\n ])\n .status()\n .context(\"Failed to run tar\")?;\n\n if !status.success() {\n bail!(\"Failed to extract tarball\");\n }\n\n // Find the binary (might be in a subdirectory)\n let find_binary = |dir: &Path| -> Option<PathBuf> {\n if dir.join(binary_name).exists() {\n return Some(dir.join(binary_name));\n }\n // Check one level deep\n if let Ok(entries) = fs::read_dir(dir) {\n for entry in entries.flatten() {\n let path = entry.path();\n if path.is_dir() {\n let bin_path = path.join(binary_name);\n if bin_path.exists() {\n return Some(bin_path);\n }\n }\n }\n }\n None\n };\n\n let binary_path = find_binary(temp_path)\n .ok_or_else(|| anyhow::anyhow!(\"Binary '{}' not found in tarball\", binary_name))?;\n\n // Copy to a persistent temp location\n let dest = env::temp_dir().join(format!(\"flow_upgrade_{}\", binary_name));\n fs::copy(&binary_path, &dest).context(\"Failed to copy binary\")?;\n\n Ok(dest)\n}\n\n/// Validate the new binary by running --version.\nfn validate_binary(path: &Path) -> Result<String> {\n let output = Command::new(path)\n .arg(\"--version\")\n .output()\n .context(\"Failed to validate new binary\")?;\n\n if !output.status.success() {\n bail!(\"New binary validation failed\");\n }\n\n Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())\n}\n\n/// Replace the current executable with the new one.\nfn replace_executable(new_exe: &Path, current_exe: &Path) -> Result<()> {\n #[cfg(unix)]\n {\n // On Unix, we can delete the running executable and replace it\n fs::remove_file(current_exe).context(\"Failed to remove current executable\")?;\n fs::copy(new_exe, current_exe).context(\"Failed to copy new executable\")?;\n\n // Set executable permissions\n use std::os::unix::fs::PermissionsExt;\n let mut perms = fs::metadata(current_exe)?.permissions();\n perms.set_mode(0o755);\n fs::set_permissions(current_exe, perms)?;\n }\n\n #[cfg(windows)]\n {\n // On Windows, rename the old executable first\n let old_exe = current_exe.with_extension(\"old.exe\");\n if old_exe.exists() {\n fs::remove_file(&old_exe).ok();\n }\n fs::rename(current_exe, &old_exe).context(\"Failed to rename current executable\")?;\n fs::copy(new_exe, current_exe).context(\"Failed to copy new executable\")?;\n }\n\n Ok(())\n}\n\n/// Get the path to the current executable.\nfn current_exe_path() -> Result<PathBuf> {\n env::current_exe().context(\"Failed to get current executable path\")\n}\n\n/// Check write permissions for the executable path.\nfn check_write_permission(path: &Path) -> Result<()> {\n let parent = path.parent().unwrap_or(path);\n\n #[cfg(unix)]\n {\n use std::os::unix::fs::MetadataExt;\n\n let metadata = fs::metadata(path).or_else(|_| fs::metadata(parent))?;\n let uid = unsafe { libc::getuid() };\n\n if metadata.uid() == 0 && uid != 0 {\n bail!(\n \"You don't have write permission to {} because it's owned by root.\\n\\\n Consider updating flow through your package manager if installed from it.\\n\\\n Otherwise run `f upgrade` as root.\",\n path.display()\n );\n }\n }\n\n // Try to check if we can write\n if path.exists() {\n let metadata = fs::metadata(path)?;\n if metadata.permissions().readonly() {\n bail!(\"You do not have write permission to {}\", path.display());\n }\n } else if !parent.exists() || fs::metadata(parent)?.permissions().readonly() {\n bail!(\"You do not have write permission to {}\", parent.display());\n }\n\n Ok(())\n}\n\n/// Run the upgrade command.\npub fn run(opts: UpgradeOpts) -> Result<()> {\n let current = current_version();\n let current_exe = current_exe_path()?;\n\n println!(\"Current version: {}\", current);\n\n // Check write permissions early\n let output_path = opts\n .output\n .as_ref()\n .map(PathBuf::from)\n .unwrap_or_else(|| current_exe.clone());\n check_write_permission(&output_path)?;\n\n let client = Client::builder()\n .timeout(Duration::from_secs(60))\n .build()\n .context(\"Failed to create HTTP client\")?;\n\n let (owner, repo) = upgrade_repo()?;\n println!(\"Upgrade source: {}/{}\", owner, repo);\n\n // Fetch release\n println!(\"Checking for updates...\");\n let requested_version = opts\n .version\n .as_deref()\n .map(|v| v.trim())\n .filter(|v| !v.is_empty())\n .map(|v| v.to_string());\n\n let (release, latest_display, skip_version_check) = if opts.canary {\n let release = fetch_release_by_tag(&client, \"canary\")?;\n (release, \"canary\".to_string(), true)\n } else if let Some(version) = requested_version.as_deref() {\n let tag = normalize_tag(version);\n let release = fetch_release_by_tag(&client, &tag)?;\n (release, parse_version(&tag).to_string(), true) // allow downgrades when version is explicit\n } else {\n let release = fetch_latest_release(&client)?;\n let latest = parse_version(&release.tag_name).to_string();\n (release, latest, opts.stable)\n };\n\n println!(\"Latest version: {}\", latest_display);\n\n if opts.force {\n println!(\"Forcing upgrade...\");\n }\n\n // Check if upgrade is needed (stable channel only).\n if !opts.force && !skip_version_check {\n let latest = parse_version(&release.tag_name);\n if !is_newer_version(current, latest) {\n println!(\"Already on the latest version.\");\n return Ok(());\n }\n }\n\n // Detect platform and find the right asset.\n // Preferred format (new): `flow-<target>.tar.gz` (where <target> is the rust target triple).\n // Legacy format (old): `flow_<tag>_<os>_<arch>.tar.gz`.\n let target = detect_release_target()?;\n let asset_name = format!(\"flow-{}.tar.gz\", target);\n let (legacy_os, legacy_arch) = detect_legacy_platform()?;\n let legacy_asset_name = format!(\n \"flow_{}_{}_{}.tar.gz\",\n release.tag_name, legacy_os, legacy_arch\n );\n\n let tarball_asset = release\n .assets\n .iter()\n .find(|a| a.name == asset_name)\n .or_else(|| release.assets.iter().find(|a| a.name == legacy_asset_name))\n .ok_or_else(|| {\n anyhow::anyhow!(\n \"No release asset found for {}. Available: {:?}\",\n target,\n release.assets.iter().map(|a| &a.name).collect::<Vec<_>>()\n )\n })?;\n\n let checksums_asset = release.assets.iter().find(|a| a.name == \"checksums.txt\");\n\n println!(\"Downloading {}...\", tarball_asset.name);\n\n // Dry run mode\n if opts.dry_run {\n println!(\n \"\\n[dry-run] Would download: {}\",\n tarball_asset.browser_download_url\n );\n if let Some(asset) = checksums_asset {\n println!(\"[dry-run] Would download: {}\", asset.browser_download_url);\n }\n println!(\"[dry-run] Would install to: {}\", output_path.display());\n return Ok(());\n }\n\n // Download the release\n let temp_tarball = env::temp_dir().join(\"flow_upgrade.tar.gz\");\n download_with_progress(&client, &tarball_asset.browser_download_url, &temp_tarball)?;\n\n let insecure = env_truthy(\"FLOW_UPGRADE_INSECURE\");\n if let Some(asset) = checksums_asset {\n let temp_checksums = env::temp_dir().join(\"flow_upgrade_checksums.txt\");\n download_with_progress(&client, &asset.browser_download_url, &temp_checksums)?;\n let checksums = fs::read_to_string(&temp_checksums)\n .context(\"failed to read downloaded checksums.txt\")?;\n\n if let Some(expected) = parse_sha256_from_checksums(&checksums, &tarball_asset.name) {\n let actual = sha256_file(&temp_tarball)?;\n if expected.to_lowercase() != actual.to_lowercase() {\n bail!(\n \"checksum mismatch for {} (expected {}, got {})\",\n tarball_asset.name,\n expected,\n actual\n );\n }\n println!(\"Checksum verified.\");\n } else if insecure {\n eprintln!(\n \"Warning: checksums.txt does not contain {}; skipping checksum verification (FLOW_UPGRADE_INSECURE=1).\",\n tarball_asset.name\n );\n } else {\n bail!(\n \"checksums.txt does not contain {}. Refusing to install.\\n\\\n Set FLOW_UPGRADE_INSECURE=1 to bypass (not recommended).\",\n tarball_asset.name\n );\n }\n let _ = fs::remove_file(&temp_checksums);\n } else if insecure {\n eprintln!(\n \"Warning: checksums.txt not found in release assets; skipping checksum verification (FLOW_UPGRADE_INSECURE=1).\"\n );\n } else {\n // Back-compat for older releases (e.g. v0.1.0) that don't ship checksums.txt.\n eprintln!(\n \"Warning: checksums.txt not found in release assets; skipping checksum verification.\"\n );\n }\n\n // Extract and find the binary\n println!(\"Extracting...\");\n let binary_name = if cfg!(windows) { \"f.exe\" } else { \"f\" };\n let new_exe = extract_binary(&temp_tarball, binary_name)?;\n\n // Validate the new binary\n println!(\"Validating...\");\n let new_version = validate_binary(&new_exe)?;\n println!(\"New binary version: {}\", new_version);\n\n // Replace the executable\n println!(\"Installing...\");\n replace_executable(&new_exe, &output_path)?;\n ensure_sibling_symlink(&output_path).ok();\n\n // Cleanup\n fs::remove_file(&temp_tarball).ok();\n fs::remove_file(&new_exe).ok();\n\n // Update cache\n // Update cache (only meaningful for stable).\n if !opts.canary {\n let latest = parse_version(&release.tag_name);\n let cache = VersionCache {\n last_checked: VersionCache::now_timestamp(),\n latest_version: latest.to_string(),\n current_version: latest.to_string(),\n };\n cache.save().ok();\n }\n\n println!();\n println!(\"Successfully upgraded to flow {}\", latest_display);\n println!();\n println!(\"Release notes: {}\", release.html_url);\n\n Ok(())\n}\n\nfn ensure_sibling_symlink(installed_path: &Path) -> Result<()> {\n #[cfg(not(unix))]\n {\n let _ = installed_path;\n return Ok(());\n }\n\n #[cfg(unix)]\n {\n use std::os::unix::fs::symlink;\n let parent = installed_path.parent().context(\"missing parent dir\")?;\n let Some(name) = installed_path.file_name().and_then(|n| n.to_str()) else {\n return Ok(());\n };\n\n // Support both `f upgrade ...` and `flow upgrade ...` by keeping a sibling symlink.\n let (link_name, target_name) = if name == \"f\" {\n (\"flow\", \"f\")\n } else if name == \"flow\" {\n (\"f\", \"flow\")\n } else {\n return Ok(());\n };\n\n let link_path = parent.join(link_name);\n if link_path.exists() && link_path.is_dir() {\n eprintln!(\n \"Warning: cannot create {} symlink at {} (path is a directory)\",\n link_name,\n link_path.display()\n );\n return Ok(());\n }\n\n let _ = fs::remove_file(&link_path);\n // Use relative target so moving the directory keeps the link valid.\n if symlink(target_name, &link_path).is_err() {\n eprintln!(\n \"Warning: failed to create {} symlink at {}\",\n link_name,\n link_path.display()\n );\n }\n Ok(())\n }\n}\n\n/// Check for upgrades in the background (non-blocking).\n/// Returns Some((latest_version)) if an upgrade is available.\npub fn check_for_upgrade_prompt() -> Option<String> {\n // Check if disabled via environment variable\n if env::var(\"FLOW_NO_UPDATE_CHECK\").is_ok() {\n return None;\n }\n\n // Check cache first\n let current = current_version();\n\n if let Some(cache) = VersionCache::load() {\n // If current version changed, user already upgraded\n if cache.current_version != current {\n return None;\n }\n\n // If we've checked recently, use cached result\n if !cache.should_check() {\n if is_newer_version(current, &cache.latest_version) {\n return Some(cache.latest_version);\n }\n return None;\n }\n }\n\n // Perform check (with short timeout for background use)\n let client = Client::builder()\n .timeout(Duration::from_secs(5))\n .build()\n .ok()?;\n\n let release = fetch_latest_release(&client).ok()?;\n let latest = parse_version(&release.tag_name).to_string();\n\n // Update cache\n let cache = VersionCache {\n last_checked: VersionCache::now_timestamp(),\n latest_version: latest.clone(),\n current_version: current.to_string(),\n };\n cache.save().ok();\n\n if is_newer_version(current, &latest) {\n Some(latest)\n } else {\n None\n }\n}\n\n/// Print upgrade prompt if a new version is available.\n/// Call this at the end of command execution.\npub fn maybe_print_upgrade_prompt() {\n // Only show on TTY\n if !atty::is(atty::Stream::Stderr) {\n return;\n }\n\n if let Some(latest) = check_for_upgrade_prompt() {\n eprintln!();\n eprintln!(\n \"A new version of flow is available: {} -> {}\",\n current_version(),\n latest\n );\n eprintln!(\"Run `f upgrade` to install it.\");\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn test_is_newer_version() {\n assert!(is_newer_version(\"0.1.0\", \"0.2.0\"));\n assert!(is_newer_version(\"0.1.0\", \"1.0.0\"));\n assert!(is_newer_version(\"1.0.0\", \"1.0.1\"));\n assert!(is_newer_version(\"1.0.0\", \"1.1.0\"));\n assert!(!is_newer_version(\"0.2.0\", \"0.1.0\"));\n assert!(!is_newer_version(\"1.0.0\", \"1.0.0\"));\n assert!(is_newer_version(\"v0.1.0\", \"v0.2.0\"));\n }\n\n #[test]\n fn test_parse_version() {\n assert_eq!(parse_version(\"v1.0.0\"), \"1.0.0\");\n assert_eq!(parse_version(\"1.0.0\"), \"1.0.0\");\n }\n}\n" }, { "path": "src/upstream.rs", "content": "//! Upstream fork management.\n//!\n//! Provides automated workflows for managing forks with upstream repositories.\n//! - `f upstream setup` - Configure upstream remote and local tracking branch\n//! - `f upstream pull` - Pull changes from upstream into local branch\n//! - `f upstream sync` - Full sync: pull upstream, merge to dev, merge to main, push\n\nuse std::process::{Command, Stdio};\n\nuse anyhow::{Context, Result, bail};\n\nuse crate::cli::{UpstreamAction, UpstreamCommand};\n\n/// Run the upstream subcommand.\npub fn run(cmd: UpstreamCommand) -> Result<()> {\n let action = cmd.action.unwrap_or(UpstreamAction::Status);\n\n match action {\n UpstreamAction::Status => show_status(),\n UpstreamAction::Setup {\n upstream_url,\n upstream_branch,\n } => setup_upstream(upstream_url.as_deref(), upstream_branch.as_deref()),\n UpstreamAction::Pull { branch } => pull_upstream(branch.as_deref()),\n UpstreamAction::Check => check_upstream(),\n UpstreamAction::Sync {\n no_push,\n create_repo,\n } => sync_upstream(!no_push, create_repo),\n UpstreamAction::Open => open_upstream(),\n }\n}\n\n/// Set up upstream remote and local tracking branch, with optional fetch depth.\npub fn setup_upstream_with_depth(\n upstream_url: Option<&str>,\n upstream_branch: Option<&str>,\n depth: Option<u32>,\n) -> Result<()> {\n setup_upstream_internal(upstream_url, upstream_branch, depth)\n}\n\n/// Show current upstream configuration status.\nfn show_status() -> Result<()> {\n println!(\"Upstream Fork Status\\n\");\n\n // Check for upstream remote\n let upstream_url = git_capture(&[\"remote\", \"get-url\", \"upstream\"]).ok();\n let origin_url = git_capture(&[\"remote\", \"get-url\", \"origin\"]).ok();\n\n if let Some(url) = &upstream_url {\n println!(\"✓ upstream remote: {}\", url.trim());\n } else {\n println!(\"✗ upstream remote: not configured\");\n }\n\n if let Some(url) = &origin_url {\n println!(\"✓ origin remote: {}\", url.trim());\n }\n\n // Check for local upstream branch\n let has_upstream_branch =\n git_capture(&[\"rev-parse\", \"--verify\", \"refs/heads/upstream\"]).is_ok();\n if has_upstream_branch {\n let tracking = git_capture(&[\"config\", \"--get\", \"branch.upstream.remote\"])\n .ok()\n .map(|s| s.trim().to_string());\n println!(\"✓ local 'upstream' branch: exists (tracks {:?})\", tracking);\n } else {\n println!(\"✗ local 'upstream' branch: not created\");\n }\n\n // Current branch\n let current = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])\n .ok()\n .map(|s| s.trim().to_string())\n .unwrap_or_else(|| \"unknown\".to_string());\n println!(\"\\nCurrent branch: {}\", current);\n\n // Show divergence if upstream exists\n if upstream_url.is_some() {\n println!(\"\\nTo set up: f upstream setup\");\n println!(\"To pull: f upstream pull\");\n println!(\"To sync: f upstream sync\");\n } else {\n println!(\"\\nTo set up upstream:\");\n println!(\" f upstream setup --url <upstream-repo-url>\");\n println!(\" f upstream setup --url https://github.com/original/repo\");\n }\n\n Ok(())\n}\n\n/// Open upstream repository URL in browser.\nfn open_upstream() -> Result<()> {\n let upstream_url = git_capture(&[\"remote\", \"get-url\", \"upstream\"])?;\n let upstream_url = upstream_url.trim();\n\n // Convert git URL to https URL if needed\n let https_url = if upstream_url.starts_with(\"git@github.com:\") {\n upstream_url\n .replace(\"git@github.com:\", \"https://github.com/\")\n .trim_end_matches(\".git\")\n .to_string()\n } else if upstream_url.starts_with(\"https://\") {\n upstream_url.trim_end_matches(\".git\").to_string()\n } else {\n upstream_url.to_string()\n };\n\n println!(\"Opening {}\", https_url);\n\n #[cfg(target_os = \"macos\")]\n {\n Command::new(\"open\")\n .arg(&https_url)\n .status()\n .context(\"failed to open URL\")?;\n }\n\n #[cfg(target_os = \"linux\")]\n {\n Command::new(\"xdg-open\")\n .arg(&https_url)\n .status()\n .context(\"failed to open URL\")?;\n }\n\n #[cfg(target_os = \"windows\")]\n {\n Command::new(\"cmd\")\n .args([\"/C\", \"start\", &https_url])\n .status()\n .context(\"failed to open URL\")?;\n }\n\n Ok(())\n}\n\n/// Set up upstream remote and local tracking branch.\nfn setup_upstream(upstream_url: Option<&str>, upstream_branch: Option<&str>) -> Result<()> {\n setup_upstream_internal(upstream_url, upstream_branch, None)\n}\n\nfn setup_upstream_internal(\n upstream_url: Option<&str>,\n upstream_branch: Option<&str>,\n depth: Option<u32>,\n) -> Result<()> {\n // Check if upstream remote exists\n let has_upstream = git_capture(&[\"remote\", \"get-url\", \"upstream\"]).is_ok();\n\n if !has_upstream {\n if let Some(url) = upstream_url {\n println!(\"Adding upstream remote: {}\", url);\n git_run(&[\"remote\", \"add\", \"upstream\", url])?;\n } else {\n // Try to detect from origin\n if let Ok(origin_url) = git_capture(&[\"remote\", \"get-url\", \"origin\"]) {\n println!(\"No upstream remote configured.\");\n println!(\"Current origin: {}\", origin_url.trim());\n println!(\"\\nTo add upstream, run:\");\n println!(\" f upstream setup --url <original-repo-url>\");\n return Ok(());\n }\n bail!(\"No upstream remote. Use: f upstream setup --url <upstream-repo-url>\");\n }\n } else {\n let url = git_capture(&[\"remote\", \"get-url\", \"upstream\"])?;\n println!(\"✓ upstream remote exists: {}\", url.trim());\n }\n\n // Fetch upstream\n println!(\"\\nFetching upstream...\");\n if let Some(depth) = depth {\n let depth_str = depth.to_string();\n git_run(&[\"fetch\", \"upstream\", \"--prune\", \"--depth\", &depth_str])?;\n } else {\n git_run(&[\"fetch\", \"upstream\", \"--prune\"])?;\n }\n\n // Determine upstream branch (explicit > HEAD > main > master)\n let upstream_branch = if let Some(branch) = upstream_branch {\n branch.to_string()\n } else if let Ok(head_ref) = git_capture(&[\"symbolic-ref\", \"refs/remotes/upstream/HEAD\"]) {\n head_ref.trim().replace(\"refs/remotes/upstream/\", \"\")\n } else if git_capture(&[\"rev-parse\", \"--verify\", \"refs/remotes/upstream/main\"]).is_ok() {\n \"main\".to_string()\n } else if git_capture(&[\"rev-parse\", \"--verify\", \"refs/remotes/upstream/master\"]).is_ok() {\n \"master\".to_string()\n } else {\n // List available branches\n let branches = git_capture(&[\"branch\", \"-r\", \"--list\", \"upstream/*\"])?;\n println!(\"Cannot auto-detect upstream branch.\");\n println!(\"Available upstream branches:\");\n for line in branches.lines() {\n println!(\" {}\", line.trim());\n }\n bail!(\"Specify branch with: f upstream setup --branch <branch-name>\");\n };\n\n // Check if upstream branch exists on remote\n let remote_ref = format!(\"refs/remotes/upstream/{}\", upstream_branch);\n if git_capture(&[\"rev-parse\", \"--verify\", &remote_ref]).is_err() {\n let branches = git_capture(&[\"branch\", \"-r\", \"--list\", \"upstream/*\"])?;\n println!(\"Branch 'upstream/{}' not found.\", upstream_branch);\n println!(\"Available upstream branches:\");\n for line in branches.lines() {\n println!(\" {}\", line.trim());\n }\n bail!(\"Specify branch with: f upstream setup --branch <branch-name>\");\n }\n\n // Create or update local upstream branch\n let local_upstream_exists =\n git_capture(&[\"rev-parse\", \"--verify\", \"refs/heads/upstream\"]).is_ok();\n let upstream_ref = format!(\"upstream/{}\", upstream_branch);\n\n if local_upstream_exists {\n println!(\n \"Updating local 'upstream' branch to match {}...\",\n upstream_ref\n );\n let current = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])?;\n let current = current.trim();\n\n if current == \"upstream\" {\n // Already on upstream, just reset\n git_run(&[\"reset\", \"--hard\", &upstream_ref])?;\n } else {\n // Update without switching\n git_run(&[\"branch\", \"-f\", \"upstream\", &upstream_ref])?;\n }\n } else {\n println!(\n \"Creating local 'upstream' branch tracking {}...\",\n upstream_ref\n );\n git_run(&[\"branch\", \"upstream\", &upstream_ref])?;\n }\n\n // Set up tracking\n git_run(&[\"config\", \"branch.upstream.remote\", \"upstream\"])?;\n git_run(&[\n \"config\",\n \"branch.upstream.merge\",\n &format!(\"refs/heads/{}\", upstream_branch),\n ])?;\n\n println!(\"\\n✓ Upstream setup complete!\");\n println!(\"\\nWorkflow:\");\n println!(\" 1. f upstream pull - Pull latest from upstream into 'upstream' branch\");\n println!(\" 2. f upstream sync - Pull, merge to dev/main, and push\");\n println!(\"\\nThe local 'upstream' branch is a clean snapshot of the original repo.\");\n println!(\"Your changes stay on dev/main, making merges cleaner.\");\n\n Ok(())\n}\n\n/// Pull changes from upstream into the local upstream branch.\nfn pull_upstream(target_branch: Option<&str>) -> Result<()> {\n // Check upstream remote exists\n if git_capture(&[\"remote\", \"get-url\", \"upstream\"]).is_err() {\n bail!(\"No upstream remote. Run: f upstream setup --url <url>\");\n }\n\n // Fetch upstream\n println!(\"Fetching upstream...\");\n git_run(&[\"fetch\", \"upstream\", \"--prune\"])?;\n\n // Determine the upstream branch to track (check config, then HEAD, then try main/master)\n let upstream_branch = resolve_upstream_branch()?;\n\n let upstream_ref = format!(\"upstream/{}\", upstream_branch);\n\n // Update local upstream branch\n let current = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])?;\n let current = current.trim();\n\n // Check for uncommitted changes and stash if needed\n let mut stashed = false;\n let stash_count_before = git_capture(&[\"stash\", \"list\"])\n .map(|s| s.lines().count())\n .unwrap_or(0);\n\n let status = git_capture(&[\"status\", \"--porcelain\"])?;\n if !status.trim().is_empty() {\n println!(\"Stashing local changes...\");\n let _ = git_run(&[\"stash\", \"push\", \"-m\", \"upstream-pull auto-stash\"]);\n\n // Check if stash actually added an entry\n let stash_count_after = git_capture(&[\"stash\", \"list\"])\n .map(|s| s.lines().count())\n .unwrap_or(0);\n stashed = stash_count_after > stash_count_before;\n }\n\n // Update local upstream branch\n let local_upstream_exists =\n git_capture(&[\"rev-parse\", \"--verify\", \"refs/heads/upstream\"]).is_ok();\n\n if local_upstream_exists {\n if current == \"upstream\" {\n git_run(&[\"reset\", \"--hard\", &upstream_ref])?;\n } else {\n git_run(&[\"branch\", \"-f\", \"upstream\", &upstream_ref])?;\n }\n println!(\"✓ Updated local 'upstream' branch to {}\", upstream_ref);\n } else {\n git_run(&[\"branch\", \"upstream\", &upstream_ref])?;\n println!(\"✓ Created local 'upstream' branch from {}\", upstream_ref);\n }\n\n // Optionally merge into target branch\n if let Some(target) = target_branch {\n println!(\"\\nMerging upstream into {}...\", target);\n\n if current != target {\n git_run(&[\"checkout\", target])?;\n }\n\n if git_run(&[\"merge\", \"--ff-only\", \"upstream\"]).is_err() {\n println!(\"Fast-forward failed, trying regular merge...\");\n if let Err(e) = git_run(&[\"merge\", \"upstream\", \"--no-edit\"]) {\n if stashed {\n println!(\"Your changes are stashed. Run 'git stash pop' after resolving.\");\n }\n return Err(e);\n }\n }\n println!(\"✓ Merged upstream into {}\", target);\n\n // Return to original branch if different\n if current != target && current != \"upstream\" {\n git_run(&[\"checkout\", current])?;\n }\n }\n\n // Restore stashed changes\n if stashed {\n println!(\"Restoring stashed changes...\");\n git_run(&[\"stash\", \"pop\"])?;\n }\n\n // Show what changed\n let behind = git_capture(&[\"rev-list\", \"--count\", &format!(\"HEAD..{}\", upstream_ref)])\n .ok()\n .and_then(|s| s.trim().parse::<u32>().ok())\n .unwrap_or(0);\n\n if behind > 0 {\n println!(\"\\nYour branch is {} commit(s) behind upstream.\", behind);\n println!(\"Run 'f upstream sync' to merge and push.\");\n } else {\n println!(\"\\n✓ Up to date with upstream!\");\n }\n\n Ok(())\n}\n\nfn resolve_upstream_branch() -> Result<String> {\n if let Ok(merge_ref) = git_capture(&[\"config\", \"--get\", \"branch.upstream.merge\"]) {\n return Ok(merge_ref.trim().replace(\"refs/heads/\", \"\"));\n }\n if let Ok(head_ref) = git_capture(&[\"symbolic-ref\", \"refs/remotes/upstream/HEAD\"]) {\n // Parse \"refs/remotes/upstream/master\" -> \"master\"\n return Ok(head_ref.trim().replace(\"refs/remotes/upstream/\", \"\"));\n }\n if git_capture(&[\"rev-parse\", \"--verify\", \"refs/remotes/upstream/main\"]).is_ok() {\n return Ok(\"main\".to_string());\n }\n if git_capture(&[\"rev-parse\", \"--verify\", \"refs/remotes/upstream/master\"]).is_ok() {\n return Ok(\"master\".to_string());\n }\n if git_capture(&[\"rev-parse\", \"--verify\", \"refs/remotes/upstream/dev\"]).is_ok() {\n return Ok(\"dev\".to_string());\n }\n bail!(\"Cannot determine upstream branch. Run: f upstream setup --branch <branch>\");\n}\n\nfn check_upstream() -> Result<()> {\n if git_capture(&[\"remote\", \"get-url\", \"upstream\"]).is_err() {\n bail!(\"No upstream remote. Run: f upstream setup --url <url>\");\n }\n\n println!(\"Fetching upstream...\");\n git_run(&[\"fetch\", \"upstream\", \"--prune\"])?;\n\n let upstream_branch = resolve_upstream_branch()?;\n let upstream_ref = format!(\"upstream/{}\", upstream_branch);\n\n let current = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])?;\n let current = current.trim();\n\n let mut stashed = false;\n let stash_count_before = git_capture(&[\"stash\", \"list\"])\n .map(|s| s.lines().count())\n .unwrap_or(0);\n\n let status = git_capture(&[\"status\", \"--porcelain\"])?;\n if !status.trim().is_empty() {\n println!(\"Stashing local changes to check upstream...\");\n let _ = git_run(&[\"stash\", \"push\", \"-m\", \"upstream-check auto-stash\"]);\n let stash_count_after = git_capture(&[\"stash\", \"list\"])\n .map(|s| s.lines().count())\n .unwrap_or(0);\n stashed = stash_count_after > stash_count_before;\n }\n\n let local_upstream_exists =\n git_capture(&[\"rev-parse\", \"--verify\", \"refs/heads/upstream\"]).is_ok();\n if local_upstream_exists {\n if current == \"upstream\" {\n git_run(&[\"reset\", \"--hard\", &upstream_ref])?;\n } else {\n git_run(&[\"branch\", \"-f\", \"upstream\", &upstream_ref])?;\n }\n println!(\"✓ Updated local 'upstream' branch to {}\", upstream_ref);\n } else {\n git_run(&[\"branch\", \"upstream\", &upstream_ref])?;\n println!(\"✓ Created local 'upstream' branch from {}\", upstream_ref);\n }\n\n git_run(&[\"checkout\", \"upstream\"])?;\n println!(\"Now on 'upstream' (tracking {}).\", upstream_ref);\n if stashed {\n println!(\"Your changes are stashed. Run 'git stash pop' when you're ready.\");\n }\n\n Ok(())\n}\n\n/// Full sync: pull upstream, merge to dev, merge to main, push.\nfn sync_upstream(push: bool, create_repo: bool) -> Result<()> {\n // Check upstream remote exists\n if git_capture(&[\"remote\", \"get-url\", \"upstream\"]).is_err() {\n bail!(\"No upstream remote. Run: f upstream setup --url <url>\");\n }\n\n let current = git_capture(&[\"rev-parse\", \"--abbrev-ref\", \"HEAD\"])?;\n let current = current.trim().to_string();\n\n // Check for uncommitted changes and stash if needed\n let mut stashed = false;\n let stash_count_before = git_capture(&[\"stash\", \"list\"])\n .map(|s| s.lines().count())\n .unwrap_or(0);\n\n let status = git_capture(&[\"status\", \"--porcelain\"])?;\n if !status.trim().is_empty() {\n println!(\"Stashing local changes...\");\n let _ = git_run(&[\"stash\", \"push\", \"-m\", \"upstream-sync auto-stash\"]);\n\n // Check if stash actually added an entry\n let stash_count_after = git_capture(&[\"stash\", \"list\"])\n .map(|s| s.lines().count())\n .unwrap_or(0);\n stashed = stash_count_after > stash_count_before;\n }\n\n // Fetch upstream\n println!(\"==> Fetching upstream...\");\n git_run(&[\"fetch\", \"upstream\", \"--prune\"])?;\n\n // Determine upstream branch (check config, then HEAD, then try main/master)\n let upstream_branch =\n if let Ok(merge_ref) = git_capture(&[\"config\", \"--get\", \"branch.upstream.merge\"]) {\n merge_ref.trim().replace(\"refs/heads/\", \"\")\n } else if let Ok(head_ref) = git_capture(&[\"symbolic-ref\", \"refs/remotes/upstream/HEAD\"]) {\n // Parse \"refs/remotes/upstream/master\" -> \"master\"\n head_ref.trim().replace(\"refs/remotes/upstream/\", \"\")\n } else if git_capture(&[\"rev-parse\", \"--verify\", \"refs/remotes/upstream/main\"]).is_ok() {\n \"main\".to_string()\n } else if git_capture(&[\"rev-parse\", \"--verify\", \"refs/remotes/upstream/master\"]).is_ok() {\n \"master\".to_string()\n } else {\n \"main\".to_string()\n };\n let upstream_ref = format!(\"upstream/{}\", upstream_branch);\n\n // Update local upstream branch\n println!(\"==> Updating local 'upstream' branch...\");\n let local_upstream_exists =\n git_capture(&[\"rev-parse\", \"--verify\", \"refs/heads/upstream\"]).is_ok();\n if local_upstream_exists {\n git_run(&[\"branch\", \"-f\", \"upstream\", &upstream_ref])?;\n } else {\n git_run(&[\"branch\", \"upstream\", &upstream_ref])?;\n }\n\n // Detect branch structure (dev+main or just main)\n let has_dev = git_capture(&[\"rev-parse\", \"--verify\", \"refs/heads/dev\"]).is_ok();\n let has_main = git_capture(&[\"rev-parse\", \"--verify\", \"refs/heads/main\"]).is_ok();\n\n if has_dev {\n // Merge upstream -> dev -> main\n println!(\"==> Merging upstream into dev...\");\n git_run(&[\"checkout\", \"dev\"])?;\n merge_branch(\"upstream\", \"dev\")?;\n\n if has_main {\n println!(\"==> Merging dev into main...\");\n git_run(&[\"checkout\", \"main\"])?;\n merge_branch(\"dev\", \"main\")?;\n }\n } else if has_main {\n // Just merge upstream -> main\n println!(\"==> Merging upstream into main...\");\n git_run(&[\"checkout\", \"main\"])?;\n merge_branch(\"upstream\", \"main\")?;\n } else {\n // Merge into current branch\n println!(\"==> Merging upstream into {}...\", current);\n git_run(&[\"checkout\", ¤t])?;\n merge_branch(\"upstream\", ¤t)?;\n }\n\n // Push if requested\n if push {\n println!(\"==> Pushing to origin...\");\n\n // Try push, auto-create repo if it doesn't exist\n let branches_to_push: Vec<&str> = if has_dev && has_main {\n vec![\"dev\", \"main\"]\n } else if has_main {\n vec![\"main\"]\n } else if has_dev {\n vec![\"dev\"]\n } else {\n vec![current.as_str()]\n };\n\n for branch in &branches_to_push {\n if let Err(e) = git_run(&[\"push\", \"origin\", branch]) {\n // Only try to create repo if explicitly requested\n if create_repo && try_create_origin_repo()? {\n // Repo created, retry push\n git_run(&[\"push\", \"-u\", \"origin\", branch])?;\n } else {\n return Err(e);\n }\n }\n }\n }\n\n // Return to original branch\n if current != \"main\" && current != \"dev\" {\n git_run(&[\"checkout\", ¤t])?;\n }\n\n // Restore stashed changes\n if stashed {\n println!(\"Restoring stashed changes...\");\n git_run(&[\"stash\", \"pop\"])?;\n }\n\n println!(\"\\n✓ Sync complete!\");\n if has_dev && has_main {\n println!(\" upstream, dev, and main are updated.\");\n } else if has_main {\n println!(\" upstream and main are updated.\");\n }\n\n Ok(())\n}\n\n/// Merge a source branch into the current branch.\nfn merge_branch(source: &str, target: &str) -> Result<()> {\n // Try fast-forward first\n if git_run(&[\"merge\", \"--ff-only\", source]).is_ok() {\n return Ok(());\n }\n\n println!(\"Fast-forward failed, trying regular merge...\");\n if let Err(_) = git_run(&[\"merge\", source, \"--no-edit\"]) {\n bail!(\n \"Merge conflicts in {}. Resolve manually:\\n git status\\n # fix conflicts\\n git add . && git commit\",\n target\n );\n }\n\n Ok(())\n}\n\n/// Run a git command and capture stdout.\nfn git_capture(args: &[&str]) -> Result<String> {\n let output = Command::new(\"git\")\n .args(args)\n .output()\n .context(\"failed to run git\")?;\n\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"git {} failed: {}\", args.join(\" \"), stderr.trim());\n }\n\n Ok(String::from_utf8_lossy(&output.stdout).to_string())\n}\n\n/// Run a git command with inherited stdio.\nfn git_run(args: &[&str]) -> Result<()> {\n let status = Command::new(\"git\")\n .args(args)\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status()\n .context(\"failed to run git\")?;\n\n if !status.success() {\n bail!(\"git {} failed\", args.join(\" \"));\n }\n\n Ok(())\n}\n\n/// Try to create the origin repo on GitHub if it doesn't exist.\n/// Returns true if repo was created, false if it already exists or creation failed.\nfn try_create_origin_repo() -> Result<bool> {\n // Get origin URL to extract repo name\n let origin_url = match git_capture(&[\"remote\", \"get-url\", \"origin\"]) {\n Ok(url) => url.trim().to_string(),\n Err(_) => return Ok(false),\n };\n\n // Extract repo name from URL (supports both SSH and HTTPS formats)\n // SSH: git@github.com:user/repo.git\n // HTTPS: https://github.com/user/repo.git\n let repo_path = if origin_url.starts_with(\"git@github.com:\") {\n origin_url\n .strip_prefix(\"git@github.com:\")\n .and_then(|s| s.strip_suffix(\".git\").or(Some(s)))\n } else if origin_url.contains(\"github.com/\") {\n origin_url\n .split(\"github.com/\")\n .nth(1)\n .and_then(|s| s.strip_suffix(\".git\").or(Some(s)))\n } else {\n None\n };\n\n let Some(repo_path) = repo_path else {\n println!(\"Cannot parse origin URL for auto-creation: {}\", origin_url);\n return Ok(false);\n };\n\n println!(\"\\nOrigin repo doesn't exist. Creating: {}\", repo_path);\n\n // Use gh CLI to create the repo\n let status = Command::new(\"gh\")\n .args([\"repo\", \"create\", repo_path, \"--private\", \"--source=.\"])\n .stdin(Stdio::inherit())\n .stdout(Stdio::inherit())\n .stderr(Stdio::inherit())\n .status();\n\n match status {\n Ok(s) if s.success() => {\n println!(\"✓ Created GitHub repo: {}\", repo_path);\n Ok(true)\n }\n Ok(_) => {\n println!(\"Failed to create repo. Is `gh` installed and authenticated?\");\n println!(\" Run: gh auth login\");\n Ok(false)\n }\n Err(e) => {\n println!(\"Failed to run gh CLI: {}\", e);\n println!(\" Install with: brew install gh\");\n Ok(false)\n }\n }\n}\n" }, { "path": "src/url_inspect.rs", "content": "use std::path::Path;\nuse std::time::{Duration, Instant};\n\nuse anyhow::{Context, Result, bail};\nuse regex::Regex;\nuse reqwest::header::{ACCEPT, AUTHORIZATION, CONTENT_TYPE};\nuse serde::{Deserialize, Serialize};\nuse serde_json::{Value, json};\n\nuse crate::{\n cli::{\n UrlAction, UrlCommand, UrlCrawlOpts, UrlCrawlSource, UrlInspectOpts, UrlInspectProvider,\n },\n config, env as flow_env, http_client, project_snapshot,\n};\n\nconst DEFAULT_EXCERPT_CHARS: usize = 420;\nconst DEFAULT_DIRECT_ACCEPT: &str = \"text/markdown, text/html;q=0.9, text/plain;q=0.8, */*;q=0.1\";\nconst CLOUDFLARE_API_BASE: &str = \"https://api.cloudflare.com/client/v4\";\n\n#[derive(Debug, Clone, Default)]\nstruct UrlInspectSettings {\n scraper_base_url: Option<String>,\n scraper_api_key: Option<String>,\n cache_ttl_hours: Option<f64>,\n allow_direct_fallback: bool,\n}\n\n#[derive(Debug, Clone, Serialize)]\npub struct UrlInspectResult {\n pub reference: String,\n pub provider: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub final_url: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub status_code: Option<u16>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub content_type: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub title: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub description: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub excerpt: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub markdown: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub cache_hit: Option<bool>,\n}\n\n#[derive(Debug, Clone, Serialize)]\npub struct UrlCrawlResult {\n pub reference: String,\n pub provider: String,\n pub job_id: String,\n pub status: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub total: Option<u64>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub finished: Option<u64>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub browser_seconds_used: Option<f64>,\n pub render: bool,\n pub source: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub cursor: Option<String>,\n #[serde(default, skip_serializing_if = \"Vec::is_empty\")]\n pub records: Vec<UrlCrawlRecord>,\n}\n\n#[derive(Debug, Clone, Serialize)]\npub struct UrlCrawlRecord {\n pub url: String,\n pub status: String,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub title: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub status_code: Option<u16>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub excerpt: Option<String>,\n #[serde(skip_serializing_if = \"Option::is_none\")]\n pub markdown: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct CloudflareEnvelope {\n success: bool,\n #[serde(default)]\n result: Option<Value>,\n #[serde(default)]\n errors: Vec<CloudflareError>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct CloudflareError {\n #[serde(default)]\n code: Option<i64>,\n #[serde(default)]\n message: Option<String>,\n}\n\n#[derive(Debug, Deserialize)]\nstruct ScrapeResult {\n success: bool,\n #[serde(default)]\n final_url: Option<String>,\n #[serde(default)]\n status_code: Option<u16>,\n #[serde(default)]\n content_type: Option<String>,\n #[serde(default)]\n title: Option<String>,\n #[serde(default)]\n text_excerpt: Option<String>,\n #[serde(default)]\n cache_hit: Option<bool>,\n #[serde(default)]\n error: Option<String>,\n}\n\npub fn run(cmd: UrlCommand) -> Result<()> {\n match cmd.action {\n UrlAction::Inspect(opts) => inspect(opts),\n UrlAction::Crawl(opts) => crawl(opts),\n }\n}\n\npub fn inspect_compact(url: &str, cwd: &Path) -> Result<String> {\n let settings = load_url_inspect_settings(cwd);\n let timeout = timeout_from_secs(12.0)?;\n let opts = UrlInspectOpts {\n url: url.to_string(),\n json: false,\n full: false,\n provider: UrlInspectProvider::Auto,\n timeout_s: 12.0,\n };\n let result = inspect_url(&opts, &settings, timeout)?;\n Ok(render_compact_result(&result))\n}\n\nfn inspect(opts: UrlInspectOpts) -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n let settings = load_url_inspect_settings(&cwd);\n let timeout = timeout_from_secs(opts.timeout_s)?;\n let result = inspect_url(&opts, &settings, timeout)?;\n print_result(&result, opts.json, opts.full)\n}\n\nfn crawl(opts: UrlCrawlOpts) -> Result<()> {\n let cwd = std::env::current_dir().context(\"failed to get current directory\")?;\n let settings = load_url_inspect_settings(&cwd);\n let request_timeout = Duration::from_secs_f64(opts.wait_timeout_s.clamp(5.0, 30.0));\n let wait_timeout = timeout_from_secs(opts.wait_timeout_s)?;\n let poll_interval = timeout_from_secs(opts.poll_interval_s)?;\n let result = crawl_url(\n &opts,\n &settings,\n request_timeout,\n wait_timeout,\n poll_interval,\n )?;\n print_crawl_result(&result, opts.json, opts.full)\n}\n\nfn crawl_url(\n opts: &UrlCrawlOpts,\n settings: &UrlInspectSettings,\n request_timeout: Duration,\n wait_timeout: Duration,\n poll_interval: Duration,\n) -> Result<UrlCrawlResult> {\n let (account_id, api_token) = cloudflare_credentials()?.ok_or_else(|| {\n anyhow::anyhow!(\n \"Cloudflare crawl requires CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN in shell env or Flow personal env store\"\n )\n })?;\n let mut result = crawl_via_cloudflare(\n opts,\n settings,\n request_timeout,\n wait_timeout,\n poll_interval,\n &account_id,\n &api_token,\n CLOUDFLARE_API_BASE,\n )?;\n if result.reference.is_empty() {\n result.reference = opts.url.clone();\n }\n Ok(result)\n}\n\nfn print_crawl_result(result: &UrlCrawlResult, json_output: bool, full: bool) -> Result<()> {\n if json_output {\n println!(\n \"{}\",\n serde_json::to_string_pretty(result)\n .context(\"failed to encode crawl result as json\")?\n );\n return Ok(());\n }\n\n println!(\"Provider: {}\", result.provider);\n println!(\"Job: {}\", result.job_id);\n println!(\"Status: {}\", result.status);\n println!(\"URL: {}\", result.reference);\n if let Some(total) = result.total {\n println!(\"Total: {}\", total);\n }\n if let Some(finished) = result.finished {\n println!(\"Finished: {}\", finished);\n }\n if let Some(browser_seconds_used) = result.browser_seconds_used {\n println!(\"Browser seconds: {:.2}\", browser_seconds_used);\n }\n if !result.records.is_empty() {\n println!(\"\\nRecords:\");\n for (index, record) in result.records.iter().enumerate() {\n let label = record.title.as_deref().unwrap_or(&record.url);\n println!(\"{}. {}\", index + 1, label);\n println!(\" URL: {}\", record.url);\n println!(\" Status: {}\", record.status);\n if let Some(status_code) = record.status_code {\n println!(\" HTTP: {}\", status_code);\n }\n if let Some(excerpt) = record.excerpt.as_deref() {\n println!(\" Excerpt: {}\", excerpt);\n }\n if full && let Some(markdown) = record.markdown.as_deref() {\n println!(\"\\n Markdown:\\n{}\\n\", markdown);\n }\n }\n if !full\n && result\n .records\n .iter()\n .any(|record| record.markdown.is_some())\n {\n println!(\"\\nHint: pass --full to print markdown bodies for returned records.\");\n }\n }\n Ok(())\n}\n\nfn inspect_url(\n opts: &UrlInspectOpts,\n settings: &UrlInspectSettings,\n timeout: Duration,\n) -> Result<UrlInspectResult> {\n let provider = opts.provider;\n let (cloudflare_creds, cloudflare_error) = match cloudflare_credentials() {\n Ok(value) => (value, None),\n Err(err) => (None, Some(format!(\"{err:#}\"))),\n };\n let scraper_ready = settings.scraper_base_url.is_some();\n let direct_allowed = settings.allow_direct_fallback || !scraper_ready;\n\n let plan: Vec<UrlInspectProvider> = match provider {\n UrlInspectProvider::Auto => {\n let mut providers = Vec::new();\n if cloudflare_creds.is_some() {\n providers.push(UrlInspectProvider::Cloudflare);\n }\n if scraper_ready {\n providers.push(UrlInspectProvider::Scraper);\n }\n providers.push(UrlInspectProvider::Direct);\n providers\n }\n UrlInspectProvider::Cloudflare => vec![UrlInspectProvider::Cloudflare],\n UrlInspectProvider::Scraper => {\n if settings.allow_direct_fallback {\n vec![UrlInspectProvider::Scraper, UrlInspectProvider::Direct]\n } else {\n vec![UrlInspectProvider::Scraper]\n }\n }\n UrlInspectProvider::Direct => vec![UrlInspectProvider::Direct],\n };\n\n let mut errors = Vec::new();\n for next in plan {\n match next {\n UrlInspectProvider::Cloudflare => {\n let Some((account_id, api_token)) = cloudflare_creds.clone() else {\n if let Some(err) = cloudflare_error.as_deref() {\n errors.push(format!(\"cloudflare: {err}\"));\n } else {\n errors.push(\n \"cloudflare: missing CLOUDFLARE_ACCOUNT_ID or CLOUDFLARE_API_TOKEN\"\n .to_string(),\n );\n }\n continue;\n };\n if account_id.trim().is_empty() || api_token.trim().is_empty() {\n errors.push(\n \"cloudflare: missing CLOUDFLARE_ACCOUNT_ID or CLOUDFLARE_API_TOKEN\"\n .to_string(),\n );\n continue;\n }\n match inspect_via_cloudflare_markdown(\n &opts.url,\n timeout,\n &account_id,\n &api_token,\n settings.cache_ttl_hours,\n CLOUDFLARE_API_BASE,\n opts.full,\n ) {\n Ok(result) => return Ok(result),\n Err(err) => errors.push(format!(\"cloudflare: {err:#}\")),\n }\n }\n UrlInspectProvider::Scraper => {\n if let Some(base_url) = settings.scraper_base_url.as_deref() {\n match inspect_via_scraper(\n &opts.url,\n timeout,\n base_url,\n settings.scraper_api_key.as_deref(),\n opts.full,\n ) {\n Ok(result) => return Ok(result),\n Err(err) => {\n errors.push(format!(\"scraper: {err:#}\"));\n if !direct_allowed && provider == UrlInspectProvider::Scraper {\n break;\n }\n }\n }\n } else {\n errors.push(\"scraper: no scraper_base_url configured\".to_string());\n }\n }\n UrlInspectProvider::Direct => {\n match inspect_via_direct_fetch(&opts.url, timeout, opts.full) {\n Ok(result) => return Ok(result),\n Err(err) => errors.push(format!(\"direct: {err:#}\")),\n }\n }\n UrlInspectProvider::Auto => {}\n }\n }\n\n if errors.is_empty() {\n bail!(\"url inspect failed with no available providers\");\n }\n\n bail!(\"url inspect failed:\\n- {}\", errors.join(\"\\n- \"))\n}\n\nfn print_result(result: &UrlInspectResult, json_output: bool, full: bool) -> Result<()> {\n if json_output {\n println!(\n \"{}\",\n serde_json::to_string_pretty(result).context(\"failed to encode result as json\")?\n );\n return Ok(());\n }\n\n println!(\"Provider: {}\", result.provider);\n if let Some(title) = &result.title {\n println!(\"Title: {title}\");\n }\n if let Some(final_url) = &result.final_url {\n println!(\"URL: {final_url}\");\n } else {\n println!(\"URL: {}\", result.reference);\n }\n if let Some(content_type) = &result.content_type {\n println!(\"Content-Type: {content_type}\");\n }\n if let Some(description) = &result.description {\n println!(\"\\nDescription:\\n{description}\");\n }\n if let Some(excerpt) = &result.excerpt {\n println!(\"\\nExcerpt:\\n{excerpt}\");\n }\n if full {\n if let Some(markdown) = &result.markdown {\n println!(\"\\nMarkdown:\\n{markdown}\");\n }\n } else if result.markdown.is_some() {\n println!(\"\\nHint: pass --full to print the full markdown body.\");\n }\n Ok(())\n}\n\nfn render_compact_result(result: &UrlInspectResult) -> String {\n let mut lines = Vec::new();\n lines.push(format!(\"- URL: {}\", result.reference));\n lines.push(format!(\"- Provider: {}\", result.provider));\n if let Some(final_url) = result.final_url.as_deref()\n && final_url != result.reference\n {\n lines.push(format!(\"- Final URL: {final_url}\"));\n }\n if let Some(title) = result.title.as_deref() {\n lines.push(format!(\"- Title: {title}\"));\n }\n if let Some(description) = result.description.as_deref() {\n lines.push(format!(\"- Description: {description}\"));\n }\n if let Some(excerpt) = result.excerpt.as_deref() {\n lines.push(format!(\"- Excerpt: {excerpt}\"));\n }\n if let Some(content_type) = result.content_type.as_deref() {\n lines.push(format!(\"- Content-Type: {content_type}\"));\n }\n lines.join(\"\\n\")\n}\n\nfn crawl_via_cloudflare(\n opts: &UrlCrawlOpts,\n settings: &UrlInspectSettings,\n request_timeout: Duration,\n wait_timeout: Duration,\n poll_interval: Duration,\n account_id: &str,\n api_token: &str,\n api_base: &str,\n) -> Result<UrlCrawlResult> {\n let client = http_client::blocking_with_timeout(request_timeout)?;\n let endpoint = format!(\n \"{}/accounts/{}/browser-rendering/crawl\",\n api_base.trim_end_matches('/'),\n account_id\n );\n let create_payload = cloudflare_crawl_create_payload(opts, settings);\n let response = client\n .post(&endpoint)\n .header(CONTENT_TYPE, \"application/json\")\n .header(AUTHORIZATION, format!(\"Bearer {api_token}\"))\n .json(&create_payload)\n .send()\n .context(\"failed to create Cloudflare Browser Rendering crawl job\")?;\n let status = response.status();\n let body = response\n .text()\n .context(\"failed to read Cloudflare crawl create response\")?;\n if !status.is_success() {\n bail!(\"http {}: {}\", status.as_u16(), body);\n }\n\n let envelope: CloudflareEnvelope =\n serde_json::from_str(&body).context(\"failed to decode Cloudflare crawl create response\")?;\n if !envelope.success {\n bail!(\n \"Cloudflare crawl failed: {}\",\n cloudflare_error_detail(&envelope.errors)\n );\n }\n let job_id = envelope\n .result\n .as_ref()\n .and_then(|value| value.as_str().map(|v| v.to_string()))\n .or_else(|| {\n envelope.result.as_ref().and_then(|value| {\n value\n .as_object()\n .and_then(|obj| obj.get(\"id\"))\n .and_then(|value| value.as_str())\n .map(|value| value.to_string())\n })\n })\n .filter(|value| !value.is_empty())\n .ok_or_else(|| anyhow::anyhow!(\"Cloudflare crawl did not return a job id\"))?;\n\n let started = Instant::now();\n loop {\n let state =\n fetch_cloudflare_crawl_result(&client, &endpoint, api_token, &job_id, 1, false, false)?;\n match state.status.as_str() {\n \"completed\" => {\n return fetch_cloudflare_crawl_result(\n &client,\n &endpoint,\n api_token,\n &job_id,\n opts.records.max(1),\n true,\n opts.full,\n );\n }\n \"failed\" | \"cancelled\" | \"canceled\" => {\n bail!(\n \"Cloudflare crawl job {} ended with status {}\",\n job_id,\n state.status\n );\n }\n _ => {\n if started.elapsed() >= wait_timeout {\n bail!(\n \"timed out waiting for Cloudflare crawl job {} after {:.1}s\",\n job_id,\n wait_timeout.as_secs_f64()\n );\n }\n std::thread::sleep(poll_interval);\n }\n }\n }\n}\n\nfn cloudflare_crawl_create_payload(\n opts: &UrlCrawlOpts,\n settings: &UrlInspectSettings,\n) -> serde_json::Value {\n let max_age_s = opts.max_age_s.or_else(|| {\n settings\n .cache_ttl_hours\n .map(|hours| (hours * 3600.0).round().clamp(0.0, 86_400.0) as u64)\n });\n let mut payload = json!({\n \"url\": opts.url,\n \"limit\": opts.limit,\n \"depth\": opts.depth,\n \"render\": opts.render,\n \"source\": cloudflare_crawl_source(opts.source),\n \"formats\": [\"markdown\"],\n });\n\n if let Some(max_age_s) = max_age_s {\n payload[\"maxAge\"] = json!(max_age_s);\n }\n\n let mut options = serde_json::Map::new();\n if opts.include_external_links {\n options.insert(\"includeExternalLinks\".to_string(), json!(true));\n }\n if opts.include_subdomains {\n options.insert(\"includeSubdomains\".to_string(), json!(true));\n }\n if !opts.include_patterns.is_empty() {\n options.insert(\"includePatterns\".to_string(), json!(opts.include_patterns));\n }\n if !opts.exclude_patterns.is_empty() {\n options.insert(\"excludePatterns\".to_string(), json!(opts.exclude_patterns));\n }\n if !options.is_empty() {\n payload[\"options\"] = Value::Object(options);\n }\n\n payload\n}\n\nfn cloudflare_crawl_source(source: UrlCrawlSource) -> &'static str {\n match source {\n UrlCrawlSource::All => \"all\",\n UrlCrawlSource::Sitemaps => \"sitemaps\",\n UrlCrawlSource::Links => \"links\",\n }\n}\n\nfn fetch_cloudflare_crawl_result(\n client: &reqwest::blocking::Client,\n endpoint: &str,\n api_token: &str,\n job_id: &str,\n records_limit: usize,\n completed_only: bool,\n include_full_markdown: bool,\n) -> Result<UrlCrawlResult> {\n let mut request = client\n .get(format!(\"{}/{}\", endpoint.trim_end_matches('/'), job_id))\n .header(AUTHORIZATION, format!(\"Bearer {api_token}\"))\n .query(&[(\"limit\", records_limit.max(1).to_string())]);\n if completed_only {\n request = request.query(&[(\"status\", \"completed\")]);\n }\n let response = request\n .send()\n .context(\"failed to fetch Cloudflare crawl status\")?;\n let status = response.status();\n let body = response\n .text()\n .context(\"failed to read Cloudflare crawl status response\")?;\n if !status.is_success() {\n bail!(\"http {}: {}\", status.as_u16(), body);\n }\n\n let envelope: CloudflareEnvelope =\n serde_json::from_str(&body).context(\"failed to decode Cloudflare crawl status response\")?;\n if !envelope.success {\n bail!(\n \"Cloudflare crawl status failed: {}\",\n cloudflare_error_detail(&envelope.errors)\n );\n }\n\n let Some(result) = envelope.result.as_ref() else {\n bail!(\"Cloudflare crawl status returned no result\");\n };\n parse_cloudflare_crawl_result(result, include_full_markdown)\n}\n\nfn parse_cloudflare_crawl_result(\n value: &Value,\n include_full_markdown: bool,\n) -> Result<UrlCrawlResult> {\n let object = value\n .as_object()\n .ok_or_else(|| anyhow::anyhow!(\"Cloudflare crawl result was not an object\"))?;\n let job_id = string_field(object, \"id\")\n .ok_or_else(|| anyhow::anyhow!(\"Cloudflare crawl result missing id\"))?;\n let status = string_field(object, \"status\").unwrap_or_else(|| \"unknown\".to_string());\n let total = u64_field(object, \"total\");\n let finished = u64_field(object, \"finished\");\n let browser_seconds_used = f64_field(object, \"browserSecondsUsed\");\n let cursor = string_field(object, \"cursor\");\n let render = bool_field(object, \"render\").unwrap_or(false);\n let source = string_field(object, \"source\").unwrap_or_else(|| \"all\".to_string());\n let reference = string_field(object, \"url\").unwrap_or_default();\n let records = object\n .get(\"records\")\n .and_then(|records| records.as_array())\n .map(|records| {\n records\n .iter()\n .filter_map(|record| parse_cloudflare_crawl_record(record, include_full_markdown))\n .collect::<Vec<_>>()\n })\n .unwrap_or_default();\n\n Ok(UrlCrawlResult {\n reference,\n provider: \"cloudflare-crawl\".to_string(),\n job_id,\n status,\n total,\n finished,\n browser_seconds_used,\n render,\n source,\n cursor,\n records,\n })\n}\n\nfn parse_cloudflare_crawl_record(\n value: &Value,\n include_full_markdown: bool,\n) -> Option<UrlCrawlRecord> {\n let object = value.as_object()?;\n let metadata = object.get(\"metadata\").and_then(|value| value.as_object());\n let url = string_field(object, \"url\")\n .or_else(|| metadata.and_then(|value| string_field(value, \"url\")))?;\n let status = string_field(object, \"status\").unwrap_or_else(|| \"unknown\".to_string());\n let title = metadata.and_then(|value| string_field(value, \"title\"));\n let status_code = metadata\n .and_then(|value| u64_field(value, \"status\"))\n .and_then(|value| u16::try_from(value).ok());\n let markdown = object\n .get(\"markdown\")\n .and_then(|value| value.as_str())\n .map(|value| value.to_string());\n let excerpt = markdown\n .as_deref()\n .map(markdown_metadata)\n .and_then(|metadata| metadata.description.or(metadata.excerpt));\n\n Some(UrlCrawlRecord {\n url,\n status,\n title,\n status_code,\n excerpt,\n markdown: include_full_markdown.then_some(markdown).flatten(),\n })\n}\n\nfn cloudflare_error_detail(errors: &[CloudflareError]) -> String {\n let detail = errors\n .iter()\n .map(|err| match (&err.code, &err.message) {\n (Some(code), Some(message)) => format!(\"{code}: {message}\"),\n (_, Some(message)) => message.clone(),\n _ => \"unknown Cloudflare error\".to_string(),\n })\n .collect::<Vec<_>>()\n .join(\"; \");\n if detail.is_empty() {\n \"unknown Cloudflare error\".to_string()\n } else {\n detail\n }\n}\n\nfn inspect_via_cloudflare_markdown(\n url: &str,\n timeout: Duration,\n account_id: &str,\n api_token: &str,\n cache_ttl_hours: Option<f64>,\n api_base: &str,\n include_full_markdown: bool,\n) -> Result<UrlInspectResult> {\n let client = http_client::blocking_with_timeout(timeout)?;\n let endpoint = format!(\n \"{}/accounts/{}/browser-rendering/markdown\",\n api_base.trim_end_matches('/'),\n account_id\n );\n let mut request = client\n .post(endpoint)\n .header(CONTENT_TYPE, \"application/json\")\n .header(AUTHORIZATION, format!(\"Bearer {api_token}\"))\n .json(&json!({ \"url\": url }));\n\n if let Some(hours) = cache_ttl_hours {\n let ttl = (hours * 3600.0).round().clamp(0.0, 86_400.0) as u32;\n request = request.query(&[(\"cacheTTL\", ttl.to_string())]);\n }\n\n let response = request\n .send()\n .context(\"failed to call Cloudflare Browser Rendering markdown endpoint\")?;\n let status = response.status();\n let body = response\n .text()\n .context(\"failed to read Cloudflare markdown response\")?;\n if !status.is_success() {\n bail!(\"http {}: {}\", status.as_u16(), body);\n }\n\n let envelope: CloudflareEnvelope =\n serde_json::from_str(&body).context(\"failed to decode Cloudflare markdown response\")?;\n if !envelope.success {\n bail!(\n \"Cloudflare markdown failed: {}\",\n cloudflare_error_detail(&envelope.errors)\n );\n }\n\n let markdown = envelope\n .result\n .as_ref()\n .and_then(|value| value.as_str())\n .unwrap_or_default()\n .to_string();\n let metadata = markdown_metadata(&markdown);\n Ok(UrlInspectResult {\n reference: url.to_string(),\n provider: \"cloudflare-markdown\".to_string(),\n final_url: Some(url.to_string()),\n status_code: Some(status.as_u16()),\n content_type: Some(\"text/markdown\".to_string()),\n title: metadata.title,\n description: metadata.description,\n excerpt: metadata.excerpt,\n markdown: include_full_markdown.then_some(markdown),\n cache_hit: None,\n })\n}\n\nfn inspect_via_scraper(\n url: &str,\n timeout: Duration,\n base_url: &str,\n api_key: Option<&str>,\n _include_full_markdown: bool,\n) -> Result<UrlInspectResult> {\n let client = http_client::blocking_with_timeout(timeout)?;\n let endpoint = format!(\"{}/scrape\", base_url.trim_end_matches('/'));\n let mut request = client.post(endpoint).json(&json!({\n \"url\": url,\n \"mode\": \"balanced\",\n \"timeout_s\": timeout.as_secs_f64(),\n \"max_bytes\": 400_000_u64\n }));\n let api_token = api_key\n .map(|value| value.to_string())\n .or_else(|| std::env::var(\"SEQ_SCRAPER_API_KEY\").ok());\n if let Some(token) = api_token {\n request = request.bearer_auth(token);\n }\n\n let response = request\n .send()\n .context(\"failed to call configured scraper endpoint\")?;\n let status = response.status();\n let body = response\n .text()\n .context(\"failed to read scraper response body\")?;\n if !status.is_success() {\n bail!(\"http {}: {}\", status.as_u16(), body);\n }\n let payload: ScrapeResult =\n serde_json::from_str(&body).context(\"failed to decode scraper response\")?;\n if !payload.success {\n bail!(\n \"{}\",\n payload\n .error\n .unwrap_or_else(|| \"scraper reported failure without an error\".to_string())\n );\n }\n\n Ok(UrlInspectResult {\n reference: url.to_string(),\n provider: \"scraper\".to_string(),\n final_url: payload.final_url,\n status_code: payload.status_code,\n content_type: payload.content_type,\n title: payload.title,\n description: None,\n excerpt: payload\n .text_excerpt\n .map(|value| truncate_excerpt(&normalize_whitespace(&value))),\n markdown: None,\n cache_hit: payload.cache_hit,\n })\n}\n\nfn inspect_via_direct_fetch(\n url: &str,\n timeout: Duration,\n include_full_markdown: bool,\n) -> Result<UrlInspectResult> {\n let client = http_client::blocking_with_timeout(timeout)?;\n let response = client\n .get(url)\n .header(ACCEPT, DEFAULT_DIRECT_ACCEPT)\n .send()\n .with_context(|| format!(\"failed to fetch {url}\"))?;\n let status = response.status();\n let final_url = response.url().to_string();\n let content_type = header_value(response.headers().get(CONTENT_TYPE));\n let markdown_tokens = header_value(response.headers().get(\"x-markdown-tokens\"));\n let body = response.text().context(\"failed to read response body\")?;\n\n if !status.is_success() {\n bail!(\"http {}: {}\", status.as_u16(), truncate_excerpt(&body));\n }\n\n let looks_like_markdown = content_type\n .as_deref()\n .map(|value| value.contains(\"markdown\"))\n .unwrap_or(false)\n || markdown_tokens.is_some();\n\n let (title, description, excerpt, markdown) = if looks_like_markdown {\n let metadata = markdown_metadata(&body);\n (\n metadata.title,\n metadata.description,\n metadata.excerpt,\n include_full_markdown.then_some(body),\n )\n } else if content_type\n .as_deref()\n .map(|value| value.contains(\"html\"))\n .unwrap_or(false)\n || body.contains(\"<html\")\n || body.contains(\"<body\")\n {\n let html = html_metadata(&body, &final_url);\n (\n html.title,\n html.description,\n html.excerpt,\n include_full_markdown.then_some(body),\n )\n } else {\n let excerpt = truncate_excerpt(&normalize_whitespace(&body));\n (\n None,\n None,\n Some(excerpt),\n include_full_markdown.then_some(body),\n )\n };\n\n Ok(UrlInspectResult {\n reference: url.to_string(),\n provider: \"direct\".to_string(),\n final_url: Some(final_url),\n status_code: Some(status.as_u16()),\n content_type,\n title,\n description,\n excerpt,\n markdown,\n cache_hit: None,\n })\n}\n\nfn timeout_from_secs(seconds: f64) -> Result<Duration> {\n if !seconds.is_finite() || seconds <= 0.0 {\n bail!(\"timeout must be a positive finite number\");\n }\n Ok(Duration::from_secs_f64(seconds))\n}\n\nfn cloudflare_credentials() -> Result<Option<(String, String)>> {\n let account_id = load_secret_env_var(\"CLOUDFLARE_ACCOUNT_ID\")?;\n let api_token = load_secret_env_var(\"CLOUDFLARE_API_TOKEN\")?;\n match (account_id, api_token) {\n (Some(account_id), Some(api_token)) => Ok(Some((account_id, api_token))),\n (None, None) => Ok(None),\n (Some(_), None) => {\n bail!(\"missing CLOUDFLARE_API_TOKEN; set it in shell env or Flow personal env store\")\n }\n (None, Some(_)) => {\n bail!(\"missing CLOUDFLARE_ACCOUNT_ID; set it in shell env or Flow personal env store\")\n }\n }\n}\n\nfn load_secret_env_var(key: &str) -> Result<Option<String>> {\n if let Ok(value) = std::env::var(key) {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(Some(trimmed.to_string()));\n }\n }\n\n let primary = flow_env::get_personal_env_var(key)\n .with_context(|| format!(\"failed to load {key} from Flow personal env store\"));\n match primary {\n Ok(Some(value)) => {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(Some(trimmed.to_string()));\n }\n }\n Ok(None) => {}\n Err(err) if wants_local_env_backend() => return Err(err),\n Err(_) => {}\n }\n\n if !wants_local_env_backend() {\n let local_value = with_local_env_backend(|| flow_env::get_personal_env_var(key))\n .with_context(|| format!(\"failed to load {key} from local Flow personal env store\"))?;\n if let Some(value) = local_value {\n let trimmed = value.trim();\n if !trimmed.is_empty() {\n return Ok(Some(trimmed.to_string()));\n }\n }\n }\n\n Ok(None)\n}\n\nfn wants_local_env_backend() -> bool {\n if let Some(backend) = crate::config::preferred_env_backend() {\n return backend == \"local\";\n }\n if let Ok(value) = std::env::var(\"FLOW_ENV_BACKEND\") {\n return value.trim().eq_ignore_ascii_case(\"local\");\n }\n std::env::var(\"FLOW_ENV_LOCAL\")\n .ok()\n .map(|value| value.trim() == \"1\" || value.trim().eq_ignore_ascii_case(\"true\"))\n .unwrap_or(false)\n}\n\nfn with_local_env_backend<T>(action: impl FnOnce() -> Result<T>) -> Result<T> {\n let previous = std::env::var(\"FLOW_ENV_BACKEND\").ok();\n unsafe {\n std::env::set_var(\"FLOW_ENV_BACKEND\", \"local\");\n }\n let result = action();\n unsafe {\n match previous {\n Some(value) => std::env::set_var(\"FLOW_ENV_BACKEND\", value),\n None => std::env::remove_var(\"FLOW_ENV_BACKEND\"),\n }\n }\n result\n}\n\nfn string_field(object: &serde_json::Map<String, Value>, key: &str) -> Option<String> {\n object\n .get(key)\n .and_then(|value| value.as_str())\n .map(|value| value.to_string())\n .filter(|value| !value.is_empty())\n}\n\nfn u64_field(object: &serde_json::Map<String, Value>, key: &str) -> Option<u64> {\n object.get(key).and_then(|value| match value {\n Value::Number(number) => number.as_u64(),\n Value::String(text) => text.parse::<u64>().ok(),\n _ => None,\n })\n}\n\nfn f64_field(object: &serde_json::Map<String, Value>, key: &str) -> Option<f64> {\n object.get(key).and_then(|value| match value {\n Value::Number(number) => number.as_f64(),\n Value::String(text) => text.parse::<f64>().ok(),\n _ => None,\n })\n}\n\nfn bool_field(object: &serde_json::Map<String, Value>, key: &str) -> Option<bool> {\n object.get(key).and_then(|value| match value {\n Value::Bool(value) => Some(*value),\n Value::String(text) => match text.as_str() {\n \"true\" => Some(true),\n \"false\" => Some(false),\n _ => None,\n },\n _ => None,\n })\n}\n\nfn load_url_inspect_settings(cwd: &Path) -> UrlInspectSettings {\n let mut settings = UrlInspectSettings::default();\n\n let global_path = config::default_config_path();\n if global_path.exists() {\n let cfg = config::load_or_default(&global_path);\n merge_seq_settings(&mut settings, cfg.skills.and_then(|skills| skills.seq));\n }\n\n if let Some(local_flow_toml) = project_snapshot::find_flow_toml_upwards(cwd) {\n let cfg = config::load_or_default(&local_flow_toml);\n merge_seq_settings(&mut settings, cfg.skills.and_then(|skills| skills.seq));\n }\n\n settings\n}\n\nfn merge_seq_settings(settings: &mut UrlInspectSettings, seq_cfg: Option<config::SkillsSeqConfig>) {\n let Some(seq_cfg) = seq_cfg else {\n return;\n };\n\n if let Some(value) = seq_cfg.scraper_base_url {\n settings.scraper_base_url = Some(value);\n }\n if let Some(value) = seq_cfg.scraper_api_key {\n settings.scraper_api_key = Some(value);\n }\n if let Some(value) = seq_cfg.cache_ttl_hours {\n settings.cache_ttl_hours = Some(value);\n }\n if let Some(value) = seq_cfg.allow_direct_fallback {\n settings.allow_direct_fallback = value;\n }\n}\n\n#[derive(Debug, Default)]\nstruct TextMetadata {\n title: Option<String>,\n description: Option<String>,\n excerpt: Option<String>,\n}\n\nfn markdown_metadata(markdown: &str) -> TextMetadata {\n let (frontmatter, content) = extract_markdown_frontmatter(markdown);\n let mut title = None;\n let mut description = None;\n let mut headings = Vec::new();\n let mut pre_heading_lines = Vec::new();\n let mut post_heading_lines = Vec::new();\n let mut heading_seen = false;\n\n if let Some(frontmatter) = frontmatter.as_deref() {\n title = capture_frontmatter_value(frontmatter, \"title\");\n description = capture_frontmatter_value(frontmatter, \"description\")\n .or_else(|| capture_frontmatter_value(frontmatter, \"summary\"));\n }\n\n for raw_line in content.lines() {\n let line = raw_line.trim();\n if line.is_empty() {\n continue;\n }\n if looks_like_markdown_boilerplate(line) {\n continue;\n }\n if line.starts_with('#') {\n headings.push(line.to_string());\n heading_seen = true;\n continue;\n }\n if line.starts_with(\"```\") {\n continue;\n }\n if looks_like_markdown_metadata_line(line) {\n continue;\n }\n if heading_seen {\n post_heading_lines.push(line.to_string());\n } else {\n pre_heading_lines.push(line.to_string());\n }\n }\n\n let first_heading = headings.iter().find_map(|heading| {\n let text = heading.trim_start_matches('#').trim();\n (!text.is_empty()).then(|| text.to_string())\n });\n\n if title.is_none() {\n title = first_heading.clone();\n }\n\n let paragraphs = if !post_heading_lines.is_empty() {\n post_heading_lines\n } else {\n pre_heading_lines\n };\n\n if description.is_none()\n && let Some(first) = paragraphs.first()\n {\n description = Some(truncate_excerpt(first));\n }\n\n let excerpt_source = paragraphs.join(\" \");\n let excerpt = (!excerpt_source.is_empty()).then(|| truncate_excerpt(&excerpt_source));\n\n TextMetadata {\n title,\n description,\n excerpt,\n }\n}\n\nfn looks_like_markdown_boilerplate(line: &str) -> bool {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n return true;\n }\n\n let lower = trimmed.to_ascii_lowercase();\n if lower == \"search\"\n || lower.starts_with(\"[skip to content]\")\n || lower.starts_with(\"search \")\n || lower.contains(\"subscribe to rss\")\n || lower.contains(\"view rss feeds\")\n || lower.contains(\"select theme\")\n || lower.contains(\"docs directory\")\n || lower.contains(\"new updates and improvements at cloudflare\")\n || lower == \"help\"\n || lower.contains(\"back to all posts\")\n || lower.starts_with(\"![\")\n || lower.starts_with(\"[ ![](\")\n || (trimmed.starts_with('[') && trimmed.matches(\"](\").count() >= 2)\n {\n return true;\n }\n\n matches!(trimmed, \"# Changelog\" | \"## Changelog\")\n}\n\nfn looks_like_markdown_metadata_line(line: &str) -> bool {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n return true;\n }\n\n let lower = trimmed.to_ascii_lowercase();\n if lower.starts_with(\"_edit:\")\n || lower.starts_with(\"*edit:\")\n || lower.starts_with(\"edit:\")\n || is_date_only_line(trimmed)\n {\n return true;\n }\n\n is_single_markdown_link_line(trimmed)\n}\n\nfn is_date_only_line(line: &str) -> bool {\n let Some((month, rest)) = line.split_once(' ') else {\n return false;\n };\n if !matches!(\n month,\n \"Jan\"\n | \"January\"\n | \"Feb\"\n | \"February\"\n | \"Mar\"\n | \"March\"\n | \"Apr\"\n | \"April\"\n | \"May\"\n | \"Jun\"\n | \"June\"\n | \"Jul\"\n | \"July\"\n | \"Aug\"\n | \"August\"\n | \"Sep\"\n | \"Sept\"\n | \"September\"\n | \"Oct\"\n | \"October\"\n | \"Nov\"\n | \"November\"\n | \"Dec\"\n | \"December\"\n ) {\n return false;\n }\n\n let Some((day, year)) = rest.split_once(',') else {\n return false;\n };\n let day = day.trim();\n let year = year.trim();\n !day.is_empty()\n && day.chars().all(|ch| ch.is_ascii_digit())\n && year.len() == 4\n && year.chars().all(|ch| ch.is_ascii_digit())\n}\n\nfn is_single_markdown_link_line(line: &str) -> bool {\n let Some(rest) = line.strip_prefix('[') else {\n return false;\n };\n let Some((label, url)) = rest.split_once(\"](\") else {\n return false;\n };\n let Some(url) = url.strip_suffix(')') else {\n return false;\n };\n !label.trim().is_empty()\n && !url.trim().is_empty()\n && !label.contains('[')\n && !url.contains('(')\n && !url.contains(')')\n}\n\nfn html_metadata(html: &str, final_url: &str) -> TextMetadata {\n let title = capture_first(r\"(?is)<title[^>]*>(.*?)\", html)\n .map(|value| normalize_whitespace(&value))\n .filter(|value| !value.is_empty());\n\n let description = capture_meta_description(html)\n .map(|value| normalize_whitespace(&value))\n .filter(|value| !value.is_empty())\n .map(|value| truncate_excerpt(&value));\n\n let excerpt = {\n let without_scripts = replace_all(r\"(?is)<(script|style)[^>]*>.*?\", html, \" \");\n let without_tags = replace_all(r\"(?is)<[^>]+>\", &without_scripts, \" \");\n let normalized = normalize_whitespace(&without_tags);\n (!normalized.is_empty()).then(|| truncate_excerpt(&normalized))\n };\n\n let mut metadata = TextMetadata {\n title,\n description,\n excerpt,\n };\n\n if looks_like_js_app_shell(final_url, html, &metadata) {\n if metadata.description.is_none() {\n metadata.description = Some(\n \"JavaScript-heavy app shell; direct fetch could not extract structured page content. Prefer Browser Rendering markdown, a configured scraper, or a domain-specific resolver.\"\n .to_string(),\n );\n }\n metadata.excerpt = None;\n if final_url.contains(\"linear.app/\") && metadata.title.as_deref() == Some(\"Linear\") {\n metadata.title = Some(\"Linear (app shell)\".to_string());\n }\n }\n\n metadata\n}\n\nfn capture_meta_description(html: &str) -> Option {\n capture_first(\n r#\"(?is)]+(?:name|property)\\s*=\\s*[\"'](?:description|og:description)[\"'][^>]+content\\s*=\\s*[\"'](.*?)[\"'][^>]*>\"#,\n html,\n )\n .or_else(|| {\n capture_first(\n r#\"(?is)]+content\\s*=\\s*[\"'](.*?)[\"'][^>]+(?:name|property)\\s*=\\s*[\"'](?:description|og:description)[\"'][^>]*>\"#,\n html,\n )\n })\n}\n\nfn capture_first(pattern: &str, haystack: &str) -> Option {\n let regex = Regex::new(pattern).ok()?;\n let captures = regex.captures(haystack)?;\n captures\n .get(1)\n .map(|capture| capture.as_str().trim().to_string())\n}\n\nfn replace_all(pattern: &str, haystack: &str, replacement: &str) -> String {\n Regex::new(pattern)\n .map(|regex| regex.replace_all(haystack, replacement).into_owned())\n .unwrap_or_else(|_| haystack.to_string())\n}\n\nfn normalize_whitespace(input: &str) -> String {\n input\n .split_whitespace()\n .filter(|segment| !segment.is_empty())\n .collect::>()\n .join(\" \")\n}\n\nfn truncate_excerpt(input: &str) -> String {\n let normalized = normalize_whitespace(input);\n if normalized.chars().count() <= DEFAULT_EXCERPT_CHARS {\n return normalized;\n }\n let truncated: String = normalized.chars().take(DEFAULT_EXCERPT_CHARS).collect();\n format!(\"{}...\", truncated.trim_end())\n}\n\nfn extract_markdown_frontmatter(markdown: &str) -> (Option, String) {\n let mut lines = markdown.lines();\n let Some(first) = lines.next() else {\n return (None, markdown.to_string());\n };\n if first.trim() != \"---\" {\n return (None, markdown.to_string());\n }\n\n let mut frontmatter = Vec::new();\n let mut remainder = Vec::new();\n let mut found_closing = false;\n for line in lines {\n if !found_closing && line.trim() == \"---\" {\n found_closing = true;\n continue;\n }\n if found_closing {\n remainder.push(line);\n } else {\n frontmatter.push(line);\n }\n }\n\n if !found_closing {\n return (None, markdown.to_string());\n }\n\n (Some(frontmatter.join(\"\\n\")), remainder.join(\"\\n\"))\n}\n\nfn capture_frontmatter_value(frontmatter: &str, key: &str) -> Option {\n let pattern = format!(r\"(?mi)^\\s*{}\\s*:\\s*(.+?)\\s*$\", regex::escape(key));\n let value = capture_first(&pattern, frontmatter)?;\n let value = value.trim().trim_matches('\"').trim_matches('\\'');\n (!value.is_empty()).then(|| value.to_string())\n}\n\nfn looks_like_js_app_shell(final_url: &str, html: &str, metadata: &TextMetadata) -> bool {\n let title = metadata.title.as_deref().unwrap_or_default();\n let excerpt = metadata.excerpt.as_deref().unwrap_or_default();\n (final_url.contains(\"linear.app/\") && title == \"Linear\")\n || metadata.description.is_none()\n && (excerpt.contains(\"performance.mark(\\\"appStart\\\")\")\n || excerpt.contains(\"--bg-sidebar-light\")\n || excerpt.contains(\"--bg-base-color-dark\")\n || html.contains(\"performance.mark(\\\"appStart\\\")\")\n || html.contains(\"--bg-sidebar-light\"))\n}\n\nfn header_value(value: Option<&reqwest::header::HeaderValue>) -> Option {\n value\n .and_then(|header| header.to_str().ok())\n .map(|value| value.to_string())\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n use mockito::Server;\n\n #[test]\n fn markdown_metadata_prefers_first_heading_and_excerpt() {\n let metadata = markdown_metadata(\n \"# Example Title\\n\\nFirst paragraph with useful context.\\n\\nSecond paragraph.\",\n );\n assert_eq!(metadata.title.as_deref(), Some(\"Example Title\"));\n assert_eq!(\n metadata.description.as_deref(),\n Some(\"First paragraph with useful context.\")\n );\n assert!(\n metadata\n .excerpt\n .as_deref()\n .unwrap_or_default()\n .contains(\"First paragraph with useful context.\")\n );\n }\n\n #[test]\n fn markdown_metadata_reads_frontmatter_title_and_description() {\n let metadata = markdown_metadata(\n \"---\\n\\\ntitle: Crawl entire websites with a single API call using Browser Rendering\\n\\\ndescription: Browser Rendering's new /crawl endpoint crawls and renders a site.\\n\\\n---\\n\\n# Ignored Heading\\n\\nBody paragraph.\",\n );\n assert_eq!(\n metadata.title.as_deref(),\n Some(\"Crawl entire websites with a single API call using Browser Rendering\")\n );\n assert_eq!(\n metadata.description.as_deref(),\n Some(\"Browser Rendering's new /crawl endpoint crawls and renders a site.\")\n );\n assert!(\n metadata\n .excerpt\n .as_deref()\n .unwrap_or_default()\n .contains(\"Body paragraph.\")\n );\n }\n\n #[test]\n fn direct_fetch_extracts_html_metadata() {\n let mut server = Server::new();\n let _mock = server\n .mock(\"GET\", \"/page\")\n .with_status(200)\n .with_header(\"content-type\", \"text/html; charset=utf-8\")\n .with_body(\n r#\"\n \n \n Flow URL Inspect\n \n \n \n
Useful body text for the excerpt.
\n \n \n \"#,\n )\n .create();\n\n let result = inspect_via_direct_fetch(\n &format!(\"{}/page\", server.url()),\n Duration::from_secs(5),\n false,\n )\n .expect(\"direct fetch should succeed\");\n assert_eq!(result.title.as_deref(), Some(\"Flow URL Inspect\"));\n assert_eq!(\n result.description.as_deref(),\n Some(\"Thin summaries for AI sessions.\")\n );\n assert!(\n result\n .excerpt\n .as_deref()\n .unwrap_or_default()\n .contains(\"Useful body text\")\n );\n }\n\n #[test]\n fn html_metadata_detects_linear_app_shell() {\n let metadata = html_metadata(\n r#\"\n \n Linear\n \n \n \n \n \n \"#,\n \"https://linear.app/fl2024008/project/example/overview\",\n );\n assert_eq!(metadata.title.as_deref(), Some(\"Linear (app shell)\"));\n assert!(\n metadata\n .description\n .as_deref()\n .unwrap_or_default()\n .contains(\"JavaScript-heavy app shell\")\n );\n assert!(metadata.excerpt.is_none());\n }\n\n #[test]\n fn cloudflare_markdown_normalizes_result() {\n let mut server = Server::new();\n let _mock = server\n .mock(\"POST\", \"/accounts/test-account/browser-rendering/markdown\")\n .match_query(mockito::Matcher::UrlEncoded(\"cacheTTL\".into(), \"7200\".into()))\n .with_status(200)\n .with_header(\"content-type\", \"application/json\")\n .with_body(\n \"{\\n \\\"success\\\": true,\\n \\\"result\\\": \\\"# Cloudflare Page\\\\n\\\\nRendered into markdown.\\\"\\n}\",\n )\n .create();\n\n let result = inspect_via_cloudflare_markdown(\n \"https://example.com/docs\",\n Duration::from_secs(5),\n \"test-account\",\n \"secret-token\",\n Some(2.0),\n &server.url(),\n false,\n )\n .expect(\"cloudflare markdown should succeed\");\n\n assert_eq!(result.provider, \"cloudflare-markdown\");\n assert_eq!(result.title.as_deref(), Some(\"Cloudflare Page\"));\n assert_eq!(\n result.description.as_deref(),\n Some(\"Rendered into markdown.\")\n );\n }\n\n #[test]\n fn markdown_metadata_skips_changelog_boilerplate() {\n let metadata = markdown_metadata(concat!(\n \"[Skip to content](#_top)\\n\",\n \"Search\\n\",\n \"[Docs Directory](https://example.com/directory)[APIs](https://example.com/api)Help\\n\",\n \"# Changelog\\n\",\n \"New updates and improvements at Cloudflare.\\n\",\n \"[ Subscribe to RSS ](https://example.com/rss)\\n\",\n \"![hero image](https://example.com/hero.svg)\\n\",\n \"[ ← Back to all posts ](https://example.com)\\n\",\n \"## Crawl entire websites with a single API call using Browser Rendering\\n\\n\",\n \"Mar 10, 2026\\n\",\n \"[ Browser Rendering ](https://example.com/browser-rendering)\\n\",\n \"_Edit: this post has been edited to clarify crawling behavior._\\n\\n\",\n \"Browser Rendering's new /crawl endpoint lets you submit a starting URL and automatically discover content.\\n\",\n ));\n\n assert_eq!(\n metadata.title.as_deref(),\n Some(\"Crawl entire websites with a single API call using Browser Rendering\")\n );\n assert_eq!(\n metadata.description.as_deref(),\n Some(\n \"Browser Rendering's new /crawl endpoint lets you submit a starting URL and automatically discover content.\"\n )\n );\n }\n\n #[test]\n fn parse_cloudflare_crawl_result_extracts_records() {\n let payload = json!({\n \"id\": \"crawl-job-123\",\n \"status\": \"completed\",\n \"url\": \"https://developers.cloudflare.com/browser-rendering/\",\n \"total\": 3,\n \"finished\": 3,\n \"browserSecondsUsed\": 0.72,\n \"render\": false,\n \"source\": \"all\",\n \"records\": [\n {\n \"url\": \"https://developers.cloudflare.com/browser-rendering/rest-api/crawl-endpoint/\",\n \"status\": \"completed\",\n \"markdown\": \"# Crawl endpoint\\n\\nCloudflare can crawl and return markdown.\",\n \"metadata\": {\n \"title\": \"Crawl endpoint\",\n \"status\": 200\n }\n }\n ]\n });\n\n let result =\n parse_cloudflare_crawl_result(&payload, false).expect(\"crawl result should parse\");\n assert_eq!(result.provider, \"cloudflare-crawl\");\n assert_eq!(result.job_id, \"crawl-job-123\");\n assert_eq!(result.status, \"completed\");\n assert_eq!(result.total, Some(3));\n assert_eq!(result.finished, Some(3));\n assert_eq!(result.records.len(), 1);\n assert_eq!(result.records[0].title.as_deref(), Some(\"Crawl endpoint\"));\n assert_eq!(result.records[0].status_code, Some(200));\n assert_eq!(\n result.records[0].excerpt.as_deref(),\n Some(\"Cloudflare can crawl and return markdown.\")\n );\n assert!(result.records[0].markdown.is_none());\n }\n}\n" }, { "path": "src/usage.rs", "content": "use std::collections::{BTreeSet, HashSet};\nuse std::fs::{self, OpenOptions};\nuse std::io::{self, BufRead, BufReader, IsTerminal, Write};\nuse std::path::{Path, PathBuf};\nuse std::sync::atomic::{AtomicBool, Ordering};\nuse std::time::{Duration, SystemTime, UNIX_EPOCH};\n\nuse anyhow::{Context, Result};\nuse hmac::{Hmac, Mac};\nuse serde::{Deserialize, Serialize};\nuse serde_json::{Value, json};\nuse sha2::Sha256;\nuse uuid::Uuid;\n\nuse crate::config;\nuse crate::http_client;\n\nconst DEFAULT_ANALYTICS_ENDPOINT: &str = \"https://api.myflow.sh/api/telemetry/flow\";\nconst QUEUE_FILE_NAME: &str = \"usage-queue.jsonl\";\nconst STATE_FILE_NAME: &str = \"analytics.toml\";\nconst MAX_QUEUE_BYTES: usize = 10 * 1024 * 1024;\nconst MAX_BATCH_SIZE: usize = 100;\nconst ANON_ROTATION_DAYS: u64 = 30;\n\nstatic FLUSH_IN_PROGRESS: AtomicBool = AtomicBool::new(false);\n\ntype HmacSha256 = Hmac;\n\n#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]\n#[serde(rename_all = \"lowercase\")]\npub enum AnalyticsConsent {\n Unknown,\n Enabled,\n Disabled,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct AnalyticsState {\n pub consent: AnalyticsConsent,\n pub install_id: String,\n pub local_secret: String,\n pub prompted_at_ms: Option,\n pub updated_at_ms: u64,\n}\n\nimpl AnalyticsState {\n fn new_unknown() -> Self {\n Self {\n consent: AnalyticsConsent::Unknown,\n install_id: Uuid::new_v4().to_string(),\n local_secret: Uuid::new_v4().to_string(),\n prompted_at_ms: None,\n updated_at_ms: now_ms(),\n }\n }\n}\n\n#[derive(Debug, Clone)]\npub struct AnalyticsRuntimeConfig {\n pub enabled: Option,\n pub endpoint: String,\n pub sample_rate: f32,\n}\n\n#[derive(Debug, Clone)]\npub struct CommandCapture {\n pub at_ms: u64,\n pub command_path: String,\n pub flags_used: Vec,\n pub interactive: bool,\n pub ci: bool,\n pub flow_version: String,\n pub os: String,\n pub arch: String,\n}\n\n#[derive(Debug, Clone)]\npub struct AnalyticsStatus {\n pub consent: AnalyticsConsent,\n pub effective_enabled: bool,\n pub install_id: String,\n pub endpoint: String,\n pub queue_path: PathBuf,\n pub queued_events: usize,\n}\n\n#[derive(Debug, Deserialize, Default)]\nstruct AnalyticsConfigProbe {\n #[serde(default)]\n analytics: Option,\n #[serde(default, rename = \"commands\")]\n command_files: Vec,\n}\n\npub fn command_capture(raw_args: &[String]) -> CommandCapture {\n CommandCapture {\n at_ms: now_ms(),\n command_path: command_path(raw_args),\n flags_used: extract_flags(raw_args),\n interactive: io::stdin().is_terminal() && io::stdout().is_terminal(),\n ci: env_flag(\"CI\"),\n flow_version: env!(\"CARGO_PKG_VERSION\").to_string(),\n os: std::env::consts::OS.to_string(),\n arch: std::env::consts::ARCH.to_string(),\n }\n}\n\npub fn is_analytics_command(raw_args: &[String]) -> bool {\n if let Some(command) = raw_args.iter().skip(1).find(|arg| !arg.starts_with('-')) {\n return command == \"analytics\";\n }\n command_path(raw_args).starts_with(\"analytics\")\n}\n\npub fn maybe_prompt_for_opt_in(is_analytics_command: bool, succeeded: bool) {\n if !succeeded || is_analytics_command {\n return;\n }\n if env_flag(\"FLOW_ANALYTICS_DISABLE\") || env_flag(\"FLOW_ANALYTICS_FORCE\") {\n return;\n }\n if !io::stdin().is_terminal() || !io::stdout().is_terminal() {\n return;\n }\n\n let mut state = match load_or_init_state() {\n Ok(state) => state,\n Err(_) => return,\n };\n\n if state.consent != AnalyticsConsent::Unknown || state.prompted_at_ms.is_some() {\n return;\n }\n\n print!(\"Enable anonymous usage tracking to improve Flow? [y/N/later]: \");\n let _ = io::stdout().flush();\n let mut input = String::new();\n if io::stdin().read_line(&mut input).is_err() {\n return;\n }\n let answer = input.trim().to_ascii_lowercase();\n match answer.as_str() {\n \"y\" | \"yes\" => {\n state.consent = AnalyticsConsent::Enabled;\n state.prompted_at_ms = Some(now_ms());\n state.updated_at_ms = now_ms();\n let _ = save_state(&state);\n println!(\"Anonymous usage tracking enabled.\");\n }\n \"later\" => {\n state.prompted_at_ms = Some(now_ms());\n state.updated_at_ms = now_ms();\n let _ = save_state(&state);\n println!(\"You can enable later with: f analytics enable\");\n }\n _ => {\n state.consent = AnalyticsConsent::Disabled;\n state.prompted_at_ms = Some(now_ms());\n state.updated_at_ms = now_ms();\n let _ = save_state(&state);\n println!(\"Anonymous usage tracking disabled.\");\n }\n }\n}\n\npub fn record_command_result(capture: &CommandCapture, duration: Duration, result: &Result<()>) {\n let runtime_cfg = runtime_config();\n let mut state = match load_or_init_state() {\n Ok(state) => state,\n Err(_) => return,\n };\n\n if !should_capture(&state, &runtime_cfg) {\n return;\n }\n\n if state.install_id.is_empty() {\n state.install_id = Uuid::new_v4().to_string();\n let _ = save_state(&state);\n }\n\n let event = json!({\n \"type\": \"flow.command.v1\",\n \"schema_version\": 1,\n \"event_id\": Uuid::new_v4().to_string(),\n \"name\": capture.command_path,\n \"ok\": result.is_ok(),\n \"at\": capture.at_ms,\n \"source\": \"flow-cli\",\n \"payload\": {\n \"anon_user_id\": rotating_anon_user_id(&state, capture.at_ms),\n \"command_path\": capture.command_path,\n \"success\": result.is_ok(),\n \"exit_code\": Option::::None,\n \"duration_ms\": duration.as_millis().min(u64::MAX as u128) as u64,\n \"flags_used\": capture.flags_used,\n \"flow_version\": capture.flow_version,\n \"os\": capture.os,\n \"arch\": capture.arch,\n \"interactive\": capture.interactive,\n \"ci\": capture.ci,\n \"project_fingerprint\": project_fingerprint(&state.local_secret, capture.at_ms),\n }\n });\n\n if append_event_to_queue(&event).is_err() {\n return;\n }\n spawn_flush_worker(runtime_cfg.endpoint);\n}\n\npub fn status() -> Result {\n let state = load_or_init_state()?;\n let runtime_cfg = runtime_config();\n let queue_path = queue_path();\n let queued_events = count_queue_lines()?;\n Ok(AnalyticsStatus {\n consent: state.consent,\n effective_enabled: should_capture(&state, &runtime_cfg),\n install_id: state.install_id,\n endpoint: runtime_cfg.endpoint,\n queue_path,\n queued_events,\n })\n}\n\npub fn set_consent(consent: AnalyticsConsent) -> Result<()> {\n let mut state = load_or_init_state()?;\n state.consent = consent;\n state.updated_at_ms = now_ms();\n if state.prompted_at_ms.is_none() {\n state.prompted_at_ms = Some(now_ms());\n }\n save_state(&state)\n}\n\npub fn export_queue() -> Result {\n let path = queue_path();\n if !path.exists() {\n return Ok(String::new());\n }\n fs::read_to_string(&path).with_context(|| format!(\"failed to read {}\", path.display()))\n}\n\npub fn purge_queue() -> Result<()> {\n let path = queue_path();\n if path.exists() {\n fs::remove_file(&path).with_context(|| format!(\"failed to remove {}\", path.display()))?;\n }\n Ok(())\n}\n\nfn command_path(raw_args: &[String]) -> String {\n let known_commands: HashSet<&'static str> = HashSet::from([\n \"search\",\n \"global\",\n \"hub\",\n \"init\",\n \"shell-init\",\n \"shell\",\n \"new\",\n \"home\",\n \"archive\",\n \"doctor\",\n \"health\",\n \"tasks\",\n \"run\",\n \"last-cmd\",\n \"last-cmd-full\",\n \"fish-last\",\n \"fish-last-full\",\n \"fish-install\",\n \"rerun\",\n \"ps\",\n \"kill\",\n \"logs\",\n \"trace\",\n \"projects\",\n \"sessions\",\n \"active\",\n \"server\",\n \"web\",\n \"match\",\n \"ask\",\n \"commit\",\n \"commit-queue\",\n \"pr\",\n \"gitignore\",\n \"review\",\n \"commitSimple\",\n \"commitWithCheck\",\n \"undo\",\n \"fix\",\n \"fixup\",\n \"changes\",\n \"diff\",\n \"hash\",\n \"daemon\",\n \"supervisor\",\n \"ai\",\n \"codex\",\n \"claude\",\n \"env\",\n \"otp\",\n \"auth\",\n \"services\",\n \"push\",\n \"ssh\",\n \"macos\",\n \"todo\",\n \"ext\",\n \"deps\",\n \"skills\",\n \"db\",\n \"tools\",\n \"notify\",\n \"commits\",\n \"setup\",\n \"agents\",\n \"hive\",\n \"sync\",\n \"checkout\",\n \"switch\",\n \"info\",\n \"upstream\",\n \"deploy\",\n \"prod\",\n \"publish\",\n \"clone\",\n \"repos\",\n \"code\",\n \"migrate\",\n \"parallel\",\n \"docs\",\n \"upgrade\",\n \"latest\",\n \"release\",\n \"install\",\n \"registry\",\n \"proxy\",\n \"analytics\",\n ]);\n\n let mut parts = Vec::new();\n for arg in raw_args.iter().skip(1) {\n if arg == \"--\" {\n break;\n }\n if arg.starts_with('-') {\n continue;\n }\n parts.push(arg.as_str());\n }\n\n if parts.is_empty() {\n return \"palette\".to_string();\n }\n\n let first = parts[0];\n if !known_commands.contains(first) {\n return \"task-shortcut\".to_string();\n }\n\n let command_with_actions: HashSet<&'static str> = HashSet::from([\n \"skills\",\n \"analytics\",\n \"ai\",\n \"trace\",\n \"proxy\",\n \"daemon\",\n \"env\",\n \"services\",\n \"todo\",\n \"ext\",\n \"deps\",\n \"tools\",\n \"agents\",\n \"hive\",\n \"sync\",\n \"release\",\n \"install\",\n \"registry\",\n ]);\n\n if command_with_actions.contains(first) && parts.len() > 1 {\n let second = parts[1];\n if second != \"force\" && second != \"review\" && !second.starts_with('-') {\n return format!(\"{}.{}\", first, second);\n }\n }\n\n first.to_string()\n}\n\nfn extract_flags(raw_args: &[String]) -> Vec {\n let mut set = BTreeSet::new();\n for arg in raw_args.iter().skip(1) {\n if arg == \"--\" {\n break;\n }\n if let Some(rest) = arg.strip_prefix(\"--\") {\n if rest.is_empty() {\n continue;\n }\n let name = rest.split('=').next().unwrap_or_default().trim();\n if !name.is_empty() {\n set.insert(name.to_string());\n }\n continue;\n }\n if let Some(rest) = arg.strip_prefix('-') {\n if rest.is_empty() || rest.starts_with('-') {\n continue;\n }\n for ch in rest.chars() {\n if ch.is_ascii_alphanumeric() {\n set.insert(ch.to_string());\n }\n }\n }\n }\n set.into_iter().collect()\n}\n\nfn rotating_anon_user_id(state: &AnalyticsState, at_ms: u64) -> Option {\n if state.local_secret.is_empty() || state.install_id.is_empty() {\n return None;\n }\n let mut mac = HmacSha256::new_from_slice(state.local_secret.as_bytes()).ok()?;\n mac.update(state.install_id.as_bytes());\n mac.update(b\":\");\n mac.update(rotation_bucket(at_ms).to_string().as_bytes());\n let bytes = mac.finalize().into_bytes();\n let full = hex::encode(bytes);\n Some(full.chars().take(24).collect())\n}\n\nfn project_fingerprint(secret: &str, at_ms: u64) -> Option {\n if secret.is_empty() {\n return None;\n }\n let cwd = std::env::current_dir().ok()?;\n let canonical = cwd.canonicalize().unwrap_or(cwd);\n let mut mac = HmacSha256::new_from_slice(secret.as_bytes()).ok()?;\n mac.update(canonical.to_string_lossy().as_bytes());\n mac.update(b\":\");\n mac.update(rotation_bucket(at_ms).to_string().as_bytes());\n let bytes = mac.finalize().into_bytes();\n let full = hex::encode(bytes);\n Some(full.chars().take(16).collect())\n}\n\nfn rotation_bucket(at_ms: u64) -> u64 {\n let window = ANON_ROTATION_DAYS\n .saturating_mul(24)\n .saturating_mul(60)\n .saturating_mul(60)\n .saturating_mul(1000);\n if window == 0 {\n return 0;\n }\n at_ms / window\n}\n\nfn should_capture(state: &AnalyticsState, runtime: &AnalyticsRuntimeConfig) -> bool {\n if env_flag(\"FLOW_ANALYTICS_DISABLE\") {\n return false;\n }\n if env_flag(\"FLOW_ANALYTICS_FORCE\") {\n return true;\n }\n if let Some(enabled) = runtime.enabled {\n return enabled;\n }\n state.consent == AnalyticsConsent::Enabled\n}\n\nfn runtime_config() -> AnalyticsRuntimeConfig {\n let mut enabled = None;\n let mut endpoint = DEFAULT_ANALYTICS_ENDPOINT.to_string();\n let mut sample_rate = 1.0f32;\n\n if let Some(cfg) = load_project_analytics_config() {\n enabled = cfg.enabled;\n if let Some(v) = cfg.endpoint {\n if !v.trim().is_empty() {\n endpoint = v.trim().to_string();\n }\n }\n if let Some(v) = cfg.sample_rate {\n sample_rate = v.clamp(0.0, 1.0);\n }\n }\n\n if sample_rate < 1.0 {\n let random = (now_ms() % 10_000) as f32 / 10_000.0;\n if random > sample_rate {\n enabled = Some(false);\n }\n }\n\n AnalyticsRuntimeConfig {\n enabled,\n endpoint,\n sample_rate,\n }\n}\n\nfn load_project_analytics_config() -> Option {\n let cwd = std::env::current_dir().ok()?;\n if let Some(candidate) = crate::project_snapshot::find_flow_toml_upwards(&cwd) {\n if let Some(analytics) = load_minimal_analytics_config(&candidate, &mut Vec::new()) {\n return Some(analytics);\n }\n let cfg = config::load_or_default(&candidate);\n return cfg.analytics;\n }\n\n let global = config::default_config_path();\n if global.exists() {\n if let Some(analytics) = load_minimal_analytics_config(&global, &mut Vec::new()) {\n return Some(analytics);\n }\n return config::load_or_default(global).analytics;\n }\n\n None\n}\n\nfn load_minimal_analytics_config(\n path: &Path,\n visited: &mut Vec,\n) -> Option {\n let canonical = path.canonicalize().ok()?;\n if visited.contains(&canonical) {\n return None;\n }\n visited.push(canonical.clone());\n\n let contents = fs::read_to_string(&canonical).ok()?;\n let parsed: AnalyticsConfigProbe = toml::from_str(&contents).ok()?;\n if let Some(analytics) = parsed.analytics {\n visited.pop();\n return Some(analytics);\n }\n\n for include in parsed.command_files {\n let include_path = config::resolve_include_path(&canonical, &include.path);\n if let Some(analytics) = load_minimal_analytics_config(&include_path, visited) {\n visited.pop();\n return Some(analytics);\n }\n }\n\n visited.pop();\n None\n}\n\nfn load_or_init_state() -> Result {\n let path = state_path();\n if path.exists() {\n let contents = fs::read_to_string(&path)\n .with_context(|| format!(\"failed to read {}\", path.display()))?;\n let mut state: AnalyticsState = toml::from_str(&contents)\n .with_context(|| format!(\"failed to parse {}\", path.display()))?;\n if state.install_id.trim().is_empty() {\n state.install_id = Uuid::new_v4().to_string();\n state.updated_at_ms = now_ms();\n save_state(&state)?;\n }\n if state.local_secret.trim().is_empty() {\n state.local_secret = Uuid::new_v4().to_string();\n state.updated_at_ms = now_ms();\n save_state(&state)?;\n }\n return Ok(state);\n }\n\n let state = AnalyticsState::new_unknown();\n save_state(&state)?;\n Ok(state)\n}\n\nfn save_state(state: &AnalyticsState) -> Result<()> {\n let path = state_path();\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n let payload = toml::to_string_pretty(state).context(\"failed to encode analytics state\")?;\n fs::write(&path, payload).with_context(|| format!(\"failed to write {}\", path.display()))\n}\n\nfn state_path() -> PathBuf {\n config::global_config_dir().join(STATE_FILE_NAME)\n}\n\nfn queue_path() -> PathBuf {\n config::global_state_dir().join(QUEUE_FILE_NAME)\n}\n\nfn append_event_to_queue(event: &Value) -> Result<()> {\n let path = queue_path();\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)\n .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n }\n\n let mut file = OpenOptions::new()\n .create(true)\n .append(true)\n .open(&path)\n .with_context(|| format!(\"failed to open {}\", path.display()))?;\n let line = serde_json::to_string(event).context(\"failed to encode analytics event\")?;\n writeln!(file, \"{line}\").with_context(|| format!(\"failed to append {}\", path.display()))?;\n enforce_queue_limit(&path)?;\n Ok(())\n}\n\nfn enforce_queue_limit(path: &PathBuf) -> Result<()> {\n let metadata =\n fs::metadata(path).with_context(|| format!(\"failed to stat {}\", path.display()))?;\n if metadata.len() as usize <= MAX_QUEUE_BYTES {\n return Ok(());\n }\n\n let lines = read_queue_lines()?;\n if lines.is_empty() {\n return Ok(());\n }\n let keep = lines.len().saturating_sub(lines.len() / 4).max(1);\n let trimmed: String = lines\n .into_iter()\n .rev()\n .take(keep)\n .collect::>()\n .into_iter()\n .rev()\n .map(|line| format!(\"{line}\\n\"))\n .collect();\n fs::write(path, trimmed).with_context(|| format!(\"failed to trim {}\", path.display()))\n}\n\nfn spawn_flush_worker(endpoint: String) {\n if FLUSH_IN_PROGRESS\n .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)\n .is_err()\n {\n return;\n }\n\n std::thread::spawn(move || {\n let _ = flush_queue(&endpoint);\n FLUSH_IN_PROGRESS.store(false, Ordering::SeqCst);\n });\n}\n\nfn flush_queue(endpoint: &str) -> Result<()> {\n let path = queue_path();\n if !path.exists() {\n return Ok(());\n }\n\n let lines = read_queue_lines()?;\n if lines.is_empty() {\n return Ok(());\n }\n\n let client = http_client::blocking_with_timeout(Duration::from_millis(500))\n .context(\"failed to build analytics HTTP client\")?;\n\n let mut sent = 0usize;\n for line in lines.iter().take(MAX_BATCH_SIZE) {\n let value: Value = match serde_json::from_str(line) {\n Ok(v) => v,\n Err(_) => {\n sent += 1;\n continue;\n }\n };\n let response = client\n .post(endpoint)\n .header(\"content-type\", \"application/json\")\n .json(&value)\n .send();\n match response {\n Ok(resp) if resp.status().is_success() => {\n sent += 1;\n }\n _ => break,\n }\n }\n\n if sent == 0 {\n return Ok(());\n }\n\n let remaining: String = lines\n .into_iter()\n .skip(sent)\n .map(|line| format!(\"{line}\\n\"))\n .collect();\n fs::write(&path, remaining).with_context(|| format!(\"failed to rewrite {}\", path.display()))\n}\n\nfn read_queue_lines() -> Result> {\n let path = queue_path();\n if !path.exists() {\n return Ok(Vec::new());\n }\n let file =\n std::fs::File::open(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let reader = BufReader::new(file);\n let mut lines = Vec::new();\n for line in reader.lines() {\n let line = line.with_context(|| format!(\"failed to read {}\", path.display()))?;\n if !line.trim().is_empty() {\n lines.push(line);\n }\n }\n Ok(lines)\n}\n\nfn count_queue_lines() -> Result {\n let path = queue_path();\n if !path.exists() {\n return Ok(0);\n }\n let file =\n std::fs::File::open(&path).with_context(|| format!(\"failed to read {}\", path.display()))?;\n let reader = BufReader::new(file);\n let mut count = 0usize;\n for line in reader.lines() {\n let line = line.with_context(|| format!(\"failed to read {}\", path.display()))?;\n if !line.trim().is_empty() {\n count += 1;\n }\n }\n Ok(count)\n}\n\nfn env_flag(name: &str) -> bool {\n std::env::var(name)\n .ok()\n .map(|value| {\n matches!(\n value.trim().to_ascii_lowercase().as_str(),\n \"1\" | \"true\" | \"yes\" | \"on\"\n )\n })\n .unwrap_or(false)\n}\n\nfn now_ms() -> u64 {\n SystemTime::now()\n .duration_since(UNIX_EPOCH)\n .map(|duration| duration.as_millis().min(u64::MAX as u128) as u64)\n .unwrap_or(0)\n}\n\n#[cfg(test)]\nmod tests {\n use std::fs;\n\n use tempfile::tempdir;\n\n use super::*;\n\n #[test]\n fn extracts_flags_without_values() {\n let args = vec![\n \"f\".to_string(),\n \"commit\".to_string(),\n \"--sync\".to_string(),\n \"-nt\".to_string(),\n \"--message=hello\".to_string(),\n \"arg\".to_string(),\n ];\n let flags = extract_flags(&args);\n assert!(flags.contains(&\"sync\".to_string()));\n assert!(flags.contains(&\"n\".to_string()));\n assert!(flags.contains(&\"t\".to_string()));\n assert!(flags.contains(&\"message\".to_string()));\n assert!(!flags.contains(&\"hello\".to_string()));\n }\n\n #[test]\n fn unknown_commands_map_to_task_shortcut() {\n let args = vec![\n \"f\".to_string(),\n \"dev\".to_string(),\n \"--port\".to_string(),\n \"3000\".to_string(),\n ];\n assert_eq!(command_path(&args), \"task-shortcut\");\n }\n\n #[test]\n fn rotating_anon_id_is_deterministic_within_bucket() {\n let state = AnalyticsState {\n consent: AnalyticsConsent::Enabled,\n install_id: \"install-123\".to_string(),\n local_secret: \"local-test-key\".to_string(), // flow:secret:ignore\n prompted_at_ms: None,\n updated_at_ms: 0,\n };\n let a = rotating_anon_user_id(&state, 1000).expect(\"anon id\");\n let b = rotating_anon_user_id(&state, 2000).expect(\"anon id\");\n assert_eq!(a, b);\n }\n\n #[test]\n fn rotating_anon_id_changes_after_rotation_window() {\n let state = AnalyticsState {\n consent: AnalyticsConsent::Enabled,\n install_id: \"install-123\".to_string(),\n local_secret: \"local-test-key\".to_string(), // flow:secret:ignore\n prompted_at_ms: None,\n updated_at_ms: 0,\n };\n let window = ANON_ROTATION_DAYS * 24 * 60 * 60 * 1000;\n let a = rotating_anon_user_id(&state, 1000).expect(\"anon id\");\n let b = rotating_anon_user_id(&state, 1000 + window).expect(\"anon id\");\n assert_ne!(a, b);\n }\n\n #[test]\n fn minimal_analytics_probe_follows_includes() {\n let dir = tempdir().expect(\"tempdir\");\n let root = dir.path().join(\"repo\");\n fs::create_dir_all(&root).expect(\"repo dir\");\n fs::write(\n root.join(\"flow.toml\"),\n r#\"\n[[commands]]\npath = \"commands.toml\"\n\"#,\n )\n .expect(\"write root flow\");\n fs::write(\n root.join(\"commands.toml\"),\n r#\"\n[analytics]\nenabled = true\nendpoint = \"https://example.test/telemetry\"\nsample_rate = 0.25\n\"#,\n )\n .expect(\"write commands flow\");\n\n let analytics = load_minimal_analytics_config(&root.join(\"flow.toml\"), &mut Vec::new())\n .expect(\"analytics\");\n assert_eq!(analytics.enabled, Some(true));\n assert_eq!(\n analytics.endpoint.as_deref(),\n Some(\"https://example.test/telemetry\")\n );\n assert_eq!(analytics.sample_rate, Some(0.25));\n }\n}\n" }, { "path": "src/vcs.rs", "content": "use std::path::{Path, PathBuf};\nuse std::process::Command;\n\nuse anyhow::{Context, Result, bail};\n\npub fn ensure_jj_installed() -> Result<()> {\n let status = Command::new(\"jj\")\n .arg(\"--version\")\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .status()\n .context(\"failed to run jj --version\")?;\n if !status.success() {\n bail!(\"jj is required but not available on PATH\");\n }\n Ok(())\n}\n\npub fn ensure_jj_repo() -> Result {\n let cwd = std::env::current_dir().context(\"failed to read current directory\")?;\n ensure_jj_repo_in(&cwd)\n}\n\npub fn ensure_jj_repo_in(path: &Path) -> Result {\n ensure_jj_installed()?;\n if let Ok(root) = try_jj_root(path) {\n return Ok(root);\n }\n\n let git_dir = path.join(\".git\");\n if git_dir.exists() {\n let status = Command::new(\"jj\")\n .current_dir(path)\n .args([\"git\", \"init\", \"--colocate\"])\n .stdout(std::process::Stdio::null())\n .stderr(std::process::Stdio::null())\n .status()\n .context(\"failed to run jj git init --colocate\")?;\n if status.success() {\n if let Ok(root) = try_jj_root(path) {\n return Ok(root);\n }\n }\n }\n\n bail!(\n \"This repo is not a jj workspace. Run `jj git init --colocate` in {} and retry.\",\n path.display()\n );\n}\n\npub fn jj_root_if_exists(path: &Path) -> Option {\n let output = Command::new(\"jj\")\n .current_dir(path)\n .arg(\"root\")\n .output()\n .ok()?;\n if !output.status.success() {\n return None;\n }\n let root = String::from_utf8_lossy(&output.stdout).trim().to_string();\n if root.is_empty() {\n None\n } else {\n Some(PathBuf::from(root))\n }\n}\n\nfn try_jj_root(path: &Path) -> Result {\n let output = Command::new(\"jj\")\n .current_dir(path)\n .arg(\"root\")\n .output()\n .context(\"failed to run jj root\")?;\n if !output.status.success() {\n bail!(\"jj root failed\");\n }\n Ok(PathBuf::from(\n String::from_utf8_lossy(&output.stdout).trim(),\n ))\n}\n" }, { "path": "src/watchers.rs", "content": "use std::{\n path::{Path, PathBuf},\n process::Command,\n sync::mpsc::{self, Receiver, Sender},\n thread,\n time::{Duration, Instant},\n};\n\nuse anyhow::{Context, Result};\nuse notify::RecursiveMode;\nuse notify_debouncer_mini::{DebouncedEvent, new_debouncer};\n\nuse crate::config::{WatcherConfig, WatcherDriver, expand_path};\n\npub struct WatchManager {\n handles: Vec,\n}\n\nimpl WatchManager {\n pub fn start(configs: &[WatcherConfig]) -> Result> {\n if configs.is_empty() {\n return Ok(None);\n }\n\n let mut handles = Vec::new();\n for cfg in configs.iter().cloned() {\n match WatcherHandle::spawn(cfg) {\n Ok(handle) => handles.push(handle),\n Err(err) => {\n tracing::error!(?err, \"failed to start watcher\");\n }\n }\n }\n\n if handles.is_empty() {\n Ok(None)\n } else {\n Ok(Some(Self { handles }))\n }\n }\n}\n\nimpl Drop for WatchManager {\n fn drop(&mut self) {\n self.handles.clear();\n }\n}\n\npub struct WatcherHandle {\n shutdown: Option>,\n join: Option>,\n}\n\nimpl WatcherHandle {\n fn spawn(cfg: WatcherConfig) -> Result {\n match cfg.driver {\n WatcherDriver::Shell => Self::spawn_shell(cfg),\n WatcherDriver::Poltergeist => Self::spawn_poltergeist(cfg),\n }\n }\n\n fn spawn_shell(cfg: WatcherConfig) -> Result {\n let (shutdown_tx, shutdown_rx) = mpsc::channel();\n let handle = thread::spawn(move || {\n if let Err(err) = run_shell_watcher(cfg, shutdown_rx) {\n tracing::error!(?err, \"watcher exited with error\");\n }\n });\n\n Ok(Self {\n shutdown: Some(shutdown_tx),\n join: Some(handle),\n })\n }\n\n fn spawn_poltergeist(cfg: WatcherConfig) -> Result {\n let (shutdown_tx, shutdown_rx) = mpsc::channel();\n let handle = thread::spawn(move || {\n if let Err(err) = run_poltergeist_watcher(cfg, shutdown_rx) {\n tracing::error!(?err, \"poltergeist watcher exited with error\");\n }\n });\n\n Ok(Self {\n shutdown: Some(shutdown_tx),\n join: Some(handle),\n })\n }\n}\n\nimpl Drop for WatcherHandle {\n fn drop(&mut self) {\n if let Some(tx) = self.shutdown.take() {\n let _ = tx.send(());\n }\n if let Some(handle) = self.join.take() {\n let _ = handle.join();\n }\n }\n}\n\nfn run_shell_watcher(cfg: WatcherConfig, shutdown: Receiver<()>) -> Result<()> {\n let watch_path = expand_path(&cfg.path);\n if !watch_path.exists() {\n anyhow::bail!(\n \"watch path {} does not exist (watcher {})\",\n watch_path.display(),\n cfg.name\n );\n }\n\n let workdir = if watch_path.is_dir() {\n watch_path.clone()\n } else {\n watch_path\n .parent()\n .map(Path::to_path_buf)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n };\n\n if cfg.run_on_start {\n run_command(&cfg, &workdir);\n }\n\n let debounce = Duration::from_millis(cfg.debounce_ms.max(50));\n let (event_tx, event_rx) = mpsc::channel();\n let mut debouncer =\n new_debouncer(debounce, event_tx).context(\"failed to initialize file watcher\")?;\n\n debouncer\n .watcher()\n .watch(&watch_path, RecursiveMode::Recursive)\n .with_context(|| format!(\"failed to watch path {}\", watch_path.display()))?;\n\n tracing::info!(\n name = cfg.name,\n path = %watch_path.display(),\n \"watcher started\"\n );\n\n loop {\n if shutdown.try_recv().is_ok() {\n break;\n }\n\n match event_rx.recv_timeout(Duration::from_millis(200)) {\n Ok(Ok(events)) => {\n if matches_filter(&events, cfg.filter.as_deref()) {\n run_command(&cfg, &workdir);\n }\n }\n Ok(Err(err)) => {\n tracing::warn!(?err, watcher = cfg.name, \"watcher error\");\n }\n Err(mpsc::RecvTimeoutError::Timeout) => {}\n Err(mpsc::RecvTimeoutError::Disconnected) => break,\n }\n }\n\n tracing::info!(name = cfg.name, \"watcher stopped\");\n Ok(())\n}\n\nfn matches_filter(events: &[DebouncedEvent], filter: Option<&str>) -> bool {\n match filter {\n None => true,\n Some(target) => events.iter().any(|event| {\n event\n .path\n .file_name()\n .and_then(|name| name.to_str())\n .map(|name| name == target || name.contains(target))\n .unwrap_or(false)\n }),\n }\n}\n\nfn run_poltergeist_watcher(cfg: WatcherConfig, shutdown: Receiver<()>) -> Result<()> {\n let watch_path = expand_path(&cfg.path);\n if !watch_path.exists() {\n anyhow::bail!(\n \"watch path {} does not exist (watcher {})\",\n watch_path.display(),\n cfg.name\n );\n }\n\n let workdir = if watch_path.is_dir() {\n watch_path.clone()\n } else {\n watch_path\n .parent()\n .map(Path::to_path_buf)\n .unwrap_or_else(|| PathBuf::from(\".\"))\n };\n\n let poltergeist = cfg.poltergeist.clone().unwrap_or_default();\n tracing::info!(\n name = cfg.name,\n path = %workdir.display(),\n mode = %poltergeist.mode.as_subcommand(),\n binary = %poltergeist.binary,\n \"starting poltergeist watcher\"\n );\n\n let mut command = Command::new(&poltergeist.binary);\n command.arg(poltergeist.mode.as_subcommand());\n if !poltergeist.args.is_empty() {\n command.args(&poltergeist.args);\n }\n command.current_dir(&workdir);\n command.envs(cfg.env.iter().map(|(k, v)| (k, v)));\n command.stdout(std::process::Stdio::inherit());\n command.stderr(std::process::Stdio::inherit());\n\n let mut child = command\n .spawn()\n .with_context(|| format!(\"failed to launch poltergeist for {}\", cfg.name))?;\n\n loop {\n if shutdown.try_recv().is_ok() {\n tracing::info!(name = cfg.name, \"stopping poltergeist watcher\");\n if let Err(err) = child.kill() {\n tracing::warn!(\n ?err,\n watcher = cfg.name,\n \"failed to kill poltergeist process\"\n );\n }\n let _ = child.wait();\n break;\n }\n\n match child.try_wait() {\n Ok(Some(status)) => {\n if status.success() {\n tracing::info!(name = cfg.name, ?status, \"poltergeist watcher exited\");\n } else {\n tracing::warn!(\n name = cfg.name,\n ?status,\n \"poltergeist watcher exited with error\"\n );\n }\n break;\n }\n Ok(None) => {\n thread::sleep(Duration::from_millis(500));\n }\n Err(err) => {\n tracing::error!(\n ?err,\n name = cfg.name,\n \"failed to query poltergeist watcher status\"\n );\n break;\n }\n }\n }\n\n Ok(())\n}\n\nfn run_command(cfg: &WatcherConfig, workdir: &Path) {\n let Some(command) = cfg\n .command\n .as_deref()\n .map(str::trim)\n .filter(|cmd| !cmd.is_empty())\n else {\n tracing::warn!(name = cfg.name, \"watcher missing command; skipping\");\n return;\n };\n\n tracing::info!(\n name = cfg.name,\n command = command,\n \"running watcher command\"\n );\n let start = Instant::now();\n let mut cmd = Command::new(\"/bin/sh\");\n cmd.arg(\"-c\").arg(command).current_dir(workdir);\n cmd.envs(cfg.env.iter().map(|(k, v)| (k, v)));\n cmd.stdout(std::process::Stdio::null());\n cmd.stderr(std::process::Stdio::piped());\n\n match cmd.spawn() {\n Ok(mut child) => {\n let _ = child.wait();\n tracing::info!(name = cfg.name, ?workdir, elapsed = ?start.elapsed(), \"watcher command finished\");\n }\n Err(err) => {\n tracing::error!(?err, name = cfg.name, \"failed to execute watcher command\");\n }\n }\n}\n" }, { "path": "src/web.rs", "content": "use std::fs;\nuse std::net::SocketAddr;\nuse std::path::{Path, PathBuf};\nuse std::time::SystemTime;\n\nuse anyhow::{Context, Result, bail};\nuse axum::{\n Router,\n extract::State,\n http::{StatusCode, Uri},\n response::{Html, IntoResponse, Json, Response},\n routing::get,\n};\nuse serde::Serialize;\nuse tokio::runtime::Runtime;\nuse which::which;\n\nuse crate::ai;\nuse crate::cli::WebOpts;\n\n#[derive(Clone)]\nstruct WebState {\n project_root: PathBuf,\n web_root: Option,\n fallback_index: Option,\n}\n\n#[derive(Serialize)]\nstruct ProjectsResponse {\n projects: Vec,\n}\n\n#[derive(Serialize)]\nstruct AiTreeResponse {\n entries: Vec,\n}\n\n#[derive(Serialize)]\nstruct SessionsResponse {\n sessions: Vec,\n}\n\n#[derive(Serialize)]\nstruct ProjectCard {\n name: String,\n path: String,\n path_url: String,\n summary: Option,\n openapi: Option,\n ai_entries: Vec,\n status: String,\n}\n\n#[derive(Serialize)]\nstruct OpenApiSpec {\n path: String,\n url: String,\n format: String,\n}\n\n#[derive(Serialize)]\nstruct AiEntry {\n path: String,\n kind: String,\n}\n\npub fn run(opts: WebOpts) -> Result<()> {\n let project_root = std::env::current_dir()?;\n ensure_web_ui(&project_root)?;\n build_web_ui(&project_root)?;\n let (web_root, fallback_index) = resolve_web_root(&project_root);\n\n let host = opts.host;\n let port = opts.port;\n let addr: SocketAddr = format!(\"{host}:{port}\")\n .parse()\n .context(\"invalid host:port\")?;\n\n let state = WebState {\n project_root: project_root.clone(),\n web_root,\n fallback_index,\n };\n\n let rt = Runtime::new().context(\"failed to create tokio runtime\")?;\n rt.block_on(async move {\n let app = Router::new()\n .route(\"/api/projects\", get(projects))\n .route(\"/api/ai\", get(ai_tree))\n .route(\"/api/sessions\", get(sessions))\n .route(\"/api/openapi\", get(openapi))\n .route(\"/\", get(index))\n .fallback(fallback)\n .with_state(state);\n\n let listener = tokio::net::TcpListener::bind(addr)\n .await\n .context(\"failed to bind web server\")?;\n\n let url = format!(\"http://{host}:{port}\");\n open_in_browser(&url)?;\n println!(\"Flow web running at {url}\");\n\n axum::serve(listener, app)\n .await\n .context(\"web server error\")?;\n\n Ok(())\n })\n}\n\nasync fn index(State(state): State) -> Result, (StatusCode, String)> {\n if let Some(html) = &state.fallback_index {\n return Ok(Html(html.clone()));\n }\n let web_root = state\n .web_root\n .as_ref()\n .ok_or((StatusCode::NOT_FOUND, \"missing web root\".to_string()))?;\n let index_path = web_root.join(\"index.html\");\n let html = fs::read_to_string(&index_path)\n .map_err(|err| (StatusCode::NOT_FOUND, format!(\"missing index.html: {err}\")))?;\n Ok(Html(html))\n}\n\nasync fn fallback(\n State(state): State,\n uri: Uri,\n) -> Result {\n let Some(web_root) = &state.web_root else {\n return index(State(state)).await.map(|html| html.into_response());\n };\n let path = uri.path().trim_start_matches('/');\n if Path::new(path)\n .components()\n .any(|component| matches!(component, std::path::Component::ParentDir))\n {\n return Err((StatusCode::NOT_FOUND, \"not found\".to_string()));\n }\n let file_path = web_root.join(path);\n if file_path.is_file() {\n let contents =\n fs::read(&file_path).map_err(|err| (StatusCode::NOT_FOUND, err.to_string()))?;\n let content_type = content_type_for_path(&file_path);\n return Ok((\n StatusCode::OK,\n [(axum::http::header::CONTENT_TYPE, content_type)],\n contents,\n )\n .into_response());\n }\n index(State(state)).await.map(|html| html.into_response())\n}\n\nasync fn projects(State(state): State) -> Result, StatusCode> {\n let project = build_project_card(&state.project_root);\n Ok(Json(ProjectsResponse {\n projects: vec![project],\n }))\n}\n\nasync fn ai_tree(State(state): State) -> Result, StatusCode> {\n let entries = list_ai_tree_entries(&state.project_root.join(\".ai\"));\n Ok(Json(AiTreeResponse { entries }))\n}\n\nasync fn sessions(State(state): State) -> Result, StatusCode> {\n let sessions = ai::get_sessions_for_web(&state.project_root)\n .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;\n Ok(Json(SessionsResponse { sessions }))\n}\n\nasync fn openapi(State(state): State) -> Result {\n let Some((path, format)) = find_openapi_spec(&state.project_root) else {\n return Err(StatusCode::NOT_FOUND);\n };\n let contents = fs::read(&path).map_err(|_| StatusCode::NOT_FOUND)?;\n let content_type = if format == \"json\" {\n \"application/json\"\n } else {\n \"application/yaml\"\n };\n Ok(([(axum::http::header::CONTENT_TYPE, content_type)], contents))\n}\n\nfn build_project_card(project_root: &Path) -> ProjectCard {\n let name = project_root\n .file_name()\n .and_then(|s| s.to_str())\n .unwrap_or(\"project\")\n .to_string();\n\n let summary = read_first_line(project_root.join(\"readme.md\"))\n .or_else(|| read_first_line(project_root.join(\"README.md\")));\n\n let openapi = find_openapi_spec(project_root).map(|(path, format)| {\n let rel = path.strip_prefix(project_root).unwrap_or(&path);\n OpenApiSpec {\n path: rel.to_string_lossy().to_string(),\n url: \"/api/openapi\".to_string(),\n format,\n }\n });\n\n let ai_entries = list_ai_top_entries(&project_root.join(\".ai\"));\n\n let has_openapi = openapi.is_some();\n\n ProjectCard {\n name,\n path: project_root.display().to_string(),\n path_url: format!(\"file://{}\", project_root.display()),\n summary,\n openapi,\n ai_entries,\n status: if has_openapi { \"OpenAPI\" } else { \"Ready\" }.to_string(),\n }\n}\n\nfn read_first_line(path: PathBuf) -> Option {\n let content = fs::read_to_string(path).ok()?;\n for line in content.lines() {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n continue;\n }\n return Some(trimmed.to_string());\n }\n None\n}\n\nfn find_openapi_spec(project_root: &Path) -> Option<(PathBuf, String)> {\n let candidates = [\n (project_root.join(\"openapi.json\"), \"json\"),\n (project_root.join(\"openapi.yaml\"), \"yaml\"),\n (project_root.join(\"openapi.yml\"), \"yaml\"),\n (project_root.join(\"spec/openapi.json\"), \"json\"),\n (project_root.join(\"spec/openapi.yaml\"), \"yaml\"),\n (project_root.join(\"spec/openapi.yml\"), \"yaml\"),\n (project_root.join(\"docs/openapi.json\"), \"json\"),\n (project_root.join(\"docs/openapi.yaml\"), \"yaml\"),\n (project_root.join(\"docs/openapi.yml\"), \"yaml\"),\n (project_root.join(\"openapi/openapi.json\"), \"json\"),\n (project_root.join(\"openapi/openapi.yaml\"), \"yaml\"),\n (project_root.join(\"openapi/openapi.yml\"), \"yaml\"),\n (project_root.join(\".ai/openapi.json\"), \"json\"),\n (project_root.join(\".ai/openapi.yaml\"), \"yaml\"),\n (project_root.join(\".ai/openapi.yml\"), \"yaml\"),\n ];\n\n candidates\n .into_iter()\n .find(|(path, _)| path.exists())\n .map(|(path, format)| (path, format.to_string()))\n}\n\nfn list_ai_top_entries(ai_root: &Path) -> Vec {\n let mut entries = Vec::new();\n let dir = match fs::read_dir(ai_root) {\n Ok(dir) => dir,\n Err(_) => return entries,\n };\n\n for entry in dir.flatten() {\n let path = entry.path();\n let name = match path.file_name().and_then(|s| s.to_str()) {\n Some(name) => name.to_string(),\n None => continue,\n };\n let kind = if path.is_dir() { \"dir\" } else { \"file\" };\n entries.push(AiEntry {\n path: name,\n kind: kind.to_string(),\n });\n }\n\n entries.sort_by(|a, b| a.path.cmp(&b.path));\n entries\n}\n\nfn list_ai_tree_entries(ai_root: &Path) -> Vec {\n let mut entries = Vec::new();\n if !ai_root.exists() {\n return entries;\n }\n\n let mut stack = vec![ai_root.to_path_buf()];\n while let Some(dir) = stack.pop() {\n let dir_entries = match fs::read_dir(&dir) {\n Ok(dir_entries) => dir_entries,\n Err(_) => continue,\n };\n\n for entry in dir_entries.flatten() {\n let path = entry.path();\n let rel = match path.strip_prefix(ai_root) {\n Ok(rel) if !rel.as_os_str().is_empty() => rel,\n _ => continue,\n };\n let metadata = match fs::symlink_metadata(&path) {\n Ok(metadata) => metadata,\n Err(_) => continue,\n };\n let file_type = metadata.file_type();\n let kind = if file_type.is_symlink() {\n \"symlink\"\n } else if file_type.is_dir() {\n \"dir\"\n } else {\n \"file\"\n };\n entries.push(AiEntry {\n path: rel.to_string_lossy().to_string(),\n kind: kind.to_string(),\n });\n\n if file_type.is_dir() && !file_type.is_symlink() {\n stack.push(path);\n }\n }\n }\n\n entries.sort_by(|a, b| a.path.cmp(&b.path));\n entries\n}\n\nfn content_type_for_path(path: &Path) -> &'static str {\n let ext = path\n .extension()\n .and_then(|ext| ext.to_str())\n .unwrap_or(\"\")\n .to_ascii_lowercase();\n match ext.as_str() {\n \"html\" => \"text/html; charset=utf-8\",\n \"css\" => \"text/css; charset=utf-8\",\n \"js\" | \"mjs\" => \"text/javascript; charset=utf-8\",\n \"json\" | \"map\" => \"application/json\",\n \"svg\" => \"image/svg+xml\",\n \"png\" => \"image/png\",\n \"jpg\" | \"jpeg\" => \"image/jpeg\",\n \"gif\" => \"image/gif\",\n \"ico\" => \"image/x-icon\",\n \"webp\" => \"image/webp\",\n \"wasm\" => \"application/wasm\",\n \"woff\" => \"font/woff\",\n \"woff2\" => \"font/woff2\",\n \"ttf\" => \"font/ttf\",\n _ => \"application/octet-stream\",\n }\n}\n\nfn build_web_ui(project_root: &Path) -> Result<()> {\n let web_root = project_root.join(\".ai\").join(\"web\");\n let package_json = web_root.join(\"package.json\");\n if !package_json.exists() {\n return Ok(());\n }\n\n if which(\"bun\").is_err() {\n bail!(\"bun is required to build .ai/web (install bun or remove .ai/web/package.json)\");\n }\n\n let node_modules = web_root.join(\"node_modules\");\n let install_stamp = node_modules.join(\".flow-web-install\");\n if needs_install(\n &node_modules,\n &package_json,\n &web_root.join(\"bun.lock\"),\n &install_stamp,\n )? {\n run_command(\"bun\", &[\"install\"], &web_root).context(\"bun install failed for .ai/web\")?;\n write_install_stamp(&install_stamp)?;\n }\n\n run_command(\"bun\", &[\"run\", \"build\"], &web_root).context(\"bun run build failed for .ai/web\")?;\n\n Ok(())\n}\n\nfn needs_install(\n node_modules: &Path,\n package_json: &Path,\n bun_lock: &Path,\n install_stamp: &Path,\n) -> Result {\n if !node_modules.exists() {\n return Ok(true);\n }\n if !install_stamp.exists() {\n return Ok(true);\n }\n if is_newer(package_json, install_stamp)? {\n return Ok(true);\n }\n if bun_lock.exists() && is_newer(bun_lock, install_stamp)? {\n return Ok(true);\n }\n Ok(false)\n}\n\nfn is_newer(path: &Path, stamp: &Path) -> Result {\n let path_time = file_modified(path)?;\n let stamp_time = file_modified(stamp)?;\n Ok(path_time > stamp_time)\n}\n\nfn file_modified(path: &Path) -> Result {\n let metadata = fs::metadata(path)?;\n Ok(metadata.modified()?)\n}\n\nfn write_install_stamp(path: &Path) -> Result<()> {\n if let Some(parent) = path.parent() {\n fs::create_dir_all(parent)?;\n }\n fs::write(path, b\"installed\")?;\n Ok(())\n}\n\nfn run_command(command: &str, args: &[&str], cwd: &Path) -> Result<()> {\n let status = std::process::Command::new(command)\n .args(args)\n .current_dir(cwd)\n .status()\n .with_context(|| format!(\"failed to spawn {}\", command))?;\n if status.success() {\n Ok(())\n } else {\n bail!(\"{} {:?} exited with {}\", command, args, status)\n }\n}\n\n#[cfg(target_os = \"macos\")]\nfn open_in_browser(url: &str) -> Result<()> {\n std::process::Command::new(\"open\").arg(url).status()?;\n Ok(())\n}\n\n#[cfg(target_os = \"linux\")]\nfn open_in_browser(url: &str) -> Result<()> {\n std::process::Command::new(\"xdg-open\").arg(url).status()?;\n Ok(())\n}\n\n#[cfg(not(any(target_os = \"macos\", target_os = \"linux\")))]\nfn open_in_browser(url: &str) -> Result<()> {\n println!(\"Open this URL in your browser: {url}\");\n Ok(())\n}\n\npub fn ensure_web_ui(project_root: &Path) -> Result<()> {\n let web_root = project_root.join(\".ai\").join(\"web\");\n if !web_root.exists() {\n fs::create_dir_all(&web_root)?;\n }\n let index_path = web_root.join(\"index.html\");\n let has_vite_source = web_root.join(\"package.json\").exists() && web_root.join(\"src\").exists();\n if !index_path.exists() && !has_vite_source {\n fs::write(&index_path, default_web_template())?;\n }\n Ok(())\n}\n\nfn resolve_web_root(project_root: &Path) -> (Option, Option) {\n let web_root = project_root.join(\".ai\").join(\"web\");\n let dist_root = web_root.join(\"dist\");\n let dist_index = dist_root.join(\"index.html\");\n if dist_index.exists() {\n return (Some(dist_root), None);\n }\n\n let has_vite_source = web_root.join(\"package.json\").exists() && web_root.join(\"src\").exists();\n if has_vite_source {\n return (None, Some(default_web_template().to_string()));\n }\n\n let root_index = web_root.join(\"index.html\");\n if root_index.exists() {\n return (Some(web_root), None);\n }\n\n (None, Some(default_web_template().to_string()))\n}\n\nfn default_web_template() -> &'static str {\n r#\"\n\n \n \n \n Flow Web\n \n \n \n
\n
\n

Flow Web UI not built

\n

\n Build your Vite app to .ai/web/dist and refresh.\n Example: vite build\n

\n

\n API endpoints are live at:\n /api/projects, /api/ai, /api/openapi\n

\n
\n
\n \n\n\"#\n}\n" }, { "path": "src/workflow.rs", "content": "use std::collections::{BTreeMap, HashMap, HashSet};\nuse std::fs;\nuse std::path::{Path, PathBuf};\nuse std::process::Command;\nuse std::sync::{Mutex, OnceLock};\nuse std::time::{Duration, Instant};\n\nuse anyhow::{Context, Result, anyhow, bail};\nuse chrono::{SecondsFormat, TimeZone, Utc};\nuse serde::{Deserialize, Serialize};\n\nuse crate::projects::{self, ProjectEntry};\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct WorkflowOverview {\n pub generated_at: String,\n pub repos: Vec,\n pub errors: Vec,\n}\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct WorkflowRepoSnapshot {\n pub id: String,\n pub name: String,\n pub vcs: String,\n pub repo_key: String,\n pub repo_root: String,\n pub repo_slug: Option,\n pub default_branch: Option,\n pub project_count: usize,\n pub workspace_count: usize,\n pub active_branch_count: usize,\n pub open_pr_count: usize,\n pub hidden_branch_count: usize,\n pub pr_error: Option,\n pub projects: Vec,\n pub workspaces: Vec,\n pub branches: Vec,\n pub error: Option,\n}\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct WorkflowProjectRef {\n pub name: String,\n pub project_root: String,\n pub repo_relative_path: String,\n pub workspace_name: Option,\n pub workspace_root: Option,\n pub current_branches: Vec,\n pub dirty: bool,\n pub conflict: bool,\n pub updated_ms: u128,\n}\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct WorkflowWorkspaceSnapshot {\n pub name: String,\n pub root_path: Option,\n pub current_branches: Vec,\n pub dirty: bool,\n pub conflict: bool,\n pub target_commit: String,\n pub description: String,\n}\n\n#[derive(Debug, Clone, Serialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct WorkflowBranchSnapshot {\n pub name: String,\n pub head_sha: String,\n pub short_sha: String,\n pub subject: String,\n pub updated_at: Option,\n pub is_current: bool,\n pub is_active: bool,\n pub hidden: bool,\n pub workspace_names: Vec,\n pub dirty: bool,\n pub conflict: bool,\n pub tracking_remote: Option,\n pub tracked: bool,\n pub synced: bool,\n pub ahead_count: Option,\n pub behind_count: Option,\n pub upstream_sha: Option,\n pub compare_base_branch: Option,\n pub pull_request: Option,\n}\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct WorkflowPullRequestSummary {\n pub number: u64,\n pub title: String,\n pub url: String,\n pub state: String,\n pub is_draft: bool,\n pub base_ref_name: String,\n pub head_ref_name: String,\n pub updated_at: String,\n pub review_decision: Option,\n}\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nenum RepoVcs {\n Jj,\n Git,\n}\n\nimpl RepoVcs {\n fn as_str(self) -> &'static str {\n match self {\n RepoVcs::Jj => \"jj\",\n RepoVcs::Git => \"git\",\n }\n }\n}\n\n#[derive(Debug, Clone)]\nstruct ProjectBinding {\n project: ProjectEntry,\n vcs: RepoVcs,\n logical_key: String,\n repo_root: PathBuf,\n workspace_root: Option,\n workspace_name: Option,\n current_branches: Vec,\n dirty: bool,\n conflict: bool,\n}\n\n#[derive(Debug, Clone)]\nstruct RepoSeed {\n vcs: RepoVcs,\n logical_key: String,\n repo_root: PathBuf,\n bindings: Vec,\n}\n\n#[derive(Debug, Clone)]\nstruct WorkspaceState {\n name: String,\n target_commit: String,\n current_branches: Vec,\n dirty: bool,\n conflict: bool,\n description: String,\n}\n\n#[derive(Debug, Clone)]\nstruct CommitMeta {\n head_sha: String,\n short_sha: String,\n subject: String,\n updated_at: Option,\n}\n\n#[derive(Debug, Clone)]\nstruct JjBookmarkRow {\n name: String,\n remote: Option,\n tracked: bool,\n conflict: bool,\n present: bool,\n synced: bool,\n ahead_count: Option,\n behind_count: Option,\n target_sha: Option,\n}\n\n#[derive(Debug, Clone)]\nstruct GitWorktreeState {\n name: String,\n path: PathBuf,\n branch: Option,\n dirty: bool,\n}\n\n#[derive(Debug, Clone)]\nstruct GitBranchRow {\n name: String,\n head_sha: String,\n short_sha: String,\n updated_at: Option,\n subject: String,\n upstream: Option,\n ahead_count: Option,\n behind_count: Option,\n}\n\n#[derive(Clone)]\nstruct CachedWorkflowOverview {\n captured_at: Instant,\n overview: WorkflowOverview,\n}\n\nstatic WORKFLOW_OVERVIEW_CACHE: OnceLock>> = OnceLock::new();\nconst WORKFLOW_OVERVIEW_TTL: Duration = Duration::from_secs(30);\n\npub fn load_workflow_overview() -> Result {\n if let Some(cached) = workflow_cache()\n .lock()\n .expect(\"workflow cache mutex poisoned\")\n .clone()\n .filter(|cached| cached.captured_at.elapsed() < WORKFLOW_OVERVIEW_TTL)\n {\n return Ok(cached.overview);\n }\n\n let projects = projects::list_projects()?;\n let mut repo_map: HashMap = HashMap::new();\n let mut errors = Vec::new();\n\n for project in projects {\n match detect_project_binding(&project) {\n Ok(Some(binding)) => {\n let key = binding.logical_key.clone();\n repo_map\n .entry(key.clone())\n .and_modify(|seed| seed.bindings.push(binding.clone()))\n .or_insert_with(|| RepoSeed {\n vcs: binding.vcs,\n logical_key: key,\n repo_root: binding.repo_root.clone(),\n bindings: vec![binding],\n });\n }\n Ok(None) => errors.push(format!(\n \"{}: no jj or git repo found at {}\",\n project.name,\n project.project_root.display()\n )),\n Err(err) => errors.push(format!(\n \"{}: failed to inspect {}: {err:#}\",\n project.name,\n project.project_root.display()\n )),\n }\n }\n\n let mut repos = Vec::new();\n for seed in repo_map.into_values() {\n let snapshot = match seed.vcs {\n RepoVcs::Jj => inspect_jj_repo(&seed),\n RepoVcs::Git => inspect_git_repo(&seed),\n };\n match snapshot {\n Ok(repo) => repos.push(repo),\n Err(err) => {\n errors.push(format!(\n \"{}: failed to build workflow snapshot: {err:#}\",\n seed.repo_root.display()\n ));\n repos.push(repo_error_snapshot(&seed, err.to_string()));\n }\n }\n }\n\n repos.sort_by(|a, b| {\n b.active_branch_count\n .cmp(&a.active_branch_count)\n .then_with(|| b.open_pr_count.cmp(&a.open_pr_count))\n .then_with(|| a.name.cmp(&b.name))\n });\n\n let overview = WorkflowOverview {\n generated_at: now_iso(),\n repos,\n errors,\n };\n\n *workflow_cache().lock().expect(\"workflow cache mutex poisoned\") = Some(CachedWorkflowOverview {\n captured_at: Instant::now(),\n overview: overview.clone(),\n });\n\n Ok(overview)\n}\n\nfn workflow_cache() -> &'static Mutex> {\n WORKFLOW_OVERVIEW_CACHE.get_or_init(|| Mutex::new(None))\n}\n\nfn detect_project_binding(project: &ProjectEntry) -> Result> {\n if let Ok(workspace_root) = capture_trimmed_in(&project.project_root, \"jj\", &[\"root\"]) {\n let workspace_root = canonical_or_same(PathBuf::from(workspace_root));\n if let Ok(repo_root) = resolve_jj_repo_store(&workspace_root) {\n let workspace_name = capture_trimmed_in(\n &project.project_root,\n \"jj\",\n &[\n \"log\",\n \"-r\",\n \"@\",\n \"-n\",\n \"1\",\n \"--no-graph\",\n \"-T\",\n \"working_copies.map(|w| w.name()).join(\\\",\\\") ++ \\\"\\\\n\\\"\",\n ],\n )\n .ok()\n .and_then(|value| first_non_empty_csv(&value));\n let current_branches = capture_trimmed_in(\n &project.project_root,\n \"jj\",\n &[\n \"log\",\n \"-r\",\n \"@-\",\n \"-n\",\n \"1\",\n \"--no-graph\",\n \"-T\",\n \"local_bookmarks.map(|b| b.name()).join(\\\",\\\") ++ \\\"\\\\n\\\"\",\n ],\n )\n .map(|value| split_csv(&value))\n .unwrap_or_default();\n let workspace_state = capture_trimmed_in(\n &project.project_root,\n \"jj\",\n &[\n \"log\",\n \"-r\",\n \"@\",\n \"-n\",\n \"1\",\n \"--no-graph\",\n \"-T\",\n \"empty ++ \\\"\\\\t\\\" ++ conflict ++ \\\"\\\\n\\\"\",\n ],\n )\n .ok();\n let (dirty, conflict) = parse_dirty_conflict_state(workspace_state.as_deref());\n\n return Ok(Some(ProjectBinding {\n project: project.clone(),\n vcs: RepoVcs::Jj,\n logical_key: format!(\"jj:{}\", repo_root.display()),\n repo_root,\n workspace_root: Some(workspace_root),\n workspace_name,\n current_branches,\n dirty,\n conflict,\n }));\n }\n }\n\n if let Ok(repo_root) = capture_trimmed_in(\n &project.project_root,\n \"git\",\n &[\"rev-parse\", \"--show-toplevel\"],\n ) {\n let repo_root = canonical_or_same(PathBuf::from(repo_root));\n let common_dir = capture_trimmed_in(\n &project.project_root,\n \"git\",\n &[\"rev-parse\", \"--git-common-dir\"],\n )?;\n let common_dir = resolve_path(&project.project_root, common_dir.trim());\n let common_dir = canonical_or_same(common_dir);\n let current_branch = capture_trimmed_in(\n &project.project_root,\n \"git\",\n &[\"branch\", \"--show-current\"],\n )\n .ok()\n .into_iter()\n .flat_map(|value| split_csv(&value))\n .collect::>();\n let status = capture_trimmed_in(&project.project_root, \"git\", &[\"status\", \"--porcelain\"])\n .unwrap_or_default();\n let dirty = !status.trim().is_empty();\n let conflict = status.lines().any(git_status_line_has_conflict);\n\n return Ok(Some(ProjectBinding {\n project: project.clone(),\n vcs: RepoVcs::Git,\n logical_key: format!(\"git:{}\", common_dir.display()),\n repo_root,\n workspace_root: None,\n workspace_name: None,\n current_branches: current_branch,\n dirty,\n conflict,\n }));\n }\n\n Ok(None)\n}\n\nfn inspect_jj_repo(seed: &RepoSeed) -> Result {\n let root = preferred_repo_root(seed);\n let repo_slug = jj_repo_slug(&root);\n let (pr_map, pr_error) = fetch_open_prs(repo_slug.as_deref());\n let workspaces = jj_workspace_states(&root)?;\n let bookmark_rows = jj_bookmark_rows(&root)?;\n let commit_meta = jj_commit_meta_by_bookmark(&root)?;\n let default_branch = infer_default_branch_jj(&bookmark_rows, pr_map.values());\n let workspace_roots = seed\n .bindings\n .iter()\n .filter_map(|binding| {\n binding\n .workspace_name\n .as_ref()\n .zip(binding.workspace_root.as_ref())\n .map(|(name, root)| (name.clone(), root.clone()))\n })\n .collect::>();\n\n let mut grouped = BTreeMap::>::new();\n for row in bookmark_rows {\n grouped.entry(row.name.clone()).or_default().push(row);\n }\n\n let mut branches = Vec::new();\n for (name, rows) in grouped {\n let Some(local) = rows.iter().find(|row| row.remote.is_none()).cloned() else {\n continue;\n };\n\n let remotes = rows\n .iter()\n .filter(|row| row.remote.is_some())\n .cloned()\n .collect::>();\n let tracking = remotes\n .iter()\n .find(|row| row.remote.as_deref() == Some(\"origin\"))\n .or_else(|| remotes.first());\n let workspace_names = workspaces\n .iter()\n .filter(|workspace| workspace.current_branches.iter().any(|branch| branch == &name))\n .map(|workspace| workspace.name.clone())\n .collect::>();\n let dirty = workspaces\n .iter()\n .any(|workspace| workspace.dirty && workspace.current_branches.iter().any(|branch| branch == &name));\n let workspace_conflict = workspaces\n .iter()\n .any(|workspace| workspace.conflict && workspace.current_branches.iter().any(|branch| branch == &name));\n let meta = commit_meta.get(&name).cloned().unwrap_or_else(|| CommitMeta {\n head_sha: local.target_sha.clone().unwrap_or_default(),\n short_sha: truncate_sha(local.target_sha.as_deref().unwrap_or(\"\")),\n subject: String::new(),\n updated_at: None,\n });\n let pull_request = pr_map.get(&name).cloned();\n let compare_base_branch = pull_request\n .as_ref()\n .map(|pr| pr.base_ref_name.clone())\n .or_else(|| default_branch.clone());\n let is_current = !workspace_names.is_empty();\n let hidden = is_hidden_branch(&name);\n let is_active = is_current\n || dirty\n || local.conflict\n || workspace_conflict\n || pull_request.is_some();\n\n branches.push(WorkflowBranchSnapshot {\n name: name.clone(),\n head_sha: meta.head_sha,\n short_sha: meta.short_sha,\n subject: meta.subject,\n updated_at: meta.updated_at,\n is_current,\n is_active,\n hidden,\n workspace_names,\n dirty,\n conflict: local.conflict || workspace_conflict,\n tracking_remote: tracking.and_then(|row| row.remote.clone()),\n tracked: tracking.map(|row| row.tracked).unwrap_or(false),\n synced: local.synced,\n ahead_count: tracking.and_then(|row| row.ahead_count),\n behind_count: tracking.and_then(|row| row.behind_count),\n upstream_sha: tracking.and_then(|row| row.target_sha.clone()),\n compare_base_branch,\n pull_request,\n });\n }\n\n sort_branches(&mut branches);\n\n let projects = seed\n .bindings\n .iter()\n .map(|binding| WorkflowProjectRef {\n name: binding.project.name.clone(),\n project_root: binding.project.project_root.display().to_string(),\n repo_relative_path: relative_display_path(\n binding.workspace_root.as_deref().unwrap_or(&binding.repo_root),\n &binding.project.project_root,\n ),\n workspace_name: binding.workspace_name.clone(),\n workspace_root: binding\n .workspace_root\n .as_ref()\n .map(|value| value.display().to_string()),\n current_branches: binding.current_branches.clone(),\n dirty: binding.dirty,\n conflict: binding.conflict,\n updated_ms: binding.project.updated_ms,\n })\n .collect::>();\n\n let workspaces = workspaces\n .into_iter()\n .map(|workspace| WorkflowWorkspaceSnapshot {\n name: workspace.name.clone(),\n root_path: workspace_roots\n .get(&workspace.name)\n .map(|value| value.display().to_string()),\n current_branches: workspace.current_branches,\n dirty: workspace.dirty,\n conflict: workspace.conflict,\n target_commit: workspace.target_commit,\n description: workspace.description,\n })\n .collect::>();\n\n let hidden_branch_count = branches.iter().filter(|branch| branch.hidden).count();\n let active_branch_count = branches\n .iter()\n .filter(|branch| branch.is_active && !branch.hidden)\n .count();\n let open_pr_count = branches\n .iter()\n .filter(|branch| {\n branch\n .pull_request\n .as_ref()\n .map(|pr| pr.state == \"OPEN\")\n .unwrap_or(false)\n })\n .count();\n\n Ok(WorkflowRepoSnapshot {\n id: seed.logical_key.clone(),\n name: display_repo_name(repo_slug.as_deref(), &root),\n vcs: seed.vcs.as_str().to_string(),\n repo_key: seed.logical_key.clone(),\n repo_root: root.display().to_string(),\n repo_slug,\n default_branch,\n project_count: projects.len(),\n workspace_count: workspaces.len(),\n active_branch_count,\n open_pr_count,\n hidden_branch_count,\n pr_error,\n projects,\n workspaces,\n branches,\n error: None,\n })\n}\n\nfn inspect_git_repo(seed: &RepoSeed) -> Result {\n let root = seed.repo_root.clone();\n let repo_slug = git_repo_slug(&root);\n let (pr_map, pr_error) = fetch_open_prs(repo_slug.as_deref());\n let default_branch = git_default_branch(&root);\n let worktrees = git_worktree_states(&root)?;\n let mut branches = git_branch_rows(&root)?\n .into_iter()\n .map(|row| {\n let workspace_names = worktrees\n .iter()\n .filter(|workspace| workspace.branch.as_deref() == Some(row.name.as_str()))\n .map(|workspace| workspace.name.clone())\n .collect::>();\n let dirty = worktrees\n .iter()\n .any(|workspace| workspace.dirty && workspace.branch.as_deref() == Some(row.name.as_str()));\n let pull_request = pr_map.get(&row.name).cloned();\n let compare_base_branch = pull_request\n .as_ref()\n .map(|pr| pr.base_ref_name.clone())\n .or_else(|| default_branch.clone());\n let hidden = is_hidden_branch(&row.name);\n let is_current = !workspace_names.is_empty();\n let is_active = is_current || dirty || pull_request.is_some();\n\n WorkflowBranchSnapshot {\n name: row.name.clone(),\n head_sha: row.head_sha.clone(),\n short_sha: row.short_sha.clone(),\n subject: row.subject.clone(),\n updated_at: row.updated_at.clone(),\n is_current,\n is_active,\n hidden,\n workspace_names,\n dirty,\n conflict: false,\n tracking_remote: row.upstream.clone(),\n tracked: row.upstream.is_some(),\n synced: row.ahead_count.unwrap_or(0) == 0 && row.behind_count.unwrap_or(0) == 0,\n ahead_count: row.ahead_count,\n behind_count: row.behind_count,\n upstream_sha: None,\n compare_base_branch,\n pull_request,\n }\n })\n .collect::>();\n\n sort_branches(&mut branches);\n\n let projects = seed\n .bindings\n .iter()\n .map(|binding| WorkflowProjectRef {\n name: binding.project.name.clone(),\n project_root: binding.project.project_root.display().to_string(),\n repo_relative_path: relative_display_path(&binding.repo_root, &binding.project.project_root),\n workspace_name: None,\n workspace_root: None,\n current_branches: binding.current_branches.clone(),\n dirty: binding.dirty,\n conflict: binding.conflict,\n updated_ms: binding.project.updated_ms,\n })\n .collect::>();\n let workspaces = worktrees\n .iter()\n .map(|workspace| WorkflowWorkspaceSnapshot {\n name: workspace.name.clone(),\n root_path: Some(workspace.path.display().to_string()),\n current_branches: workspace.branch.clone().into_iter().collect(),\n dirty: workspace.dirty,\n conflict: false,\n target_commit: String::new(),\n description: String::new(),\n })\n .collect::>();\n let hidden_branch_count = branches.iter().filter(|branch| branch.hidden).count();\n let active_branch_count = branches\n .iter()\n .filter(|branch| branch.is_active && !branch.hidden)\n .count();\n let open_pr_count = branches\n .iter()\n .filter(|branch| {\n branch\n .pull_request\n .as_ref()\n .map(|pr| pr.state == \"OPEN\")\n .unwrap_or(false)\n })\n .count();\n\n Ok(WorkflowRepoSnapshot {\n id: seed.logical_key.clone(),\n name: display_repo_name(repo_slug.as_deref(), &root),\n vcs: seed.vcs.as_str().to_string(),\n repo_key: seed.logical_key.clone(),\n repo_root: root.display().to_string(),\n repo_slug,\n default_branch,\n project_count: projects.len(),\n workspace_count: workspaces.len(),\n active_branch_count,\n open_pr_count,\n hidden_branch_count,\n pr_error,\n projects,\n workspaces,\n branches,\n error: None,\n })\n}\n\nfn repo_error_snapshot(seed: &RepoSeed, error: String) -> WorkflowRepoSnapshot {\n WorkflowRepoSnapshot {\n id: seed.logical_key.clone(),\n name: display_repo_name(None, &seed.repo_root),\n vcs: seed.vcs.as_str().to_string(),\n repo_key: seed.logical_key.clone(),\n repo_root: seed.repo_root.display().to_string(),\n repo_slug: None,\n default_branch: None,\n project_count: seed.bindings.len(),\n workspace_count: 0,\n active_branch_count: 0,\n open_pr_count: 0,\n hidden_branch_count: 0,\n pr_error: None,\n projects: seed\n .bindings\n .iter()\n .map(|binding| WorkflowProjectRef {\n name: binding.project.name.clone(),\n project_root: binding.project.project_root.display().to_string(),\n repo_relative_path: \".\".to_string(),\n workspace_name: binding.workspace_name.clone(),\n workspace_root: binding\n .workspace_root\n .as_ref()\n .map(|value| value.display().to_string()),\n current_branches: binding.current_branches.clone(),\n dirty: binding.dirty,\n conflict: binding.conflict,\n updated_ms: binding.project.updated_ms,\n })\n .collect(),\n workspaces: Vec::new(),\n branches: Vec::new(),\n error: Some(error),\n }\n}\n\nfn preferred_repo_root(seed: &RepoSeed) -> PathBuf {\n let mut roots = seed\n .bindings\n .iter()\n .filter_map(|binding| binding.workspace_root.clone())\n .collect::>();\n if roots.is_empty() {\n return seed.repo_root.clone();\n }\n roots.sort_by(|a, b| {\n root_preference_score(a)\n .cmp(&root_preference_score(b))\n .then_with(|| a.to_string_lossy().len().cmp(&b.to_string_lossy().len()))\n });\n roots[0].clone()\n}\n\nfn root_preference_score(path: &Path) -> u8 {\n let text = path.to_string_lossy();\n if text.contains(\"/.jj/workspaces/\") {\n 2\n } else if text.contains(\"/private/tmp/\") {\n 1\n } else {\n 0\n }\n}\n\nfn resolve_jj_repo_store(workspace_root: &Path) -> Result {\n let repo_marker = workspace_root.join(\".jj\").join(\"repo\");\n if repo_marker.is_dir() {\n return Ok(canonical_or_same(repo_marker));\n }\n if repo_marker.is_file() {\n let target = fs::read_to_string(&repo_marker)\n .with_context(|| format!(\"failed to read {}\", repo_marker.display()))?;\n let resolved = resolve_path(\n repo_marker\n .parent()\n .ok_or_else(|| anyhow!(\"missing .jj parent for {}\", repo_marker.display()))?,\n target.trim(),\n );\n return Ok(canonical_or_same(resolved));\n }\n bail!(\"expected {} to exist\", repo_marker.display())\n}\n\nfn jj_workspace_states(repo_root: &Path) -> Result> {\n let output = capture_trimmed_in(\n repo_root,\n \"jj\",\n &[\n \"workspace\",\n \"list\",\n \"-T\",\n \"name ++ \\\"\\\\t\\\" ++ target.commit_id().short() ++ \\\"\\\\t\\\" ++ target.parents().map(|p| p.local_bookmarks().map(|b| b.name()).join(\\\",\\\")).join(\\\",\\\") ++ \\\"\\\\t\\\" ++ target.empty() ++ \\\"\\\\t\\\" ++ target.conflict() ++ \\\"\\\\t\\\" ++ target.description().first_line() ++ \\\"\\\\n\\\"\",\n ],\n )?;\n let mut workspaces = Vec::new();\n for line in output.lines() {\n if line.trim().is_empty() {\n continue;\n }\n let mut parts = line.splitn(6, '\\t');\n let name = parts.next().unwrap_or(\"\").trim();\n if name.is_empty() {\n continue;\n }\n let target_commit = parts.next().unwrap_or(\"\").trim().to_string();\n let current_branches = split_csv(parts.next().unwrap_or(\"\"));\n let dirty = !parse_bool(parts.next().unwrap_or(\"true\"));\n let conflict = parse_bool(parts.next().unwrap_or(\"false\"));\n let description = parts.next().unwrap_or(\"\").trim().to_string();\n workspaces.push(WorkspaceState {\n name: name.to_string(),\n target_commit,\n current_branches,\n dirty,\n conflict,\n description,\n });\n }\n Ok(workspaces)\n}\n\nfn jj_bookmark_rows(repo_root: &Path) -> Result> {\n let output = capture_trimmed_in(\n repo_root,\n \"jj\",\n &[\n \"bookmark\",\n \"list\",\n \"--all-remotes\",\n \"-T\",\n \"name ++ \\\"\\\\t\\\" ++ remote ++ \\\"\\\\t\\\" ++ tracked ++ \\\"\\\\t\\\" ++ conflict ++ \\\"\\\\t\\\" ++ present ++ \\\"\\\\t\\\" ++ synced ++ \\\"\\\\t\\\" ++ if(tracked, tracking_ahead_count.exact(), \\\"\\\") ++ \\\"\\\\t\\\" ++ if(tracked, tracking_behind_count.exact(), \\\"\\\") ++ \\\"\\\\t\\\" ++ if(normal_target, normal_target.commit_id().short(), \\\"\\\") ++ \\\"\\\\n\\\"\",\n ],\n )?;\n let mut rows = Vec::new();\n for line in output.lines() {\n if line.trim().is_empty() {\n continue;\n }\n let mut parts = line.splitn(9, '\\t');\n let name = parts.next().unwrap_or(\"\").trim();\n if name.is_empty() {\n continue;\n }\n rows.push(JjBookmarkRow {\n name: name.to_string(),\n remote: non_empty(parts.next().unwrap_or(\"\")),\n tracked: parse_bool(parts.next().unwrap_or(\"false\")),\n conflict: parse_bool(parts.next().unwrap_or(\"false\")),\n present: parse_bool(parts.next().unwrap_or(\"false\")),\n synced: parse_bool(parts.next().unwrap_or(\"false\")),\n ahead_count: parse_u32(parts.next().unwrap_or(\"\")),\n behind_count: parse_u32(parts.next().unwrap_or(\"\")),\n target_sha: non_empty(parts.next().unwrap_or(\"\")),\n });\n }\n Ok(rows)\n}\n\nfn jj_commit_meta_by_bookmark(repo_root: &Path) -> Result> {\n let output = capture_trimmed_in(\n repo_root,\n \"jj\",\n &[\n \"log\",\n \"-r\",\n \"bookmarks()\",\n \"--no-graph\",\n \"-T\",\n \"local_bookmarks.map(|b| b.name()).join(\\\",\\\") ++ \\\"\\\\t\\\" ++ commit_id.short() ++ \\\"\\\\t\\\" ++ commit_id.short() ++ \\\"\\\\t\\\" ++ description.first_line() ++ \\\"\\\\t\\\" ++ author.timestamp().utc().format(\\\"%Y-%m-%dT%H:%M:%SZ\\\") ++ \\\"\\\\n\\\"\",\n ],\n )?;\n let mut commits = HashMap::new();\n for line in output.lines() {\n if line.trim().is_empty() {\n continue;\n }\n let mut parts = line.splitn(5, '\\t');\n let names = parts.next().unwrap_or(\"\");\n let head_sha = parts.next().unwrap_or(\"\").trim().to_string();\n let short_sha = parts.next().unwrap_or(\"\").trim().to_string();\n let subject = parts.next().unwrap_or(\"\").trim().to_string();\n let updated_at = non_empty(parts.next().unwrap_or(\"\"));\n for name in split_csv(names) {\n commits.entry(name).or_insert_with(|| CommitMeta {\n head_sha: head_sha.clone(),\n short_sha: short_sha.clone(),\n subject: subject.clone(),\n updated_at: updated_at.clone(),\n });\n }\n }\n Ok(commits)\n}\n\nfn jj_repo_slug(repo_root: &Path) -> Option {\n let output = capture_trimmed_in(repo_root, \"jj\", &[\"git\", \"remote\", \"list\"]).ok()?;\n for line in output.lines() {\n let mut parts = line.split_whitespace();\n let remote = parts.next().unwrap_or(\"\");\n let url = parts.next().unwrap_or(\"\");\n if remote == \"origin\" {\n if let Some(slug) = parse_github_repo_slug(url) {\n return Some(slug);\n }\n }\n }\n output\n .lines()\n .find_map(|line| line.split_whitespace().nth(1))\n .and_then(parse_github_repo_slug)\n}\n\nfn infer_default_branch_jj<'a>(\n rows: &[JjBookmarkRow],\n prs: impl Iterator,\n) -> Option {\n let local_names = rows\n .iter()\n .filter(|row| row.remote.is_none() && row.present)\n .map(|row| row.name.as_str())\n .collect::>();\n if local_names.contains(\"main\") {\n return Some(\"main\".to_string());\n }\n if local_names.contains(\"master\") {\n return Some(\"master\".to_string());\n }\n\n let mut counts = HashMap::::new();\n for pr in prs {\n *counts.entry(pr.base_ref_name.clone()).or_default() += 1;\n }\n counts\n .into_iter()\n .max_by_key(|(_, count)| *count)\n .map(|(branch, _)| branch)\n}\n\nfn git_worktree_states(repo_root: &Path) -> Result> {\n let output = capture_trimmed_in(repo_root, \"git\", &[\"worktree\", \"list\", \"--porcelain\"])?;\n let mut worktrees = Vec::new();\n let mut current_path: Option = None;\n let mut current_branch: Option = None;\n\n for line in output.lines().chain(std::iter::once(\"\")) {\n let trimmed = line.trim();\n if trimmed.is_empty() {\n if let Some(path) = current_path.take() {\n let dirty = path.exists()\n && capture_trimmed_in(&path, \"git\", &[\"status\", \"--porcelain\"])\n .map(|status| !status.trim().is_empty())\n .unwrap_or(false);\n worktrees.push(GitWorktreeState {\n name: path\n .file_name()\n .and_then(|value| value.to_str())\n .unwrap_or(\"worktree\")\n .to_string(),\n path,\n branch: current_branch.take(),\n dirty,\n });\n }\n current_branch = None;\n continue;\n }\n\n if let Some(path) = trimmed.strip_prefix(\"worktree \") {\n current_path = Some(PathBuf::from(path.trim()));\n continue;\n }\n if let Some(branch) = trimmed.strip_prefix(\"branch refs/heads/\") {\n current_branch = Some(branch.trim().to_string());\n }\n }\n\n Ok(worktrees)\n}\n\nfn git_branch_rows(repo_root: &Path) -> Result> {\n let output = capture_trimmed_in(\n repo_root,\n \"git\",\n &[\n \"for-each-ref\",\n \"--sort=-committerdate\",\n \"--format=%(refname:short)%09%(objectname)%09%(committerdate:iso-strict)%09%(subject)%09%(upstream:short)%09%(upstream:track)\",\n \"refs/heads\",\n ],\n )?;\n let mut branches = Vec::new();\n for line in output.lines() {\n if line.trim().is_empty() {\n continue;\n }\n let mut parts = line.splitn(6, '\\t');\n let name = parts.next().unwrap_or(\"\").trim();\n if name.is_empty() {\n continue;\n }\n let head_sha = parts.next().unwrap_or(\"\").trim().to_string();\n let updated_at = non_empty(parts.next().unwrap_or(\"\"));\n let subject = parts.next().unwrap_or(\"\").trim().to_string();\n let upstream = non_empty(parts.next().unwrap_or(\"\"));\n let (ahead_count, behind_count) = parse_git_track(parts.next().unwrap_or(\"\"));\n branches.push(GitBranchRow {\n name: name.to_string(),\n short_sha: truncate_sha(&head_sha),\n head_sha,\n updated_at,\n subject,\n upstream,\n ahead_count,\n behind_count,\n });\n }\n Ok(branches)\n}\n\nfn git_repo_slug(repo_root: &Path) -> Option {\n capture_trimmed_in(repo_root, \"git\", &[\"remote\", \"get-url\", \"origin\"])\n .ok()\n .as_deref()\n .and_then(parse_github_repo_slug)\n}\n\nfn git_default_branch(repo_root: &Path) -> Option {\n capture_trimmed_in(repo_root, \"git\", &[\"symbolic-ref\", \"refs/remotes/origin/HEAD\"])\n .ok()\n .and_then(|value| value.trim().rsplit('/').next().map(|branch| branch.to_string()))\n .or_else(|| {\n let branches = capture_trimmed_in(\n repo_root,\n \"git\",\n &[\"for-each-ref\", \"--format=%(refname:short)\", \"refs/heads\"],\n )\n .ok()?;\n let names = branches.lines().map(str::trim).collect::>();\n if names.contains(\"main\") {\n Some(\"main\".to_string())\n } else if names.contains(\"master\") {\n Some(\"master\".to_string())\n } else {\n None\n }\n })\n}\n\nfn fetch_open_prs(\n repo_slug: Option<&str>,\n) -> (HashMap, Option) {\n let Some(repo_slug) = repo_slug else {\n return (HashMap::new(), None);\n };\n\n let output = capture_trimmed(\n \"gh\",\n &[\n \"pr\",\n \"list\",\n \"--repo\",\n repo_slug,\n \"--state\",\n \"open\",\n \"--limit\",\n \"200\",\n \"--json\",\n \"number,title,url,state,isDraft,baseRefName,headRefName,updatedAt,reviewDecision\",\n ],\n );\n let output = match output {\n Ok(output) => output,\n Err(err) => return (HashMap::new(), Some(err.to_string())),\n };\n\n let prs: Vec = match serde_json::from_str(&output) {\n Ok(prs) => prs,\n Err(err) => {\n return (\n HashMap::new(),\n Some(format!(\"failed to parse gh pr list for {repo_slug}: {err}\")),\n );\n }\n };\n\n let by_head = prs\n .into_iter()\n .map(|pr| (pr.head_ref_name.clone(), pr))\n .collect::>();\n (by_head, None)\n}\n\nfn sort_branches(branches: &mut [WorkflowBranchSnapshot]) {\n branches.sort_by(|a, b| {\n branch_rank(b)\n .cmp(&branch_rank(a))\n .then_with(|| b.updated_at.cmp(&a.updated_at))\n .then_with(|| a.name.cmp(&b.name))\n });\n}\n\nfn branch_rank(branch: &WorkflowBranchSnapshot) -> u8 {\n if branch.conflict {\n 5\n } else if branch.pull_request.is_some() {\n 4\n } else if branch.is_current {\n 3\n } else if branch.dirty {\n 2\n } else if branch.is_active {\n 1\n } else {\n 0\n }\n}\n\nfn is_hidden_branch(name: &str) -> bool {\n name.starts_with(\"backup/\") || name.starts_with(\"jj/keep/\")\n}\n\nfn display_repo_name(repo_slug: Option<&str>, repo_root: &Path) -> String {\n repo_slug\n .and_then(|slug| slug.rsplit('/').next())\n .map(str::to_string)\n .or_else(|| {\n repo_root\n .file_name()\n .and_then(|value| value.to_str())\n .map(str::to_string)\n })\n .unwrap_or_else(|| \"repo\".to_string())\n}\n\nfn relative_display_path(root: &Path, path: &Path) -> String {\n match path.strip_prefix(root) {\n Ok(relative) if relative.as_os_str().is_empty() => \".\".to_string(),\n Ok(relative) => relative.display().to_string(),\n Err(_) => path.display().to_string(),\n }\n}\n\nfn parse_git_track(value: &str) -> (Option, Option) {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n return (None, None);\n }\n let ahead = extract_number_after(trimmed, \"ahead \");\n let behind = extract_number_after(trimmed, \"behind \");\n (ahead, behind)\n}\n\nfn extract_number_after(text: &str, needle: &str) -> Option {\n let start = text.find(needle)? + needle.len();\n let digits = text[start..]\n .chars()\n .take_while(|ch| ch.is_ascii_digit())\n .collect::();\n digits.parse().ok()\n}\n\nfn parse_dirty_conflict_state(value: Option<&str>) -> (bool, bool) {\n let Some(value) = value else {\n return (false, false);\n };\n let mut parts = value.splitn(2, '\\t');\n let empty = parse_bool(parts.next().unwrap_or(\"true\"));\n let conflict = parse_bool(parts.next().unwrap_or(\"false\"));\n (!empty, conflict)\n}\n\nfn git_status_line_has_conflict(line: &str) -> bool {\n let bytes = line.as_bytes();\n if bytes.len() < 2 {\n return false;\n }\n matches!(\n (bytes[0] as char, bytes[1] as char),\n ('U', _) | (_, 'U') | ('A', 'A') | ('D', 'D')\n )\n}\n\nfn parse_github_repo_slug(url: &str) -> Option {\n let trimmed = url.trim().trim_end_matches(\".git\").trim_end_matches('/');\n if let Some(rest) = trimmed.strip_prefix(\"git@github.com:\") {\n return normalize_repo_slug(rest);\n }\n let marker = \"github.com/\";\n let start = trimmed.find(marker)?;\n normalize_repo_slug(&trimmed[start + marker.len()..])\n}\n\nfn normalize_repo_slug(rest: &str) -> Option {\n let mut parts = rest.split('/').filter(|part| !part.is_empty());\n let owner = parts.next()?;\n let repo = parts.next()?;\n Some(format!(\"{owner}/{repo}\"))\n}\n\nfn capture_trimmed(command: &str, args: &[&str]) -> Result {\n let mut cmd = Command::new(command);\n cmd.args(args);\n capture_trimmed_inner(&mut cmd)\n}\n\nfn capture_trimmed_in(cwd: &Path, command: &str, args: &[&str]) -> Result {\n let mut cmd = Command::new(command);\n cmd.args(args).current_dir(cwd);\n capture_trimmed_inner(&mut cmd)\n}\n\nfn capture_trimmed_inner(cmd: &mut Command) -> Result {\n let rendered = format!(\"{cmd:?}\");\n let output = cmd\n .output()\n .with_context(|| format!(\"failed to run {rendered}\"))?;\n if !output.status.success() {\n let stderr = String::from_utf8_lossy(&output.stderr);\n bail!(\"command failed: {rendered}: {}\", stderr.trim());\n }\n Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())\n}\n\nfn resolve_path(base: &Path, value: &str) -> PathBuf {\n let path = PathBuf::from(value);\n if path.is_absolute() {\n path\n } else {\n base.join(path)\n }\n}\n\nfn canonical_or_same(path: PathBuf) -> PathBuf {\n path.canonicalize().unwrap_or(path)\n}\n\nfn parse_bool(value: &str) -> bool {\n value.trim() == \"true\"\n}\n\nfn parse_u32(value: &str) -> Option {\n value.trim().parse().ok()\n}\n\nfn split_csv(value: &str) -> Vec {\n value\n .split(',')\n .map(str::trim)\n .filter(|item| !item.is_empty())\n .map(str::to_string)\n .collect()\n}\n\nfn first_non_empty_csv(value: &str) -> Option {\n split_csv(value).into_iter().next()\n}\n\nfn non_empty(value: &str) -> Option {\n let trimmed = value.trim();\n if trimmed.is_empty() {\n None\n } else {\n Some(trimmed.to_string())\n }\n}\n\nfn truncate_sha(value: &str) -> String {\n value.chars().take(12).collect()\n}\n\nfn now_iso() -> String {\n Utc::now().to_rfc3339_opts(SecondsFormat::Secs, true)\n}\n\n#[allow(dead_code)]\nfn ms_to_iso(ms: u128) -> Option {\n let ms = i64::try_from(ms).ok()?;\n Utc.timestamp_millis_opt(ms)\n .single()\n .map(|ts| ts.to_rfc3339_opts(SecondsFormat::Secs, true))\n}\n" }, { "path": "test-extension.md", "content": "# Testing Pi-Mono Extensibility\n\nThis directory contains a test extension demonstrating pi-mono's extensibility.\n\n## Setup\n\nThe extension is at `.pi/extensions/test-extensibility.ts` and loads automatically.\n\n## Run\n\n```bash\ncd ~/code/flow\npi\n```\n\n## Test Commands\n\nOnce pi is running, try these:\n\n### 1. Test Custom Tool\n\n```\nuse the counter tool to increment by 5\n```\n\n```\nincrement the counter 3 times, then show me the value\n```\n\n### 2. Test Event Hooks\n\n```\nrun: echo \"hello world\"\n```\n\n(Watch the console for `[test-ext] Tool called: bash`)\n\n```\nrun: rm -i test.txt\n```\n\n(Should show a warning notification)\n\n### 3. Test Custom Command\n\nType directly:\n```\n/count\n```\n\n### 4. View Extension Logs\n\nThe extension logs to console. Look for `[test-ext]` prefixed messages.\n\n## What This Demonstrates\n\n1. **Custom Tools** - `counter` tool with multiple actions\n2. **Event Hooks** - `tool_call` and `turn_end` listeners\n3. **Custom Commands** - `/count` slash command\n4. **Session Events** - Reset state on `session_start`\n5. **UI Interactions** - `ctx.ui.notify()` for warnings\n\n## Extending Further\n\nEdit `.pi/extensions/test-extensibility.ts` to:\n\n- Add more tools\n- Block dangerous operations (return `{ block: true }`)\n- Add keyboard shortcuts with `pi.registerShortcut()`\n- Register custom LLM providers with `pi.registerProvider()`\n" }, { "path": "tests/deps.ts", "content": "#!/usr/bin/env tsx\n/**\n * Quick e2e check that tasks with managed deps run inside the generated env.\n * Uses a fake `flox` shim so no real installs or network calls are needed.\n */\n\nimport { mkdtempSync, writeFileSync, chmodSync, mkdirSync } from \"fs\";\nimport { tmpdir } from \"os\";\nimport { join } from \"path\";\nimport { spawnSync } from \"child_process\";\n\nfunction assertOk(result: ReturnType, context: string) {\n if (result.status !== 0) {\n const stdout = result.stdout?.toString() ?? \"\";\n const stderr = result.stderr?.toString() ?? \"\";\n throw new Error(\n `${context} failed (code ${result.status})\\nstdout:\\n${stdout}\\nstderr:\\n${stderr}`\n );\n }\n}\n\nfunction main() {\n const base = mkdtempSync(join(tmpdir(), \"flow-flox-test-\"));\n const binDir = join(base, \"bin\");\n mkdirSync(binDir, { recursive: true });\n\n const fakeFlox = join(base, \"flox\");\n const helloDep = join(binDir, \"hello-dep\");\n\n // Fake flox binary: lock-manifest echoes the manifest; activate adds our bin to PATH then execs the command.\n const floxScript = `#!/usr/bin/env bash\nset -e\nif [[ \"$1\" == \"lock-manifest\" ]]; then\n cat \"$2\"\n exit 0\nfi\nif [[ \"$1\" == \"activate\" ]]; then\n shift\n while [[ \"$1\" != \"--\" && \"$#\" -gt 0 ]]; do shift; done\n shift || true\n export PATH=\"${binDir}:$PATH\"\n exec \"$@\"\nfi\nprintf \"unknown flox args: %s\\n\" \"$@\" 1>&2\nexit 1\n`;\n writeFileSync(fakeFlox, floxScript, { encoding: \"utf8\" });\n chmodSync(fakeFlox, 0o755);\n\n // Fake dependency command\n writeFileSync(helloDep, \"#!/usr/bin/env bash\\necho from-managed-env\\n\", {\n encoding: \"utf8\",\n });\n chmodSync(helloDep, 0o755);\n\n // flow.toml using a managed dependency\n const flowToml = `version = 1\n\n[deps.hello]\npkg-path = \"hello-dep\"\n\n[[tasks]]\nname = \"use-managed-dep\"\ncommand = \"hello-dep\"\ndescription = \"Confirm managed dep is used\"\ndependencies = [\"hello\"]\n`;\n writeFileSync(join(base, \"flow.toml\"), flowToml, { encoding: \"utf8\" });\n\n const env = {\n ...process.env,\n PATH: `${fakeFlox}:${process.env.PATH}`,\n HOME: base,\n FLOX_NO_TELEMETRY: \"1\",\n };\n\n const cargo = spawnSync(\n \"cargo\",\n [\"run\", \"--bin\", \"f\", \"--\", \"run\", \"use-managed-dep\"],\n {\n cwd: base,\n env,\n }\n );\n assertOk(cargo, \"cargo run f use-managed-dep\");\n\n const output = cargo.stdout?.toString() ?? \"\";\n if (!output.includes(\"from-managed-env\")) {\n throw new Error(`unexpected task output:\\n${output}`);\n }\n\n console.log(\"deps e2e passed:\\n\" + output.trim());\n}\n\nmain();\n\n" }, { "path": "tests/test_log_server.ts", "content": "#!/usr/bin/env bun\n/**\n * Test script for flow log server ingestion and query.\n * Run: bun tests/test_log_server.ts\n */\n\nconst SERVER_URL = \"http://127.0.0.1:9060\";\n\ninterface LogEntry {\n project: string;\n content: string;\n timestamp: number;\n type: string;\n service: string;\n stack?: string;\n format: string;\n}\n\ninterface StoredLogEntry {\n id: number;\n project: string;\n content: string;\n timestamp: number;\n type: string;\n service: string;\n stack?: string;\n format: string;\n}\n\nasync function checkHealth(): Promise {\n try {\n const res = await fetch(`${SERVER_URL}/health`);\n const data = await res.json();\n console.log(\"✓ Health check:\", data);\n return data.status === \"ok\";\n } catch (e) {\n console.error(\"✗ Health check failed:\", e);\n return false;\n }\n}\n\nasync function ingestLog(entry: LogEntry): Promise<{ inserted: number; ids: number[] } | null> {\n try {\n console.log(\"\\n→ Ingesting log:\", JSON.stringify(entry));\n const res = await fetch(`${SERVER_URL}/logs/ingest`, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify(entry),\n });\n\n console.log(\" Response status:\", res.status);\n const text = await res.text();\n console.log(\" Response body:\", text);\n\n if (!res.ok) {\n console.error(\"✗ Ingest failed with status:\", res.status);\n return null;\n }\n\n return JSON.parse(text);\n } catch (e) {\n console.error(\"✗ Ingest error:\", e);\n return null;\n }\n}\n\nasync function queryLogs(project?: string): Promise {\n try {\n const url = project\n ? `${SERVER_URL}/logs/query?project=${encodeURIComponent(project)}`\n : `${SERVER_URL}/logs/query`;\n\n console.log(\"\\n→ Querying logs:\", url);\n const res = await fetch(url);\n\n console.log(\" Response status:\", res.status);\n const text = await res.text();\n console.log(\" Response body:\", text);\n\n if (!res.ok) {\n console.error(\"✗ Query failed with status:\", res.status);\n return [];\n }\n\n return JSON.parse(text);\n } catch (e) {\n console.error(\"✗ Query error:\", e);\n return [];\n }\n}\n\nasync function main() {\n console.log(\"=== Flow Log Server Test ===\\n\");\n console.log(\"Server URL:\", SERVER_URL);\n\n // 1. Health check\n console.log(\"\\n--- Step 1: Health Check ---\");\n const healthy = await checkHealth();\n if (!healthy) {\n console.error(\"\\n✗ Server is not healthy. Make sure 'f server' is running.\");\n process.exit(1);\n }\n\n // 2. Query existing logs (baseline)\n console.log(\"\\n--- Step 2: Query Existing Logs (baseline) ---\");\n const existingLogs = await queryLogs();\n console.log(`Found ${existingLogs.length} existing logs`);\n\n // 3. Ingest a test log\n console.log(\"\\n--- Step 3: Ingest Test Log ---\");\n const testEntry: LogEntry = {\n project: \"test-project\",\n content: `Test log at ${new Date().toISOString()}`,\n timestamp: Date.now(),\n type: \"log\",\n service: \"test-runner\",\n format: \"text\",\n };\n\n const ingestResult = await ingestLog(testEntry);\n if (!ingestResult) {\n console.error(\"\\n✗ Failed to ingest log\");\n process.exit(1);\n }\n console.log(\"✓ Ingested:\", ingestResult);\n\n // 4. Ingest an error log with stack trace\n console.log(\"\\n--- Step 4: Ingest Error Log ---\");\n const errorEntry: LogEntry = {\n project: \"test-project\",\n content: \"TypeError: Cannot read property 'foo' of undefined\",\n timestamp: Date.now(),\n type: \"error\",\n service: \"api\",\n stack: \"at Object. (test.ts:10:5)\\nat Module._compile (node:internal/modules/cjs/loader:1234:14)\",\n format: \"text\",\n };\n\n const errorResult = await ingestLog(errorEntry);\n if (!errorResult) {\n console.error(\"\\n✗ Failed to ingest error log\");\n process.exit(1);\n }\n console.log(\"✓ Ingested error:\", errorResult);\n\n // 5. Query logs for our test project\n console.log(\"\\n--- Step 5: Query Test Project Logs ---\");\n const projectLogs = await queryLogs(\"test-project\");\n console.log(`Found ${projectLogs.length} logs for test-project`);\n\n // 6. Query all logs\n console.log(\"\\n--- Step 6: Query All Logs ---\");\n const allLogs = await queryLogs();\n console.log(`Found ${allLogs.length} total logs`);\n\n // 7. Verify results\n console.log(\"\\n--- Step 7: Verification ---\");\n if (projectLogs.length >= 2) {\n console.log(\"✓ Successfully ingested and queried logs!\");\n console.log(\"\\nSample log entry:\");\n console.log(JSON.stringify(projectLogs[0], null, 2));\n } else {\n console.error(\"✗ Expected at least 2 logs, got:\", projectLogs.length);\n console.error(\"This suggests logs are not being persisted correctly.\");\n process.exit(1);\n }\n\n console.log(\"\\n=== All tests passed! ===\");\n}\n\nmain().catch(console.error);\n" }, { "path": "tools/domainsd-cpp/domainsd.cpp", "content": "#include \n#include \n#ifdef __APPLE__\n#include \n#endif\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nnamespace {\n\nconstexpr const char* kHeaderName = \"X-Flow-Domainsd\";\nconstexpr const char* kHeaderValue = \"1\";\nconstexpr size_t kMaxHeaderBytes = 1024 * 1024;\nconstexpr size_t kIoBufferSize = 16 * 1024;\nconstexpr size_t kDefaultPoolMaxIdlePerKey = 8;\nconstexpr size_t kDefaultPoolMaxIdleTotal = 256;\nconstexpr int kDefaultPoolIdleTimeoutMs = 15'000;\nconstexpr int kDefaultPoolMaxAgeMs = 120'000;\nconstexpr int kDefaultUpstreamConnectTimeoutMs = 10'000;\nconstexpr int kDefaultUpstreamIoTimeoutMs = 15'000;\nconstexpr int kDefaultClientIoTimeoutMs = 30'000;\nconstexpr int kDefaultMaxActiveClients = 128;\nconstexpr int kDefaultRouteReloadCheckIntervalMs = 100;\n\nstd::atomic g_running{true};\nint g_listen_fd = -1;\nstd::string g_pidfile;\nstd::atomic g_active_clients{0};\nstd::atomic g_overload_rejections{0};\nsize_t g_pool_max_idle_per_key = kDefaultPoolMaxIdlePerKey;\nsize_t g_pool_max_idle_total = kDefaultPoolMaxIdleTotal;\nstd::chrono::milliseconds g_pool_idle_timeout{kDefaultPoolIdleTimeoutMs};\nstd::chrono::milliseconds g_pool_max_age{kDefaultPoolMaxAgeMs};\nint g_upstream_connect_timeout_ms = kDefaultUpstreamConnectTimeoutMs;\nint g_upstream_io_timeout_ms = kDefaultUpstreamIoTimeoutMs;\nint g_client_io_timeout_ms = kDefaultClientIoTimeoutMs;\nint g_max_active_clients = kDefaultMaxActiveClients;\n\nbool try_acquire_client_slot() {\n int prev = g_active_clients.fetch_add(1, std::memory_order_acq_rel);\n if (prev >= g_max_active_clients) {\n g_active_clients.fetch_sub(1, std::memory_order_acq_rel);\n g_overload_rejections.fetch_add(1, std::memory_order_relaxed);\n return false;\n }\n return true;\n}\n\nvoid release_client_slot() {\n g_active_clients.fetch_sub(1, std::memory_order_acq_rel);\n}\n\nstd::string trim(const std::string& s) {\n size_t begin = 0;\n while (begin < s.size() && std::isspace(static_cast(s[begin]))) {\n begin++;\n }\n size_t end = s.size();\n while (end > begin && std::isspace(static_cast(s[end - 1]))) {\n end--;\n }\n return s.substr(begin, end - begin);\n}\n\nstd::string to_lower(std::string s) {\n std::transform(s.begin(), s.end(), s.begin(), [](unsigned char ch) {\n return static_cast(std::tolower(ch));\n });\n return s;\n}\n\nstd::string strip_port_from_host(const std::string& host) {\n auto pos = host.find(':');\n if (pos == std::string::npos) {\n return host;\n }\n return host.substr(0, pos);\n}\n\nbool parse_host_port(const std::string& target, std::string& host, int& port) {\n auto pos = target.rfind(':');\n if (pos == std::string::npos || pos == 0 || pos + 1 >= target.size()) {\n return false;\n }\n host = target.substr(0, pos);\n try {\n port = std::stoi(target.substr(pos + 1));\n } catch (...) {\n return false;\n }\n return port >= 1 && port <= 65535;\n}\n\nbool send_all(int fd, const char* data, size_t len) {\n size_t off = 0;\n while (off < len) {\n ssize_t n = ::send(fd, data + off, len - off, 0);\n if (n <= 0) {\n if (errno == EINTR) {\n continue;\n }\n return false;\n }\n off += static_cast(n);\n }\n return true;\n}\n\nbool send_all(int fd, const std::string& data) {\n return send_all(fd, data.data(), data.size());\n}\n\nvoid send_simple_response(int fd, int status, const std::string& reason, const std::string& body) {\n std::ostringstream out;\n out << \"HTTP/1.1 \" << status << \" \" << reason << \"\\r\\n\"\n << kHeaderName << \": \" << kHeaderValue << \"\\r\\n\"\n << \"Content-Type: text/plain; charset=utf-8\\r\\n\"\n << \"Content-Length: \" << body.size() << \"\\r\\n\"\n << \"Connection: close\\r\\n\\r\\n\"\n << body;\n (void)send_all(fd, out.str());\n}\n\nstruct Request {\n std::string method;\n std::string path;\n std::string version;\n std::vector> headers;\n std::unordered_map headers_lc;\n std::string body;\n std::string leftover;\n std::string normalized_host;\n bool chunked = false;\n bool client_wants_keepalive = false;\n};\n\nbool iequals_ascii(std::string_view a, std::string_view b) {\n if (a.size() != b.size()) {\n return false;\n }\n for (size_t i = 0; i < a.size(); ++i) {\n const unsigned char ac = static_cast(a[i]);\n const unsigned char bc = static_cast(b[i]);\n if (std::tolower(ac) != std::tolower(bc)) {\n return false;\n }\n }\n return true;\n}\n\nbool should_skip_forward_header(std::string_view key) {\n return iequals_ascii(key, \"host\") || iequals_ascii(key, \"connection\") ||\n iequals_ascii(key, \"proxy-connection\") || iequals_ascii(key, \"x-forwarded-for\") ||\n iequals_ascii(key, \"x-forwarded-host\") || iequals_ascii(key, \"x-forwarded-proto\") ||\n iequals_ascii(key, \"content-length\") || iequals_ascii(key, \"transfer-encoding\");\n}\n\nbool request_wants_keepalive(const Request& req) {\n bool connection_close = false;\n bool connection_keepalive = false;\n if (auto it = req.headers_lc.find(\"connection\"); it != req.headers_lc.end()) {\n const std::string connection = to_lower(it->second);\n connection_close = connection.find(\"close\") != std::string::npos;\n connection_keepalive = connection.find(\"keep-alive\") != std::string::npos;\n }\n\n const std::string version = to_lower(req.version);\n if (version == \"http/1.1\") {\n return !connection_close;\n }\n if (version == \"http/1.0\") {\n return connection_keepalive;\n }\n return false;\n}\n\nbool recv_append(int fd, std::string& buf, std::string& error) {\n char tmp[kIoBufferSize];\n while (true) {\n ssize_t n = ::recv(fd, tmp, sizeof(tmp), 0);\n if (n == 0) {\n error = \"client closed connection\";\n return false;\n }\n if (n < 0) {\n if (errno == EINTR) {\n continue;\n }\n error = std::string(\"recv failed: \") + std::strerror(errno);\n return false;\n }\n buf.append(tmp, static_cast(n));\n return true;\n }\n}\n\nbool ensure_bytes_available(int fd, std::string& buf, size_t need, std::string& error) {\n while (buf.size() < need) {\n if (!recv_append(fd, buf, error)) {\n return false;\n }\n }\n return true;\n}\n\nbool decode_chunked_body(int fd, std::string initial, std::string& out_body, std::string& leftover,\n std::string& error) {\n out_body.clear();\n size_t cursor = 0;\n std::string buf = std::move(initial);\n\n for (;;) {\n while (true) {\n auto line_end = buf.find(\"\\r\\n\", cursor);\n if (line_end != std::string::npos) {\n const std::string line = trim(buf.substr(cursor, line_end - cursor));\n cursor = line_end + 2;\n\n const auto semi = line.find(';');\n const std::string size_str = semi == std::string::npos ? line : line.substr(0, semi);\n size_t chunk_size = 0;\n try {\n chunk_size = static_cast(std::stoull(size_str, nullptr, 16));\n } catch (...) {\n error = \"invalid chunk size\";\n return false;\n }\n\n if (!ensure_bytes_available(fd, buf, cursor + chunk_size + 2, error)) {\n return false;\n }\n\n if (chunk_size == 0) {\n // Consume trailer headers until empty line.\n for (;;) {\n auto trailer_end = buf.find(\"\\r\\n\", cursor);\n while (trailer_end == std::string::npos) {\n if (!recv_append(fd, buf, error)) {\n return false;\n }\n trailer_end = buf.find(\"\\r\\n\", cursor);\n }\n const std::string trailer_line = buf.substr(cursor, trailer_end - cursor);\n cursor = trailer_end + 2;\n if (trailer_line.empty()) {\n leftover = buf.substr(cursor);\n return true;\n }\n }\n }\n\n out_body.append(buf, cursor, chunk_size);\n cursor += chunk_size;\n if (buf.substr(cursor, 2) != \"\\r\\n\") {\n error = \"invalid chunk terminator\";\n return false;\n }\n cursor += 2;\n\n break;\n }\n if (!recv_append(fd, buf, error)) {\n return false;\n }\n }\n }\n}\n\nbool read_request(int client_fd, std::string& pending, Request& req, std::string& error) {\n req = Request{};\n std::string buf = std::move(pending);\n pending.clear();\n if (buf.capacity() < 8192) {\n buf.reserve(8192);\n }\n\n char tmp[kIoBufferSize];\n size_t header_end = std::string::npos;\n while (true) {\n header_end = buf.find(\"\\r\\n\\r\\n\");\n if (header_end != std::string::npos) {\n break;\n }\n if (buf.size() > kMaxHeaderBytes) {\n error = \"request headers too large\";\n return false;\n }\n\n ssize_t n = ::recv(client_fd, tmp, sizeof(tmp), 0);\n if (n == 0) {\n error = \"client closed before request\";\n return false;\n }\n if (n < 0) {\n if (errno == EINTR) {\n continue;\n }\n error = std::string(\"recv failed: \") + std::strerror(errno);\n return false;\n }\n buf.append(tmp, static_cast(n));\n }\n\n const size_t headers_len = header_end + 4;\n std::string headers_blob = buf.substr(0, headers_len);\n\n std::istringstream header_stream(headers_blob);\n std::string line;\n\n if (!std::getline(header_stream, line)) {\n error = \"missing request line\";\n return false;\n }\n if (!line.empty() && line.back() == '\\r') {\n line.pop_back();\n }\n\n {\n std::istringstream rl(line);\n if (!(rl >> req.method >> req.path >> req.version)) {\n error = \"invalid request line\";\n return false;\n }\n }\n\n while (std::getline(header_stream, line)) {\n if (!line.empty() && line.back() == '\\r') {\n line.pop_back();\n }\n if (line.empty()) {\n break;\n }\n auto pos = line.find(':');\n if (pos == std::string::npos) {\n continue;\n }\n std::string key = trim(line.substr(0, pos));\n std::string val = trim(line.substr(pos + 1));\n req.headers.emplace_back(key, val);\n req.headers_lc[to_lower(key)] = val;\n }\n\n if (auto host_it = req.headers_lc.find(\"host\"); host_it != req.headers_lc.end()) {\n req.normalized_host = to_lower(strip_port_from_host(trim(host_it->second)));\n }\n\n bool chunked = false;\n size_t content_length = 0;\n if (auto it = req.headers_lc.find(\"content-length\"); it != req.headers_lc.end()) {\n try {\n content_length = static_cast(std::stoul(it->second));\n } catch (...) {\n error = \"invalid content-length\";\n return false;\n }\n }\n\n if (auto it = req.headers_lc.find(\"transfer-encoding\"); it != req.headers_lc.end()) {\n if (to_lower(it->second).find(\"chunked\") != std::string::npos) {\n chunked = true;\n }\n }\n req.chunked = chunked;\n\n std::string initial = buf.substr(headers_len);\n if (chunked) {\n const bool ok = decode_chunked_body(client_fd, std::move(initial), req.body, req.leftover, error);\n if (ok) {\n req.client_wants_keepalive = request_wants_keepalive(req);\n pending = req.leftover;\n }\n return ok;\n }\n\n if (initial.size() >= content_length) {\n req.body = initial.substr(0, content_length);\n req.leftover = initial.substr(content_length);\n req.client_wants_keepalive = request_wants_keepalive(req);\n pending = req.leftover;\n return true;\n }\n\n req.body = std::move(initial);\n req.body.reserve(content_length);\n while (req.body.size() < content_length) {\n ssize_t n = ::recv(client_fd, tmp, sizeof(tmp), 0);\n if (n <= 0) {\n if (n < 0 && errno == EINTR) {\n continue;\n }\n error = \"client closed before full request body\";\n return false;\n }\n req.body.append(tmp, static_cast(n));\n }\n if (req.body.size() > content_length) {\n req.leftover = req.body.substr(content_length);\n req.body.resize(content_length);\n }\n req.client_wants_keepalive = request_wants_keepalive(req);\n pending = req.leftover;\n return true;\n}\n\nclass RouteTable {\n public:\n explicit RouteTable(std::string routes_path) : routes_path_(std::move(routes_path)) {}\n\n std::optional lookup(const std::string& host) {\n reload_if_needed();\n std::lock_guard lock(mu_);\n auto it = routes_.find(to_lower(host));\n if (it == routes_.end()) {\n return std::nullopt;\n }\n return it->second;\n }\n\n size_t size() {\n reload_if_needed();\n std::lock_guard lock(mu_);\n return routes_.size();\n }\n\n private:\n void reload_if_needed() {\n const auto now = std::chrono::steady_clock::now();\n {\n std::lock_guard lock(mu_);\n if (loaded_ &&\n now - last_reload_check_ <\n std::chrono::milliseconds(kDefaultRouteReloadCheckIntervalMs)) {\n return;\n }\n last_reload_check_ = now;\n }\n\n std::error_code ec;\n auto current = std::filesystem::last_write_time(routes_path_, ec);\n if (ec) {\n return;\n }\n\n {\n std::lock_guard lock(mu_);\n if (loaded_ && current == mtime_) {\n return;\n }\n }\n\n std::ifstream in(routes_path_);\n if (!in) {\n return;\n }\n\n std::ostringstream raw;\n raw << in.rdbuf();\n\n std::unordered_map parsed;\n static const std::regex pair_re(\"\\\\\\\"([^\\\\\\\"]+)\\\\\\\"\\\\s*:\\\\s*\\\\\\\"([^\\\\\\\"]*)\\\\\\\"\");\n\n const std::string content = raw.str();\n auto begin = std::sregex_iterator(content.begin(), content.end(), pair_re);\n auto end = std::sregex_iterator();\n for (auto it = begin; it != end; ++it) {\n const std::string host = to_lower((*it)[1].str());\n const std::string target = trim((*it)[2].str());\n if (!host.empty() && !target.empty()) {\n parsed[host] = target;\n }\n }\n\n std::lock_guard lock(mu_);\n routes_ = std::move(parsed);\n mtime_ = current;\n loaded_ = true;\n }\n\n std::string routes_path_;\n std::unordered_map routes_;\n std::filesystem::file_time_type mtime_{};\n std::chrono::steady_clock::time_point last_reload_check_{};\n bool loaded_ = false;\n std::mutex mu_;\n};\n\nvoid set_common_socket_opts(int fd) {\n int one = 1;\n (void)setsockopt(fd, IPPROTO_TCP, TCP_NODELAY, &one, sizeof(one));\n (void)setsockopt(fd, SOL_SOCKET, SO_KEEPALIVE, &one, sizeof(one));\n}\n\nvoid set_socket_timeouts_ms(int fd, int timeout_ms) {\n timeval tv{};\n tv.tv_sec = timeout_ms / 1000;\n tv.tv_usec = (timeout_ms % 1000) * 1000;\n (void)setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));\n (void)setsockopt(fd, SOL_SOCKET, SO_SNDTIMEO, &tv, sizeof(tv));\n}\n\nbool set_nonblocking(int fd, bool nonblocking) {\n int flags = fcntl(fd, F_GETFL, 0);\n if (flags < 0) {\n return false;\n }\n if (nonblocking) {\n flags |= O_NONBLOCK;\n } else {\n flags &= ~O_NONBLOCK;\n }\n return fcntl(fd, F_SETFL, flags) == 0;\n}\n\nbool connect_with_timeout(int fd, const sockaddr* addr, socklen_t addrlen, int timeout_ms) {\n if (!set_nonblocking(fd, true)) {\n return false;\n }\n int rc = connect(fd, addr, addrlen);\n if (rc == 0) {\n (void)set_nonblocking(fd, false);\n return true;\n }\n if (errno != EINPROGRESS) {\n return false;\n }\n\n pollfd pfd{};\n pfd.fd = fd;\n pfd.events = POLLOUT;\n while (true) {\n int prc = poll(&pfd, 1, timeout_ms);\n if (prc == 0) {\n errno = ETIMEDOUT;\n return false;\n }\n if (prc < 0) {\n if (errno == EINTR) {\n continue;\n }\n return false;\n }\n int so_error = 0;\n socklen_t slen = sizeof(so_error);\n if (getsockopt(fd, SOL_SOCKET, SO_ERROR, &so_error, &slen) < 0) {\n return false;\n }\n if (so_error != 0) {\n errno = so_error;\n return false;\n }\n (void)set_nonblocking(fd, false);\n return true;\n }\n}\n\nint connect_upstream(const std::string& host, int port) {\n struct addrinfo hints;\n std::memset(&hints, 0, sizeof(hints));\n hints.ai_family = AF_UNSPEC;\n hints.ai_socktype = SOCK_STREAM;\n\n struct addrinfo* res = nullptr;\n const std::string port_str = std::to_string(port);\n int rc = getaddrinfo(host.c_str(), port_str.c_str(), &hints, &res);\n if (rc != 0) {\n return -1;\n }\n\n int fd = -1;\n for (auto* p = res; p != nullptr; p = p->ai_next) {\n fd = socket(p->ai_family, p->ai_socktype, p->ai_protocol);\n if (fd < 0) {\n continue;\n }\n set_common_socket_opts(fd);\n if (connect_with_timeout(fd, p->ai_addr, p->ai_addrlen, g_upstream_connect_timeout_ms)) {\n set_socket_timeouts_ms(fd, g_upstream_io_timeout_ms);\n break;\n }\n close(fd);\n fd = -1;\n }\n\n freeaddrinfo(res);\n return fd;\n}\n\nbool socket_is_idle_usable(int fd) {\n char c;\n ssize_t n = recv(fd, &c, 1, MSG_PEEK | MSG_DONTWAIT);\n if (n == 0) {\n return false;\n }\n if (n < 0) {\n if (errno == EAGAIN || errno == EWOULDBLOCK) {\n return true;\n }\n if (errno == EINTR) {\n return socket_is_idle_usable(fd);\n }\n return false;\n }\n // Data pending means stream is not in a clean idle state for reuse.\n return false;\n}\n\nstruct PooledConn {\n int fd = -1;\n std::chrono::steady_clock::time_point created_at{};\n std::chrono::steady_clock::time_point last_used_at{};\n};\n\nclass UpstreamPool {\n public:\n ~UpstreamPool() {\n std::lock_guard lock(mu_);\n for (auto& [_, conns] : by_key_) {\n for (auto& conn : conns) {\n if (conn.fd >= 0) {\n close(conn.fd);\n }\n }\n }\n }\n\n int acquire(const std::string& key, const std::string& host, int port) {\n const auto now = std::chrono::steady_clock::now();\n {\n std::lock_guard lock(mu_);\n reap_locked(now);\n auto it = by_key_.find(key);\n if (it != by_key_.end()) {\n auto& conns = it->second;\n while (!conns.empty()) {\n auto conn = conns.back();\n conns.pop_back();\n idle_total_ = idle_total_ > 0 ? idle_total_ - 1 : 0;\n if (!is_conn_fresh(now, conn) || !socket_is_idle_usable(conn.fd)) {\n close(conn.fd);\n continue;\n }\n return conn.fd;\n }\n }\n }\n return connect_upstream(host, port);\n }\n\n void release(const std::string& key, int fd) {\n if (fd < 0) {\n return;\n }\n if (!socket_is_idle_usable(fd)) {\n close(fd);\n return;\n }\n\n const auto now = std::chrono::steady_clock::now();\n std::lock_guard lock(mu_);\n reap_locked(now);\n if (idle_total_ >= g_pool_max_idle_total) {\n close(fd);\n return;\n }\n auto& conns = by_key_[key];\n if (conns.size() >= g_pool_max_idle_per_key) {\n close(fd);\n return;\n }\n conns.push_back(PooledConn{\n .fd = fd,\n .created_at = now,\n .last_used_at = now,\n });\n idle_total_++;\n }\n\n void discard(int fd) {\n if (fd >= 0) {\n close(fd);\n }\n }\n\n private:\n bool is_conn_fresh(const std::chrono::steady_clock::time_point& now, const PooledConn& conn) {\n if (now - conn.last_used_at > g_pool_idle_timeout) {\n return false;\n }\n if (now - conn.created_at > g_pool_max_age) {\n return false;\n }\n return true;\n }\n\n void reap_locked(const std::chrono::steady_clock::time_point& now) {\n for (auto it = by_key_.begin(); it != by_key_.end();) {\n auto& conns = it->second;\n size_t write = 0;\n for (size_t read = 0; read < conns.size(); ++read) {\n if (!is_conn_fresh(now, conns[read]) || !socket_is_idle_usable(conns[read].fd)) {\n close(conns[read].fd);\n idle_total_ = idle_total_ > 0 ? idle_total_ - 1 : 0;\n continue;\n }\n if (write != read) {\n conns[write] = conns[read];\n }\n write++;\n }\n conns.resize(write);\n if (conns.empty()) {\n it = by_key_.erase(it);\n } else {\n ++it;\n }\n }\n }\n\n std::mutex mu_;\n std::unordered_map> by_key_;\n size_t idle_total_ = 0;\n};\n\nUpstreamPool g_upstream_pool;\n\nbool is_upgrade_request(const Request& req) {\n auto upgrade_it = req.headers_lc.find(\"upgrade\");\n if (upgrade_it == req.headers_lc.end()) {\n return false;\n }\n auto conn_it = req.headers_lc.find(\"connection\");\n if (conn_it == req.headers_lc.end()) {\n return false;\n }\n return to_lower(conn_it->second).find(\"upgrade\") != std::string::npos;\n}\n\nstd::string build_upstream_request(const Request& req, const std::string& host_header,\n bool tunnel_upgrade, bool keepalive_upstream) {\n std::string out;\n out.reserve(512 + req.method.size() + req.path.size() + req.version.size() + req.body.size());\n out.append(req.method).append(\" \").append(req.path).append(\" \").append(req.version).append(\"\\r\\n\");\n\n for (const auto& [key, value] : req.headers) {\n if (should_skip_forward_header(key)) {\n continue;\n }\n out.append(key).append(\": \").append(value).append(\"\\r\\n\");\n }\n\n out.append(\"Host: \").append(host_header).append(\"\\r\\n\");\n auto host_it = req.headers_lc.find(\"host\");\n std::string original_host = host_it == req.headers_lc.end() ? host_header : host_it->second;\n out.append(\"X-Forwarded-Host: \").append(original_host).append(\"\\r\\n\");\n out.append(\"X-Forwarded-Proto: http\\r\\n\");\n if (tunnel_upgrade) {\n auto up_it = req.headers_lc.find(\"upgrade\");\n std::string up = up_it == req.headers_lc.end() ? \"websocket\" : up_it->second;\n out.append(\"Connection: Upgrade\\r\\n\");\n out.append(\"Upgrade: \").append(up).append(\"\\r\\n\");\n out.append(\"\\r\\n\");\n } else {\n out.append(\"Connection: \").append(keepalive_upstream ? \"keep-alive\" : \"close\").append(\"\\r\\n\");\n out.append(\"Content-Length: \").append(std::to_string(req.body.size())).append(\"\\r\\n\\r\\n\");\n out.append(req.body);\n }\n return out;\n}\n\nvoid shutdown_quiet(int fd, int how) {\n if (fd >= 0) {\n (void)shutdown(fd, how);\n }\n}\n\nvoid pump_fd(int src, int dst, std::atomic& done) {\n char buf[kIoBufferSize];\n while (!done.load()) {\n ssize_t n = recv(src, buf, sizeof(buf), 0);\n if (n == 0) {\n break;\n }\n if (n < 0) {\n if (errno == EINTR) {\n continue;\n }\n break;\n }\n if (!send_all(dst, buf, static_cast(n))) {\n break;\n }\n }\n done.store(true);\n shutdown_quiet(dst, SHUT_WR);\n shutdown_quiet(src, SHUT_RD);\n}\n\nvoid tunnel_bidirectional(int a_fd, int b_fd) {\n std::atomic done{false};\n std::thread upstream_to_client([&]() { pump_fd(b_fd, a_fd, done); });\n pump_fd(a_fd, b_fd, done);\n upstream_to_client.join();\n}\n\nstruct ResponseMeta {\n int status_code = 0;\n bool chunked = false;\n bool connection_close = false;\n bool no_body = false;\n std::optional content_length;\n};\n\nbool parse_response_headers(const std::string& raw_headers, const std::string& req_method, ResponseMeta& out) {\n std::istringstream s(raw_headers);\n std::string line;\n if (!std::getline(s, line)) {\n return false;\n }\n if (!line.empty() && line.back() == '\\r') {\n line.pop_back();\n }\n {\n std::istringstream first(line);\n std::string http_version;\n if (!(first >> http_version >> out.status_code)) {\n return false;\n }\n }\n\n while (std::getline(s, line)) {\n if (!line.empty() && line.back() == '\\r') {\n line.pop_back();\n }\n if (line.empty()) {\n break;\n }\n auto pos = line.find(':');\n if (pos == std::string::npos) {\n continue;\n }\n auto key = to_lower(trim(line.substr(0, pos)));\n auto val = to_lower(trim(line.substr(pos + 1)));\n if (key == \"transfer-encoding\" && val.find(\"chunked\") != std::string::npos) {\n out.chunked = true;\n } else if (key == \"content-length\") {\n try {\n out.content_length = static_cast(std::stoull(val));\n } catch (...) {\n return false;\n }\n } else if (key == \"connection\" && val.find(\"close\") != std::string::npos) {\n out.connection_close = true;\n }\n }\n\n const std::string method = to_lower(req_method);\n const bool informational = out.status_code >= 100 && out.status_code < 200 && out.status_code != 101;\n out.no_body = (method == \"head\") || informational || out.status_code == 204 || out.status_code == 304;\n if (out.no_body) {\n out.chunked = false;\n out.content_length = 0;\n }\n return true;\n}\n\nbool recv_append_upstream(int fd, std::string& buf) {\n char tmp[kIoBufferSize];\n while (true) {\n ssize_t n = recv(fd, tmp, sizeof(tmp), 0);\n if (n == 0) {\n return false;\n }\n if (n < 0) {\n if (errno == EINTR) {\n continue;\n }\n return false;\n }\n buf.append(tmp, static_cast(n));\n return true;\n }\n}\n\nbool relay_body_with_length(int upstream_fd, int client_fd, std::string body_buf, size_t body_len) {\n size_t sent = 0;\n if (!body_buf.empty()) {\n size_t first = std::min(body_buf.size(), body_len);\n if (first > 0 && !send_all(client_fd, body_buf.data(), first)) {\n return false;\n }\n sent += first;\n if (body_buf.size() > body_len) {\n return false;\n }\n }\n\n char tmp[kIoBufferSize];\n while (sent < body_len) {\n ssize_t n = recv(upstream_fd, tmp, sizeof(tmp), 0);\n if (n == 0) {\n return false;\n }\n if (n < 0) {\n if (errno == EINTR) {\n continue;\n }\n return false;\n }\n size_t to_send = std::min(static_cast(n), body_len - sent);\n if (!send_all(client_fd, tmp, to_send)) {\n return false;\n }\n sent += to_send;\n if (static_cast(n) > to_send) {\n // Unexpected bytes beyond declared content-length. Treat as non-reusable.\n return false;\n }\n }\n return true;\n}\n\nbool relay_chunked_body(int upstream_fd, int client_fd, std::string buf) {\n size_t cursor = 0;\n for (;;) {\n while (true) {\n auto line_end = buf.find(\"\\r\\n\", cursor);\n if (line_end == std::string::npos) {\n if (!recv_append_upstream(upstream_fd, buf)) {\n return false;\n }\n continue;\n }\n\n const std::string line = trim(buf.substr(cursor, line_end - cursor));\n const auto semi = line.find(';');\n const std::string size_str = semi == std::string::npos ? line : line.substr(0, semi);\n size_t chunk_size = 0;\n try {\n chunk_size = static_cast(std::stoull(size_str, nullptr, 16));\n } catch (...) {\n return false;\n }\n\n const size_t chunk_prefix = line_end + 2;\n while (buf.size() < chunk_prefix + chunk_size + 2) {\n if (!recv_append_upstream(upstream_fd, buf)) {\n return false;\n }\n }\n if (buf.substr(chunk_prefix + chunk_size, 2) != \"\\r\\n\") {\n return false;\n }\n\n if (!send_all(client_fd, buf.data() + cursor, chunk_prefix + chunk_size + 2 - cursor)) {\n return false;\n }\n cursor = chunk_prefix + chunk_size + 2;\n\n if (chunk_size == 0) {\n // Forward trailers and ending CRLF.\n auto trailer_end = buf.find(\"\\r\\n\\r\\n\", cursor);\n while (trailer_end == std::string::npos) {\n if (!recv_append_upstream(upstream_fd, buf)) {\n return false;\n }\n trailer_end = buf.find(\"\\r\\n\\r\\n\", cursor);\n }\n const size_t end = trailer_end + 4;\n if (!send_all(client_fd, buf.data() + cursor, end - cursor)) {\n return false;\n }\n return end == buf.size();\n }\n break;\n }\n }\n}\n\nstruct RelayOutcome {\n bool upstream_reusable = false;\n bool client_can_keepalive = false;\n};\n\nRelayOutcome relay_response_and_decide_reuse(int upstream_fd, int client_fd, const std::string& req_method) {\n std::string buf;\n buf.reserve(8192);\n size_t header_end = std::string::npos;\n while (header_end == std::string::npos) {\n header_end = buf.find(\"\\r\\n\\r\\n\");\n if (header_end != std::string::npos) {\n break;\n }\n if (!recv_append_upstream(upstream_fd, buf)) {\n return {};\n }\n if (buf.size() > kMaxHeaderBytes) {\n return {};\n }\n }\n\n const size_t hdr_len = header_end + 4;\n const std::string raw_headers = buf.substr(0, hdr_len);\n ResponseMeta meta;\n if (!parse_response_headers(raw_headers, req_method, meta)) {\n return {};\n }\n if (!send_all(client_fd, raw_headers)) {\n return {};\n }\n\n std::string body_buf = buf.substr(hdr_len);\n if (meta.no_body) {\n if (!body_buf.empty()) {\n if (!send_all(client_fd, body_buf)) {\n return {};\n }\n return {};\n }\n return {\n .upstream_reusable = !meta.connection_close,\n .client_can_keepalive = !meta.connection_close,\n };\n }\n\n if (meta.chunked) {\n bool complete = relay_chunked_body(upstream_fd, client_fd, std::move(body_buf));\n const bool keepalive = complete && !meta.connection_close;\n return {\n .upstream_reusable = keepalive,\n .client_can_keepalive = keepalive,\n };\n }\n\n if (meta.content_length.has_value()) {\n bool ok = relay_body_with_length(upstream_fd, client_fd, std::move(body_buf), *meta.content_length);\n const bool keepalive = ok && !meta.connection_close;\n return {\n .upstream_reusable = keepalive,\n .client_can_keepalive = keepalive,\n };\n }\n\n // Unknown body framing: read until close and do not reuse socket.\n if (!body_buf.empty() && !send_all(client_fd, body_buf)) {\n return {};\n }\n char tmp[kIoBufferSize];\n while (true) {\n ssize_t n = recv(upstream_fd, tmp, sizeof(tmp), 0);\n if (n == 0) {\n break;\n }\n if (n < 0) {\n if (errno == EINTR) {\n continue;\n }\n return {};\n }\n if (!send_all(client_fd, tmp, static_cast(n))) {\n return {};\n }\n }\n return {};\n}\n\nvoid handle_client(int client_fd, RouteTable& routes) {\n std::string pending;\n int cached_upstream_fd = -1;\n std::string cached_upstream_key;\n auto discard_cached = [&]() {\n if (cached_upstream_fd >= 0) {\n g_upstream_pool.discard(cached_upstream_fd);\n cached_upstream_fd = -1;\n cached_upstream_key.clear();\n }\n };\n auto release_cached = [&]() {\n if (cached_upstream_fd >= 0 && !cached_upstream_key.empty()) {\n g_upstream_pool.release(cached_upstream_key, cached_upstream_fd);\n cached_upstream_fd = -1;\n cached_upstream_key.clear();\n }\n };\n\n while (g_running.load(std::memory_order_relaxed)) {\n Request req;\n std::string parse_error;\n if (!read_request(client_fd, pending, req, parse_error)) {\n if (!parse_error.empty() && parse_error != \"client closed before request\" &&\n parse_error != \"client closed connection\") {\n send_simple_response(client_fd, 400, \"Bad Request\", parse_error + \"\\n\");\n }\n break;\n }\n\n if (req.path == \"/_flow/domains/health\") {\n std::ostringstream body;\n body << \"ok active_clients=\" << g_active_clients.load(std::memory_order_relaxed)\n << \" overload_rejections=\" << g_overload_rejections.load(std::memory_order_relaxed)\n << \" max_active_clients=\" << g_max_active_clients\n << \" upstream_connect_timeout_ms=\" << g_upstream_connect_timeout_ms\n << \" upstream_io_timeout_ms=\" << g_upstream_io_timeout_ms\n << \" client_io_timeout_ms=\" << g_client_io_timeout_ms\n << \" pool_max_idle_per_key=\" << g_pool_max_idle_per_key\n << \" pool_max_idle_total=\" << g_pool_max_idle_total\n << \" pool_idle_timeout_ms=\" << g_pool_idle_timeout.count()\n << \" pool_max_age_ms=\" << g_pool_max_age.count()\n << \"\\n\";\n const auto body_s = body.str();\n std::ostringstream out;\n out << \"HTTP/1.1 200 OK\\r\\n\"\n << kHeaderName << \": \" << kHeaderValue << \"\\r\\n\"\n << \"Content-Type: text/plain; charset=utf-8\\r\\n\"\n << \"Content-Length: \" << body_s.size() << \"\\r\\n\"\n << \"Connection: \" << (req.client_wants_keepalive ? \"keep-alive\" : \"close\")\n << \"\\r\\n\\r\\n\"\n << body_s;\n if (!send_all(client_fd, out.str()) || !req.client_wants_keepalive) {\n break;\n }\n continue;\n }\n\n if (req.normalized_host.empty()) {\n send_simple_response(client_fd, 400, \"Bad Request\", \"Missing Host header\\n\");\n break;\n }\n\n const std::string& req_host = req.normalized_host;\n auto target = routes.lookup(req_host);\n if (!target.has_value()) {\n std::ostringstream body;\n body << \"No local route configured for \" << req_host << \"\\n\";\n send_simple_response(client_fd, 404, \"Not Found\", body.str());\n break;\n }\n\n std::string upstream_host;\n int upstream_port = 0;\n if (!parse_host_port(*target, upstream_host, upstream_port)) {\n send_simple_response(client_fd, 502, \"Bad Gateway\", \"Invalid target route\\n\");\n break;\n }\n\n const bool upgrade = is_upgrade_request(req);\n const std::string upstream_key = upstream_host + \":\" + std::to_string(upstream_port);\n if (upgrade) {\n // Upgrade tunnels are one-shot; keepalive cache is irrelevant.\n release_cached();\n }\n\n bool used_cached = false;\n int upstream_fd = -1;\n if (!upgrade && cached_upstream_fd >= 0 && cached_upstream_key == upstream_key) {\n upstream_fd = cached_upstream_fd;\n used_cached = true;\n } else {\n if (!upgrade) {\n release_cached();\n }\n upstream_fd =\n upgrade ? connect_upstream(upstream_host, upstream_port)\n : g_upstream_pool.acquire(upstream_key, upstream_host, upstream_port);\n }\n\n if (upstream_fd < 0) {\n if (errno == ETIMEDOUT) {\n send_simple_response(client_fd, 504, \"Gateway Timeout\", \"Upstream connect timed out\\n\");\n } else {\n send_simple_response(client_fd, 502, \"Bad Gateway\", \"Upstream connection failed\\n\");\n }\n break;\n }\n\n std::string host_header =\n (upstream_host == \"127.0.0.1\" || upstream_host == \"::1\") ? \"localhost\" : upstream_host;\n std::string upstream_req = build_upstream_request(req, host_header, upgrade, true);\n if (!send_all(upstream_fd, upstream_req)) {\n // Stale keepalive sockets can fail first write; retry once with fresh socket.\n if (!upgrade && used_cached) {\n discard_cached();\n upstream_fd = g_upstream_pool.acquire(upstream_key, upstream_host, upstream_port);\n if (upstream_fd >= 0 && send_all(upstream_fd, upstream_req)) {\n used_cached = false;\n } else if (upstream_fd >= 0) {\n g_upstream_pool.discard(upstream_fd);\n upstream_fd = -1;\n }\n } else if (upgrade) {\n close(upstream_fd);\n upstream_fd = -1;\n } else {\n g_upstream_pool.discard(upstream_fd);\n upstream_fd = -1;\n }\n\n if (upstream_fd < 0) {\n send_simple_response(client_fd, 502, \"Bad Gateway\", \"Failed to forward request\\n\");\n break;\n }\n }\n\n if (upgrade) {\n if (!req.leftover.empty() && !send_all(upstream_fd, req.leftover)) {\n close(upstream_fd);\n break;\n }\n tunnel_bidirectional(client_fd, upstream_fd);\n close(upstream_fd);\n break;\n }\n\n RelayOutcome relay = relay_response_and_decide_reuse(upstream_fd, client_fd, req.method);\n if (relay.upstream_reusable) {\n cached_upstream_fd = upstream_fd;\n cached_upstream_key = upstream_key;\n } else {\n g_upstream_pool.discard(upstream_fd);\n if (used_cached) {\n cached_upstream_fd = -1;\n cached_upstream_key.clear();\n }\n }\n\n if (!(req.client_wants_keepalive && relay.client_can_keepalive)) {\n break;\n }\n }\n release_cached();\n close(client_fd);\n}\n\nbool parse_listen(const std::string& listen, std::string& host, int& port) {\n return parse_host_port(listen, host, port);\n}\n\nbool parse_u64_arg(const std::string& raw, uint64_t& out) {\n if (raw.empty()) {\n return false;\n }\n size_t idx = 0;\n try {\n out = std::stoull(raw, &idx, 10);\n } catch (...) {\n return false;\n }\n return idx == raw.size();\n}\n\nbool assign_positive_int(const std::string& value, int& target) {\n uint64_t parsed = 0;\n if (!parse_u64_arg(value, parsed) || parsed == 0 || parsed > static_cast(INT32_MAX)) {\n return false;\n }\n target = static_cast(parsed);\n return true;\n}\n\nbool assign_positive_size(const std::string& value, size_t& target) {\n uint64_t parsed = 0;\n if (!parse_u64_arg(value, parsed) || parsed == 0 ||\n parsed > static_cast(std::numeric_limits::max())) {\n return false;\n }\n target = static_cast(parsed);\n return true;\n}\n\nvoid cleanup_pidfile() {\n if (!g_pidfile.empty()) {\n std::error_code ec;\n std::filesystem::remove(g_pidfile, ec);\n }\n}\n\nvoid on_signal(int) {\n g_running.store(false);\n if (g_listen_fd >= 0) {\n close(g_listen_fd);\n g_listen_fd = -1;\n }\n}\n\nint start_listener(const std::string& host, int port) {\n int fd = socket(AF_INET, SOCK_STREAM, 0);\n if (fd < 0) {\n return -1;\n }\n\n int opt = 1;\n if (setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt)) < 0) {\n close(fd);\n return -1;\n }\n\n sockaddr_in addr{};\n addr.sin_family = AF_INET;\n addr.sin_port = htons(static_cast(port));\n if (inet_pton(AF_INET, host.c_str(), &addr.sin_addr) != 1) {\n close(fd);\n return -1;\n }\n\n if (bind(fd, reinterpret_cast(&addr), sizeof(addr)) < 0) {\n close(fd);\n return -1;\n }\n\n if (listen(fd, 256) < 0) {\n close(fd);\n return -1;\n }\n\n return fd;\n}\n\nint start_listener_from_launchd_socket(const std::string& socket_name) {\n#ifdef __APPLE__\n int* fds = nullptr;\n size_t count = 0;\n const int rc = launch_activate_socket(socket_name.c_str(), &fds, &count);\n if (rc != 0) {\n errno = rc;\n return -1;\n }\n if (count == 0 || fds == nullptr) {\n errno = ENOENT;\n return -1;\n }\n int fd = fds[0];\n for (size_t i = 1; i < count; ++i) {\n if (fds[i] >= 0) {\n close(fds[i]);\n }\n }\n std::free(fds);\n return fd;\n#else\n (void)socket_name;\n errno = ENOTSUP;\n return -1;\n#endif\n}\n\nvoid print_usage(const char* argv0) {\n std::cerr << \"Usage: \" << argv0\n << \" --listen 127.0.0.1:80 --routes --pidfile [options]\\n\"\n << \"Options:\\n\"\n << \" --launchd-socket (macOS only)\\n\"\n << \" --max-active-clients \\n\"\n << \" --upstream-connect-timeout-ms \\n\"\n << \" --upstream-io-timeout-ms \\n\"\n << \" --client-io-timeout-ms \\n\"\n << \" --pool-max-idle-per-key \\n\"\n << \" --pool-max-idle-total \\n\"\n << \" --pool-idle-timeout-ms \\n\"\n << \" --pool-max-age-ms \\n\";\n}\n\n} // namespace\n\nint main(int argc, char** argv) {\n std::string listen = \"127.0.0.1:80\";\n std::string routes_path;\n std::string pidfile;\n std::string launchd_socket_name;\n\n for (int i = 1; i < argc; ++i) {\n std::string arg = argv[i];\n if ((arg == \"-h\") || (arg == \"--help\")) {\n print_usage(argv[0]);\n return 0;\n }\n if (arg == \"--listen\" && i + 1 < argc) {\n listen = argv[++i];\n continue;\n }\n if (arg == \"--routes\" && i + 1 < argc) {\n routes_path = argv[++i];\n continue;\n }\n if (arg == \"--pidfile\" && i + 1 < argc) {\n pidfile = argv[++i];\n continue;\n }\n if (arg == \"--launchd-socket\" && i + 1 < argc) {\n launchd_socket_name = argv[++i];\n continue;\n }\n if (arg == \"--max-active-clients\" && i + 1 < argc) {\n if (!assign_positive_int(argv[++i], g_max_active_clients)) {\n std::cerr << \"Invalid value for --max-active-clients\\n\";\n return 2;\n }\n continue;\n }\n if (arg == \"--upstream-connect-timeout-ms\" && i + 1 < argc) {\n if (!assign_positive_int(argv[++i], g_upstream_connect_timeout_ms)) {\n std::cerr << \"Invalid value for --upstream-connect-timeout-ms\\n\";\n return 2;\n }\n continue;\n }\n if (arg == \"--upstream-io-timeout-ms\" && i + 1 < argc) {\n if (!assign_positive_int(argv[++i], g_upstream_io_timeout_ms)) {\n std::cerr << \"Invalid value for --upstream-io-timeout-ms\\n\";\n return 2;\n }\n continue;\n }\n if (arg == \"--client-io-timeout-ms\" && i + 1 < argc) {\n if (!assign_positive_int(argv[++i], g_client_io_timeout_ms)) {\n std::cerr << \"Invalid value for --client-io-timeout-ms\\n\";\n return 2;\n }\n continue;\n }\n if (arg == \"--pool-max-idle-per-key\" && i + 1 < argc) {\n if (!assign_positive_size(argv[++i], g_pool_max_idle_per_key)) {\n std::cerr << \"Invalid value for --pool-max-idle-per-key\\n\";\n return 2;\n }\n continue;\n }\n if (arg == \"--pool-max-idle-total\" && i + 1 < argc) {\n if (!assign_positive_size(argv[++i], g_pool_max_idle_total)) {\n std::cerr << \"Invalid value for --pool-max-idle-total\\n\";\n return 2;\n }\n continue;\n }\n if (arg == \"--pool-idle-timeout-ms\" && i + 1 < argc) {\n int ms = 0;\n if (!assign_positive_int(argv[++i], ms)) {\n std::cerr << \"Invalid value for --pool-idle-timeout-ms\\n\";\n return 2;\n }\n g_pool_idle_timeout = std::chrono::milliseconds(ms);\n continue;\n }\n if (arg == \"--pool-max-age-ms\" && i + 1 < argc) {\n int ms = 0;\n if (!assign_positive_int(argv[++i], ms)) {\n std::cerr << \"Invalid value for --pool-max-age-ms\\n\";\n return 2;\n }\n g_pool_max_age = std::chrono::milliseconds(ms);\n continue;\n }\n\n std::cerr << \"Unknown or incomplete argument: \" << arg << \"\\n\";\n print_usage(argv[0]);\n return 2;\n }\n\n if (routes_path.empty() || pidfile.empty()) {\n print_usage(argv[0]);\n return 2;\n }\n\n std::string listen_host;\n int listen_port = 0;\n if (!parse_listen(listen, listen_host, listen_port)) {\n std::cerr << \"Invalid --listen value: \" << listen << \"\\n\";\n return 2;\n }\n if (g_pool_max_idle_total < g_pool_max_idle_per_key) {\n g_pool_max_idle_total = g_pool_max_idle_per_key;\n }\n\n g_pidfile = pidfile;\n {\n std::ofstream out(pidfile, std::ios::trunc);\n if (!out) {\n std::cerr << \"Failed to write pid file: \" << pidfile << \"\\n\";\n return 1;\n }\n out << getpid() << \"\\n\";\n }\n\n std::signal(SIGINT, on_signal);\n std::signal(SIGTERM, on_signal);\n\n if (!launchd_socket_name.empty()) {\n g_listen_fd = start_listener_from_launchd_socket(launchd_socket_name);\n } else {\n g_listen_fd = start_listener(listen_host, listen_port);\n }\n if (g_listen_fd < 0) {\n cleanup_pidfile();\n if (!launchd_socket_name.empty()) {\n std::cerr << \"Failed to activate launchd socket '\" << launchd_socket_name << \"' (\"\n << std::strerror(errno) << \")\\n\";\n } else {\n std::cerr << \"Failed to bind \" << listen_host << \":\" << listen_port << \" (\"\n << std::strerror(errno) << \")\\n\";\n }\n return 1;\n }\n\n if (!launchd_socket_name.empty()) {\n std::cerr << \"domainsd-cpp listening via launchd socket '\" << launchd_socket_name << \"'\\n\";\n } else {\n std::cerr << \"domainsd-cpp listening on \" << listen_host << \":\" << listen_port << \"\\n\";\n }\n\n RouteTable routes(routes_path);\n while (g_running.load()) {\n sockaddr_in client_addr{};\n socklen_t client_len = sizeof(client_addr);\n int client_fd = accept(g_listen_fd, reinterpret_cast(&client_addr), &client_len);\n if (client_fd < 0) {\n if (errno == EINTR) {\n continue;\n }\n if (!g_running.load()) {\n break;\n }\n continue;\n }\n\n set_socket_timeouts_ms(client_fd, g_client_io_timeout_ms);\n if (!try_acquire_client_slot()) {\n send_simple_response(client_fd, 503, \"Service Unavailable\",\n \"Proxy overloaded, retry shortly\\n\");\n close(client_fd);\n continue;\n }\n\n std::thread([client_fd, &routes]() {\n struct SlotGuard {\n ~SlotGuard() { release_client_slot(); }\n } guard;\n handle_client(client_fd, routes);\n }).detach();\n }\n\n if (g_listen_fd >= 0) {\n close(g_listen_fd);\n g_listen_fd = -1;\n }\n cleanup_pidfile();\n return 0;\n}\n" }, { "path": "tools/domainsd-cpp/install-macos-launchd.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nif [[ \"$(uname -s)\" != \"Darwin\" ]]; then\n echo \"error: this installer is macOS-only\" >&2\n exit 1\nfi\n\nif [[ \"${1:-}\" == \"-h\" || \"${1:-}\" == \"--help\" ]]; then\n cat <<'EOF'\nInstall native domainsd launchd socket-activation on macOS (port 80, no docker).\n\nUsage:\n sudo ./tools/domainsd-cpp/install-macos-launchd.sh\nEOF\n exit 0\nfi\n\nif [[ \"${EUID}\" -ne 0 ]]; then\n exec sudo \"$0\" \"$@\"\nfi\n\nLABEL=\"dev.flow.domainsd\"\nSOCKET_NAME=\"domainsd\"\nPLIST_PATH=\"/Library/LaunchDaemons/${LABEL}.plist\"\n\nTARGET_USER=\"${SUDO_USER:-}\"\nif [[ -z \"${TARGET_USER}\" ]]; then\n TARGET_USER=\"$(stat -f '%Su' /dev/console)\"\nfi\nif [[ -z \"${TARGET_USER}\" ]]; then\n echo \"error: failed to determine target user\" >&2\n exit 1\nfi\nTARGET_GROUP=\"$(id -gn \"${TARGET_USER}\")\"\nTARGET_HOME=\"$(dscl . -read \"/Users/${TARGET_USER}\" NFSHomeDirectory 2>/dev/null | awk '{print $2}')\"\nif [[ -z \"${TARGET_HOME}\" ]]; then\n TARGET_HOME=\"$(eval echo \"~${TARGET_USER}\")\"\nfi\nif [[ ! -d \"${TARGET_HOME}\" ]]; then\n echo \"error: target home does not exist: ${TARGET_HOME}\" >&2\n exit 1\nfi\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nFLOW_REPO=\"$(cd \"${SCRIPT_DIR}/../..\" && pwd)\"\nSOURCE_PATH=\"${FLOW_REPO}/tools/domainsd-cpp/domainsd.cpp\"\nif [[ ! -f \"${SOURCE_PATH}\" ]]; then\n echo \"error: source missing: ${SOURCE_PATH}\" >&2\n exit 1\nfi\n\nSTATE_ROOT=\"${TARGET_HOME}/Library/Application Support/flow/local-domains\"\nBIN_PATH=\"${STATE_ROOT}/domainsd-cpp\"\nROUTES_PATH=\"${STATE_ROOT}/routes.json\"\nPID_PATH=\"${STATE_ROOT}/domainsd.pid\"\nLOG_PATH=\"${STATE_ROOT}/domainsd.log\"\n\nmkdir -p \"${STATE_ROOT}\"\nif [[ ! -f \"${ROUTES_PATH}\" ]]; then\n printf '{}\\n' > \"${ROUTES_PATH}\"\nfi\ntouch \"${LOG_PATH}\"\nrm -f \"${PID_PATH}\"\n\necho \"[domainsd-launchd] building native daemon...\"\n/usr/bin/clang++ -std=c++20 -O3 -DNDEBUG -Wall -Wextra -pthread \\\n \"${SOURCE_PATH}\" \\\n -o \"${BIN_PATH}\"\n\nchown \"${TARGET_USER}:${TARGET_GROUP}\" \"${BIN_PATH}\" \"${ROUTES_PATH}\" \"${LOG_PATH}\" \"${STATE_ROOT}\"\nchmod 755 \"${BIN_PATH}\"\nchmod 644 \"${ROUTES_PATH}\" \"${LOG_PATH}\"\n\ncat > \"${PLIST_PATH}\" <\n\n\n\n Label\n ${LABEL}\n ProgramArguments\n \n ${BIN_PATH}\n --launchd-socket\n ${SOCKET_NAME}\n --routes\n ${ROUTES_PATH}\n --pidfile\n ${PID_PATH}\n \n UserName\n ${TARGET_USER}\n WorkingDirectory\n ${STATE_ROOT}\n RunAtLoad\n \n KeepAlive\n \n StandardOutPath\n ${LOG_PATH}\n StandardErrorPath\n ${LOG_PATH}\n Sockets\n \n ${SOCKET_NAME}\n \n SockNodeName\n 127.0.0.1\n SockServiceName\n 80\n SockType\n stream\n SockProtocol\n TCP\n \n \n\n\nEOF\n\nchown root:wheel \"${PLIST_PATH}\"\nchmod 644 \"${PLIST_PATH}\"\n\necho \"[domainsd-launchd] loading launchd service...\"\nlaunchctl bootout \"system/${LABEL}\" >/dev/null 2>&1 || true\nlaunchctl bootstrap system \"${PLIST_PATH}\"\nlaunchctl enable \"system/${LABEL}\" >/dev/null 2>&1 || true\nlaunchctl kickstart -k \"system/${LABEL}\"\n\nsleep 0.3\nif curl -fsS \"http://127.0.0.1/_flow/domains/health\" >/dev/null 2>&1; then\n echo \"[domainsd-launchd] health check OK\"\nelse\n echo \"[domainsd-launchd] warning: health check failed, inspect log: ${LOG_PATH}\" >&2\nfi\n\ncat < `host:port`)\n- WebSocket upgrade passthrough (full duplex tunnel)\n- request-side chunked transfer-encoding decode/forward\n- upstream keepalive connection pooling (safe framed-response reuse)\n- overload shedding with bounded active client handlers (`503` when saturated)\n- upstream connect/IO timeouts (`504` for connect timeout)\n- health endpoint: `GET /_flow/domains/health`\n- mtime-based route reload (no daemon restart required)\n- optional macOS launchd socket activation (`--launchd-socket `) for privileged `:80` bind without Docker\n\nRuntime tuning:\n- daemon supports CLI flags (`--max-active-clients`, `--upstream-*-timeout-ms`, `--pool-*`)\n- Flow passes tuning via env vars prefixed `FLOW_DOMAINS_NATIVE_*`\n\nCurrent limitations:\n- no HTTP/2/TLS yet\n\nThe Flow CLI builds this binary automatically with `clang++` when needed.\n\n## macOS native `:80` without Docker\n\nWhen direct bind to `127.0.0.1:80` is blocked by permissions, install launchd socket mode once:\n\n```bash\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\nThis installs `dev.flow.domainsd` in `/Library/LaunchDaemons`, binds port `80` via launchd, and runs `domainsd-cpp` as your user with inherited socket fd.\n\nUninstall:\n\n```bash\nsudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh\n```\n" }, { "path": "tools/domainsd-cpp/uninstall-macos-launchd.sh", "content": "#!/usr/bin/env bash\nset -euo pipefail\n\nif [[ \"$(uname -s)\" != \"Darwin\" ]]; then\n echo \"error: this uninstaller is macOS-only\" >&2\n exit 1\nfi\n\nif [[ \"${EUID}\" -ne 0 ]]; then\n exec sudo \"$0\" \"$@\"\nfi\n\nLABEL=\"dev.flow.domainsd\"\nPLIST_PATH=\"/Library/LaunchDaemons/${LABEL}.plist\"\n\necho \"[domainsd-launchd] unloading service...\"\nlaunchctl bootout \"system/${LABEL}\" >/dev/null 2>&1 || true\nlaunchctl disable \"system/${LABEL}\" >/dev/null 2>&1 || true\n\nif [[ -f \"${PLIST_PATH}\" ]]; then\n rm -f \"${PLIST_PATH}\"\n echo \"[domainsd-launchd] removed ${PLIST_PATH}\"\nfi\n\necho \"[domainsd-launchd] uninstalled.\"\necho \"Note: binary/routes/log files under ~/Library/Application Support/flow/local-domains were kept.\"\n" }, { "path": "vendor.lock.toml", "content": "[flow_vendor]\nrepo = \"https://github.com/nikivdev/flow-vendor.git\"\nbranch = \"main\"\ncheckout = \".vendor/flow-vendor\"\ncommit = \"50060e8f7fbe3eabab911d4943a62698228c9f53\"\n\n[[crate]]\nname = \"axum\"\nrepo_path = \"crates/axum\"\nmanifest_path = \"manifests/axum.toml\"\nmaterialized_path = \"lib/vendor/axum\"\n\n[[crate]]\nname = \"reqwest\"\nrepo_path = \"crates/reqwest\"\nmanifest_path = \"manifests/reqwest.toml\"\nmaterialized_path = \"lib/vendor/reqwest\"\n\n[[crate]]\nname = \"tower-http\"\nrepo_path = \"crates/tower-http\"\nmanifest_path = \"manifests/tower-http.toml\"\nmaterialized_path = \"lib/vendor/tower-http\"\n\n[[crate]]\nname = \"ratatui\"\nrepo_path = \"crates/ratatui\"\nmanifest_path = \"manifests/ratatui.toml\"\nmaterialized_path = \"lib/vendor/ratatui\"\n\n[[crate]]\nname = \"url\"\nrepo_path = \"crates/url\"\nmanifest_path = \"manifests/url.toml\"\nmaterialized_path = \"lib/vendor/url\"\n\n[[crate]]\nname = \"crypto_secretbox\"\nrepo_path = \"crates/crypto_secretbox\"\nmanifest_path = \"manifests/crypto_secretbox.toml\"\nmaterialized_path = \"lib/vendor/crypto_secretbox\"\n\n[[crate]]\nname = \"portable-pty\"\nrepo_path = \"crates/portable-pty\"\nmanifest_path = \"manifests/portable-pty.toml\"\nmaterialized_path = \"lib/vendor/portable-pty\"\n\n[[crate]]\nname = \"tokio-stream\"\nrepo_path = \"crates/tokio-stream\"\nmanifest_path = \"manifests/tokio-stream.toml\"\nmaterialized_path = \"lib/vendor/tokio-stream\"\n\n[[crate]]\nname = \"tracing-subscriber\"\nrepo_path = \"crates/tracing-subscriber\"\nmanifest_path = \"manifests/tracing-subscriber.toml\"\nmaterialized_path = \"lib/vendor/tracing-subscriber\"\n\n[[crate]]\nname = \"futures\"\nrepo_path = \"crates/futures\"\nmanifest_path = \"manifests/futures.toml\"\nmaterialized_path = \"lib/vendor/futures\"\n\n[[crate]]\nname = \"sha1\"\nrepo_path = \"crates/sha1\"\nmanifest_path = \"manifests/sha1.toml\"\nmaterialized_path = \"lib/vendor/sha1\"\n\n[[crate]]\nname = \"sha2\"\nrepo_path = \"crates/sha2\"\nmanifest_path = \"manifests/sha2.toml\"\nmaterialized_path = \"lib/vendor/sha2\"\n\n[[crate]]\nname = \"tokio\"\nrepo_path = \"crates/tokio\"\nmanifest_path = \"manifests/tokio.toml\"\nmaterialized_path = \"lib/vendor/tokio\"\n\n[[crate]]\nname = \"crossterm\"\nrepo_path = \"crates/crossterm\"\nmanifest_path = \"manifests/crossterm.toml\"\nmaterialized_path = \"lib/vendor/crossterm\"\n\n[[crate]]\nname = \"hmac\"\nrepo_path = \"crates/hmac\"\nmanifest_path = \"manifests/hmac.toml\"\nmaterialized_path = \"lib/vendor/hmac\"\n\n[[crate]]\nname = \"toml\"\nrepo_path = \"crates/toml\"\nmanifest_path = \"manifests/toml.toml\"\nmaterialized_path = \"lib/vendor/toml\"\n\n[[crate]]\nname = \"clap\"\nrepo_path = \"crates/clap\"\nmanifest_path = \"manifests/clap.toml\"\nmaterialized_path = \"lib/vendor/clap\"\n\n[[crate]]\nname = \"notify-debouncer-mini\"\nrepo_path = \"crates/notify-debouncer-mini\"\nmanifest_path = \"manifests/notify-debouncer-mini.toml\"\nmaterialized_path = \"lib/vendor/notify-debouncer-mini\"\n\n\n[[crate]]\nname = \"ignore\"\nrepo_path = \"crates/ignore\"\nmanifest_path = \"manifests/ignore.toml\"\nmaterialized_path = \"lib/vendor/ignore\"\n\n[[crate]]\nname = \"x25519-dalek\"\nrepo_path = \"crates/x25519-dalek\"\nmanifest_path = \"manifests/x25519-dalek.toml\"\nmaterialized_path = \"lib/vendor/x25519-dalek\"\n\n[[crate]]\nname = \"rusqlite\"\nrepo_path = \"crates/rusqlite\"\nmanifest_path = \"manifests/rusqlite.toml\"\nmaterialized_path = \"lib/vendor/rusqlite\"\n\n[[crate]]\nname = \"rmp-serde\"\nrepo_path = \"crates/rmp-serde\"\nmanifest_path = \"manifests/rmp-serde.toml\"\nmaterialized_path = \"lib/vendor/rmp-serde\"\n\n[[crate]]\nname = \"ctrlc\"\nrepo_path = \"crates/ctrlc\"\nmanifest_path = \"manifests/ctrlc.toml\"\nmaterialized_path = \"lib/vendor/ctrlc\"\n\n[[crate]]\nname = \"notify\"\nrepo_path = \"crates/notify\"\nmanifest_path = \"manifests/notify.toml\"\nmaterialized_path = \"lib/vendor/notify\"\n\n[[crate]]\nname = \"regex\"\nrepo_path = \"crates/regex\"\nmanifest_path = \"manifests/regex.toml\"\nmaterialized_path = \"lib/vendor/regex\"\n\n[[crate]]\nname = \"serde\"\nrepo_path = \"crates/serde\"\nmanifest_path = \"manifests/serde.toml\"\nmaterialized_path = \"lib/vendor/serde\"\n" } ]