@caddis/cli 0.4.92 → 0.4.94

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +4 -0
  2. package/bundles/antigravity-plugin/agents/debug.md +2 -0
  3. package/bundles/antigravity-plugin/guard_agy.py +6 -2
  4. package/bundles/antigravity-plugin/plugin.json +1 -1
  5. package/bundles/antigravity-plugin/repo_freshness.py +71 -6
  6. package/bundles/antigravity-plugin/repo_hygiene.py +516 -0
  7. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
  8. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
  9. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
  10. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
  11. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
  12. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
  13. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
  14. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
  15. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
  16. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
  17. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
  18. package/bundles/antigravity-plugin/scripts/caddis_checkout_guard.py +1 -1
  19. package/bundles/antigravity-plugin/scripts/caddis_finished.py +537 -0
  20. package/bundles/antigravity-plugin/scripts/caddis_fleet.py +26 -9
  21. package/bundles/antigravity-plugin/scripts/caddis_guide.json +65 -12
  22. package/bundles/antigravity-plugin/scripts/caddis_own_cleanup.py +23 -248
  23. package/bundles/antigravity-plugin/scripts/caddis_preload_review.py +554 -0
  24. package/bundles/antigravity-plugin/scripts/caddis_repo_tidy.py +240 -0
  25. package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +9 -3
  26. package/bundles/antigravity-plugin/scripts/caddis_run.py +160 -0
  27. package/bundles/antigravity-plugin/scripts/caddis_spawn.py +17 -1
  28. package/bundles/antigravity-plugin/scripts/caddis_tidy.py +12 -0
  29. package/bundles/antigravity-plugin/scripts/caddis_upstream_check.py +108 -10
  30. package/bundles/antigravity-plugin/scripts/caddis_worktree_root.py +111 -2
  31. package/bundles/antigravity-plugin/scripts/setup_project_ai.py +132 -11
  32. package/bundles/antigravity-plugin/skills/_registry.md +7 -5
  33. package/bundles/antigravity-plugin/skills/adopt-app/SKILL.md +2 -5
  34. package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md +232 -40
  35. package/bundles/antigravity-plugin/skills/brainstorming/builder-check-prompt.md +25 -0
  36. package/bundles/antigravity-plugin/skills/cloud-phases/SKILL.md +1 -1
  37. package/bundles/antigravity-plugin/skills/dashboard-perf-sweep/SKILL.md +1 -1
  38. package/bundles/antigravity-plugin/skills/db-diagram/SKILL.md +1 -1
  39. package/bundles/antigravity-plugin/skills/explainer-doc/SKILL.md +1 -1
  40. package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +7 -1
  41. package/bundles/antigravity-plugin/skills/fleet-close/SKILL.md +4 -1
  42. package/bundles/antigravity-plugin/skills/graph-email/SKILL.md +15 -0
  43. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +9 -2
  44. package/bundles/antigravity-plugin/skills/implement/SKILL.md +7 -0
  45. package/bundles/antigravity-plugin/skills/particle-art/SKILL.md +1 -3
  46. package/bundles/antigravity-plugin/skills/port-to-github/SKILL.md +2 -5
  47. package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md +1 -1
  48. package/bundles/antigravity-plugin/skills/preload-review/SKILL.md +69 -0
  49. package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +4 -0
  50. package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md +6 -5
  51. package/bundles/antigravity-plugin/skills/ship-merge/SKILL.md +1 -1
  52. package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md +1 -1
  53. package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md +5 -0
  54. package/bundles/antigravity-plugin/skills/tdd/SKILL.md +2 -1
  55. package/bundles/antigravity-plugin/skills/tech-explainer/SKILL.md +2 -6
  56. package/bundles/antigravity-plugin/skills/usage-review/SKILL.md +2 -0
  57. package/bundles/antigravity-plugin/skills/using-git-worktrees/SKILL.md +19 -2
  58. package/bundles/antigravity-plugin/skills/warm-editorial-ui/SKILL.md +1 -1
  59. package/bundles/antigravity-plugin-extras/plugin.json +1 -1
  60. package/bundles/antigravity-plugin-extras/skills/_registry.md +3 -2
  61. package/bundles/antigravity-plugin-extras/skills/building-ai-agent-on-cloudflare/SKILL.md +1 -2
  62. package/bundles/antigravity-plugin-extras/skills/building-mcp-server-on-cloudflare/SKILL.md +1 -2
  63. package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/SKILL.md +1 -1
  64. package/bundles/antigravity-plugin-extras/skills/graph-email/SKILL.md +53 -0
  65. package/bundles/antigravity-plugin-extras/skills/graph-email/email.toml.example +44 -0
  66. package/bundles/antigravity-plugin-extras/skills/graph-email/scripts/send_email.py +432 -0
  67. package/bundles/antigravity-plugin-extras/skills/responsive-mobile-native/SKILL.md +2 -4
  68. package/bundles/antigravity-plugin-extras/skills/runner-move/SKILL.md +2 -4
  69. package/bundles/antigravity-plugin-extras/skills/setup-project-ai/SKILL.md +1 -1
  70. package/bundles/antigravity-plugin-extras/skills/understand-anything/SKILL.md +2 -5
  71. package/bundles/codex/.codex/skills/coding/dashboard-perf-sweep/SKILL.md +1 -1
  72. package/bundles/codex/.codex/skills/data/db-diagram/SKILL.md +1 -1
  73. package/bundles/codex/.codex/skills/devops/adopt-app/SKILL.md +2 -5
  74. package/bundles/codex/.codex/skills/devops/port-to-github/SKILL.md +2 -5
  75. package/bundles/codex/.codex/skills/devops/using-git-worktrees/SKILL.md +19 -2
  76. package/bundles/codex/.codex/skills/docs/explainer-doc/SKILL.md +1 -1
  77. package/bundles/codex/.codex/skills/docs/tech-explainer/SKILL.md +2 -6
  78. package/bundles/codex/.codex/skills/frontend/warm-editorial-ui/SKILL.md +1 -1
  79. package/bundles/codex/.codex/skills/media/particle-art/SKILL.md +1 -3
  80. package/bundles/codex/.codex/skills/workflow/brainstorming/SKILL.md +232 -40
  81. package/bundles/codex/.codex/skills/workflow/brainstorming/builder-check-prompt.md +25 -0
  82. package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +4 -0
  83. package/bundles/codex/.codex/skills/workflow/roadmap/assets/plan-resume-prompt.md +6 -5
  84. package/bundles/manifest.json +3 -3
  85. package/dist/export/assets/export-CMtV-slT.css +1 -0
  86. package/dist/export/index.html +2 -2
  87. package/dist/ui/assets/{Activity-DZKPMOeV.js → Activity-BDjet2xd.js} +1 -1
  88. package/dist/ui/assets/Guide-Czn5sK0f.js +9 -0
  89. package/dist/ui/assets/Guide-D-Zy4cUT.css +1 -0
  90. package/dist/ui/assets/{RoadmapTab-DPsiSmIF.js → RoadmapTab-Bd8geyQx.js} +1 -1
  91. package/dist/ui/assets/index-Bd0Z4jR8.css +1 -0
  92. package/dist/ui/assets/{index-xl156OCN.js → index-CmngQ8Mk.js} +12 -12
  93. package/dist/ui/index.html +2 -2
  94. package/package.json +1 -1
  95. package/dist/export/assets/export-HxTgj3z2.css +0 -1
  96. package/dist/ui/assets/Guide-5ZFfL6sl.js +0 -9
  97. package/dist/ui/assets/Guide-Dnsb-TRd.css +0 -1
  98. package/dist/ui/assets/index-DGlNAmeA.css +0 -1
  99. /package/dist/export/assets/{export-B7BBDg5I.js → export-DtlDFN4L.js} +0 -0
