{"_id":"@dabighomie/ugwtf","name":"@dabighomie/ugwtf","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@dabighomie/ugwtf","version":"1.0.0","description":"Unified GitHub Workflow Transformation Framework — deploy standardized CI/CD, Copilot automation, and quality gates across all DaBigHomie repos","type":"module","exports":{".":"./dist/index.js","./types":"./dist/types.js"},"bin":{"ugwtf":"dist/index.js"},"scripts":{"build":"rm -rf dist && tsc","dev":"tsx src/index.ts","deploy":"tsx src/index.ts deploy","validate":"tsx src/index.ts validate","fix":"tsx src/index.ts fix","labels":"tsx src/index.ts labels","chain:folder:verify":"tsc --noEmit && vitest run && tsx src/index.ts generate-chain --dry-run --verbose --no-cache","chain:folder:run":"tsx src/index.ts chain","dogfood:setup":"tsx scripts/generate-publish-chain.mts","dogfood:verify":"tsc --noEmit && vitest run && tsx src/index.ts chain ugwtf --dry-run --verbose --no-cache && tsx src/index.ts generate-chain ugwtf --dry-run --verbose --no-cache --path docs/agent-prompts/publish-chain","dogfood:execute":"tsx src/index.ts chain ugwtf --verbose","dogfood:full":"npm run dogfood:setup && npm run dogfood:verify","publish:verify":"npm run build && npm publish --dry-run","type-check":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["github","workflow","automation","copilot","ci-cd","ugwtf"],"author":{"name":"DaBigHomie"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/DaBigHomie/ugwtf.git"},"publishConfig":{"access":"public"},"engines":{"node":">=20.0.0"},"devDependencies":{"@types/node":"^22.0.0","@vitest/coverage-v8":"^3.2.4","tsx":"^4.19.0","typescript":"^5.7.0","vitest":"^3.2.4"},"main":"dist/index.js","types":"dist/index.d.ts","_id":"@dabighomie/ugwtf@1.0.0","gitHead":"2d397128d3e0c96ea7632b034afe496558aaf3d2","bugs":{"url":"https://github.com/DaBigHomie/ugwtf/issues"},"homepage":"https://github.com/DaBigHomie/ugwtf#readme","_nodeVersion":"23.2.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-ecfPCz5pQTom55rxq5p21u1fR76lKqXHL/c7GlyjEh+er3QslO6E77BsqrGytjpSwBxDetTarrGF1kZD+DiuOA==","shasum":"2425746981aa1cdb21d81f350cb1be9aa5c1b493","tarball":"https://registry.npmjs.org/@dabighomie/ugwtf/-/ugwtf-1.0.0.tgz","fileCount":202,"unpackedSize":637596,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDGVYitJVn8Yp2esOWHunr5bKI2z9ugbuVigoTsoazfbAIhAKINZFyoMJwr/G7DVx4xQr+ReiuODihPaxogdui9hIQ+"}]},"_npmUser":{"name":"dabighomie213","email":"dabighomie213@gmail.com"},"directories":{},"maintainers":[{"name":"dabighomie213","email":"dabighomie213@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ugwtf_1.0.0_1774037750713_0.19872831701618088"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-20T20:15:50.528Z","1.0.0":"2026-03-20T20:15:50.920Z","modified":"2026-03-20T20:15:51.182Z"},"maintainers":[{"name":"dabighomie213","email":"dabighomie213@gmail.com"}],"description":"Unified GitHub Workflow Transformation Framework — deploy standardized CI/CD, Copilot automation, and quality gates across all DaBigHomie repos","homepage":"https://github.com/DaBigHomie/ugwtf#readme","keywords":["github","workflow","automation","copilot","ci-cd","ugwtf"],"repository":{"type":"git","url":"git+https://github.com/DaBigHomie/ugwtf.git"},"author":{"name":"DaBigHomie"},"bugs":{"url":"https://github.com/DaBigHomie/ugwtf/issues"},"license":"MIT","readme":"# @dabighomie/ugwtf\n\n**Unified GitHub Workflow & Task Framework** — deploy standardized CI/CD, Copilot automation, and quality gates across all DaBigHomie repos.\n\n## Overview\n\nUGWTF orchestrates **86 agents** across **35 clusters** to manage labels, issues, PRs, workflows, audits, and domain-specific scans for a multi-repo portfolio. Each agent is a self-contained unit with `shouldRun()` and `execute()` methods, coordinated by a swarm executor.\n\n## Quick Start\n\n```bash\n# Install dependencies\nnpm install\n\n# Run a command (dev mode)\nnpx tsx src/index.ts <command> [repos...] [flags]\n\n# Examples\nnpx tsx src/index.ts labels damieus          # Sync labels for damieus\nnpx tsx src/index.ts deploy 043 ffs          # Deploy labels + workflows\nnpx tsx src/index.ts audit --verbose         # Audit all repos\nnpx tsx src/index.ts scan maximus --dry-run  # Full scan, preview only\n```\n\n## Commands\n\n| Command | Clusters | Purpose |\n|---------|----------|---------|\n| `deploy` | labels, workflows | Sync labels + deploy CI/CD workflow YAML |\n| `validate` | quality | Run quality gates (tsc, lint, build, config) |\n| `fix` | labels, workflows, quality | Auto-fix labels + workflows + quality issues |\n| `labels` | labels | Sync universal + repo-specific labels |\n| `issues` | issues | Detect stalled issues, assign Copilot, auto-triage |\n| `prs` | prs | Review Copilot PRs, enforce DB migration firewall |\n| `audit` | audit, visual-audit | Full audit with scoreboard generation |\n| `status` | audit | Quick health snapshot |\n| `prompts` | prompts | Manage prompt files |\n| `chain` | chain | Run prompt chain workflows |\n| `security` | security | Security vulnerability scan |\n| `performance` | performance | Performance audit |\n| `a11y` | a11y | Accessibility audit |\n| `seo` | seo | SEO optimization scan |\n| `docs` | docs, context | Documentation sync + context analysis |\n| `commerce` | commerce | E-commerce feature scan |\n| `scenarios` | scenarios | Scenario-based testing |\n| `design-system` | design-system | Design system audit |\n| `supabase` | supabase-fsd | Supabase + FSD compliance |\n| `gateway` | ai-gateway | AI gateway integration |\n| `scan` | *(all 27 domain clusters)* | Comprehensive full scan |\n\n## Flags\n\n```\n--dry-run        Preview changes without executing\n--verbose, -v    Show debug output\n--concurrency N  Max parallel repos (default: 3)\n--cluster ID     Run specific cluster (repeatable)\n```\n\n## Registered Repos\n\n| Alias | Repository |\n|-------|-----------|\n| `damieus` | DaBigHomie/damieus-com-migration |\n| `ffs` | DaBigHomie/flipflops-sundays-reboot |\n| `043` | DaBigHomie/one4three-co-next-app |\n| `maximus` | DaBigHomie/maximus-ai |\n| `cae` | DaBigHomie/cae-luxury-hair |\n\nOmit repos to target all registered repos.\n\n## Architecture\n\n```\nsrc/\n├── index.ts               # CLI entry point + argument parser\n├── orchestrator.ts        # Maps commands → clusters, runs swarm\n├── types.ts               # All TypeScript interfaces\n├── agents/                # 86 agent implementations (36 files)\n│   ├── label-agents.ts\n│   ├── issue-agents.ts\n│   ├── pr-agents.ts\n│   ├── audit-agents.ts\n│   └── ...\n├── clients/\n│   └── github.ts          # GitHub API client (Octokit wrapper)\n├── clusters/\n│   └── index.ts           # 34 cluster definitions + dependency ordering\n├── commands/\n│   ├── list.ts            # List repos/clusters/agents\n│   └── run-agent.ts       # Run a single agent by ID\n├── config/\n│   └── repo-registry.ts   # Repo definitions + universal labels\n├── generators/            # Workflow YAML generators (7 files)\n│   ├── ci-workflow.ts\n│   ├── copilot-automation.ts\n│   └── ...\n├── integrations/\n│   └── supabase.ts        # Supabase integration utilities\n├── output/\n│   ├── scoreboard.ts      # Health scoreboard generation\n│   ├── persist.ts         # Result persistence (JSON + Markdown)\n│   ├── json-reporter.ts   # JSON report formatter\n│   ├── markdown-reporter.ts # Markdown report formatter\n│   └── findings-formatter.ts # Findings output\n├── plugins/\n│   └── loader.ts          # Auto-discovers @ugwtf/* plugin packages\n├── scaffold/\n│   ├── new-agent.ts       # Scaffold a new agent file\n│   └── new-repo.ts        # Scaffold a new repo config\n├── swarm/\n│   └── executor.ts        # Fan-out executor (sequential/parallel)\n├── watch/\n│   ├── watcher.ts         # File watcher for dev mode\n│   └── cache.ts           # Watch cache management\n└── utils/\n    ├── fs.ts              # File I/O + YAML helpers\n    └── logger.ts          # Structured logger with levels\n```\n\n## Agent Model\n\nEvery agent implements the `Agent` interface:\n\n```typescript\ninterface Agent {\n  id: string;          // Unique identifier (e.g., \"label-sync\")\n  name: string;        // Display name\n  description: string; // What the agent does\n  clusterId: string;   // Parent cluster ID\n  execute(ctx: AgentContext): Promise<AgentResult>;\n  shouldRun(ctx: AgentContext): boolean;\n}\n```\n\nAgents are grouped into **clusters**. The executor fans out across repos, running each cluster's agents in sequence per repo while optionally parallelizing across repos.\n\n## Plugins\n\nUGWTF supports external plugin packages that register additional clusters without modifying the core source.\n\n### How plugins work\n\nA plugin exports a `UGWTFPlugin` object:\n\n```typescript\nimport type { UGWTFPlugin, PluginRegistry } from '@dabighomie/ugwtf/types';\nimport { myCluster } from './cluster.js';\n\nexport const plugin: UGWTFPlugin = {\n  name: 'my-plugin',\n  version: '1.0.0',\n  register(registry: PluginRegistry): void {\n    registry.addCluster(myCluster);\n    // registry.addAgent('existing-cluster-id', extraAgent);\n    // registry.addCommand('my-command', ['my-cluster']);\n  },\n};\n```\n\n### Auto-discovery\n\nPackages scoped under `@ugwtf/*` are scanned at startup. Any package that declares `\"ugwtf-plugin\": true` in its `package.json` is loaded automatically via `src/plugins/loader.ts`.\n\n### First-party plugins\n\n**`@dabighomie/audit-orchestrator`** — visual audit cluster with 10 agents:\n\n```typescript\n// audit-orchestrator/src/ugwtf-plugin.ts\nexport const plugin: UGWTFPlugin = {\n  name: 'visual-audit',\n  version: '1.1.0',\n  register(registry: PluginRegistry): void {\n    registry.addCluster(visualAuditCluster);\n  },\n};\n```\n\nUsage:\n\n```bash\nnpx ugwtf audit --cluster visual-audit\nnpx ugwtf audit damieus --cluster visual-audit --verbose\n```\n\n### Writing a custom plugin\n\nSee **[docs/ADDING-AGENTS.md](docs/ADDING-AGENTS.md)** for a step-by-step guide covering:\n\n- The `Agent` interface and `AgentContext` / `AgentResult` types\n- Creating agents and registering them in a cluster\n- Plugin package structure for external distribution\n- Testing patterns and checklist for new agents\n\n## Development\n\n### Environment Setup\n\nCopy `.env.example` to `.env` and fill in your values:\n\n```bash\ncp .env.example .env\n```\n\nThe `.env` file is loaded automatically by the CLI. Existing env vars always take precedence.\n\n**Required when `gh` CLI is not installed:**\n- `GITHUB_TOKEN` — Personal Access Token with `repo`, `workflow`, `read:org` scopes\n\nThe CLI auto-detects `gh` CLI on PATH and uses it for API calls. If `gh` is unavailable, it falls back to native `fetch` with `GITHUB_TOKEN` or `GH_TOKEN`.\n\n### GitHub Actions Secrets\n\n| Secret | Required For | Description |\n|--------|-------------|-------------|\n| `UGWTF_PAT` | Deploy + Audit workflows | Fine-grained PAT with `contents:write`, `issues:write`, `pull-requests:write`, `workflows:write` scoped to DaBigHomie org repos |\n| `NPM_TOKEN` | Release workflow | npm publish token (automation type) |\n| `NOTIFICATION_WEBHOOK_URL` | Audit regression alerts | Slack or Discord webhook URL |\n\n### Branch Protection (Recommended)\n\nEnable on `main` branch:\n- Require CI status checks to pass (`type-check`, `test`)\n- Prevent force pushes\n- Require linear history (optional)\n\n```bash\n# Type check\nnpx tsc --noEmit\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Build\nnpm run build\n```\n\n## CI/CD Workflows\n\n| Workflow | Trigger | Purpose |\n|----------|---------|---------|\n| `ci.yml` | Push + PR to `main` | Type check, test, PR scoreboard comment |\n| `release.yml` | Tag `v*` | Build, publish to npm, create GitHub Release |\n| `ugwtf-audit.yml` | Nightly cron + manual | Run audit, upload scoreboard, notify on regression |\n| `ugwtf-deploy.yml` | Push to `main` | Deploy labels + workflows to all repos |\n\n**Dependabot** is configured for weekly npm + GitHub Actions updates.\n\n## Testing\n\n- **Framework**: Vitest\n- **400 tests** across 21 test files\n- **Coverage threshold**: 60% lines\n\n```\nsrc/utils/fs.test.ts             10 tests\nsrc/utils/logger.test.ts          6 tests\nsrc/utils/output.test.ts         14 tests\nsrc/config/repo-registry.test.ts 11 tests\nsrc/clusters/clusters.test.ts    11 tests\nsrc/orchestrator.test.ts          5 tests\nsrc/index.test.ts                17 tests\nsrc/swarm/executor.test.ts        8 tests\nsrc/scoreboard/scoreboard.test.ts 9 tests\nsrc/integration.test.ts          12 tests\n... + additional swarm/scoreboard tests up to 147 total\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n","readmeFilename":"README.md","_rev":"1-615abaa6c52740df9dadd0cf4b00b048"}