{"id":51943368,"url":"https://github.com/dbcli/symphony-dbcli","last_synced_at":"2026-07-28T21:30:36.748Z","repository":{"id":359881834,"uuid":"1247861915","full_name":"dbcli/symphony-dbcli","owner":"dbcli","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-16T17:31:08.000Z","size":696,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-14T09:39:36.408Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dbcli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-23T22:05:23.000Z","updated_at":"2026-06-16T04:42:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dbcli/symphony-dbcli","commit_stats":null,"previous_names":["amjith/symphony-dbcli","dbcli/symphony-dbcli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dbcli/symphony-dbcli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbcli%2Fsymphony-dbcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbcli%2Fsymphony-dbcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbcli%2Fsymphony-dbcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbcli%2Fsymphony-dbcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbcli","download_url":"https://codeload.github.com/dbcli/symphony-dbcli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbcli%2Fsymphony-dbcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36009144,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-28T02:00:06.341Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-28T21:30:34.523Z","updated_at":"2026-07-28T21:30:36.741Z","avatar_url":"https://github.com/dbcli.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# symphony-dbcli\n\nPython implementation of a Symphony-style worker orchestrator for the DBCLI\nprojects: `dbcli/pgcli`, `dbcli/mycli`, and `dbcli/litecli`.\n\nThe project is intentionally lightweight for the first implementation:\n\n- `uv` and `pyproject.toml` for packaging.\n- `WORKFLOW.md` with a fenced TOML configuration block.\n- SQLite for durable state, workflow version history, and worker metrics.\n- GitHub Issues as the tracker.\n- Git worktrees for parallel per-issue coding workers.\n- A FastAPI + Jinja + HTMX dashboard for status and operational questions.\n\n## Quick Start\n\n```bash\nuv run symphony-dbcli init-workflow\nuv run symphony-dbcli init-db\nuv run symphony-dbcli status\nuv run symphony-dbcli serve\n```\n\nThe default workflow is safe for local development. GitHub writes require\ncredentials before workers can label issues. Workers save research answers and\ncode summaries as local review drafts instead of posting comments or opening\npull requests automatically.\n`serve-web` is available for dashboard-only debugging without starting workers.\nNormal local iteration should use `serve`. Local profiles start Uvicorn with\nreload enabled so Python, template, static, and workflow edits restart the web\nprocess. Use `--no-reload` to disable file watching, or `--reload` to force it\nfor a non-local profile.\n\n## Worker Lifecycle\n\n`serve` runs the FastAPI dashboard and the full local orchestration loop:\n\n1. Acquire a SQLite-backed runtime leader lock so only one process dispatches workers.\n2. Reload and record `WORKFLOW.md` when it changes.\n3. Sync configured sources into the SQLite-backed board.\n4. Advance ready workflow instances and claim queued work items.\n5. Spawn worker subprocesses automatically.\n6. Record worker ids, PIDs, heartbeats, deadlines, attempts, turns, errors, and outcomes in SQLite.\n7. Mark crashed or timed-out workers as failed and queue a retry when `workers.retry_limit` allows it.\n\nWorker lifecycle settings live in `WORKFLOW.md` under `[workers]`, including\n`poll_interval_seconds`, `heartbeat_interval_seconds`,\n`heartbeat_timeout_seconds`, `max_runtime_seconds`, `retry_limit`, and\n`shutdown_grace_seconds`.\n\nThe pre-alpha runtime is designed for one FastAPI/Uvicorn process locally. A\nSQLite leader lock prevents duplicate worker dispatch if another process starts,\nbut production multi-worker deployment still needs more soak testing before it\nshould be treated as hardened.\n\n## Reviewing Results\n\nCompleted worker attempts are stored in SQLite with their final markdown result,\nregardless of `policy.dry_run`. Open the dashboard, select an attempt in review,\nand read the `Worker Result` section. Draft GitHub replies are shown separately\nso they can be edited before posting to GitHub.\n\nCode attempts in review can ask Codex to open a draft pull request from the\ndashboard. Codex creates the PR from the attempt worktree with a tailored title\nand description; Symphony then fetches the PR metadata, records the PR URL in\nSQLite, and links it back to the GitHub issue. Once a recorded PR is merged, the\norchestration loop checks the PR state and removes the associated clean worktree\nto avoid filling the disk. Dirty worktrees are left in place and the cleanup\nerror is recorded for review.\n\nResearch results can be promoted into code work. From a research attempt page,\nuse `Create Code Follow-up` to queue a linked code attempt. The code worker\nreceives the original issue plus the stored research result in its prompt, and\nthe relationship is recorded in SQLite. The same operation is available from the\nCLI:\n\n```bash\nuv run symphony-dbcli attempt create-code-follow-up --attempt-id 2\n```\n\nMerged-PR worktree cleanup also has a manual command:\n\n```bash\nuv run symphony-dbcli worktree cleanup-merged-prs\n```\n\n## Profiles\n\n`WORKFLOW.md` includes explicit runtime profiles. The default `local` profile\nkeeps SQLite, shared repos, and worktrees under `.symphony/` so local iteration\ndoes not need privileged filesystem paths. The `prod` profile uses `/srv/symphony`\npaths and binds the dashboard to `0.0.0.0` for hosted deployment.\n\nProfile precedence is:\n\n1. `--profile`, for example `uv run symphony-dbcli --profile prod serve`\n2. `SYMPHONY_PROFILE`\n3. `[profile].active` in `WORKFLOW.md`\n4. `local`\n\n## GitHub App Setup\n\nGenerate a local manifest form:\n\n```bash\nuv run symphony-dbcli github-app manifest --account amjith\n```\n\nOpen `.symphony/github-app-manifest.html` in a browser and submit the form.\nGitHub will redirect to `http://127.0.0.1:8765/github-app/callback` with a\ntemporary code. If the dashboard is not running, copy the `code` from the\nbrowser address bar.\n\nExchange the code within one hour:\n\n```bash\nuv run symphony-dbcli github-app convert --code CODE\n```\n\nThis writes `.symphony/github-app.env` and `.symphony/github-app.private-key.pem`\nwith `0600` permissions. Local CLI commands load `.symphony/github-app.env`\nautomatically without overriding existing environment variables.\n\nInstall the app on the target DBCLI repositories, then list installations:\n\n```bash\nuv run symphony-dbcli github-app installations\n```\n\nSet `SYMPHONY_GITHUB_INSTALLATION_ID` in the env file to the installation id for\nthe account that owns the DBCLI repositories.\n\n## Development\n\n```bash\nuv sync --dev\nuv run pre-commit install\nuv run pytest\nuv run ruff check .\nuv run ruff format --check .\nuv run mypy\n```\n\n## End-to-End Fixture\n\nUse the disposable fixture repo to exercise the GitHub-backed orchestration loop\nwithout touching DBCLI repos:\n\n```bash\nuv run symphony-dbcli e2e run-fixture\nuv run symphony-dbcli e2e run-fixture --scenario research_to_code_follow_up\n```\n\nThe harness targets `amjith/symphony-dbcli-e2e-fixture`, creates a labeled issue,\npolls and claims it, allocates a worktree, runs a deterministic fake Codex\nworker, stores the result in SQLite, and opens a draft PR for code-path\nscenarios unless `--no-create-pr` is passed. Scenarios include\n`code_happy_path`, `research_answer_review`, `research_to_code_follow_up`,\n`pr_review_comments`, and `ci_failure_fix`.\n\nGenerated workflow files, databases, fake worker binaries, and worktrees live\nunder `.symphony/e2e/`. The fixture expects `gh` to be authenticated with repo\naccess and uses local SSH git auth for the fixture branch push. To run the live\npytest fixture, opt in explicitly:\n\n```bash\nSYMPHONY_RUN_GITHUB_E2E=1 uv run pytest tests/test_e2e.py\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbcli%2Fsymphony-dbcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbcli%2Fsymphony-dbcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbcli%2Fsymphony-dbcli/lists"}