@jiggai/recipes 0.2.22 → 0.2.24

package/README.md

@@ -1,7 +1,7 @@
 # ClawRecipes (OpenClaw Recipes Plugin)
 
 <p align="center">
-  <img src="./clawrecipes_cook.jpg" alt="ClawRecipes logo" width="240" />
+  <img src="https://github.com/JIGGAI/ClawRecipes/blob/main/clawcipes_cook.jpg" alt="ClawRecipes logo" width="240" />
 </p>
 
 ClawRecipes is an OpenClaw plugin that provides **CLI-first recipes** for scaffolding specialist agents and teams from Markdown.
@@ -134,12 +134,15 @@ Notes:
 ## Links
 - GitHub: https://github.com/JIGGAI/ClawRecipes
 - Docs:
-  - Installation: `docs/INSTALLATION.md`
-  - Commands: `docs/COMMANDS.md`
-  - Recipe format: `docs/RECIPE_FORMAT.md`
-  - Team workflow: `docs/TEAM_WORKFLOW.md`
-
-## What you should be developing (not this plugin)
+  - [Installation](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/INSTALLATION.md): `docs/INSTALLATION.md`
+  - [Commands](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/COMMANDS.md): `docs/COMMANDS.md`
+  - [Recipe format](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/RECIPE_FORMAT.md): `docs/RECIPE_FORMAT.md`
+  - [Team workflow](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/TEAM_WORKFLOW.md): `docs/TEAM_WORKFLOW.md`
+  - [Agents & Skills](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/AGENTS_AND_SKILLS.md): `docs/AGENTS_AND_SKILLS.md`
+  - [Bundled](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/BUNDLED_RECIPES.md): `docs/BUNDLED_RECIPES.md`
+  - [Create Recipe Tutorial](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/TUTORIAL_CREATE_RECIPE.md): `docs/TUTORIAL_CREATE_RECIPE.md`
+
+## Note
 ClawRecipes is meant to be *installed* and then used to build **agents + teams**.
 
 Most users should focus on:

package/docs/AGENTS_AND_SKILLS.md

@@ -38,15 +38,27 @@ In OpenClaw, skills are surfaced as tools the agent can use.
 ## Tool policies (allow/deny)
 Every agent can have a tool policy in OpenClaw config (written via `--apply-config` when scaffolding).
 
-ClawRecipes recipes commonly use:
-- `allow: ["group:fs", "group:web"]` for safe file + web access
-- `allow: ["group:runtime"]` when the agent needs to run local commands
-- `allow: ["group:automation"]` for automation-oriented tools
-- `deny: ["exec"]` for safety on agents that shouldn’t execute commands
-
-The intent:
-- Most agents should **not** have `exec`.
-- Only agents that truly need it (dev/devops) should get runtime/exec capabilities.
+### About `exec`
+`exec` is the shell-command tool. It can be used for things like:
+- running tests/builds (`npm test`, `npm run build`)
+- git operations (`git status`, `git diff`)
+- codegen/migrations (`prisma migrate`, `pnpm lint`)
+- quick diagnostics (`curl`, `jq`, `rg`)
+
+ClawRecipes **does not deny `exec` by default** (many recipes set `deny: []`).
+
+If you want an agent to be able to run commands, you must explicitly allow runtime capabilities.
+
+### Common patterns
+- Safe-by-default agents:
+  - `allow: ["group:fs", "group:web"]`
+  - `deny: ["exec"]` (optional hard block)
+
+- Developer/devops-style agents:
+  - `allow: ["group:fs", "group:web", "group:runtime"]`
+  - `deny: []`
+
+> Note: even when allowed, `exec` may still be gated by your OpenClaw exec approvals / allowlists.
 
 ## How to add/update tool access (allow list)
 There are two common approaches.

package/docs/BUNDLED_RECIPES.md

@@ -29,7 +29,7 @@ Default tool policy (recipe-defined):
 ## 2) `social-team` (team)
 **Kind:** team
 
-**Use when:** you want a multi-role social pipeline: lead + research + writer + editor.
+**Use when:** you want platform-specialist social execution (not copywriting): distribution + listening + platform SEO + community + reporting back to marketing.
 
 Scaffold:
 ```bash
@@ -37,14 +37,19 @@ openclaw recipes scaffold-team social-team --team-id social-team-team --apply-co
 ```
 
 What it creates:
-- `teams/social-team-team/` shared workspace
+- shared team workspace
 - agents:
-  - `agents/social-team-team-lead/`
-  - `agents/social-team-team-research/`
-  - `agents/social-team-team-writer/`
-  - `agents/social-team-team-editor/`
+  - `lead`
+  - `research`
+  - `listening`
+  - `social-seo`
+  - `editorial`
+  - `community`
+  - `distributor`
+  - platform roles: `tiktok`, `instagram`, `youtube`, `facebook`, plus defaults `x`, `linkedin`
 
 Notes:
+- Copy + creative live in `marketing-team` (not here).
 - Default `tools` in the recipe deny `exec` (safer by default).
 
 ## 3) `development-team` (team)
@@ -206,7 +211,7 @@ openclaw recipes scaffold-team marketing-team --team-id marketing-team-team --ap
 ```
 
 Roles:
-- lead, seo, copywriter, ads, social, designer, analyst
+- lead, seo, copywriter, ads, social, designer, analyst, video, compliance
 
 ---
 

package/docs/CLEANUP_TODO.md

@@ -0,0 +1,31 @@
+# Cleanup TODO
+
+## Infrastructure
+
+- [x] Add @vitest/coverage-v8, test:coverage script
+- [x] Create TEST_COVERAGE_PROGRESS.md, CODE_SMELLS_TRACKER.md
+- [x] Run baseline coverage, populate progress doc
+- [x] Update TEST_COVERAGE_PROGRESS.md after each coverage batch
+
+## Code Smells
+
+- [x] Extract fileExists to src/lib/fs-utils
+- [x] Extract stableStringify to src/lib/stable-stringify
+- [x] Unify parseFrontmatter/normalizeCronJobs (use recipe-frontmatter)
+- [x] Replace magic numbers in toolsInvoke
+
+## Test Coverage
+
+- [x] lanes.ts
+- [x] ticket-finder.ts
+- [x] cleanup-workspaces (expand)
+- [x] remove-team (expand)
+- [x] marketplaceFetch (with fetch mock)
+- [x] toolsInvoke (with fetch mock)
+- [x] Extracted config, template, cron-utils, agent-config
+- [x] index.ts handlers (via extraction or integration)
+
+## Final
+
+- [x] Set coverage thresholds (phased: 25% baseline; target 95%)
+- [x] Verify npm run test:coverage passes

package/docs/CODE_SMELLS_TRACKER.md

@@ -0,0 +1,42 @@
+# Code Smells Tracker
+
+| # | Smell | Status | Priority | Notes |
+|---|-------|--------|----------|-------|
+| 1 | fileExists duplicated (index, ticket-finder, ticket-workflow, lanes, remove-team) | done | high | Extracted to src/lib/fs-utils |
+| 2 | stableStringify duplicated (index, bindings) | done | high | Extracted to src/lib/stable-stringify |
+| 3 | parseFrontmatter/normalizeCronJobs duplicated (index, recipe-frontmatter) | done | high | Unified; recipe-frontmatter extended with message/task/prompt |
+| 4 | Magic numbers in toolsInvoke (30_000, 150*attempt) | done | medium | Extracted as TOOLS_INVOKE_TIMEOUT_MS, RETRY_DELAY_BASE_MS |
+| 5 | index.ts god file (~2500 lines) | done | low | Extracted handlers to src/handlers/; index now ~670 lines (Phase 3) |
+| 6 | Duplicate ticket-finding logic (ticket-workflow vs ticket-finder) | done | medium | ticket-workflow now delegates to ticket-finder |
+| 7 | Duplicated ticket regex patterns | done | low | TICKET_FILENAME_REGEX in ticket-finder; tickets uses it |
+| 8 | Hardcoded "recipes" in scaffold | done | low | scaffold uses cfg.workspaceRecipesDir |
+| 9 | Lane path duplication in tickets | done | low | tickets uses ticketStageDir from lanes |
+| 10 | Magic numbers (1000, 18789, 0000) | done | low | MAX_RECIPE_ID_AUTO_INCREMENT, GATEWAY_DEFAULT_PORT, DEFAULT_TICKET_NUMBER in constants |
+| 11 | Overlapping TicketLane/TicketStage types | done | low | TicketLane = Exclude<TicketStage, "assignments"> in lanes; ticket-finder re-exports |
+| 12 | Config load/write duplicated | done | medium | loadOpenClawConfig, writeOpenClawConfig in recipes-config; all callers use them |
+| 13 | nextTicketNumber inline in dispatch | done | low | Extracted computeNextTicketNumber to ticket-finder |
+| 14 | bindings.ts vs recipes-config duplication | done | low | bindings re-exports from recipes-config; bindings.test uses recipes-config |
+| 15 | Silent catch in handleDispatch | done | low | Documented: non-critical enqueueSystemEvent, nudgeQueued reflects skip |
+| 16 | Duplicate pickRecipeId (scaffold vs team) | done | medium | Extracted to src/lib/recipe-id |
+| 17 | Hardcoded "recipes" in team | done | low | team uses cfg.workspaceRecipesDir |
+| 18 | as any in recipe-frontmatter normalizeCronJobs | done | low | CronJobInput type |
+| 19 | as any in cron.ts (scope, created response) | done | low | Proper types; CronAddResponse, CronReconcileResult |
+| 20 | getCfg trivial wrapper in recipes | done | very low | Inlined getRecipesConfig |
+| 21 | results: any[] in cron | done | low | CronReconcileResult union type |
+
+## Automated smell detection
+
+Run `npm run smell-check` to:
+- **ESLint**: `no-explicit-any`, `complexity`, `max-lines-per-function`, `max-params` (src/; index.ts exempt from complexity/lines)
+- **jscpd**: Duplicate code detection (≥8 lines, ≥50 tokens)
+- **Pattern grep**: `as any` in src/ (max 10), TODO/FIXME/XXX (max 20)
+
+Scripts: `npm run lint`, `npm run lint:fix`, `npm run jscpd`, `npm run smell-check`
+
+## Resolution log
+
+- **Smell 5**: Index handler extraction (Phase 2–3) moved ~1200 lines to src/handlers/{cron,recipes,scaffold,team,tickets,install}.ts. index.ts now thin CLI wiring only.
+- **Smells 6–11**: Additional cleanup: consolidated ticket-finding, extracted regex/constants, used config for recipes dir, ticketStageDir, magic-number constants, unified lane types.
+- **Smells 12–15**: Config helpers (load/write), computeNextTicketNumber, bindings consolidation, silent-catch documentation.
+- **Smells 16–21**: pickRecipeId extracted to recipe-id; team uses workspaceRecipesDir; CronJobInput type; cron types (CronAddResponse, CronReconcileResult); getCfg inlined; config double-lookup comment.
+- **Post-cleanup complete** (Feb 2026): All 21 smells resolved; smell-check passes with 0 warnings. Additional quality improvements: pre-commit hooks (husky + lint-staged), CI coverage enforcement, tsconfig.json, JSDoc for public APIs.

package/docs/SMELLS_TODO.md

@@ -0,0 +1,23 @@
+# Remaining Code Smells — TODO
+
+## Type safety (`as any` / `any`) — DONE
+
+- [x] **cron.ts** — Replaced with OpenClawCronJob, CronJobPatch, OpenClawPluginApi
+- [x] **team.ts** — AgentScaffoldResult, MigrateStep types
+- [x] **recipes-config.ts** — OpenClawConfigMutable
+- [x] **remove-team.ts** — Record<string, unknown>
+- [ ] **index.ts** — ~16 options: any remain (partial: install, scaffold use typed opts)
+- [x] **Misc** — recipes, tickets, agent-config, config, cron-utils, marketplaceFetch, toolsInvoke, lanes, cleanup-workspaces, recipe-frontmatter
+
+## Duplicate code (jscpd) — DONE
+
+- [x] **ticket-workflow.ts** — patchTicketFields extracted
+- [x] **tickets.ts** — dryRunTicketMove extracted
+- [x] **index.ts** — runInstallRecipe, logScaffoldResult extracted
+
+## Remaining (deferred)
+
+- [ ] **Complexity** — reconcileRecipeCronJobs (55), handleScaffoldTeam (27), etc.
+- [ ] **Long functions** — handleScaffoldTeam (163), reconcileRecipeCronJobs (139)
+- [ ] **scaffold.ts ↔ team.ts** — pickRecipeId already shared; further unification optional
+- [ ] **Console in src/lib** — Logging abstraction

package/docs/TEAM_WORKFLOW.md

@@ -61,7 +61,9 @@ Two concepts people often mix up:
 Even if `openclaw recipes dispatch` created an inbox entry + backlog ticket, the lead won’t act unless:
 - a human opens the lead agent/chat, **or**
 - an automation loop runs (cron triage), **or**
-- `main` is allowed to message/spawn the lead agent.
+- a best-effort nudge reaches the lead session.
+
+By default, `openclaw recipes dispatch` will try to **enqueue a system event** to `agent:<teamId>-lead:main` (best-effort). If it can’t, the CLI prints explicit next steps (enable cron / run lead once / allowlist direct pings).
 
 ### Allowlisting other agents (subagents.allowAgents)
 To allow `main` to target team role agents (like `development-team-lead`), add this to your OpenClaw config:

package/docs/TEST_COVERAGE_PROGRESS.md

@@ -0,0 +1,37 @@
+# Test Coverage Progress
+
+Target: 95% line coverage.
+
+## Baseline (before cleanup)
+
+| File | % Stmts | % Branch | % Funcs | % Lines | Notes |
+|------|---------|----------|---------|---------|-------|
+| index.ts | 4.16 | 61.53 | 18.42 | 4.16 | God file; most logic untested |
+| src/marketplaceFetch.ts | 0 | 100 | 100 | 0 | Needs fetch mock |
+| src/toolsInvoke.ts | 0 | 100 | 0 | 0 | Needs fetch mock |
+| src/lib/bindings.ts | 91.42 | 66.66 | 100 | 91.42 | Lines 50-52 uncovered |
+| src/lib/cleanup-workspaces.ts | 78.51 | 61.9 | 100 | 78.51 | |
+| src/lib/lanes.ts | 60 | 83.33 | 66.66 | 60 | |
+| src/lib/recipe-frontmatter.ts | 93.54 | 70.83 | 100 | 93.54 | |
+| src/lib/remove-team.ts | 81.51 | 70.58 | 63.63 | 81.51 | |
+| src/lib/scaffold-templates.ts | 100 | 100 | 100 | 100 | |
+| src/lib/shared-context.ts | 100 | 85.71 | 100 | 100 | |
+| src/lib/ticket-finder.ts | 0 | 0 | 0 | 0 | Not yet exercised by tests |
+| src/lib/ticket-workflow.ts | 96.52 | 37.5 | 100 | 96.52 | |
+| **All files** | **18.25** | **58.85** | **48.83** | **18.25** | |
+
+## Gaps to address
+
+- index.ts: extract logic to src/lib and test there; add integration tests for command handlers
+- ticket-finder.ts: add tests
+- marketplaceFetch, toolsInvoke: mock fetch, add tests
+- lanes.ts, cleanup-workspaces, remove-team: expand tests
+
+## Updates
+
+- **Baseline**: Initial coverage run before cleanup work.
+- **Post-cleanup**: 25% overall; src/lib at 91.53%, src/ at 98.36%. index.ts remains low (3.91%) — extraction moved logic to lib. Thresholds set at 25% baseline; target 95% as further index extraction proceeds.
+- **Index handler extraction (Phase 2–3)**: Handler logic moved to src/handlers/; exercised via __internal in integration tests.
+- **Post-extraction baseline** (npm run test:coverage): 56.55% overall; src/ at 98.36%; src/handlers at 66.44%; src/lib at 94.63%; index.ts at 9.62% (thin CLI wiring).
+- **Comprehensive coverage plan** (Phase 1–3): cron-handler, install-handler, prompt, workspace, scaffold, team, tickets, recipes tests added. Thresholds raised to 60% lines/statements, 90% functions. index.ts remains thin wiring; logic exercised via __internal.
+- **CI coverage enforcement** (Feb 2026): CI now runs `npm run test:coverage`; build fails if thresholds are not met. Thresholds: lines 60%, statements 60%, functions 90%, branches 65%.