@@ -46,7 +46,7 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
46
46
  `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
47
47
  - **Pull a branch to test it:** `git fetch origin`, then
48
48
  `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name> --record --purpose "test <name>")" origin/<branch>` (for the default branch,
49
- `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
49
+ `origin/<default>`), and run the gates there. Install dependencies fresh with `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" --bootstrap` (run in the worktree); never link `node_modules` or a venv.
50
50
  - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
51
51
  `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
52
52
  checkout has the default branch out; then leave it and report it. Delete the local feature branch only when no
@@ -45,7 +45,7 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
45
45
  `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
46
46
  - **Pull a branch to test it:** `git fetch origin`, then
47
47
  `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name> --record --purpose "test <name>")" origin/<branch>` (for the default branch,
48
- `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
48
+ `origin/<default>`), and run the gates there. Install dependencies fresh with `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" --bootstrap` (run in the worktree); never link `node_modules` or a venv.
49
49
  - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
50
50
  `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
51
51
  checkout has the default branch out; then leave it and report it. Delete the local feature branch only when no
@@ -166,6 +166,11 @@ Then add the four things the inventory cannot derive:
166
166
  **Nothing may be written from recall.** Every number comes from a command run during this capture,
167
167
  or from a file quoted by path.
168
168
 
169
+ **Script commands.** The successor reads this handover after an update, so write a script command as
170
+ `python "<home>/.caddis/bin/caddis_run.py" <script> ...` (`<home>` is the user's home folder, forward
171
+ slashes), never the expanded plugin path (`${CLAUDE_PLUGIN_ROOT}` holds the plugin version).
172
+ `caddis_spawn.py check` refuses a versioned path.
173
+
169
174
  ### Then check what you wrote
170
175
 
171
176
  ```bash
@@ -29,7 +29,8 @@ test. Show it green.
29
29
  layer, dispatch the **tester** subagent.
30
30
 
31
31
  ## Rules
32
- - Never write production code with no failing test demanding it.
32
+ - **Iron Law:** no production code without a failing test first. Code written before its test is deleted,
33
+ not adapted or kept as reference. The `tdd-workflow` skill has the rationalizations and red flags.
33
34
  - Test behavior, not internals. Assert what a caller observes.
34
35
  - Each test independent; shared setup in fixtures.
35
36
  - Show real command output at RED and GREEN — don't claim a state you didn't run.
@@ -2,12 +2,8 @@
2
2
  name: tech-explainer
3
3
  context: fork
4
4
  description: >-
5
- Plain-language explainer, with ranked Mermaid diagrams and Simplified Technical English, for a
6
- reader who did NOT do the investigation (manager, stakeholder). Use when the user says "explain this
7
- to X", "explainer", "write this up for someone non-technical", "plain English", "STE", "explain our
8
- findings", "write up the benchmark results", "why is it slow — document it", or summarises an
9
- investigation for a reader who won't read the raw data. Not for build hand-offs (explainer-doc) or
10
- READMEs.
5
+ Plain-language explainer with Mermaid diagrams and STE for stakeholders. Use when the user says
6
+ "explain this to X", "plain English", "STE", or "explain our findings".
11
7
  ---
12
8
 
13
9
  # tech-explainer — make a stranger understand, and able to push back
@@ -41,6 +41,8 @@ installed on this machine. Show every `DRIFT` line in the report under **Upstrea
41
41
  line means: review the upstream diff, port what fits, then update `.github/upstream-sources.json`.
42
42
  Say nothing for `UP-TO-DATE`, `NOT-INSTALLED` or `NO-SOURCES` (no record: not the caddis source repo).
43
43
  The check never fails the review.
44
+ This local check is blind when the upstream plugin is off. `--remote` asks GitHub instead, and the weekly
45
+ `upstream-drift` workflow runs it and keeps one "Upstream drift: obra/superpowers" issue open.
44
46
 
45
47
  ## Step 3 — offer to apply
46
48
 
@@ -55,8 +55,25 @@ git worktree add -b <branch> $wt origin/<default>
55
55
 
56
56
  ## Install dependencies fresh
57
57
 
58
- Install inside the worktree. Use the project's own command (`npm ci`, `python -m venv .venv` then
59
- `.venv\Scripts\python -m pip install -r requirements.txt`, `cargo build`, `go mod download`). Call the
58
+ Run one command, inside the new worktree:
59
+
60
+ ```powershell
61
+ python "<caddis scripts>\caddis_worktree_root.py" --bootstrap
62
+ ```
63
+
64
+ It installs this worktree's own dependencies:
65
+
66
+ - `uv sync --frozen --all-extras` when `uv.lock` exists. Without `uv.lock`: `python -m venv .venv`, then `pip install`
67
+ of what the repo declares (`-e ".[dev]"` or `-e .`, then `requirements.txt` and `requirements-dev.txt`).
68
+ - `npm ci` in the root and in `frontend/`, for each folder that has a `package-lock.json`.
69
+
70
+ It refuses to run in a main checkout (exit 2) and stops at the first failing step (exit 1).
71
+
72
+ The pre-push gate needs this. In a worktree the gate uses only the worktree's own `.venv`. It never uses the main
73
+ checkout's venv (stale, and it belongs to a running dev service) and never the system Python. A worktree with no
74
+ `.venv` fails the gate with this command in the message. Do not push with `--no-verify` to get round it.
75
+
76
+ For a stack the script does not cover, use the project's own command (`cargo build`, `go mod download`). Call the
60
77
  venv's own `python`; a bare `pip` can install into the global Python.
