{"id":51573791,"url":"https://github.com/tolom/project-xray","last_synced_at":"2026-07-10T22:30:25.107Z","repository":{"id":367924717,"uuid":"1252354455","full_name":"tolom/project-xray","owner":"tolom","description":"Find fragile zones in AI-built apps before launch.","archived":false,"fork":false,"pushed_at":"2026-06-28T09:51:41.000Z","size":261,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-28T10:21:26.062Z","etag":null,"topics":["ai-agents","ai-built-products","ai-debt","claude-code","code-audit","codex","coding-agents","cursor","developer-tools","grok","launch-readiness","llm","nextjs","project-audit","react","supabase","technical-debt","typescript","vibe-coding"],"latest_commit_sha":null,"homepage":"","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/tolom.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"docs/roadmap.md","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-28T12:43:32.000Z","updated_at":"2026-06-28T09:42:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tolom/project-xray","commit_stats":null,"previous_names":["tolom/project-xray"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tolom/project-xray","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolom%2Fproject-xray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolom%2Fproject-xray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolom%2Fproject-xray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolom%2Fproject-xray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tolom","download_url":"https://codeload.github.com/tolom/project-xray/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolom%2Fproject-xray/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35345661,"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-10T02:00:06.465Z","response_time":60,"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","ai-built-products","ai-debt","claude-code","code-audit","codex","coding-agents","cursor","developer-tools","grok","launch-readiness","llm","nextjs","project-audit","react","supabase","technical-debt","typescript","vibe-coding"],"created_at":"2026-07-10T22:30:23.959Z","updated_at":"2026-07-10T22:30:25.099Z","avatar_url":"https://github.com/tolom.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project X-Ray\n\n**AI-built app? Find the fragile parts before users do.**\n\nProject X-Ray scans repositories created or heavily modified with Claude Code, Codex, Cursor, Grok, Lovable, Bolt, v0, and other AI coding tools.\n\nIt finds launch-readiness risks: weak access boundaries, auth/billing coupling, browser-side mutations, missing ownership checks, oversized orchestration files, duplicated business logic, and temporary AI patches that quietly become production architecture.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/project-xray-hero.svg\" alt=\"Project X-Ray launch-readiness report preview\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Status: MVP\" src=\"https://img.shields.io/badge/status-MVP-orange\" /\u003e\n  \u003cimg alt=\"Next.js 16\" src=\"https://img.shields.io/badge/Next.js-16-black\" /\u003e\n  \u003cimg alt=\"Code storage: none\" src=\"https://img.shields.io/badge/code_storage-none-green\" /\u003e\n  \u003cimg alt=\"LLM Skill included\" src=\"https://img.shields.io/badge/LLM_skill-included-blue\" /\u003e\n  \u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-lightgrey\" /\u003e\n\u003c/p\u003e\n\n\u003e You built fast with AI coding agents. The demo works. Project X-Ray helps you see what deserves review before real users depend on it.\n\n---\n\n## Pick your path\n\n| I want to... | Start here |\n|---|---|\n| Scan an AI-built repository | [Quick start](#quick-start) |\n| Understand what X-Ray checks | [What Project X-Ray checks](#what-project-x-ray-checks) |\n| See the report format | [Example output](#example-output) |\n| Use it inside a chat or IDE agent | [Skill mode](#skill-mode) |\n| Repair issues with Claude Code, Codex, Cursor, or Grok | [Agent repair workflow](#agent-repair-workflow) |\n| Understand the current privacy model | [Privacy model](#privacy-model) |\n\n## What you get\n\n- **Health score** — a `0-100` launch-readiness signal.\n- **Verdict** — `Ready`, `Caution`, or `High Risk`.\n- **Top risks** — the most important findings to verify first.\n- **Risk zones** — files and subsystems that deserve manual review.\n- **Plain-language impact** — what can break and why it matters for the product.\n- **Repair plan** — small, scoped tasks instead of broad rewrites.\n- **Agent repair prompts** — prompts you can give to Claude Code, Codex, Cursor, Grok, or another coding agent.\n- **Markdown export** — reports that can be saved, shared, or pasted into an issue.\n\n## Why Project X-Ray exists\n\nAI coding tools make it easy to build a working prototype.\n\nThey also make it easy to accidentally ship:\n\n- auth logic mixed into UI;\n- payment state changed from browser-controlled code;\n- database writes without ownership checks;\n- huge files that nobody wants to touch;\n- duplicated business rules across unrelated components;\n- temporary AI fixes that become production architecture.\n\nProject X-Ray exists for the moment after the demo works — but before real users depend on it.\n\n## Who it is for\n\nProject X-Ray is designed for:\n\n- founders and solo builders shipping AI-built MVPs;\n- developers using coding agents for real product work;\n- consultants reviewing client prototypes before handoff;\n- teams adopting AI-assisted development and needing a lightweight safety layer;\n- anyone who needs a practical repair plan before launch.\n\n## What Project X-Ray checks\n\nProject X-Ray uses a deterministic browser-side rule engine. The current rule set focuses on structural and launch-critical risks:\n\n1. Protected route exposure.\n2. Auth and billing coupling.\n3. Fragile payment webhook handling.\n4. Client-side mutation of roles, prices, permissions, or access.\n5. Database access without an obvious ownership or RLS boundary.\n6. Server-only value exposure to browser code.\n7. Oversized files.\n8. Repeated business or access logic.\n9. TODO/FIXME/HACK markers in critical flows.\n10. Mixed responsibilities in one module.\n11. Sensitive update/delete operations without clear ownership checks.\n12. Missing error handling around access, payment, database, or external APIs.\n13. Missing success, cancel, onboarding, or account-status paths.\n14. Sensitive modules imported across too many places.\n15. Composite AI-chaos smell: large file plus temporary fixes plus mixed responsibilities plus critical flow.\n\nSee [docs/scoring-model.md](docs/scoring-model.md) for the scoring model.\n\n## How it works\n\n```text\nRepository\n   ↓\nStructural risk scan\n   ↓\nHealth score + verdict\n   ↓\nTop risks with evidence\n   ↓\nRepair plan\n   ↓\nSmall prompts for Claude Code / Codex / Cursor / Grok\n   ↓\nRe-scan after fixes\n```\n\nProject X-Ray is designed to work with AI coding agents, not compete with them.\n\n## Example output\n\nA typical scan returns:\n\n```text\nHealth score: 58 / 100\nVerdict: High Risk\n\nTop risks:\n1. Payment event handling needs verification review\n2. Account access changes are too close to browser code\n3. Large mixed-responsibility dashboard file\n\nRecommended next step:\nReview launch blockers first, then split fragile orchestration files into smaller modules.\n```\n\nSee [examples/xray-report-example.md](examples/xray-report-example.md) for a full sample report.\n\n## Skill mode\n\nProject X-Ray also ships as a reusable LLM skill:\n\n```text\nskills/ai-project-xray/SKILL.md\n```\n\nUse it when you want a model to run the same audit workflow in a chat, IDE agent, or repository-review flow.\n\nThe skill is intentionally focused on one repeatable task: **audit an AI-built project for launch-readiness and fragility risks, then produce a repair plan.**\n\nThe skill follows current agent-workflow practices:\n\n- clear activation criteria;\n- specific required inputs;\n- progressive disclosure through supporting docs and examples;\n- evidence-based findings;\n- explicit confidence levels;\n- small repair prompts instead of large rewrites;\n- verification steps after each proposed change.\n\n## Agent repair workflow\n\nRecommended loop:\n\n1. Scan the repository.\n2. Review top risks manually.\n3. Export repair tasks.\n4. Give one small repair prompt to a coding agent.\n5. Run lint, build, and tests.\n6. Re-scan.\n7. Repeat.\n\nBad repair prompt:\n\n```text\nRefactor the whole app and fix everything risky.\n```\n\nGood repair prompt:\n\n```text\nReview `app/api/stripe/webhook/route.ts` and improve payment event verification. Do not change unrelated billing logic. Keep the change narrow. Return clear error responses for invalid events. After the change, run `npm run lint` and `npm run build`.\n```\n\nFor a more detailed repair loop, see [docs/agent-repair-workflow.md](docs/agent-repair-workflow.md).\n\n## Privacy model\n\nProject X-Ray is browser-first.\n\n- Public repositories can be scanned without signing in.\n- Private repositories require GitHub OAuth.\n- Repository code is fetched through the GitHub API.\n- Project X-Ray does not store repository code.\n- Local scan history is stored in the browser.\n\nImportant security note: the current browser-first design exposes the GitHub access token to the browser session so the client can call GitHub directly. This preserves the zero-backend architecture, but browser-side XSS would be high impact. For a production SaaS, add a server-side GitHub proxy mode.\n\n## Requirements\n\n- Node.js compatible with Next.js 16.\n- npm.\n- A GitHub OAuth App for private repository access.\n- Optional xAI API key for generated repair prompts.\n\n## Quick start\n\n```bash\nnpm install\nnpm run dev\n```\n\nOpen the URL printed by Next.js, usually:\n\n```text\nhttp://localhost:3000\n```\n\n## GitHub OAuth\n\nIf you run your own copy of Project X-Ray, create a GitHub OAuth App:\n\n1. Open `https://github.com/settings/applications/new`.\n2. Set the Homepage URL to the URL where Project X-Ray is running.\n3. Set the Authorization callback URL to:\n\n```text\nhttp://localhost:3000/api/auth/callback/github\n```\n\nFor production, replace `http://localhost:3000` with your deployed domain.\n\nThen create `.env.local`:\n\n```env\nAUTH_GITHUB_ID=...\nAUTH_GITHUB_SECRET=...\nAUTH_SECRET=...\n```\n\nProject X-Ray requests the GitHub scopes `read:user repo` through Auth.js so it can read private repositories that the signed-in GitHub user can access.\n\n## Optional xAI/Grok setup\n\nPrompt generation uses deterministic fallback text by default. To enable xAI/Grok prompt generation, add:\n\n```env\nXAI_API_KEY=...\n```\n\nThe core scanner does not require an LLM API key.\n\n## Architecture\n\n- `app/page.tsx` — main scanner UI and orchestration.\n- `lib/github.ts` — GitHub API calls and repository file selection.\n- `lib/xray-analyzer.ts` — deterministic rule engine.\n- `lib/scan-history.ts` — browser localStorage scan history.\n- `components/` — reusable result views and UI surfaces.\n- `skills/ai-project-xray/` — portable LLM skill workflow.\n- `docs/` — scoring model and launch docs.\n- `examples/` — example reports and future demo repositories.\n\n## Development\n\nRun checks before opening a pull request:\n\n```bash\nnpm run lint\nnpm run build\n```\n\n## Roadmap\n\nNear-term:\n\n- [ ] Replace the SVG preview with a real screenshot or demo GIF.\n- [ ] Add server-side GitHub proxy mode.\n- [ ] Add CLI mode.\n- [ ] Add intentionally fragile demo repository.\n- [ ] Add framework-specific rule packs: Next.js, Supabase, Stripe, Firebase.\n- [ ] Add `AGENTS.md` / `CLAUDE.md` repair task export.\n- [ ] Add false-positive verification workflow.\n- [ ] Add before/after scan comparison.\n\nLonger-term:\n\n- [ ] Pull request risk analysis.\n- [ ] AI-edit regression detection.\n- [ ] Rule pack marketplace.\n- [ ] Team audit history.\n- [ ] CI mode for launch gates.\n\n## What Project X-Ray is not\n\nProject X-Ray is not:\n\n- a full security audit;\n- a replacement for tests;\n- a replacement for manual architecture review;\n- a static analysis competitor;\n- a style or formatting checker;\n- a guarantee that a project is production-safe.\n\nIt is a practical early-warning system for AI-assisted product development.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftolom%2Fproject-xray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftolom%2Fproject-xray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftolom%2Fproject-xray/lists"}