{"id":51633847,"url":"https://github.com/sjh9714/cleanroom-run","last_synced_at":"2026-07-13T11:32:31.037Z","repository":{"id":367221234,"uuid":"1279525752","full_name":"sjh9714/cleanroom-run","owner":"sjh9714","description":"Catch dirty-local-state bugs in AI-generated code before CI does.","archived":false,"fork":false,"pushed_at":"2026-06-25T04:09:37.000Z","size":93,"stargazers_count":0,"open_issues_count":6,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T05:11:01.081Z","etag":null,"topics":["ai-agents","automation","ci","cleanroom","cli","codegen","codex","coding-agents","developer-tools","git","npm","pre-ci","testing","typescript","worktree"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/sjh9714.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2026-06-24T19:15:06.000Z","updated_at":"2026-06-25T04:09:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sjh9714/cleanroom-run","commit_stats":null,"previous_names":["sjh9714/cleanroom-run"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/sjh9714/cleanroom-run","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjh9714%2Fcleanroom-run","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjh9714%2Fcleanroom-run/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjh9714%2Fcleanroom-run/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjh9714%2Fcleanroom-run/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sjh9714","download_url":"https://codeload.github.com/sjh9714/cleanroom-run/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjh9714%2Fcleanroom-run/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35421716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"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":["ai-agents","automation","ci","cleanroom","cli","codegen","codex","coding-agents","developer-tools","git","npm","pre-ci","testing","typescript","worktree"],"created_at":"2026-07-13T11:32:28.620Z","updated_at":"2026-07-13T11:32:31.032Z","avatar_url":"https://github.com/sjh9714.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cleanroom Run\n\n[![CI](https://github.com/sjh9714/cleanroom-run/actions/workflows/ci.yml/badge.svg)](https://github.com/sjh9714/cleanroom-run/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n**Command exited 0. The repo was still wrong.**\n\nCleanroom Run checks agent-generated changes from a temporary Git worktree before CI catches dirty local state.\n\n```bash\nnpm exec --yes --package github:sjh9714/cleanroom-run#v0.1.1 -- cleanroom-run run --strict -- sh -lc \"npm ci \u0026\u0026 npm test\"\n```\n\nIt creates a temporary Git worktree from `HEAD`, applies your intended tracked changes, runs your command, and reports files that were generated or modified unexpectedly.\n\nNot a sandbox. Not a GitHub Actions emulator. A local clean-state proof runner.\n\n```text\n$ cleanroom-run run --strict -- npm test\nCleanroom check failed\n\nCommand: npm test\nExit: 0\nDuration: 1.24s\nInput untracked files: 0\nGenerated untracked files: 1\nModified tracked files: 1\nFailure reasons: generated-untracked-files, modified-tracked-files\nReport: /tmp/cleanroom-run-reports/2026-06-25T12-00-00-000Z-inline.md\n\nGenerated files:\n  + generated/schema.json\n\nTracked files changed during command:\n  ~ package-lock.json\n```\n\n## Why\n\nAI coding agents made it cheap to generate code. They did not make it cheap to know whether the code works outside your laptop's dirty state.\n\nCleanroom Run catches:\n\n- generated files that were never committed\n- tests that pass only when untracked local files are copied in\n- commands that rely on stale build output\n- commands that silently modify tracked files\n- \"works on my machine\" checks before you push to CI\n\nUse it before you trust:\n\n- AI-agent generated code\n- local test results\n- codegen-heavy changes\n- \"works on my machine\" verification\n\n## 3-Minute Quickstart\n\nRun from any Git repo with at least one commit:\n\n```bash\nnpm exec --yes --package github:sjh9714/cleanroom-run#v0.1.1 -- cleanroom-run run --strict -- sh -lc \"npm ci \u0026\u0026 npm test\"\n```\n\nWhen the npm package is published, the shorter form is:\n\n```bash\nnpx cleanroom-run run --strict -- sh -lc \"npm ci \u0026\u0026 npm test\"\n```\n\nFor a faster command that does not need dependency install:\n\n```bash\nnpm exec --yes --package github:sjh9714/cleanroom-run#v0.1.1 -- cleanroom-run run --strict -- npm test\n```\n\nCleanroom Run writes Markdown reports to your OS temp directory by default and exits non-zero when:\n\n- the command exits non-zero\n- the command times out\n- strict mode sees pre-existing untracked input files\n- the command leaves new untracked files behind\n- the command modifies tracked files unexpectedly\n\n## Install\n\nFrom this GitHub release candidate:\n\n```bash\nnpm install --save-dev github:sjh9714/cleanroom-run#v0.1.1\n```\n\nAfter npm publication:\n\n```bash\nnpm install --save-dev cleanroom-run\n```\n\nFrom source:\n\n```bash\ngit clone https://github.com/sjh9714/cleanroom-run.git\ncd cleanroom-run\nnpm ci\nnpm test\nnpm run build\nnpm link\n```\n\n## Usage\n\nRun an inline command:\n\n```bash\ncleanroom-run run --strict -- sh -lc \"npm ci \u0026\u0026 npm test\"\n```\n\nCreate a config:\n\n```bash\ncleanroom-run init\n```\n\nEdit `.cleanroom-run.yml`:\n\n```yaml\nchecks:\n  verify:\n    command: npm ci \u0026\u0026 npm run verify\n    timeoutMs: 180000\n    strict: true\n```\n\nRun the named check:\n\n```bash\ncleanroom-run run verify\n```\n\nKeep the temporary worktree for debugging:\n\n```bash\ncleanroom-run run --strict --keep -- sh -lc \"npm ci \u0026\u0026 npm test\"\n```\n\nEmit JSON for automation:\n\n```bash\ncleanroom-run run --strict --json -- sh -lc \"npm ci \u0026\u0026 npm test\"\n```\n\nKeep Markdown reports inside the repo:\n\n```bash\ncleanroom-run run --strict --report-dir .cleanroom-run/reports -- sh -lc \"npm ci \u0026\u0026 npm test\"\n```\n\nCheck whether the repo is ready:\n\n```bash\ncleanroom-run doctor\n```\n\n## GitHub Actions\n\n```yaml\nname: Cleanroom\n\non:\n  pull_request:\n\npermissions:\n  contents: read\n\njobs:\n  cleanroom:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 22\n          cache: npm\n      - run: npm ci\n      - run: npm exec --yes --package github:sjh9714/cleanroom-run#v0.1.1 -- cleanroom-run run --strict -- sh -lc \"npm ci \u0026\u0026 npm test\"\n```\n\n## Input Modes\n\nCleanroom Run has three input modes:\n\n```text\ndefault:\n  apply tracked changes only\n  pre-existing untracked files are reported but not copied\n\n--include-untracked:\n  also copy untracked, non-ignored files into the cleanroom\n  use this when you have new files that are not git-added yet\n\n--strict:\n  fail before running the command if pre-existing untracked files exist\n  use this before pushing agent-generated or codegen-heavy changes\n```\n\n## How It Works\n\n1. Finds the Git repository root.\n2. Creates a temporary detached worktree at `HEAD`.\n3. Applies tracked local changes with `git diff --binary HEAD`.\n4. Copies untracked, non-ignored files only when `--include-untracked` is set.\n5. Runs your command in the temp worktree.\n6. Reports command output, exit status, generated untracked files, and tracked files changed during the command.\n7. Removes the temporary worktree unless `--keep` is set.\n\nYour original working tree is not cleaned, reset, or modified by default. Passing `--report-dir` with a repo-relative path intentionally writes the report there.\n\n## Example Failure\n\nThe fixture in `fixtures/generated-file-demo` has a command that writes `generated/schema.json` without committing it.\n\n```bash\nnpm run build\nnode dist/index.js run --strict -- npm run check\n```\n\nCleanroom Run reports the generated file and exits with status 1 even though the command itself exits 0.\n\n## Limitations\n\n- Requires Git and at least one commit.\n- macOS and Linux are the v0.1 target platforms.\n- Commands run with your normal environment. This is not a security sandbox.\n- Dependency installation is your responsibility. Use `sh -lc \"npm ci \u0026\u0026 npm test\"` or a named config check when a clean worktree needs dependencies.\n- Ignored files are not treated as generated-file failures.\n- `--strict` and `--include-untracked` are mutually exclusive by design.\n\n## Roadmap\n\n- JUnit and SARIF report output.\n- First-class `cleanroom-run action` wrapper for GitHub Actions summaries.\n- Optional Docker backend for stronger isolation.\n- Policy mode for max generated files, changed-file allowlists, and required report artifacts.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjh9714%2Fcleanroom-run","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsjh9714%2Fcleanroom-run","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjh9714%2Fcleanroom-run/lists"}