61
78
 
62
79
  Never link `node_modules` or a venv from another folder. Tools that follow the link then change the
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: warm-editorial-ui
3
- description: Apply the "Warm Editorial Refinement" design system (warm cream/charcoal surfaces, Bahnschrift + Plus Jakarta Sans, layered shadows), the canonical template for new frontend builds. Use for apps, dashboards or UI in the abc-project style, or on "use our design system", "apply our template", "make it look like abc-project", "use the warm editorial style", "use our brand template", "add dark mode", or a new tool for XYZ Brand.
3
+ description: Apply the Warm Editorial Refinement design system. Use when the user says "use our design system", "warm editorial style", "apply our template", or "make it look like abc-project".
4
4
  ---
5
5
 
6
6
  # Warm Editorial Refinement — Design System
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "caddis-extras",
3
- "version": "1.3.49",
3
+ "version": "1.3.51",
4
4
  "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
5
5
  }
@@ -52,6 +52,7 @@
52
52
  |-------|------|-------------|
53
53
  | Changelog Generator | `changelog-generator/` | Create user-facing changelogs and release notes from git commit history, grouping changes and rewriting technical commits in plain language. |
54
54
  | Deploy Local | `deploy-local/` | Local deployment loop for Gitea-hosted projects: commit on dev, push, watch the golden CI/build/deploy workflow, check prod, and fix lint/test/pipeline failures until the deploy is healthy. |
