{"id":31574707,"url":"https://github.com/stackql/stackql-provider-homebrew","last_synced_at":"2025-10-05T16:58:05.713Z","repository":{"id":315392275,"uuid":"1059286631","full_name":"stackql/stackql-provider-homebrew","owner":"stackql","description":"generate stackql provider for Homebrew from openapi specs","archived":false,"fork":false,"pushed_at":"2025-09-18T09:09:51.000Z","size":285,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-18T11:30:46.619Z","etag":null,"topics":["homebrew","stackql","stackql-provider"],"latest_commit_sha":null,"homepage":"http://homebrew-provider.stackql.io/","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/stackql.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":null,"dco":null,"cla":null}},"created_at":"2025-09-18T08:43:22.000Z","updated_at":"2025-09-18T09:09:56.000Z","dependencies_parsed_at":"2025-09-18T11:31:26.137Z","dependency_job_id":"279b718c-0510-489c-b695-1014fa914009","html_url":"https://github.com/stackql/stackql-provider-homebrew","commit_stats":null,"previous_names":["stackql/stackql-provider-homebrew"],"tags_count":null,"template":false,"template_full_name":"stackql/stackql-provider-TEMPLATE","purl":"pkg:github/stackql/stackql-provider-homebrew","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-homebrew","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-homebrew/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-homebrew/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-homebrew/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackql","download_url":"https://codeload.github.com/stackql/stackql-provider-homebrew/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fstackql-provider-homebrew/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278486275,"owners_count":25994941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"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":["homebrew","stackql","stackql-provider"],"created_at":"2025-10-05T16:58:01.585Z","updated_at":"2025-10-05T16:58:05.708Z","avatar_url":"https://github.com/stackql.png","language":"JavaScript","readme":"# `homebrew` provider for [`stackql`](https://github.com/stackql/stackql)\r\n\r\nThis repository is used to generate and document the `homebrew` provider for StackQL, allowing you to query Homebrew packages, formulas, and repositories using SQL-like syntax. The provider is built using the `@stackql/provider-utils` package, which provides tools for converting OpenAPI specifications into StackQL-compatible provider schemas.\r\n\r\n## Prerequisites\r\n\r\nTo use the Homebrew provider with StackQL, you'll need:\r\n\r\n1. StackQL CLI installed on your system (see [StackQL](https://github.com/stackql/stackql))\r\n2. Basic understanding of Homebrew API endpoints\r\n\r\n## 1. Download the Open API Specification\r\n\r\nFirst, create an OpenAPI specification for the Homebrew API (since Homebrew doesn't provide an official one):\r\n\r\n```bash\r\nmkdir -p provider-dev/downloaded\r\n# Create or download the homebrew OpenAPI spec\r\n# You'll need to implement a script that generates an OpenAPI spec from Homebrew's API endpoints\r\npython3 provider-dev/scripts/generate_homebrew_spec.py \\\r\n  --output provider-dev/downloaded/openapi.json\r\n```\r\n\r\n## 2. Split into Service Specs\r\n\r\nNext, split the OpenAPI specification into service-specific files:\r\n\r\n```bash\r\nrm -rf provider-dev/source/*\r\nnpm run split -- \\\r\n  --provider-name homebrew \\\r\n  --api-doc provider-dev/downloaded/openapi.json \\\r\n  --svc-discriminator tag \\\r\n  --output-dir provider-dev/source \\\r\n  --overwrite \\\r\n  --svc-name-overrides \"$(cat \u003c\u003cEOF\r\n{\r\n  \"formulas\": \"formulas\",\r\n  \"casks\": \"casks\",\r\n  \"analytics\": \"analytics\",\r\n  \"taps\": \"taps\"\r\n}\r\nEOF\r\n)\"\r\n```\r\n\r\n## 3. Generate Mappings\r\n\r\nGenerate the mapping configuration that connects OpenAPI operations to StackQL resources:\r\n\r\n```bash\r\nnpm run generate-mappings -- \\\r\n  --provider-name homebrew \\\r\n  --input-dir provider-dev/source \\\r\n  --output-dir provider-dev/config\r\n```\r\n\r\nUpdate the resultant `provider-dev/config/all_services.csv` to add the `stackql_resource_name`, `stackql_method_name`, `stackql_verb` values for each operation.\r\n\r\n## 4. Generate Provider\r\n\r\nThis step transforms the split OpenAPI service specs into a fully-functional StackQL provider by applying the resource and method mappings defined in your CSV file.\r\n\r\n```bash\r\nrm -rf provider-dev/openapi/*\r\nnpm run generate-provider -- \\\r\n  --provider-name homebrew \\\r\n  --input-dir provider-dev/source \\\r\n  --output-dir provider-dev/openapi/src/homebrew \\\r\n  --config-path provider-dev/config/all_services.csv \\\r\n  --servers '[{\"url\": \"https://formulae.brew.sh/api\"}]' \\\r\n  --provider-config '{\"auth\": {\"type\": \"none\"}}' \\\r\n  --overwrite\r\n```\r\n\r\n## 5. Test Provider\r\n\r\n### Starting the StackQL Server\r\n\r\nBefore running tests, start a StackQL server with your provider:\r\n\r\n```bash\r\nPROVIDER_REGISTRY_ROOT_DIR=\"$(pwd)/provider-dev/openapi\"\r\nnpm run start-server -- --provider homebrew --registry $PROVIDER_REGISTRY_ROOT_DIR\r\n```\r\n\r\n### Test Meta Routes\r\n\r\nTest all metadata routes (services, resources, methods) in the provider:\r\n\r\n```bash\r\nnpm run test-meta-routes -- homebrew --verbose\r\n```\r\n\r\nWhen you're done testing, stop the StackQL server:\r\n\r\n```bash\r\nnpm run stop-server\r\n```\r\n\r\nUse this command to view the server status:\r\n\r\n```bash\r\nnpm run server-status\r\n```\r\n\r\n### Run test queries\r\n\r\nRun some test queries against the provider using the `stackql shell`:\r\n\r\n```bash\r\nPROVIDER_REGISTRY_ROOT_DIR=\"$(pwd)/provider-dev/openapi\"\r\nREG_STR='{\"url\": \"file://'${PROVIDER_REGISTRY_ROOT_DIR}'\", \"localDocRoot\": \"'${PROVIDER_REGISTRY_ROOT_DIR}'\", \"verifyConfig\": {\"nopVerify\": true}}'\r\n./stackql shell --registry=\"${REG_STR}\"\r\n```\r\n\r\nExample queries to try:\r\n\r\n```sql\r\n-- List all formulas\r\nSELECT \r\nname,\r\nfull_name,\r\ndesc,\r\nlicense,\r\nhomepage,\r\nversions,\r\ndependencies,\r\nconflicts_with\r\nFROM homebrew.formulas.formulas;\r\n\r\n-- Get information about a specific formula\r\nSELECT \r\nname,\r\nfull_name,\r\ndesc,\r\nlicense,\r\nhomepage,\r\nversions,\r\ndependencies,\r\nconflicts_with,\r\nbuild_dependencies,\r\nrequirements\r\nFROM homebrew.formulas.formula\r\nWHERE name = 'wget';\r\n\r\n-- List all casks\r\nSELECT \r\nname,\r\nfull_name,\r\ntoken,\r\ndesc,\r\nhomepage,\r\nversion,\r\nurl\r\nFROM homebrew.casks.casks;\r\n\r\n-- Get analytics for popular formula installations\r\nSELECT \r\nformula,\r\ncount,\r\npercent\r\nFROM homebrew.analytics.install_30d\r\nORDER BY count DESC\r\nLIMIT 10;\r\n\r\n-- Get analytics for formula installations over longer periods\r\nSELECT \r\nformula,\r\ncount,\r\npercent\r\nFROM homebrew.analytics.install_365d\r\nORDER BY count DESC\r\nLIMIT 10;\r\n```\r\n\r\n## 6. Publish the provider\r\n\r\nTo publish the provider push the `homebrew` dir to `providers/src` in a feature branch of the [`stackql-provider-registry`](https://github.com/stackql/stackql-provider-registry). Follow the [registry release flow](https://github.com/stackql/stackql-provider-registry/blob/dev/docs/build-and-deployment.md).  \r\n\r\nLaunch the StackQL shell:\r\n\r\n```bash\r\nexport DEV_REG=\"{ \\\"url\\\": \\\"https://registry-dev.stackql.app/providers\\\" }\"\r\n./stackql --registry=\"${DEV_REG}\" shell\r\n```\r\n\r\nPull the latest dev `homebrew` provider:\r\n\r\n```sql\r\nregistry pull homebrew;\r\n```\r\n\r\nRun some test queries to verify the provider works as expected.\r\n\r\n## 7. Generate web docs\r\n\r\nProvider doc microsites are built using Docusaurus and published using GitHub Pages.  \r\n\r\na. Update `headerContent1.txt` and `headerContent2.txt` accordingly in `provider-dev/docgen/provider-data/`  \r\n\r\nb. Update the following in `website/docusaurus.config.js`:  \r\n\r\n```js\r\n// Provider configuration - change these for different providers\r\nconst providerName = \"homebrew\";\r\nconst providerTitle = \"Homebrew Provider\";\r\n```\r\n\r\nc. Then generate docs using...\r\n\r\n```bash\r\nnpm run generate-docs -- \\\r\n  --provider-name homebrew \\\r\n  --provider-dir ./provider-dev/openapi/src/homebrew/v00.00.00000 \\\r\n  --output-dir ./website \\\r\n  --provider-data-dir ./provider-dev/docgen/provider-data\r\n```  \r\n\r\n## 8. Test web docs locally\r\n\r\n```bash\r\ncd website\r\n# test build\r\nyarn build\r\n\r\n# run local dev server\r\nyarn start\r\n```\r\n\r\n## 9. Publish web docs to GitHub Pages\r\n\r\nUnder __Pages__ in the repository, in the __Build and deployment__ section select __GitHub Actions__ as the __Source__. In Netlify DNS create the following records:\r\n\r\n| Source Domain | Record Type  | Target |\r\n|---------------|--------------|--------|\r\n| homebrew-provider.stackql.io | CNAME | stackql.github.io. |\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fstackql-provider-homebrew","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackql%2Fstackql-provider-homebrew","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fstackql-provider-homebrew/lists"}