{"id":33295195,"url":"https://github.com/rustkas/devstate","last_synced_at":"2026-05-05T14:31:54.920Z","repository":{"id":324189555,"uuid":"1096285037","full_name":"rustkas/devstate","owner":"rustkas","description":"DevState is a lightweight HTTP service for .trae/state.json and .trae/history.json : validation, export/import, HMAC chain verification, and no-drift. Works locally and via Docker. Integrates with the TRAE IDE.","archived":false,"fork":false,"pushed_at":"2025-11-23T13:04:02.000Z","size":133,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-23T15:06:19.035Z","etag":null,"topics":["audit","devstate","docker","hmac","jsonschema","no-drift","nodejs","postgres","state-management","trae"],"latest_commit_sha":null,"homepage":"https://www.trae.ai/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rustkas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-14T07:47:59.000Z","updated_at":"2025-11-23T13:03:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rustkas/devstate","commit_stats":null,"previous_names":["rustkas/devstat","rustkas/devstate"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/rustkas/devstate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rustkas%2Fdevstate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rustkas%2Fdevstate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rustkas%2Fdevstate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rustkas%2Fdevstate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rustkas","download_url":"https://codeload.github.com/rustkas/devstate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rustkas%2Fdevstate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32653463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["audit","devstate","docker","hmac","jsonschema","no-drift","nodejs","postgres","state-management","trae"],"created_at":"2025-11-18T02:01:38.347Z","updated_at":"2026-05-05T14:31:54.897Z","avatar_url":"https://github.com/rustkas.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DevState — State \u0026 Audit Service\n\n![ci](https://img.shields.io/github/actions/workflow/status/rustkas/devstate/devstate-verify.yml?style=for-the-badge)\n![downloads](https://img.shields.io/github/downloads/rustkas/devstate/total?style=for-the-badge)\n![repo-size](https://img.shields.io/github/repo-size/rustkas/devstate?style=for-the-badge)\n[![license](https://img.shields.io/github/license/rustkas/devstate?style=for-the-badge)](https://github.com/rustkas/devstate/blob/main/LICENSE)\n\nDevState is a lightweight HTTP service that manages the project state (`.trae/state.json`) and audit history (`.trae/history.json`), enforces No-Drift, and verifies an HMAC chain of operations. It is designed to support development consistency across IDEs and CI/CD pipelines.\n\nTRAE IDE\n- Website: https://www.trae.ai/\n- DevState integrates with TRAE as the source-of-truth validator for `.trae/state.json` and `.trae/history.json`.\n\n## Features\n- Read/write state and history with verification of HMAC digest chain.\n- Import/Export helpers for JSON ⇄ memory/DB workflows.\n- Health endpoint for monitoring (`/health`).\n- Standalone Docker Compose stack for isolated validation.\n\n## Project Structure\n- `server/` — Node.js HTTP server and domain logic.\n- `docs/` — service documentation and usage guides.\n- `scripts/` — CLI utilities for import/export/verify.\n- `sql/` — initialization scripts (Postgres schema).\n- `docker-compose.yml` — standalone DevState stack (HTTP 3180, Postgres 55432).\n- `metadata.json` — service metadata (ports, artifacts, usage).\n\n## Quick Start\nPrerequisites: Docker, Docker Compose.\n\n1. Start standalone stack:\n   - `make devstate-up`\n   - Check health: `curl http://localhost:3180/health`\n2. Use CLI utilities:\n   - Import: `bash devstate/scripts/devstate.sh import`\n   - Export: `bash devstate/scripts/devstate.sh export`\n   - Verify: `bash devstate/scripts/devstate.sh verify`\n3. Stop the stack when done:\n   - `make devstate-down`\n\nTrae IDE Integration\n- Trae IDE uses `.trae/state.json` and `.trae/history.json` as sources of truth.\n- DevState validates and exports these files to keep multiple IDEs consistent.\n- Recommended: add `bash devstate/scripts/devstate_verify.sh` to pre-commit/pre-push.\n\nInstallation \u0026 Usage\n- No Docker: `npm install` in `devstate/server`, then run `node devstate/server/http-server.js` with env vars.\n- Docker: `make devstate-up` to run isolated HTTP `3180` and Postgres `55432`.\n- Scripts: `devstate/scripts/*` provide import/export/verify helpers.\n\nGitHub Publication (devstat)\n- Create a new repository `rustkas/devstat`.\n- Put the contents of this `devstate/` directory at the repository root.\n- Ensure `LICENSE` is MIT and present at the root.\n- Ensure this `README.md` is at the root and references TRAE.\n- Initial commit and push:\n  - `git init \u0026\u0026 git add . \u0026\u0026 git commit -m \"DevState initial release (MIT)\"`\n  - `git branch -M main \u0026\u0026 git remote add origin git@github.com:rustkas/devstate.git`\n  - `git push -u origin main`\n\nGitHub Actions\n- Not required for publication.\n- Optional (if needed later): add a single workflow to run `devstate/scripts/devstate_verify.sh` on push/PR to validate `.trae/state.json` and HMAC chain.\n\n## Configuration\nEnvironment variables (Compose):\n- `DEVSTATE_HTTP_PORT` — internal HTTP port (default `3080`).\n- `HMAC_SECRET` — HMAC secret for audit verification (default dev-only value).\n- `DATABASE_URL` — Postgres connection string (see compose).\n- `PGHOST`, `DB_SCHEMA` — Postgres host and schema.\nSecurity:\n- Set `DEVSTATE_API_TOKEN` to protect mutating endpoints (Bearer token).\n\n## Security Practices\n- Bearer token\n  - Generate a strong token and set `DEVSTATE_API_TOKEN` on the server; clients pass `Authorization: Bearer \u003ctoken\u003e`.\n  - Store tokens in secret managers; avoid committing tokens to code or configs.\n- HMAC rotation\n  - Use `/v1/devstate/keys/rotate` to publish a new active key; record `kid` in history metadata.\n  - Schedule rotation (e.g., monthly/quarterly); verify chain with `/v1/devstate/verify` after rotation.\n- Rate-limit\n  - Default limiter: 120 req/min for mutating endpoints; adjust per environment.\n  - Recommended: `state`/`history` ≤ 120 rpm, `verify` ≤ 600 rpm.\n- Best practices\n  - Protect API behind reverse proxy with TLS/mTLS in production.\n  - Monitor `append_fail_total`, `state_update_fail_total`, and success rate per route.\n  - Audit: all changes append to `history_entries` with HMAC chain; export `.trae/*` for cross‑IDE sync.\n\n## Deployment (CI/CD)\n- Verify workflow: `.github/workflows/devstate-verify.yml` (compose up → health → verify → export).\n- No‑Drift deny: `.github/workflows/no-drift-deny.yml` (blocks PR if `.trae/*` tracked).\n- OpenAPI release and clients: TS/Go/Python workflows publish artifacts on tags.\n\n \n\n## Observability Assets\n- Prometheus scrape example: `docs/prometheus_scrape.yml` (targets `localhost:3180`, path `/metrics`).\n- Grafana dashboard example: `docs/grafana_dashboard.json` (p95 verify, failure counts, rate‑limited, locks).\n- Grafana extended dashboard: `docs/grafana_dashboard_extended.json` (latency percentiles, throughput, error metrics).\n- Real-time updates: Prometheus pulls `/metrics`; ensure scrape interval ≤ `15s` and Grafana dashboard refresh set to `5s`.\n\n## Deploy Observability\n- Commands:\n  - `docker compose -f docs/compose-prometheus.yml up -d`\n  - `docker compose -f docs/compose-grafana.yml up -d`\n  - Import dashboards in Grafana (URL: `http://localhost:3000/`, password `admin`).\n - Prometheus: start with scrape config above; validate targets state.\n - Grafana: import JSON dashboards via UI; set refresh to `5s`.\n - Production monitoring: set alerts for p95 latency, success rate \u003c 95%, and append/state failures increase; configure dashboards per tenant if multi-tenant.\n\n## API\n- `GET /health` — returns service status.\n\n## Documentation\n- Index: `devstate/docs/README.md`\n- Overview: `devstate/docs/DEVSTATE_OVERVIEW.md`\n- MCP usage: `devstate/docs/MCP_USAGE.md`\n- Historical note: `devstate/docs/BEAMLINE_STORE_TZ.md`\n- Scripts: `devstate/scripts/README.md`\n\n## Troubleshooting\n- Health check fails: verify that `docker compose` started DB and server; check logs with `docker compose logs`.\n- Verify returns 500: on empty history chain server returns `{ ok: true }`; ensure DB is initialized and `HMAC_SECRET` set.\n- Import/Export .trae:\n  - Import errors: validate `.trae/state.json` against `docs/STATE.schema.json`; ensure HMAC chain in `.trae/history.json` is consistent.\n  - Export issues: verify write permissions to `.trae/`; check resulting file checksums.\n- HTTP codes:\n  - 200: success for verify/state/history operations.\n  - 400: validation failure (state schema, append payload); check error message.\n  - 429: rate-limited; reduce request rate or increase limits.\n  - 500: server errors; inspect logs and metrics.\n- Metrics analysis:\n  - Latency histograms: `devstate_*_duration_seconds` expose buckets; use Grafana panels for p95/p99.\n  - Success rate: computed via `devstate_request_total{status='200'}` over total per route.\n  - Fail counters: `devstate_append_fail_total`, `devstate_state_update_fail_total` for error tracking.\n- Bearer token required: set `DEVSTATE_API_TOKEN` in server env and pass `Authorization: Bearer \u003ctoken\u003e`.\n- k6 append errors: check `DEVSTATE_API_TOKEN` is provided in workflow or remove `requireAuth` for tests.\n\n## Clients QuickStart\n- TypeScript: `npm install @rustkas/devstate-client` → see `clients/typescript/README.md` for usage.\n- Python: `pip install devstate-client` (after publish) → see `clients/python/USAGE.md`.\n- Go: `go get github.com/rustkas/devstate/clients/go@client-go-vX.Y.Z`.\n\n## License\nMIT. See `LICENSE`.\nPackage compliance: `server/package.json` declares `MIT`.\n\n## Maintainers\n- AIGROUP / [Beamline Constructor platform team](https://github.com/BeamLine-Development).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frustkas%2Fdevstate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frustkas%2Fdevstate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frustkas%2Fdevstate/lists"}