55
+ | Graph Email | `graph-email/` | Email a Markdown file via Microsoft Graph or SMTP. Use to email a draft or note. |
55
56
  | Monorepo | `monorepo/` | Turborepo and pnpm workspaces: turbo.json tasks, remote caching, shared packages, affected-only CI, apps/ vs packages/ layout, and pitfalls like circular deps, version drift and hoisting. |
56
57
  | Runner Move | `runner-move/` | >- |
57
58
  | Safe Cleanup | `safe-cleanup/` | Use BEFORE deleting a directory tree, scratchpad or git worktree, or "tidying up" generated folders, especially on Windows, where deleting through a junction or symlink destroys its target; and to verify a venv or node_modules survived. |
@@ -130,12 +131,12 @@
130
131
  | Agent Md Refactor | `agent-md-refactor/` | Refactor bloated agent instruction files (AGENTS.md, .cursorrules, .github/ files) into linked, progressively disclosed docs. |
131
132
  | Agent Orchestration | `agent-orchestration/` | Blueprint for orchestrating the agent pipeline from spec to planning, implementation, testing and debugging, plus when a second model is worth it, the intent→model map and cost guardrails. |
132
133
  | Ask Questions If Underspecified | `asking-questions/` | Clarify requirements before implementing. Do not use automatically, only when invoked explicitly. |
