@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.
- package/README.md +4 -0
- package/bundles/antigravity-plugin/agents/debug.md +2 -0
- package/bundles/antigravity-plugin/guard_agy.py +6 -2
- package/bundles/antigravity-plugin/plugin.json +1 -1
- package/bundles/antigravity-plugin/repo_freshness.py +71 -6
- package/bundles/antigravity-plugin/repo_hygiene.py +516 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/caddis_checkout_guard.py +1 -1
- package/bundles/antigravity-plugin/scripts/caddis_finished.py +537 -0
- package/bundles/antigravity-plugin/scripts/caddis_fleet.py +26 -9
- package/bundles/antigravity-plugin/scripts/caddis_guide.json +65 -12
- package/bundles/antigravity-plugin/scripts/caddis_own_cleanup.py +23 -248
- package/bundles/antigravity-plugin/scripts/caddis_preload_review.py +554 -0
- package/bundles/antigravity-plugin/scripts/caddis_repo_tidy.py +240 -0
- package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +9 -3
- package/bundles/antigravity-plugin/scripts/caddis_run.py +160 -0
- package/bundles/antigravity-plugin/scripts/caddis_spawn.py +17 -1
- package/bundles/antigravity-plugin/scripts/caddis_tidy.py +12 -0
- package/bundles/antigravity-plugin/scripts/caddis_upstream_check.py +108 -10
- package/bundles/antigravity-plugin/scripts/caddis_worktree_root.py +111 -2
- package/bundles/antigravity-plugin/scripts/setup_project_ai.py +132 -11
- package/bundles/antigravity-plugin/skills/_registry.md +7 -5
- package/bundles/antigravity-plugin/skills/adopt-app/SKILL.md +2 -5
- package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md +232 -40
- package/bundles/antigravity-plugin/skills/brainstorming/builder-check-prompt.md +25 -0
- package/bundles/antigravity-plugin/skills/cloud-phases/SKILL.md +1 -1
- package/bundles/antigravity-plugin/skills/dashboard-perf-sweep/SKILL.md +1 -1
- package/bundles/antigravity-plugin/skills/db-diagram/SKILL.md +1 -1
- package/bundles/antigravity-plugin/skills/explainer-doc/SKILL.md +1 -1
- package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +7 -1
- package/bundles/antigravity-plugin/skills/fleet-close/SKILL.md +4 -1
- package/bundles/antigravity-plugin/skills/graph-email/SKILL.md +15 -0
- package/bundles/antigravity-plugin/skills/handoff/SKILL.md +9 -2
- package/bundles/antigravity-plugin/skills/implement/SKILL.md +7 -0
- package/bundles/antigravity-plugin/skills/particle-art/SKILL.md +1 -3
- package/bundles/antigravity-plugin/skills/port-to-github/SKILL.md +2 -5
- package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md +1 -1
- package/bundles/antigravity-plugin/skills/preload-review/SKILL.md +69 -0
- package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +4 -0
- package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md +6 -5
- package/bundles/antigravity-plugin/skills/ship-merge/SKILL.md +1 -1
- package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md +1 -1
- package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md +5 -0
- package/bundles/antigravity-plugin/skills/tdd/SKILL.md +2 -1
- package/bundles/antigravity-plugin/skills/tech-explainer/SKILL.md +2 -6
- package/bundles/antigravity-plugin/skills/usage-review/SKILL.md +2 -0
- package/bundles/antigravity-plugin/skills/using-git-worktrees/SKILL.md +19 -2
- package/bundles/antigravity-plugin/skills/warm-editorial-ui/SKILL.md +1 -1
- package/bundles/antigravity-plugin-extras/plugin.json +1 -1
- package/bundles/antigravity-plugin-extras/skills/_registry.md +3 -2
- package/bundles/antigravity-plugin-extras/skills/building-ai-agent-on-cloudflare/SKILL.md +1 -2
- package/bundles/antigravity-plugin-extras/skills/building-mcp-server-on-cloudflare/SKILL.md +1 -2
- package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/SKILL.md +1 -1
- package/bundles/antigravity-plugin-extras/skills/graph-email/SKILL.md +53 -0
- package/bundles/antigravity-plugin-extras/skills/graph-email/email.toml.example +44 -0
- package/bundles/antigravity-plugin-extras/skills/graph-email/scripts/send_email.py +432 -0
- package/bundles/antigravity-plugin-extras/skills/responsive-mobile-native/SKILL.md +2 -4
- package/bundles/antigravity-plugin-extras/skills/runner-move/SKILL.md +2 -4
- package/bundles/antigravity-plugin-extras/skills/setup-project-ai/SKILL.md +1 -1
- package/bundles/antigravity-plugin-extras/skills/understand-anything/SKILL.md +2 -5
- package/bundles/codex/.codex/skills/coding/dashboard-perf-sweep/SKILL.md +1 -1
- package/bundles/codex/.codex/skills/data/db-diagram/SKILL.md +1 -1
- package/bundles/codex/.codex/skills/devops/adopt-app/SKILL.md +2 -5
- package/bundles/codex/.codex/skills/devops/port-to-github/SKILL.md +2 -5
- package/bundles/codex/.codex/skills/devops/using-git-worktrees/SKILL.md +19 -2
- package/bundles/codex/.codex/skills/docs/explainer-doc/SKILL.md +1 -1
- package/bundles/codex/.codex/skills/docs/tech-explainer/SKILL.md +2 -6
- package/bundles/codex/.codex/skills/frontend/warm-editorial-ui/SKILL.md +1 -1
- package/bundles/codex/.codex/skills/media/particle-art/SKILL.md +1 -3
- package/bundles/codex/.codex/skills/workflow/brainstorming/SKILL.md +232 -40
- package/bundles/codex/.codex/skills/workflow/brainstorming/builder-check-prompt.md +25 -0
- package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +4 -0
- package/bundles/codex/.codex/skills/workflow/roadmap/assets/plan-resume-prompt.md +6 -5
- package/bundles/manifest.json +3 -3
- package/dist/export/assets/export-CMtV-slT.css +1 -0
- package/dist/export/index.html +2 -2
- package/dist/ui/assets/{Activity-DZKPMOeV.js → Activity-BDjet2xd.js} +1 -1
- package/dist/ui/assets/Guide-Czn5sK0f.js +9 -0
- package/dist/ui/assets/Guide-D-Zy4cUT.css +1 -0
- package/dist/ui/assets/{RoadmapTab-DPsiSmIF.js → RoadmapTab-Bd8geyQx.js} +1 -1
- package/dist/ui/assets/index-Bd0Z4jR8.css +1 -0
- package/dist/ui/assets/{index-xl156OCN.js → index-CmngQ8Mk.js} +12 -12
- package/dist/ui/index.html +2 -2
- package/package.json +1 -1
- package/dist/export/assets/export-HxTgj3z2.css +0 -1
- package/dist/ui/assets/Guide-5ZFfL6sl.js +0 -9
- package/dist/ui/assets/Guide-Dnsb-TRd.css +0 -1
- package/dist/ui/assets/index-DGlNAmeA.css +0 -1
- /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
|
-
-
|
|
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
|
|
6
|
-
|
|
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
|
-
|
|
59
|
-
|
|
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
|
|
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
|
|
@@ -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
|
|
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
|
|
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", "
|
|
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", "
|
|
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
|
|
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
|