{"_id":"@elysiumoss/grepo","_rev":"5-40d65485c3c1ef432de647d6c2a0a29d","name":"@elysiumoss/grepo","dist-tags":{"latest":"0.5.0"},"versions":{"0.2.0":{"name":"@elysiumoss/grepo","version":"0.2.0","keywords":["ai","cli","documentation","gemini","github","readme","repository"],"author":{"url":"https://github.com/WomB0ComB0","name":"Mike Odnis"},"license":"MIT","_id":"@elysiumoss/grepo@0.2.0","maintainers":[{"name":"womb0comb0","email":"mike@mikeodnis.dev"}],"homepage":"https://github.com/ElysiumOSS/grepo#readme","bugs":{"url":"https://github.com/ElysiumOSS/grepo/issues"},"bin":{"grepo":"lib/cli.js"},"dist":{"shasum":"8fd9b541f38221d970cc3f8f573ba1a57b5ecef2","tarball":"https://registry.npmjs.org/@elysiumoss/grepo/-/grepo-0.2.0.tgz","fileCount":72,"integrity":"sha512-KH6jcwEhM3UWGmIhBGu8JdHuzL+fkbpCiuczuyCIKEd53xOm1jq5BNRJTdz5UmDLiHYn52poZuJB21PXUjn3bg==","signatures":[{"sig":"MEUCIGaRhGvwno6nQ/LegTKi1+nXYflyiKPoSu8hGSWU3wgHAiEA0Epv0w+W9f93AOOKSUzGMYQMnO/Jbx6lih2ZAKEdx90=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@elysiumoss%2fgrepo@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":222615},"main":"lib/index.js","type":"module","types":"./lib/index.d.ts","engines":{"node":">=20.19.0"},"gitHead":"a38f4e42e773e2b3cd1731946611dddc8e09deb7","scripts":{"tsc":"tsc","docs":"bunx typedoc --entryPointStrategy Expand src","lint":"biome check .","test":"vitest","build":"tsdown","format":"biome format --write .","lint:md":"markdownlint \"**/*.md\" \".github/**/*.md\" --rules sentences-per-line","prepare":"husky","lint:knip":"knip","lint:packages":"bun pm ls","lint:spelling":"cspell \"**\" \".github/**/*\""},"_npmUser":{"name":"womb0comb0","email":"mike@mikeodnis.dev"},"repository":{"url":"git+https://github.com/ElysiumOSS/grepo.git","type":"git"},"_npmVersion":"10.8.2","description":"AI-powered GitHub repository management CLI — generate READMEs, topics, descriptions, and more using Gemini","directories":{},"lint-staged":{"*":"biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"},"_nodeVersion":"20.20.0","dependencies":{"effect":"^3.19.15","@google/genai":"^1.22.0","@effect/platform":"^0.94.2","@mermaid-js/mermaid-cli":"^11.12.0"},"publishConfig":{"provenance":true},"_hasShrinkwrap":false,"devDependencies":{"knip":"5.64.1","husky":"9.1.7","cspell":"9.2.1","tsdown":"0.15.6","vitest":"3.2.4","@types/bun":"^1.3.10","release-it":"19.0.5","typescript":"5.9.3","@types/node":"24.6.2","lint-staged":"16.2.3","markdownlint":"0.38.0","@biomejs/biome":"^2.4.7","markdownlint-cli":"0.45.0","console-fail-test":"0.5.0","sentences-per-line":"0.3.0","@vitest/coverage-v8":"3.2.4","@release-it/conventional-changelog":"10.0.1"},"_npmOperationalInternal":{"tmp":"tmp/grepo_0.2.0_1773647084229_0.018628563290938205","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@elysiumoss/grepo","version":"0.3.0","keywords":["ai","cli","documentation","gemini","github","readme","repository"],"author":{"url":"https://github.com/WomB0ComB0","name":"Mike Odnis"},"license":"MIT","_id":"@elysiumoss/grepo@0.3.0","maintainers":[{"name":"womb0comb0","email":"mike@mikeodnis.dev"}],"homepage":"https://github.com/ElysiumOSS/grepo#readme","bugs":{"url":"https://github.com/ElysiumOSS/grepo/issues"},"bin":{"grepo":"lib/cli.js"},"dist":{"shasum":"0dc765884d869d8beab4c66ee9f1d597ba317106","tarball":"https://registry.npmjs.org/@elysiumoss/grepo/-/grepo-0.3.0.tgz","fileCount":72,"integrity":"sha512-E6MP5JEf7bXnoQzZuww9jOJ0ORoOrfTC2Snt/fp7nX9/+p2ybr8M96x2aW+iUmmZ1AM/OVr9i7hyY1PBkpEa4w==","signatures":[{"sig":"MEUCIGjzIciX6IkItGWOjTD1FRQ5RlK1fiVnceT7H7nAllMwAiEA7w5kInl45DPYDpNRmKkxrFcYVctKGlFdpm01dRTX2Nw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@elysiumoss%2fgrepo@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":225724},"main":"lib/index.js","type":"module","types":"./lib/index.d.ts","engines":{"node":">=20.19.0"},"gitHead":"3d21adc1e62b2751367680697860526380689aed","scripts":{"tsc":"tsc","docs":"bunx typedoc --entryPointStrategy Expand src","lint":"biome check .","test":"vitest","build":"tsdown","format":"biome format --write .","lint:md":"markdownlint \"**/*.md\" \".github/**/*.md\" --rules sentences-per-line","prepare":"husky","lint:knip":"knip","lint:packages":"bun pm ls","lint:spelling":"cspell \"**\" \".github/**/*\""},"_npmUser":{"name":"womb0comb0","email":"mike@mikeodnis.dev"},"repository":{"url":"git+https://github.com/ElysiumOSS/grepo.git","type":"git"},"_npmVersion":"10.8.2","description":"AI-powered GitHub repository management CLI — generate READMEs, topics, descriptions, and more using Gemini","directories":{},"lint-staged":{"*":"biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"},"_nodeVersion":"20.20.0","dependencies":{"effect":"^3.19.15","@google/genai":"^1.22.0","@effect/platform":"^0.94.2","@mermaid-js/mermaid-cli":"^11.12.0"},"publishConfig":{"provenance":true},"_hasShrinkwrap":false,"devDependencies":{"knip":"5.64.1","husky":"9.1.7","cspell":"9.2.1","tsdown":"0.15.6","vitest":"3.2.4","@types/bun":"^1.3.10","release-it":"19.0.5","typescript":"5.9.3","@types/node":"24.6.2","lint-staged":"16.2.3","markdownlint":"0.38.0","@biomejs/biome":"^2.4.7","markdownlint-cli":"0.45.0","console-fail-test":"0.5.0","sentences-per-line":"0.3.0","@vitest/coverage-v8":"3.2.4","@release-it/conventional-changelog":"10.0.1"},"_npmOperationalInternal":{"tmp":"tmp/grepo_0.3.0_1773649247036_0.3605894775717027","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@elysiumoss/grepo","version":"0.4.0","keywords":["ai","cli","documentation","gemini","github","readme","repository"],"author":{"url":"https://github.com/WomB0ComB0","name":"Mike Odnis"},"license":"MIT","_id":"@elysiumoss/grepo@0.4.0","maintainers":[{"name":"womb0comb0","email":"mike@mikeodnis.dev"}],"homepage":"https://github.com/ElysiumOSS/grepo#readme","bugs":{"url":"https://github.com/ElysiumOSS/grepo/issues"},"bin":{"grepo":"lib/cli.js"},"dist":{"shasum":"256c9fc11540dbdcb60656efa1c5202fbb7096a8","tarball":"https://registry.npmjs.org/@elysiumoss/grepo/-/grepo-0.4.0.tgz","fileCount":76,"integrity":"sha512-wL05EhcddmjZoUKmkdVgSgoOFsMLcVphL2rRqGPFl3ZfKMWnsDjT1H9xRUaHBdorRh30+hOarHFPRpvNQxw74g==","signatures":[{"sig":"MEQCIHToTyRoRASBQSNv5t4250oeaVdUXX6UuTu7NbRb99lIAiB4+qDhfzXwP15obDfu6w1zwW88ez+hvUKbZntdxmtA1Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@elysiumoss%2fgrepo@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":239032},"main":"lib/index.js","type":"module","types":"./lib/index.d.ts","engines":{"node":">=20.19.0"},"gitHead":"927037d2723a350c8d4a6b9de9c5db094ab4531e","scripts":{"tsc":"tsc","docs":"bunx typedoc --entryPointStrategy Expand src","lint":"biome check .","test":"vitest","build":"tsdown","format":"biome format --write .","lint:md":"markdownlint \"**/*.md\" \".github/**/*.md\" --rules sentences-per-line","prepare":"husky","lint:knip":"knip","lint:packages":"bun pm ls","lint:spelling":"cspell \"**\" \".github/**/*\""},"_npmUser":{"name":"womb0comb0","email":"mike@mikeodnis.dev"},"repository":{"url":"git+https://github.com/ElysiumOSS/grepo.git","type":"git"},"_npmVersion":"10.8.2","description":"AI-powered GitHub repository management CLI — generate READMEs, topics, descriptions, and more using Gemini","directories":{},"lint-staged":{"*":"biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"},"_nodeVersion":"20.20.0","dependencies":{"effect":"^3.19.15","@google/genai":"^1.22.0","@effect/platform":"^0.94.2","@mermaid-js/mermaid-cli":"^11.12.0"},"publishConfig":{"provenance":true},"_hasShrinkwrap":false,"devDependencies":{"knip":"5.64.1","husky":"9.1.7","cspell":"9.2.1","tsdown":"0.15.6","vitest":"3.2.4","@types/bun":"^1.3.10","release-it":"19.0.5","typescript":"5.9.3","@types/node":"24.6.2","lint-staged":"16.2.3","markdownlint":"0.38.0","@biomejs/biome":"^2.4.7","markdownlint-cli":"0.45.0","console-fail-test":"0.5.0","sentences-per-line":"0.3.0","@vitest/coverage-v8":"3.2.4","@release-it/conventional-changelog":"10.0.1"},"_npmOperationalInternal":{"tmp":"tmp/grepo_0.4.0_1773722039390_0.3371994675400498","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@elysiumoss/grepo","version":"0.4.2","keywords":["ai","cli","documentation","gemini","github","readme","repository"],"author":{"url":"https://github.com/WomB0ComB0","name":"Mike Odnis"},"license":"MIT","_id":"@elysiumoss/grepo@0.4.2","maintainers":[{"name":"womb0comb0","email":"mike@mikeodnis.dev"}],"homepage":"https://github.com/ElysiumOSS/grepo#readme","bugs":{"url":"https://github.com/ElysiumOSS/grepo/issues"},"bin":{"grepo":"lib/cli.js"},"dist":{"shasum":"a2df2fa76d5eb7262495bc712fc1a3709e8e93ac","tarball":"https://registry.npmjs.org/@elysiumoss/grepo/-/grepo-0.4.2.tgz","fileCount":80,"integrity":"sha512-zWWzy1+2wrhW4pdnquNZIKQXXvS27Ol68uh+pe+LaYULlZK5VRsoLZ0k6SPjyuyw6jS7TKii5ujd4wpAak7Gfg==","signatures":[{"sig":"MEQCIF4NAYHvPvK1tE19FCDlLVVqBvCLfZxBLCloyRLT37MVAiBdPaSf+1qM59tDFqFRLTIB8S9Brcgke25OnHoUIqLwMA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@elysiumoss%2fgrepo@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":258038},"main":"lib/index.js","type":"module","types":"./lib/index.d.ts","engines":{"node":">=20.19.0"},"gitHead":"ac7cf3021c91d412b6761c7fff68c7c9f3962d2e","scripts":{"tsc":"tsc","docs":"bunx typedoc --entryPointStrategy Expand src","lint":"biome check .","test":"vitest","build":"tsdown","format":"biome format --write .","lint:md":"markdownlint \"**/*.md\" \".github/**/*.md\" --rules sentences-per-line","prepare":"husky","lint:knip":"knip","lint:packages":"bun pm ls","lint:spelling":"cspell \"**\" \".github/**/*\""},"_npmUser":{"name":"womb0comb0","email":"mike@mikeodnis.dev"},"repository":{"url":"git+https://github.com/ElysiumOSS/grepo.git","type":"git"},"_npmVersion":"11.4.2","description":"AI-powered GitHub repository management CLI — generate READMEs, topics, descriptions, and more using Gemini","directories":{},"lint-staged":{"*":"biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"},"_nodeVersion":"24.3.0","dependencies":{"effect":"^3.19.15","@google/genai":"^1.22.0","@effect/platform":"^0.94.2","@mermaid-js/mermaid-cli":"^11.12.0"},"publishConfig":{"provenance":true},"_hasShrinkwrap":false,"devDependencies":{"knip":"5.64.1","husky":"9.1.7","cspell":"9.2.1","tsdown":"0.15.6","vitest":"3.2.6","@types/bun":"^1.3.10","release-it":"19.0.5","typescript":"5.9.3","@types/node":"24.6.2","lint-staged":"16.2.3","markdownlint":"0.38.0","@biomejs/biome":"^2.4.7","markdownlint-cli":"0.45.0","console-fail-test":"0.5.0","sentences-per-line":"0.3.0","@vitest/coverage-v8":"3.2.6","@release-it/conventional-changelog":"10.0.1"},"_npmOperationalInternal":{"tmp":"tmp/grepo_0.4.2_1781637469387_0.46832698994270405","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@elysiumoss/grepo","version":"0.5.0","description":"AI-powered GitHub repository management CLI — generate READMEs, topics, descriptions, and more using Gemini","keywords":["ai","cli","documentation","gemini","github","readme","repository"],"repository":{"type":"git","url":"git+https://github.com/ElysiumOSS/grepo.git"},"license":"MIT","author":{"name":"Mike Odnis","url":"https://github.com/WomB0ComB0"},"type":"module","main":"lib/index.js","bin":{"grepo":"lib/cli.js"},"scripts":{"build":"tsdown","docs":"bunx typedoc --entryPointStrategy Expand src","format":"biome format --write .","lint":"biome check .","lint:knip":"knip","lint:md":"markdownlint \"**/*.md\" \".github/**/*.md\" --rules sentences-per-line","lint:packages":"bun pm ls","lint:spelling":"cspell \"**\" \".github/**/*\"","prepare":"husky","test":"vitest","tsc":"tsc"},"lint-staged":{"*":"biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"},"dependencies":{"@effect/platform":"^0.94.2","@google/genai":"^1.22.0","@mermaid-js/mermaid-cli":"^11.12.0","effect":"^3.19.15"},"devDependencies":{"@biomejs/biome":"^2.4.7","@release-it/conventional-changelog":"10.0.1","@types/bun":"^1.3.10","@types/node":"24.6.2","@vitest/coverage-v8":"3.2.6","console-fail-test":"0.5.0","cspell":"9.2.1","husky":"9.1.7","knip":"5.64.1","lint-staged":"16.2.3","markdownlint":"0.38.0","markdownlint-cli":"0.45.0","release-it":"19.0.5","sentences-per-line":"0.3.0","tsdown":"0.15.6","typescript":"5.9.3","vitest":"3.2.6"},"engines":{"node":">=20.19.0"},"publishConfig":{"provenance":true},"_id":"@elysiumoss/grepo@0.5.0","gitHead":"37d99158553eaa11645f4f3ffdee254ec432e350","types":"./lib/index.d.ts","bugs":{"url":"https://github.com/ElysiumOSS/grepo/issues"},"homepage":"https://github.com/ElysiumOSS/grepo#readme","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-wWyGhx/DBB5SS37RnY+YNOkCnGvjhvhSEa2SDtmZez1FJ1cdLk6hxYwLAAjiwRhbC8/JQXa6Wu6d5L5TRjKhGA==","shasum":"e10aab982ce51a839a24dca0ed0946aca8c0816a","tarball":"https://registry.npmjs.org/@elysiumoss/grepo/-/grepo-0.5.0.tgz","fileCount":88,"unpackedSize":292669,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@elysiumoss%2fgrepo@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC+yulikPVhlfmUpjRRimIh76pF9XOW4UEiqoGpTb/FxwIgHBWnBvjlClAx077R6KKDK/CvhaalVCs9Lv/M1Lv87IE="}]},"_npmUser":{"name":"womb0comb0","email":"mike@mikeodnis.dev"},"directories":{},"maintainers":[{"name":"womb0comb0","email":"mike@mikeodnis.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/grepo_0.5.0_1781639856139_0.5986843376722575"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-16T07:44:44.111Z","modified":"2026-06-16T19:57:36.646Z","0.2.0":"2026-03-16T07:44:44.391Z","0.3.0":"2026-03-16T08:20:47.180Z","0.4.0":"2026-03-17T04:33:59.524Z","0.4.2":"2026-06-16T19:17:49.555Z","0.5.0":"2026-06-16T19:57:36.295Z"},"bugs":{"url":"https://github.com/ElysiumOSS/grepo/issues"},"author":{"name":"Mike Odnis","url":"https://github.com/WomB0ComB0"},"license":"MIT","homepage":"https://github.com/ElysiumOSS/grepo#readme","keywords":["ai","cli","documentation","gemini","github","readme","repository"],"repository":{"type":"git","url":"git+https://github.com/ElysiumOSS/grepo.git"},"description":"AI-powered GitHub repository management CLI — generate READMEs, topics, descriptions, and more using Gemini","maintainers":[{"name":"womb0comb0","email":"mike@mikeodnis.dev"}],"readme":"# grepo\n\n<p align=\"center\">\n  <b>An agentic CLI tool for analyzing, describing, and generating documentation for GitHub repositories.</b>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/ElysiumOSS/grepo/blob/main/LICENSE.md\" target=\"_blank\"><img alt=\"📝 License: MIT\" src=\"https://img.shields.io/badge/%F0%9F%93%9D_license-MIT-21bb42.svg\" /></a>\n  <a href=\"https://npmjs.com/package/@elysiumoss/grepo\" target=\"_blank\"><img alt=\"📦 npm version\" src=\"https://img.shields.io/npm/v/@elysiumoss/grepo?color=21bb42&label=%F0%9F%93%A6%20npm\" /></a>\n</p>\n\n## Overview\n\n`grepo` automates the heavy lifting of repository maintenance.\nBy integrating with LLM providers like Google Gemini, it intelligently analyzes your codebase to generate professional READMEs, suggest relevant repository topics, craft repository descriptions, summarize technologies, and recommend improvements.\n\n### High-Level Flow\n\n```mermaid\nflowchart LR\n    User([\"👤 User\"]) -->|grepo readme owner/repo| CLI[\"🛠️ grepo CLI\"]\n    CLI --> Config[\"⚙️ Config Builder<br/>env + .grepo + flags\"]\n    Config --> Ingest[\"📦 GitIngest<br/>tree + content\"]\n    Ingest --> LLM[\"🤖 Gemini LLM\"]\n    LLM --> Validator[\"🧪 Mermaid Validator\"]\n    Validator --> Output{\"Output target?\"}\n    Output -->|--push / --apply| GitHub[\"🐙 GitHub API\"]\n    Output -->|local| File[\"📄 README.md / stdout\"]\n    GitHub -.->|writes| Repo[(\"Repository\")]\n```\n\n## Architecture\n\n`grepo` is built on top of the [Effect](https://effect.website/) ecosystem, providing typed errors, composable services, and structured concurrency.\nThe CLI is decomposed into **commands**, **services**, and **utilities**.\n\n### Module Layout\n\n```mermaid\ngraph TB\n    subgraph Entry[\"Entry Point\"]\n        cli[\"cli.ts<br/>argv router\"]\n    end\n\n    subgraph Commands[\"Commands (src/commands)\"]\n        readme[\"readme.ts\"]\n        topics[\"topics.ts\"]\n        describe[\"describe.ts\"]\n        analyze[\"analyze.ts<br/>summary/tech/improve\"]\n    end\n\n    subgraph Services[\"Services (src/services.ts)\"]\n        gemini[\"Gemini Service\"]\n        github[\"GitHub Service\"]\n        gitingest[\"GitIngest fetcher\"]\n    end\n\n    subgraph Utils[\"Utilities (src/utils)\"]\n        args[\"args.ts<br/>parser\"]\n        validation[\"validation.ts<br/>URL/key checks\"]\n        configFile[\"config-file.ts<br/>~/.grepo\"]\n        prompts[\"prompts/readme.ts\"]\n        mermaid[\"mermaid.ts<br/>diagram fixer\"]\n        logger[\"logger.ts\"]\n    end\n\n    cli --> args\n    cli --> configFile\n    cli --> Commands\n    Commands --> Services\n    Commands --> validation\n    readme --> prompts\n    readme --> mermaid\n    Services --> logger\n```\n\n### Layered Architecture\n\n```mermaid\nflowchart TB\n    subgraph Presentation[\"Presentation Layer\"]\n        argv[\"argv parsing\"]\n        usage[\"usage / help text\"]\n        loggerOut[\"structured logger\"]\n    end\n\n    subgraph Application[\"Application Layer (Commands)\"]\n        runReadme[\"readme.run\"]\n        runTopics[\"topics.run\"]\n        runDescribe[\"describe.run\"]\n        runAnalyze[\"analyze.run\"]\n    end\n\n    subgraph Domain[\"Domain Layer (Services)\"]\n        Gemini[\"Gemini (Effect Tag)\"]\n        GitHub[\"GitHub (Effect Tag)\"]\n        fetchRepo[\"fetchRepo\"]\n    end\n\n    subgraph Infra[\"Infrastructure\"]\n        GeminiClient[\"@google/genai\"]\n        GitHubClient[\"fetch + REST v3\"]\n        GitIngestAPI[\"gitingest.com\"]\n    end\n\n    Presentation --> Application\n    Application --> Domain\n    Domain --> Infra\n```\n\n## Command Pipeline\n\nEvery command follows the same shape: **parse → fetch context → prompt → act**.\nThe `readme` command adds analysis, generation, and mermaid validation phases.\n\n### Generic Command Flow\n\n```mermaid\nflowchart TD\n    Start([\"grepo <cmd> <url>\"]) --> ParseArgs[\"Parse argv<br/>(args.ts)\"]\n    ParseArgs --> LoadEnv[\"Load .env / ~/.grepo\"]\n    LoadEnv --> HasKey{\"GEMINI_API_KEY<br/>present?\"}\n    HasKey -->|no| Prompt[\"Interactive setup<br/>(promptConfigSetup)\"]\n    HasKey -->|yes| Build[\"buildConfig()\"]\n    Prompt --> Build\n    Build --> Validate{\"Valid URL +<br/>key + token?\"}\n    Validate -->|no| Fail([\"❌ ValidationError\"])\n    Validate -->|yes| Branch[\"Detect default branch\"]\n    Branch --> Layers[\"Compose Effect layers<br/>(GeminiLive, GitHubLive)\"]\n    Layers --> Dispatch[\"Dispatch by command\"]\n    Dispatch --> Run[\"run(config)\"]\n    Run --> Done([\"✅ Result / push\"])\n```\n\n### `readme` — Three-Phase Generation\n\n```mermaid\nflowchart LR\n    A[\"Repo URL\"] --> B[\"GitIngest fetch\"]\n    B --> C[\"extractExistingReadme\"]\n    C --> D[\"Phase 1<br/>Analysis prompt\"]\n    D --> E[\"parseAnalysis\"]\n    E --> F[\"Phase 2<br/>Generation prompt\"]\n    F --> G[\"Raw markdown\"]\n    G --> H[\"Phase 3<br/>validateAndFixMermaid\"]\n    H --> I{\"Push?\"}\n    I -->|yes| J[\"github.pushFile\"]\n    I -->|no| K[\"writeFile(README.md)\"]\n```\n\n### `topics` — Suggest & Apply\n\n```mermaid\nflowchart LR\n    A[\"Repo URL\"] --> B[\"GitIngest fetch\"]\n    B --> C[\"Topics prompt\"]\n    C --> D[\"Gemini → JSON array\"]\n    D --> E[\"validate topics\"]\n    E --> F{\"--apply?\"}\n    F -->|yes + --merge| G[\"getTopics ∪ new\"]\n    F -->|yes| H[\"setTopics(new)\"]\n    F -->|no / --dry-run| I[\"Print only\"]\n    G --> H\n    H --> J([\"✅ Topics updated\"])\n```\n\n### `describe` — Description + Homepage Detection\n\n```mermaid\nflowchart LR\n    A[\"Repo URL\"] --> B[\"GitIngest fetch\"]\n    B --> C[\"Describe prompt<br/>(detect homepage<br/>from package.json,<br/>CNAME, badges...)\"]\n    C --> D[\"Gemini → {description, homepage}\"]\n    D --> E{\"--apply?\"}\n    E -->|yes| F[\"github.updateRepo\"]\n    E -->|no| G[\"Print only\"]\n    F --> H([\"✅ About section updated\"])\n```\n\n## Service Topology\n\nServices are exposed as `Effect` Context Tags so commands can declare dependencies in their type signature without coupling to concrete clients.\n\n```mermaid\nclassDiagram\n    class GeminiServiceApi {\n        +generateContent(prompt) Effect~string, GeminiError~\n    }\n    class GitHubServiceApi {\n        +getDefaultBranch(owner, repo)\n        +getTopics(owner, repo)\n        +setTopics(owner, repo, topics)\n        +pushFile(owner, repo, path, content, msg, branch)\n        +updateRepo(owner, repo, data)\n    }\n    class GitIngest {\n        +fetchRepo(url, token) Effect~RepoData, GitIngestError~\n    }\n    class GeminiClient {\n        -apiKey\n        +generateContent(prompt)\n    }\n    class GitHubClient {\n        -token\n        +getDefaultBranch()\n        +pushFile()\n        +setTopics()\n        +updateRepo()\n    }\n\n    GeminiServiceApi <|.. GeminiClient : provides\n    GitHubServiceApi <|.. GitHubClient : provides\n    GeminiServiceApi --> GeminiError : may fail with\n    GitHubServiceApi --> GitHubError : may fail with\n    GitIngest --> GitIngestError : may fail with\n```\n\n## Sequence: Generating a README\n\n```mermaid\nsequenceDiagram\n    autonumber\n    actor U as User\n    participant C as grepo CLI\n    participant Cfg as Config\n    participant GI as GitIngest\n    participant G as Gemini\n    participant M as Mermaid Validator\n    participant GH as GitHub API\n    participant FS as Local FS\n\n    U->>C: grepo readme https://github.com/o/r --push\n    C->>Cfg: loadEnv + buildConfig\n    Cfg-->>C: GrepoConfig\n    C->>GH: getDefaultBranch(o, r)\n    GH-->>C: \"main\"\n    C->>GI: fetchRepositoryContent(url)\n    GI-->>C: { tree, content }\n    C->>G: analysisPrompt(tree, content)\n    G-->>C: structured analysis\n    C->>G: generationPrompt(analysis)\n    G-->>C: raw README markdown\n    C->>M: validateAndFixMermaid(raw)\n    alt Diagram has syntax errors\n        M->>G: re-prompt with error\n        G-->>M: corrected diagram\n    end\n    M-->>C: validated README\n    C->>FS: writeFile(\"README.md\")\n    C->>GH: pushFile(o, r, \"README.md\", branch)\n    GH-->>U: ✅ commit\n```\n\n## Configuration Resolution\n\n`grepo` resolves credentials in a layered, override-friendly order:\n\n```mermaid\nflowchart TD\n    Start([\"Need GEMINI_API_KEY\"]) --> Env{\"process.env<br/>GEMINI_API_KEY?\"}\n    Env -->|yes| Use([\"✅ use it\"])\n    Env -->|no| Google{\"GOOGLE_API_KEY?\"}\n    Google -->|yes| Use\n    Google -->|no| File{\"~/.grepo/config<br/>geminiApiKey?\"}\n    File -->|yes| Use\n    File -->|no| Prompt[\"Interactive setup<br/>(promptConfigSetup)\"]\n    Prompt --> Save[\"Save 0600 file<br/>writeConfigFile\"]\n    Save --> Use\n```\n\n## Error Model\n\nErrors are tagged data classes from `errors.ts`.\nEach command declares its possible failures in the type so `Effect.catchTags` can route them to user-friendly messages.\n\n```mermaid\nstateDiagram-v2\n    [*] --> Running\n    Running --> GeminiError: LLM call failed\n    Running --> GitHubError: API call failed\n    Running --> GitIngestError: ingest failed\n    Running --> ValidationError: bad URL / key\n    Running --> Success: ✅ exit 0\n\n    GeminiError --> ExitNonZero: log + exit 1\n    GitHubError --> ExitNonZero\n    GitIngestError --> ExitNonZero\n    ValidationError --> ExitNonZero\n    ExitNonZero --> [*]\n    Success --> [*]\n```\n\n## Installation\n\nEnsure you have [Bun](https://bun.sh/) (or Node ≥ 20.19) installed, then install `grepo` globally:\n\n```bash\nbun add -g @elysiumoss/grepo\n# or\nnpm install -g @elysiumoss/grepo\n```\n\n## Usage\n\nGenerate a new `README.md` for a repository:\n\n```bash\ngrepo readme https://github.com/owner/repo --format md --push\n```\n\nAutomatically update repository topics based on code analysis:\n\n```bash\ngrepo topics https://github.com/owner/repo --apply --merge\n```\n\nGenerate a description and detect the homepage:\n\n```bash\ngrepo describe https://github.com/owner/repo --apply\n```\n\n## CLI Reference\n\n| Command    | Description                                                |\n| :--------- | :--------------------------------------------------------- |\n| `readme`   | Generate and optionally push a README documentation file   |\n| `topics`   | Analyze code and suggest/apply repository topics           |\n| `describe` | Generate a repository description and detect homepage URLs |\n| `summary`  | Provide a comprehensive summary of the repository          |\n| `tech`     | List technologies, frameworks, and tools used              |\n| `improve`  | Suggest 5 specific, actionable improvements                |\n\n### Options\n\n| Flag                  | Applies to              | Description                                                |\n| :-------------------- | :---------------------- | :--------------------------------------------------------- |\n| `--format md\\|mdx`    | `readme`                | Output format (default: `md`)                              |\n| `--style …`           | `readme`                | `minimal`, `standard`, or `comprehensive` (default: standard) |\n| `--output <file>`     | `readme`                | Output file path                                           |\n| `--push`              | `readme`                | Commit the generated file directly to GitHub               |\n| `--apply`             | `topics`, `describe`    | Apply changes to the GitHub API                            |\n| `--merge`             | `topics`                | Merge with existing topics instead of replacing            |\n| `--dry-run`           | all mutating commands   | Preview changes without writing or pushing                 |\n| `--branch <name>`     | `readme`                | Target branch (default: auto-detect from repo)             |\n| `--tone <voice>`      | `readme`                | `casual`, `professional`, `minimal`, or `technical`        |\n\n## Configuration\n\n`grepo` requires authentication for repository access and AI analysis.\nConfigure these via environment variables, a `.env` file, or `~/.grepo/config.json`:\n\n| Key                                 | Required for                       |\n| :---------------------------------- | :--------------------------------- |\n| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | All commands (LLM analysis)        |\n| `GH_TOKEN` / `GITHUB_TOKEN`         | `--push`, `--apply`, `--merge`     |\n\n**Example `.env` file:**\n\n```env\nGEMINI_API_KEY=AIzaSy...\nGH_TOKEN=ghp_...\n```\n\nIf no key is present, `grepo` will run an interactive setup on first use and persist your choices to `~/.grepo/config.json` with `0600` permissions.\n\n## Development\n\n```bash\ngit clone https://github.com/ElysiumOSS/grepo\ncd grepo\nbun install\nbun run build       # tsdown build\nbun run test        # vitest\nbun run lint        # biome check\n```\n\n### Testing Topology\n\n```mermaid\ngraph LR\n    Vitest[\"vitest\"] --> Unit[\"Unit tests<br/>*.test.ts\"]\n    Unit --> ConfigT[\"config.test.ts\"]\n    Unit --> CommandT[\"commands/*.test.ts\"]\n    Unit --> UtilT[\"utils/*.test.ts\"]\n    Unit --> MermaidT[\"mermaid.test.ts\"]\n    Vitest --> Coverage[\"@vitest/coverage-v8<br/>≥ 80% target\"]\n```\n\nSee [`.github/CONTRIBUTING.md`](./.github/CONTRIBUTING.md) and [`.github/DEVELOPMENT.md`](./.github/DEVELOPMENT.md) for detailed guidelines.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE.md).\n","readmeFilename":"README.md"}