133
- | Data Contract Pipeline | `data-contract-pipeline/` | Build, audit and validate data-to-UI contracts. Use when the user mentions data mapping, UI lineage, DB-to-UI, DisplayDTOs, source-to-screen mapping, data contracts, schema drift, typed API responses, mockup grounding, or asks whether a UI is backed by real data. |
134
+ | Data Contract Pipeline | `data-contract-pipeline/` | Build, audit, and validate DB-to-UI data contracts. Use when the user mentions data mapping, UI lineage, DisplayDTOs, source-to-screen mapping, or asks if a UI is backed by real data. |
134
135
  | Developer Growth Analysis | `developer-growth-analysis/` | Analyze recent Claude Code chat history for coding patterns and gaps, find learning resources on HackerNews, and send a growth report to Slack DMs. |
135
136
  | File Organizer | `file-organizer/` | Organize files and folders by context: find duplicates, suggest better structures, automate cleanup. |
136
137
  | Game Changing Features | `game-changing-features/` | Find 10x product opportunities and high-leverage features. Use when the user mentions '10x', says 'what would make this 10x better', 'product strategy', or 'what should we build next'. |
137
138
  | Golden Nuggets | `golden-nuggets/` | Extract durable tribal knowledge ('gold nuggets') from a codebase or changed files and route each to an instruction file, runbook, hub or CI review inbox. Use after a feature, fix, sprint, incident or release. |
138
139
  | Intent Writer | `intent-writer/` | Structure freetext ideas, backlog items, or vague requirements into a formal Intent Document that preserves user intent across the entire agent pipeline chain. |
139
140
  | Receiving Code Review | `receiving-code-review/` | Use when receiving code review feedback, before implementing it, especially if it seems unclear or wrong: verify with technical rigor, no performative agreement or blind implementation. |
140
- | Setup Project Ai | `setup-project-ai/` | Install or refresh the agent-agnostic harness in a project: AGENTS.md rules with CLAUDE.md shims, subagents, commands and settings. Use when setting up AI resources on a project, or the user says 'set up the harness', 'setup-project-ai', 'generate CLAUDE.md', 'onboard this project to Claude Code / Codex / agy', or runs /setup-project-ai. |
141
+ | Setup Project Ai | `setup-project-ai/` | Install or refresh the project AI harness: AGENTS.md, CLAUDE.md shims, agents, settings. Use when the user says 'set up the harness', 'generate CLAUDE.md', or runs /setup-project-ai. |
141
142
  | Verification Loop | `verification-loop/` | Systematic code change verification — lint, test, type-check, review |
@@ -3,8 +3,7 @@ name: building-ai-agent-on-cloudflare
3
3
  context: fork
4
4
  description: |
5
5
  Builds stateful AI agents on Cloudflare Workers with the Agents SDK. Use when the user wants to
6
- "build an agent", "AI agent", "chat agent", "stateful agent", mentions "Agents SDK", "real-time
7
- AI", "WebSocket AI", or asks about agent "state management", "scheduled tasks" or "tool calling".
6
+ "build an agent", "stateful agent", "WebSocket AI", or mentions "Agents SDK".
8
7
  ---
9
8
 
10
9
  # Building Cloudflare Agents
@@ -3,8 +3,7 @@ name: building-mcp-server-on-cloudflare
3
3
  context: fork
4
4
  description: |
5
5
  Builds and deploys remote MCP servers on Cloudflare Workers with tools and OAuth. Use when the
6
- user wants to "build MCP server", "create MCP tools", "remote MCP", "deploy MCP", add "OAuth to
7
- MCP", or mentions "MCP authentication", "MCP deployment" or Model Context Protocol on Cloudflare.
6
+ user wants to "build MCP server", "remote MCP", "deploy MCP", or add "OAuth to MCP".
8
7
  ---
9
8
 
10
9
  # Building MCP Servers on Cloudflare
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: data-contract-pipeline
3
3
  context: fork
4
- description: "Build, audit and validate data-to-UI contracts. Use when the user mentions data mapping, UI lineage, DB-to-UI, DisplayDTOs, source-to-screen mapping, data contracts, schema drift, typed API responses, mockup grounding, or asks whether a UI is backed by real data."
4
+ description: "Build, audit, and validate DB-to-UI data contracts. Use when the user mentions data mapping, UI lineage, DisplayDTOs, source-to-screen mapping, or asks if a UI is backed by real data."
5
5
  ---
6
6
 
7
7
  # Data Contract Pipeline
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: graph-email
3
+ description: Email a Markdown file via Microsoft Graph or SMTP. Use to email a draft or note.
4
+ ---
5
+
6
+ # graph-email
7
+
8
+ Sends one email. The provider is `graph` (Microsoft Graph `sendMail`, client credentials) or `smtp`.
9
+ The body is a Markdown file. The script turns it into simple HTML. It never prints a secret or a token.
10
+
11
+ ## One-time setup (per machine)
12
+
13
+ 1. Copy `email.toml.example` from this skill folder to `~/.caddis/email.toml`.
14
+ 2. Set `provider`, `sender` and `env_file`. For SMTP also set the `[smtp]` table.
15
+ 3. Put the secrets in the env file, not in the config file:
16
+ - graph: three keys. The default names are `ALERT_GRAPH_TENANT_ID`, `ALERT_GRAPH_CLIENT_ID`, `ALERT_GRAPH_CLIENT_SECRET`. Change the names in the `[graph]` table if your file uses other names.
17
+ - smtp: one key. The default name is `EMAIL_SMTP_PASSWORD`. Change it with `password_key`.
18
+ 4. Check the setup. This sends nothing and prints no secret:
19
+ `python -I scripts/send_email.py --check`
20
+
21
+ Every setting can be overridden. The order is: command-line flag, then environment variable, then the config file.
22
+ The variables are `CADDIS_EMAIL_PROVIDER`, `CADDIS_EMAIL_SENDER`, `CADDIS_EMAIL_ENV_FILE`, `CADDIS_EMAIL_CONFIG`
23
+ and `CADDIS_EMAIL_SMTP_HOST`, `_PORT`, `_SECURITY`, `_USERNAME`, `_TIMEOUT`. The flags are `--provider`, `--sender`,
24
+ `--env-file`, `--config`, `--smtp-host`, `--smtp-port`, `--smtp-security` (`starttls`, `ssl` or `none`),
25
+ `--smtp-username`, `--smtp-timeout`. The old names `GRAPH_EMAIL_ENV_FILE` and `GRAPH_EMAIL_SENDER` still work.
26
+ Secrets can also be set as process environment variables. They win over the env file.
27
+ With smtp security `none`, the script refuses a username or password and exits with code 2. Use `starttls` or `ssl`.
28
+ For a local test relay only, set `allow_insecure_auth = true` (a boolean) in the `[smtp]` table.
29
+
30
+ ## Steps
31
+
32
+ 1. Write the email as a Markdown file in the project's `comms/` folder (a copy stays in the repo).
33
+ - Put `<!-- email-start -->` before the greeting and `<!-- email-end -->` after the sign-off. Only that part is sent.
34
+ - Write plain, short sentences. No em dashes, no arrows, no emoji, no check marks.
35
+ 2. Subject line: `caddis-<app-name> <short subject>`, for example `caddis-myapp Data request for the weekly report`.
36
+ 3. Dry run. It sends nothing, needs no credentials and writes `<file>.preview.html`:
37
+ `python -I scripts/send_email.py --dry-run --to x@example.com --subject t --body-file <file.md>`
38
+ Read the preview, then delete it.
39
+ 4. Send:
40
+ `python -I scripts/send_email.py --to <address> --subject '<subject>' --body-file <file.md> [--attach <file> ...]`
41
+ `--to` can repeat. Graph HTTP 202 means Graph accepted the mail. An SMTP "accepted" means the server took it.
42
+ Neither proves the inbox received it.
43
+ 5. Tell the owner what was sent, to whom, and the subject.
44
+
45
+ ## Rules
46
+
47
+ - **Default recipient is the owner's own address.** The owner forwards it. Send to a team only when the owner says so
48
+ in this request. Sending to any other address is an outward action: confirm first.
49
+ - Never put personal data, secrets, payment data or customer text in the body.
50
+ - Errors show the provider, the HTTP or SMTP status code and the error name. Do not retry in a loop.
51
+ - Exit codes: 0 done, 1 provider error, 2 missing or invalid setting.
52
+
53
+ Script: `scripts/send_email.py` in this skill folder (Python 3.11 or later, standard library only).
@@ -0,0 +1,44 @@
1
+ # Example config for the graph-email skill. Copy to ~/.caddis/email.toml and fill in your values.
2
+ #
3
+ # Precedence for every setting: command-line flag, then environment variable, then this file.
4
+ # Secrets (Graph client secret, SMTP password) never go in this file. They come from the process
5
+ # environment or from the env file named by `env_file` below.
6
+
7
+ # Which sender to use: "graph" (Microsoft Graph sendMail) or "smtp". Default: "graph".
8
+ # Env var: CADDIS_EMAIL_PROVIDER. Flag: --provider.
9
+ provider = "graph"
10
+
11
+ # The mailbox or address the mail is sent from.
12
+ # Env var: CADDIS_EMAIL_SENDER. Flag: --sender.
13
+ sender = ""
14
+
15
+ # Path to an env file (KEY=value lines) that holds the secrets. Use a literal string
16
+ # (single quotes) so a Windows path needs no escaping.
17
+ # Env var: CADDIS_EMAIL_ENV_FILE. Flag: --env-file.
18
+ env_file = ""
19
+
20
+ [graph]
21
+ # The NAMES of the keys in the env file (or environment) that hold the values.
22
+ # These are the defaults. Change them only if your env file uses other names.
23
+ tenant_id_key = "ALERT_GRAPH_TENANT_ID"
24
+ client_id_key = "ALERT_GRAPH_CLIENT_ID"
25
+ client_secret_key = "ALERT_GRAPH_CLIENT_SECRET"
26
+
27
+ [smtp]
28
+ # Used when provider = "smtp".
29
+ # Env vars: CADDIS_EMAIL_SMTP_HOST, _PORT, _SECURITY, _USERNAME, _TIMEOUT.
30
+ # Flags: --smtp-host, --smtp-port, --smtp-security, --smtp-username, --smtp-timeout.
31
+ host = ""
32
+ # "starttls" (port 587), "ssl" (port 465) or "none" (port 25, no encryption).
33
+ security = "starttls"
34
+ # With security "none", the script refuses to send a username or password. Set this to true
35
+ # (a boolean, not a string) only for a local test relay. File only: no env var or flag.
36
+ # allow_insecure_auth = false
37
+ # Leave out `port` to use the default for the security mode.
38
+ # port = 587
39
+ # Leave empty if the server needs no login.
40
+ username = ""
41
+ # The NAME of the key that holds the password (in the environment or the env file).
42
+ password_key = "EMAIL_SMTP_PASSWORD"
43
+ # Seconds to wait for the server.
44
+ timeout = 30