@codewizard-dt/bootstrap 3.1.0 → 4.0.0
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/bin/cli.js +0 -5
- package/lib/hooks/README.md +14 -5
- package/lib/hooks/lib/command-parse.js +28 -0
- package/lib/hooks/package-install-consent.js +60 -2
- package/lib/scripts/README.md +21 -12
- package/lib/scripts/bootstrap-prefs.js +20 -1
- package/lib/scripts/install-global.sh +14 -2
- package/lib/scripts/templates/bootstrap-prefs-schema.json +18 -0
- package/lib/skills/README.md +1 -0
- package/lib/skills/bootstrap-config/SKILL.md +1 -1
- package/lib/skills/bug-assess/SKILL.md +137 -0
- package/lib/skills/git-commit/SKILL.md +47 -13
- package/lib/skills/roadmap-assess/SKILL.md +51 -13
- package/package.json +2 -4
- package/.github/workflows/docker-harness.yml +0 -26
- package/.github/workflows/security.yml +0 -24
- package/.gitleaks.toml +0 -15
- package/lib/prompts/setup-deployment.md +0 -322
- package/lib/scripts/setup-deployment.sh +0 -113
- package/raw/guides/deployment-strategy.md +0 -448
|
@@ -10,26 +10,43 @@ user-invocable: true
|
|
|
10
10
|
|
|
11
11
|
# git-commit
|
|
12
12
|
|
|
13
|
-
## Step 0:
|
|
13
|
+
## Step 0: Verify working directory, then read the three preferences that govern this skill
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
### Precondition: current directory must be the repo root
|
|
16
|
+
|
|
17
|
+
Before anything else, confirm the working directory is the repository root — every later step (`git status`/`git diff HEAD`, manifest Detection, the `--project .` preference reads below, and `git-commit`'s own `git add .`) assumes it. Running from a subdirectory would silently stage, diff, or bump only that subtree instead of the whole repo.
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
cd "$(git rev-parse --show-toplevel)"
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
If this fails (not inside a git repo at all), **STOP** and report: `/git-commit must run inside a git repository — no repo root found from the current directory.` Otherwise the working directory is now the repo root; proceed for the rest of this run without re-checking.
|
|
24
|
+
|
|
25
|
+
**Worktree-safe by construction**: `--show-toplevel` resolves to the current *worktree's own* root when run from inside a linked worktree, not the main checkout's — exactly the directory this run should operate in, so no worktree-specific branch is needed here. (Contrast with `--git-dir`/`--git-common-dir`, which resolve to the *shared* `.git` location across all worktrees — the right tool when code needs the common git directory instead, as in `file-suggestion.sh`'s worktree fix, but the wrong one here.)
|
|
26
|
+
|
|
27
|
+
### Read the three preferences that govern this skill
|
|
28
|
+
|
|
29
|
+
Three stored preferences change what this command does. Read **all three, once, before Step 1** — never mid-run, and never once per file:
|
|
16
30
|
|
|
17
31
|
```bash
|
|
18
32
|
node ~/.claude/bootstrap-prefs.js --get gitCommit.versionBump --project . 2>/dev/null || echo unset
|
|
19
33
|
node ~/.claude/bootstrap-prefs.js --get gitCommit.autoPush --project . 2>/dev/null || echo unset
|
|
34
|
+
node ~/.claude/bootstrap-prefs.js --get gitCommit.lint --project . 2>/dev/null || echo unset
|
|
20
35
|
```
|
|
21
36
|
|
|
22
|
-
`--project .` is required.
|
|
37
|
+
`--project .` is required. All three keys are `scope: either`, so the answer resolves **project file → global file → schema default**; dropping the flag would read the machine-wide answer even in a repo that overrides it. If any command fails — bootstrap was never installed globally, or `node` is not on PATH — treat that answer as `unset`.
|
|
23
38
|
|
|
24
|
-
`unset` means *nobody has ever been asked*.
|
|
39
|
+
`unset` means *nobody has ever been asked*. For `gitCommit.versionBump` and `gitCommit.autoPush` this keeps today's behavior; it never invents one. `gitCommit.lint` is the deliberate exception: it is opt-in by explicit design, so `unset` (and `false`) both mean **do not lint** — a fresh install must never lint before the user has said yes. Mention an `unset` key **once**, in the final report, never as a mid-run interruption.
|
|
25
40
|
|
|
26
|
-
## Step 1: Run Lint Fix Cycles
|
|
41
|
+
## Step 1: Run Lint Fix Cycles (gated on `gitCommit.lint`)
|
|
27
42
|
|
|
28
|
-
|
|
43
|
+
`gitCommit.lint` is `true | false`, default `false`, no `ask` value — read once in Step 0, never re-checked mid-run.
|
|
29
44
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
45
|
+
- **`true`**: run the `/lint` workflow to catch and fix any diagnostics:
|
|
46
|
+
1. Execute the full `/lint` command (all cycles until clean or issues are skipped)
|
|
47
|
+
2. If any fixes were applied, they will be included in the commit automatically
|
|
48
|
+
3. If any issues were skipped (unfixable), warn the user before proceeding
|
|
49
|
+
- **`false` or `unset`**: skip this step entirely — do not invoke `/lint`. Note once in the final report when `unset`: `gitCommit.lint is unanswered — /git-commit does not lint by default. Set it with: node ~/.claude/bootstrap-prefs.js --set gitCommit.lint --value true --global` (or `false`).
|
|
33
50
|
|
|
34
51
|
## Step 2: Condense Verbose Inline Comments
|
|
35
52
|
|
|
@@ -59,9 +76,26 @@ Run all three in parallel:
|
|
|
59
76
|
- `git diff HEAD` — see exact diffs for ALL staged and unstaged changes
|
|
60
77
|
- `git log --oneline -10` — see recent commit history for context
|
|
61
78
|
|
|
62
|
-
## Step 4: Summarize Changes and Recommend Semver Bump
|
|
79
|
+
## Step 4: Summarize Changes, and Recommend a Semver Bump Only If It Will Be Used
|
|
80
|
+
|
|
81
|
+
`gitCommit.versionBump` was already read in Step 0 — branch on it now, **before** doing any bump classification, so a `never` project never pays for reasoning it can't use.
|
|
82
|
+
|
|
83
|
+
### If `gitCommit.versionBump` is `never`
|
|
84
|
+
|
|
85
|
+
No manifest will be touched and no prefix will be written (Step 5 skips straight through). Determining PATCH/MINOR/MAJOR would be pure wasted effort — skip the semver table entirely and print only:
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
**Changes being committed:**
|
|
90
|
+
- <bullet list of what changed and why, derived from the diff>
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
Then go directly to Step 6 (Commit) with a bare, unprefixed subject.
|
|
95
|
+
|
|
96
|
+
### Otherwise (`auto`, `confirm`, or `unset`)
|
|
63
97
|
|
|
64
|
-
|
|
98
|
+
The bump classification is actually needed — either to write the prefix (`auto`/`unset`) or to ask about it (`confirm`, in Step 5). Output the full summary block:
|
|
65
99
|
|
|
66
100
|
---
|
|
67
101
|
|
|
@@ -82,7 +116,7 @@ Use these semver rules to determine the bump:
|
|
|
82
116
|
| **minor** | New features or capabilities that are backward-compatible; new commands, skills, config options, or APIs added without breaking existing ones |
|
|
83
117
|
| **major** | Breaking changes — removed or renamed commands/APIs/config keys, changed behavior that callers must update for, deleted files that others depend on |
|
|
84
118
|
|
|
85
|
-
Print the summary. What happens next is decided by `gitCommit.versionBump`
|
|
119
|
+
Print the summary. What happens next is decided by the same `gitCommit.versionBump` value — see the table in Step 5. **Do not ask for confirmation here**; the only value that asks is `confirm`, and it asks in Step 5 where the manifest list is known.
|
|
86
120
|
|
|
87
121
|
## Step 5: Bump Version in Project Files
|
|
88
122
|
|
|
@@ -269,5 +303,5 @@ Runs only after the commit in Step 6 succeeded. A failed commit means there is n
|
|
|
269
303
|
One short report at the end. Include, in this order:
|
|
270
304
|
|
|
271
305
|
1. The commit subject that was written.
|
|
272
|
-
2. Any of the once-only preference notes from Steps 5 and 7 that apply. Each appears **at most once per run**, here — not inline, and not repeated per file.
|
|
306
|
+
2. Any of the once-only preference notes from Steps 1, 5, and 7 that apply. Each appears **at most once per run**, here — not inline, and not repeated per file.
|
|
273
307
|
3. The push outcome (pushed / not pushed and why / push failed and how).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: roadmap-assess
|
|
3
|
-
description: Survey all active roadmaps together — parse status and progress, detect cross-roadmap dependencies, and produce a single prioritized list with a status update for each roadmap
|
|
3
|
+
description: Survey all active roadmaps together — parse status and progress, flag outstanding decisions blocking readiness, detect cross-roadmap dependencies, and produce a single prioritized list with a status update for each roadmap
|
|
4
4
|
category: researching
|
|
5
5
|
model: claude-sonnet-5
|
|
6
6
|
disable-model-invocation: false
|
|
@@ -20,12 +20,14 @@ This skill is read-mostly: it never upgrades inline placeholders to task files a
|
|
|
20
20
|
|
|
21
21
|
`list_dir` `wiki/work/roadmaps/` for `.md` files **directly** in it (not `archive/`); skip `lifecycle.md`, `index.md`, `README.md`. None found → STOP: `No roadmaps found in wiki/work/roadmaps/. Use /roadmap-create <topic> to draft one.`
|
|
22
22
|
|
|
23
|
-
A single active roadmap is still worth assessing — don't short-circuit to `/roadmap-next`; the status update in Step
|
|
23
|
+
A single active roadmap is still worth assessing — don't short-circuit to `/roadmap-next`; the status update in Step 6d is useful on its own.
|
|
24
24
|
|
|
25
25
|
## Step 2: Parse every roadmap
|
|
26
26
|
|
|
27
27
|
For each file, run the **Parse a roadmap** procedure defined in `lib/skills/roadmap-next/SKILL.md` — do not restate it here, follow it as written. In addition to what that procedure captures, also extract from frontmatter: `owner`, `tags`, `linked_requirements`, `linked_decisions`, `created`, `updated`.
|
|
28
28
|
|
|
29
|
+
Also scan the roadmap body for inline typed links referencing decisions (e.g. `rel::[[DEC-0003#D2]]`, `implements::[[DEC-0003]]`) — a decision can gate a roadmap without being listed in `linked_decisions`. Merge these into the same per-roadmap decision-reference set.
|
|
30
|
+
|
|
29
31
|
Do **not** run the Upgrade-inline-items or Parallelism-analysis procedures from that same file — those materialize task files, which is out of scope here. This step only reads.
|
|
30
32
|
|
|
31
33
|
## Step 3: Auto-archive fully-complete roadmaps
|
|
@@ -34,7 +36,23 @@ For any roadmap where `total > 0` and `done == total`: run the **Archive a fully
|
|
|
34
36
|
|
|
35
37
|
If every discovered roadmap was archived this step, STOP and report: `All roadmaps complete — archived: <list>. Nothing active to assess.`
|
|
36
38
|
|
|
37
|
-
## Step 4:
|
|
39
|
+
## Step 4: Outstanding decision check
|
|
40
|
+
|
|
41
|
+
Before weighing priority or dependencies, check whether any remaining roadmap is gated on a decision that hasn't been finalized yet — an unresolved decision means the roadmap isn't truly ready to work, regardless of how it otherwise ranks.
|
|
42
|
+
|
|
43
|
+
For every remaining roadmap, take its merged decision-reference set from Step 2 (`linked_decisions` frontmatter + inline `rel::[[DEC-...]]` links). Each reference is a Decision Group file (`DEC-NNNN`) and, ideally, a specific decision block within it (`DEC-NNNN#DM`, e.g. `#D2`). For each unique reference:
|
|
44
|
+
|
|
45
|
+
1. `find_file` / `Read` the Decision Group file in `wiki/work/decisions/` (check `archive/` too if not found active). Missing file → note as a broken reference, don't block on it.
|
|
46
|
+
2. Find the `## DM. <title>` block matching the referenced `#DM`. If the roadmap referenced only `DEC-NNNN` with no `#DM`, treat every `proposed` block in that group as a separate outstanding decision.
|
|
47
|
+
3. Read that block's `Status:` field (`proposed | accepted | superseded`).
|
|
48
|
+
4. If `Status: superseded`, the block is annotated `superseded by DEC-NNNN#DM` — follow that pointer to the current decision's block and re-check its status instead of stopping at the superseded one.
|
|
49
|
+
5. If the resolved status is `proposed` (not yet `accepted`), record it as an **outstanding decision** blocking that roadmap: `{roadmap, DEC-NNNN#DM, title, file path}`.
|
|
50
|
+
|
|
51
|
+
Deduplicate by decision so a shared unresolved decision blocking multiple roadmaps is only reported once per roadmap it actually gates.
|
|
52
|
+
|
|
53
|
+
This step is read-only — never run `/decision-finalize` yourself; surface the blockers so the user can resolve them (or explicitly choose to proceed anyway).
|
|
54
|
+
|
|
55
|
+
## Step 5: Cross-roadmap dependency analysis
|
|
38
56
|
|
|
39
57
|
For every remaining roadmap's `task-link` items (skip `inline` items — no task file exists yet to inspect): `Read` the task file, find `## Dependencies` / `## Blocked by` / `depends_on::` / `blocks::` refs, extract `TASK-NNN` IDs.
|
|
40
58
|
|
|
@@ -42,19 +60,21 @@ For each referenced `TASK-NNN`, check whether it belongs to a *different* roadma
|
|
|
42
60
|
|
|
43
61
|
Also note — but do not treat as a hard edge — soft relatedness: roadmaps sharing a `linked_requirements` or `linked_decisions` entry. If a shared linked decision's text explicitly states a sequence ("do X before Y", "requires X shipped first"), `Read` that decision file and promote it to a hard edge instead.
|
|
44
62
|
|
|
45
|
-
Deduplicate edges. Walk the graph via DFS to detect cycles — if found, flag them in Step
|
|
63
|
+
Deduplicate edges. Walk the graph via DFS to detect cycles — if found, flag them in Step 6e rather than silently picking a winner.
|
|
46
64
|
|
|
47
|
-
## Step
|
|
65
|
+
## Step 6: Rank roadmaps
|
|
48
66
|
|
|
49
67
|
Order the remaining roadmaps, highest priority first, using this precedence:
|
|
50
68
|
|
|
51
|
-
1. **Hard dependency order** (from Step
|
|
69
|
+
1. **Hard dependency order** (from Step 5) — a roadmap that blocks another always outranks the one it blocks. Never violate this to satisfy #2, #3, or the outstanding-decision flag below.
|
|
52
70
|
2. **Functional priority** — a judgment call from each roadmap's `## Goal`, `tags`, and any linked requirement's priority/severity field (`Read` it if present). Goals that unblock or protect other work (infra, security, load-bearing bug fixes) outrank polish or nice-to-have goals. Record a one-sentence rationale per roadmap in the report — this is a judgment call the user can override, not a fact.
|
|
53
71
|
3. **Momentum** (tie-break only — never overrides #1 or #2) — a higher `done/total` ratio ranks slightly higher; finishing in-flight work compounds value faster than starting a new thread.
|
|
54
72
|
|
|
55
73
|
If two or more roadmaps are genuinely indistinguishable on all three signals, keep their existing relative order (`ROADMAP-NNN` ascending) rather than guessing.
|
|
56
74
|
|
|
57
|
-
|
|
75
|
+
An outstanding decision (Step 4) does **not** change a roadmap's rank — it changes what "next" means for it. A blocked roadmap can still be #1 in priority; it's just not actionable via `/roadmap-next` until the decision resolves. Reflect that in the rank table's `Depends on` column and in the Step 6d status block.
|
|
76
|
+
|
|
77
|
+
## Step 7: Report
|
|
58
78
|
|
|
59
79
|
Print, in this order:
|
|
60
80
|
|
|
@@ -65,7 +85,19 @@ Archived to wiki/work/roadmaps/archive/ (fully complete):
|
|
|
65
85
|
• <filename> — done
|
|
66
86
|
```
|
|
67
87
|
|
|
68
|
-
### 6b.
|
|
88
|
+
### 6b. Outstanding Decisions (omit if none found)
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
## Warning: Outstanding Decisions
|
|
92
|
+
|
|
93
|
+
These roadmaps are gated on decisions still `proposed` — resolve via `/decision-finalize <file>#<DM>` before treating the roadmap as ready to work:
|
|
94
|
+
|
|
95
|
+
| Decision | Status | Blocks Roadmap | Title |
|
|
96
|
+
|----------|--------|-----------------|-------|
|
|
97
|
+
| DEC-0003#D2 | proposed | ROADMAP-009 — <title> | <decision title> |
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### 6c. Prioritized Roadmaps
|
|
69
101
|
|
|
70
102
|
```
|
|
71
103
|
## Prioritized Roadmaps
|
|
@@ -76,9 +108,9 @@ Archived to wiki/work/roadmaps/archive/ (fully complete):
|
|
|
76
108
|
| 2 | ROADMAP-MMM — <title> | M/N | <one sentence> | ROADMAP-NNN (Phase X blocks it) |
|
|
77
109
|
```
|
|
78
110
|
|
|
79
|
-
`Depends on` lists the hard-edge blockers found in Step
|
|
111
|
+
`Depends on` lists the hard-edge blockers found in Step 5, or `—` if none. A roadmap with an outstanding decision also gets `Blocked by DEC-NNNN#DM` appended here even if it has no roadmap-to-roadmap dependency.
|
|
80
112
|
|
|
81
|
-
###
|
|
113
|
+
### 6d. Status update per roadmap
|
|
82
114
|
|
|
83
115
|
One block per roadmap, in ranked order:
|
|
84
116
|
|
|
@@ -86,13 +118,19 @@ One block per roadmap, in ranked order:
|
|
|
86
118
|
### ROADMAP-NNN — <title>
|
|
87
119
|
- Owner: <owner, or "unassigned">
|
|
88
120
|
- Progress: M/N items checked
|
|
89
|
-
- Status: <active — on track | active — stalled | active — mostly inline placeholders, not yet materialized>
|
|
121
|
+
- Status: <active — on track | active — stalled | active — mostly inline placeholders, not yet materialized | blocked — awaiting decision(s)>
|
|
90
122
|
- Next: `/roadmap-next wiki/work/roadmaps/NNN-slug.md`
|
|
91
123
|
```
|
|
92
124
|
|
|
93
125
|
Base `Status` on progress momentum and whether items remain `inline` (unmaterialized) vs `task-link` — call out roadmaps that are still mostly inline placeholders, since `/roadmap-next` needs to run on them before real progress can be tracked.
|
|
94
126
|
|
|
95
|
-
|
|
127
|
+
If the roadmap has an outstanding decision from Step 4, set `Status: blocked — awaiting decision(s): DEC-NNNN#DM` and replace `Next` with the decision-resolution action instead of `/roadmap-next`:
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
- Next: `/decision-finalize wiki/work/decisions/NNNN-slug.md#DM`
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### 6e. Dependency cycles (omit if none found)
|
|
96
134
|
|
|
97
135
|
```
|
|
98
136
|
## Warning: Dependency Cycle
|
|
@@ -105,7 +143,7 @@ These roadmaps block each other — resolve the cycle manually before treating e
|
|
|
105
143
|
|
|
106
144
|
## Constraints
|
|
107
145
|
|
|
108
|
-
- Read-only except the Step 3 auto-archive procedure (status flip + `git mv` + index/log updates) — never flip checkboxes, never upgrade inline items, never create task files. That is `/roadmap-next`'s job once the user
|
|
146
|
+
- Read-only except the Step 3 auto-archive procedure (status flip + `git mv` + index/log updates) — never flip checkboxes, never upgrade inline items, never create task files, never finalize decisions. That is `/roadmap-next`'s and `/decision-finalize`'s job once the user acts on this report.
|
|
109
147
|
- Permitted tools: `list_dir`, `find_file`, `Read`, `Edit`, `Bash` (only for `git mv` during archiving), `AskUserQuestion` (only if genuinely needed to disambiguate — this skill should normally run to completion without prompting).
|
|
110
148
|
- Never bash reads (`cat`/`find`/`grep`/`sed`/`ls`).
|
|
111
149
|
- Keep the report terse — no preamble, no closing summary beyond the tables above.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codewizard-dt/bootstrap",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "4.0.0",
|
|
4
4
|
"description": "Bootstrap Claude Code projects with an LLM Wiki, reusable skills, hooks, and MCP setup",
|
|
5
5
|
"homepage": "https://github.com/codewizard-dt/bootstrap-wiki#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -25,9 +25,7 @@
|
|
|
25
25
|
"raw/",
|
|
26
26
|
"!raw/research/",
|
|
27
27
|
"!raw/companies/",
|
|
28
|
-
"!raw/*.pdf"
|
|
29
|
-
".github/",
|
|
30
|
-
".gitleaks.toml"
|
|
28
|
+
"!raw/*.pdf"
|
|
31
29
|
],
|
|
32
30
|
"scripts": {
|
|
33
31
|
"test": "node --test 'test/*.test.js'"
|
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
name: Docker Fresh-Machine Harness
|
|
2
|
-
|
|
3
|
-
on:
|
|
4
|
-
pull_request:
|
|
5
|
-
paths:
|
|
6
|
-
- "test/docker/fresh-machine/**"
|
|
7
|
-
- "lib/scripts/**"
|
|
8
|
-
|
|
9
|
-
jobs:
|
|
10
|
-
fresh-machine:
|
|
11
|
-
runs-on: ubuntu-latest
|
|
12
|
-
steps:
|
|
13
|
-
- name: Checkout repo
|
|
14
|
-
uses: actions/checkout@v4
|
|
15
|
-
|
|
16
|
-
- name: Build fresh-machine image
|
|
17
|
-
run: docker build -t bootstrap-claude-fresh-machine test/docker/fresh-machine
|
|
18
|
-
|
|
19
|
-
- name: Run setup mode
|
|
20
|
-
run: ./test/docker/fresh-machine/run.sh setup
|
|
21
|
-
|
|
22
|
-
- name: Run update mode
|
|
23
|
-
run: ./test/docker/fresh-machine/run.sh update
|
|
24
|
-
|
|
25
|
-
# TASK-071 (stale mode) and TASK-072 (idempotency check) are still `status: todo` —
|
|
26
|
-
# add their run.sh modes as additional steps here once those tasks land.
|
|
@@ -1,24 +0,0 @@
|
|
|
1
|
-
name: Security
|
|
2
|
-
|
|
3
|
-
on:
|
|
4
|
-
push:
|
|
5
|
-
branches: [main]
|
|
6
|
-
pull_request:
|
|
7
|
-
branches: [main]
|
|
8
|
-
|
|
9
|
-
env:
|
|
10
|
-
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
|
|
11
|
-
|
|
12
|
-
jobs:
|
|
13
|
-
secret-scan:
|
|
14
|
-
name: Secret Detection (Gitleaks)
|
|
15
|
-
runs-on: ubuntu-latest
|
|
16
|
-
steps:
|
|
17
|
-
- uses: actions/checkout@v4
|
|
18
|
-
with:
|
|
19
|
-
fetch-depth: 0
|
|
20
|
-
|
|
21
|
-
- uses: gitleaks/gitleaks-action@v2
|
|
22
|
-
env:
|
|
23
|
-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
24
|
-
GITLEAKS_CONFIG: .gitleaks.toml
|
package/.gitleaks.toml
DELETED
|
@@ -1,15 +0,0 @@
|
|
|
1
|
-
title = "Gitleaks Configuration"
|
|
2
|
-
|
|
3
|
-
[extend]
|
|
4
|
-
useDefault = true
|
|
5
|
-
|
|
6
|
-
[allowlist]
|
|
7
|
-
description = "Project allowlist"
|
|
8
|
-
# Uncomment and add paths/regexes to suppress false positives:
|
|
9
|
-
# paths = [
|
|
10
|
-
# '''(?i)test/fixtures''',
|
|
11
|
-
# '''(?i)\.example$''',
|
|
12
|
-
# ]
|
|
13
|
-
# regexes = [
|
|
14
|
-
# '''EXAMPLE_PLACEHOLDER''',
|
|
15
|
-
# ]
|
|
@@ -1,322 +0,0 @@
|
|
|
1
|
-
Scaffold the deployment infrastructure described in the guide above for the project at: __PROJECT_DIR__
|
|
2
|
-
|
|
3
|
-
## Your task
|
|
4
|
-
|
|
5
|
-
Inspect the project's structure (directory layout, existing Dockerfiles, package.json/pyproject.toml/go.mod, existing Makefile, existing docker-compose files), then create or update the files listed below using real project values — never placeholder strings like `<ORG>`, `<PROJECT>`, or `<LABEL>`.
|
|
6
|
-
|
|
7
|
-
**If you cannot confidently identify the services, their entrypoints, or their runtimes from the files you find, stop and ask the user before creating anything.**
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
### Step 1 — Detect services
|
|
12
|
-
|
|
13
|
-
Identify each deployable service by scanning for directories (or the repo root for single-service repos) that contain any of:
|
|
14
|
-
|
|
15
|
-
- `package.json` — Node.js. Check `scripts.dev` / `scripts.start` for the dev command and inspect `dependencies` to identify the framework: Vite, Next.js, Express, Fastify, etc.
|
|
16
|
-
- `pyproject.toml` or `requirements.txt` — Python. Check dependencies for `fastapi`/`uvicorn`, `flask`, `django`, etc.
|
|
17
|
-
- `go.mod` — Go.
|
|
18
|
-
- `Cargo.toml` — Rust.
|
|
19
|
-
|
|
20
|
-
For each service record: **runtime · framework · dev command · port · whether it proxies to another service**.
|
|
21
|
-
|
|
22
|
-
---
|
|
23
|
-
|
|
24
|
-
### Step 2 — Create or update files
|
|
25
|
-
|
|
26
|
-
#### 1. `.github/workflows/security.yml` — always overwrite
|
|
27
|
-
Generic; no project-specific content. Include:
|
|
28
|
-
- **CodeQL** — matrix over the detected languages (use `python`, `javascript-typescript`, `go`, etc. as appropriate)
|
|
29
|
-
- **Gitleaks** secret detection with `fetch-depth: 0`
|
|
30
|
-
|
|
31
|
-
#### 2. `.github/workflows/build.yml` — create or overwrite with confirmation
|
|
32
|
-
Fill in real image names, Dockerfile paths, and runner label. If the file already exists, show the user what you plan to write and ask for confirmation before overwriting.
|
|
33
|
-
|
|
34
|
-
#### 3. `.gitleaks.toml` — create or overwrite with confirmation
|
|
35
|
-
If the file already exists, show the user what you plan to write and ask for confirmation before overwriting.
|
|
36
|
-
|
|
37
|
-
#### 4. `Makefile` — merge Docker targets if a Makefile already exists; create from scratch if not
|
|
38
|
-
Add only the targets from the guide that are not already present. Never remove or reformat existing targets.
|
|
39
|
-
Set `GITHUB_USER ?= $(shell gh api user --jq .login 2>/dev/null)` so auth resolves at runtime rather than being hardcoded.
|
|
40
|
-
|
|
41
|
-
The deploy targets **must** use this exact shape (copy verbatim, substituting the real `$(PROJECT)` variable name):
|
|
42
|
-
|
|
43
|
-
```makefile
|
|
44
|
-
## deploy — sync compose file + Makefile to VPS then restart
|
|
45
|
-
deploy: deploy-sync
|
|
46
|
-
ssh $(PROJECT) "cd /opt/$(PROJECT) && make deploy-pull"
|
|
47
|
-
|
|
48
|
-
deploy-sync:
|
|
49
|
-
ssh $(PROJECT) "mkdir -p /opt/$(PROJECT)"
|
|
50
|
-
scp docker-compose.yml Makefile $(PROJECT):/opt/$(PROJECT)/
|
|
51
|
-
scp .env.production $(PROJECT):/opt/$(PROJECT)/.env
|
|
52
|
-
scp lib/scripts/setup-runner.sh $(PROJECT):~/setup-runner.sh
|
|
53
|
-
|
|
54
|
-
## setup-runner — upload and run the runner installer on the VPS
|
|
55
|
-
## Usage: make setup-runner RUNNER_TOKEN=<token>
|
|
56
|
-
setup-runner: deploy-sync
|
|
57
|
-
ssh $(PROJECT) "RUNNER_TOKEN=$(RUNNER_TOKEN) REPO_URL=$(REPO_URL) bash ~/setup-runner.sh"
|
|
58
|
-
|
|
59
|
-
## deploy-pull — pull new images and restart (run directly on the VPS)
|
|
60
|
-
deploy-pull: up
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
#### 5. `docker-compose.yml` — create or overwrite with confirmation
|
|
64
|
-
|
|
65
|
-
If the file already exists, show the user what you plan to write and ask for confirmation before overwriting. Production-style compose file. **Hard rules:**
|
|
66
|
-
- Every service **must** use a pre-built GHCR image (`image: ghcr.io/<org>/<project>-<service>:latest`).
|
|
67
|
-
- **No `build:` blocks** — image building belongs exclusively in `docker-compose.build.yml` and the CI workflow.
|
|
68
|
-
- Set realistic `healthcheck`, `restart: unless-stopped`, and environment variables with sane defaults.
|
|
69
|
-
- Declare named volumes for any stateful services (databases, caches).
|
|
70
|
-
|
|
71
|
-
#### 6. `docker-compose.build.yml` — create or overwrite with confirmation
|
|
72
|
-
|
|
73
|
-
If the file already exists, show the user what you plan to write and ask for confirmation before overwriting.
|
|
74
|
-
Local dev overlay. Layered on top of `docker-compose.yml` via:
|
|
75
|
-
```
|
|
76
|
-
docker compose -f docker-compose.yml -f docker-compose.build.yml up --build --wait
|
|
77
|
-
```
|
|
78
|
-
For each service:
|
|
79
|
-
- Add a `build:` block pointing to the service directory and its `Dockerfile.dev`
|
|
80
|
-
- Bind-mount the full source tree into the working directory (e.g. `./backend:/app`)
|
|
81
|
-
- **Shield installed dependencies with an anonymous volume** declared immediately after the source mount. This prevents the host bind mount from overwriting the container's installed packages:
|
|
82
|
-
- Node.js: `- /app/node_modules`
|
|
83
|
-
- Python venv: `- /app/.venv`
|
|
84
|
-
- Add others (e.g. `/app/.cargo`) for any runtime that installs into a subdirectory
|
|
85
|
-
- **Override service URLs that hardcode `localhost`**: inside Docker, `localhost` resolves to the container itself. Replace with the compose service name (e.g. `DATABASE_URL: postgresql+asyncpg://postgres:postgres@db:5432/mydb`)
|
|
86
|
-
- **Vite / Node frontend proxy targets**: Vite's dev-server proxy runs server-side (Node.js), so its `target` also can't use `localhost` to reach the backend container. Pass the backend address via an env var in the compose service (e.g. `PROXY_TARGET: http://backend:8000`) and update `vite.config.ts` to read it:
|
|
87
|
-
```ts
|
|
88
|
-
target: process.env.PROXY_TARGET ?? 'http://localhost:8000',
|
|
89
|
-
```
|
|
90
|
-
- **Vite `--host` flag**: the Vite dev server binds to `127.0.0.1` by default and is unreachable via Docker port mapping. Override the container command: `command: npx vite --host` (do not bake `--host` into the Dockerfile so the image stays usable outside Docker)
|
|
91
|
-
- Wire `depends_on` with `condition: service_healthy` for any service that requires the database to be ready before starting
|
|
92
|
-
|
|
93
|
-
#### 7. `Dockerfile.dev` + `docker-entrypoint.sh` per service — create or overwrite with confirmation
|
|
94
|
-
|
|
95
|
-
If any of these files already exist, show the user what you plan to write and ask for confirmation before overwriting.
|
|
96
|
-
Minimal, fast-to-build dev image. The guiding principle: **install dependencies in the image; let source arrive via the bind mount at runtime**.
|
|
97
|
-
|
|
98
|
-
**Use a `docker-entrypoint.sh` watcher script** for Node.js and Python services so that adding or removing a dependency inside the container is not needed — the entrypoint watches the manifest file for changes and automatically reinstalls + restarts the dev server. This makes the developer workflow seamless: edit `package.json` or `pyproject.toml` on the host, save, and the container self-heals.
|
|
99
|
-
|
|
100
|
-
**Node.js entrypoint pattern** (`docker-entrypoint.sh`, place alongside `Dockerfile.dev`):
|
|
101
|
-
```sh
|
|
102
|
-
#!/bin/sh
|
|
103
|
-
set -e
|
|
104
|
-
|
|
105
|
-
npm install
|
|
106
|
-
|
|
107
|
-
HASH=$(md5sum package.json | cut -d' ' -f1)
|
|
108
|
-
APP_PID=""
|
|
109
|
-
|
|
110
|
-
start_app() {
|
|
111
|
-
npx vite --host & # or: npm run dev &, npx ts-node-dev src/index.ts &, etc.
|
|
112
|
-
APP_PID=$!
|
|
113
|
-
}
|
|
114
|
-
|
|
115
|
-
stop_app() {
|
|
116
|
-
if [ -n "$APP_PID" ]; then
|
|
117
|
-
kill "$APP_PID" 2>/dev/null
|
|
118
|
-
wait "$APP_PID" 2>/dev/null || true
|
|
119
|
-
APP_PID=""
|
|
120
|
-
fi
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
start_app
|
|
124
|
-
|
|
125
|
-
while sleep 3; do
|
|
126
|
-
NEW=$(md5sum package.json | cut -d' ' -f1)
|
|
127
|
-
if [ "$NEW" != "$HASH" ]; then
|
|
128
|
-
echo "[entrypoint] package.json changed — reinstalling..."
|
|
129
|
-
npm install
|
|
130
|
-
HASH=$NEW
|
|
131
|
-
stop_app
|
|
132
|
-
start_app
|
|
133
|
-
fi
|
|
134
|
-
done
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
**Python entrypoint pattern** (`docker-entrypoint.sh`):
|
|
138
|
-
```sh
|
|
139
|
-
#!/bin/sh
|
|
140
|
-
set -e
|
|
141
|
-
|
|
142
|
-
pip install -e ".[dev]" --quiet # or: pip install -r requirements.txt --quiet
|
|
143
|
-
|
|
144
|
-
MANIFEST=${MANIFEST_FILE:-pyproject.toml} # override to requirements.txt if needed
|
|
145
|
-
HASH=$(md5sum "$MANIFEST" | cut -d' ' -f1)
|
|
146
|
-
APP_PID=""
|
|
147
|
-
|
|
148
|
-
start_app() {
|
|
149
|
-
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload & # adjust module path
|
|
150
|
-
APP_PID=$!
|
|
151
|
-
}
|
|
152
|
-
|
|
153
|
-
stop_app() {
|
|
154
|
-
if [ -n "$APP_PID" ]; then
|
|
155
|
-
kill "$APP_PID" 2>/dev/null
|
|
156
|
-
wait "$APP_PID" 2>/dev/null || true
|
|
157
|
-
APP_PID=""
|
|
158
|
-
fi
|
|
159
|
-
}
|
|
160
|
-
|
|
161
|
-
start_app
|
|
162
|
-
|
|
163
|
-
while sleep 3; do
|
|
164
|
-
NEW=$(md5sum "$MANIFEST" | cut -d' ' -f1)
|
|
165
|
-
if [ "$NEW" != "$HASH" ]; then
|
|
166
|
-
echo "[entrypoint] $MANIFEST changed — reinstalling..."
|
|
167
|
-
pip install -e ".[dev]" --quiet
|
|
168
|
-
HASH=$NEW
|
|
169
|
-
stop_app
|
|
170
|
-
start_app
|
|
171
|
-
fi
|
|
172
|
-
done
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
The `Dockerfile.dev` copies and `chmod +x`s the entrypoint, then sets it as `CMD`:
|
|
176
|
-
|
|
177
|
-
- **Node.js frontend (Vite / CRA / Next dev mode)**: `FROM node:22-alpine`, `COPY package*.json ./`, `RUN npm ci`, `COPY docker-entrypoint.sh ./`, `RUN chmod +x docker-entrypoint.sh`, `CMD ["/bin/sh", "./docker-entrypoint.sh"]`. Do not `COPY` source. Adjust the `start_app` command in the entrypoint for the framework (Vite uses `--host` in the entrypoint; remove the compose `command:` override for Vite if using the entrypoint).
|
|
178
|
-
- **Node.js backend (Express / Fastify / etc.)**: same Dockerfile pattern; update `start_app` in the entrypoint to run the server with hot-reload (e.g. `node --watch src/index.js` or `npx ts-node-dev src/index.ts`).
|
|
179
|
-
- **Python (FastAPI/uvicorn)**: `FROM python:3.11-slim`, copy the manifest (`pyproject.toml` or `requirements.txt`), install deps, copy and `chmod +x` the entrypoint, set `CMD` to run it. Adjust the uvicorn module path (`app.main:app`) and install command to match the project. Do not `COPY` source.
|
|
180
|
-
- **Go**: `FROM golang:1.22-alpine`, copy `go.mod` + `go.sum`, `RUN go mod download`, `CMD ["go", "run", "./cmd/server"]` (adjust path). Use `air` for hot-reload if the project already depends on it. No entrypoint watcher needed — Go has no install-time manifest changes that require a restart.
|
|
181
|
-
- **Other runtimes**: apply the same principle — install deps in the image; source arrives via bind mount; dev server runs with hot-reload; add an entrypoint watcher if the runtime has a lockfile-driven install step.
|
|
182
|
-
|
|
183
|
-
#### 8. Caddy reverse proxy — create or overwrite with confirmation
|
|
184
|
-
|
|
185
|
-
If any Caddy files already exist, show the user what you plan to write and ask for confirmation before overwriting. Add Caddy when the project has **both a frontend and a backend service** (i.e. two separate containers that need to be served under a single domain). Skip this section for single-service projects or projects that already have a reverse proxy configured.
|
|
186
|
-
|
|
187
|
-
**`Dockerfile.caddy`**
|
|
188
|
-
```dockerfile
|
|
189
|
-
FROM caddy:2-alpine
|
|
190
|
-
COPY Caddyfile /etc/caddy/Caddyfile
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
**`Caddyfile`** (production — uses real domain, TLS handled automatically by Caddy):
|
|
194
|
-
```
|
|
195
|
-
<domain> {
|
|
196
|
-
handle /api/* {
|
|
197
|
-
reverse_proxy backend:<backend-port>
|
|
198
|
-
}
|
|
199
|
-
handle {
|
|
200
|
-
reverse_proxy frontend:<frontend-port>
|
|
201
|
-
}
|
|
202
|
-
}
|
|
203
|
-
```
|
|
204
|
-
- Replace `<domain>` with the project's real domain (e.g. `myapp.example.com`)
|
|
205
|
-
- Replace `backend:<backend-port>` with the compose service name and port (e.g. `backend:8000`)
|
|
206
|
-
- Replace `frontend:<frontend-port>` with the compose service name and port (e.g. `frontend:80`)
|
|
207
|
-
- Add additional `handle` blocks if the project has more routing rules
|
|
208
|
-
|
|
209
|
-
**`Caddyfile.local`** (local dev — plain HTTP on port 80, same routing, no TLS):
|
|
210
|
-
```
|
|
211
|
-
:80 {
|
|
212
|
-
handle /api/* {
|
|
213
|
-
reverse_proxy backend:<backend-port>
|
|
214
|
-
}
|
|
215
|
-
handle {
|
|
216
|
-
reverse_proxy frontend:<frontend-port>
|
|
217
|
-
}
|
|
218
|
-
}
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
**Integrate Caddy into compose files** — for each file, if a `caddy` entry already exists show the user the planned change and ask for confirmation before overwriting:
|
|
222
|
-
- In `docker-compose.yml`: add a `caddy` service using the GHCR image (`ghcr.io/<org>/<project>-caddy:latest`), ports `80:80` and `443:443`, and named volumes `caddy_data` and `caddy_config`.
|
|
223
|
-
- In `docker-compose.build.yml`: add a `caddy` override with `build: { context: ., dockerfile: Dockerfile.caddy }` and bind-mount `./Caddyfile.local:/etc/caddy/Caddyfile`.
|
|
224
|
-
- In `.github/workflows/build.yml`: add `caddy` to the build matrix.
|
|
225
|
-
|
|
226
|
-
---
|
|
227
|
-
|
|
228
|
-
### Step 3 — Provision the DigitalOcean droplet and GitHub Actions runner
|
|
229
|
-
|
|
230
|
-
#### 3a. Check for an existing droplet
|
|
231
|
-
|
|
232
|
-
Look for `DROPLET_IP` in the Makefile (search for the literal string `DROPLET_IP`).
|
|
233
|
-
|
|
234
|
-
- **If `DROPLET_IP` is already set** — a droplet exists. Skip to **3c** (runner setup).
|
|
235
|
-
- **If `DROPLET_IP` is absent** — proceed to **3b**.
|
|
236
|
-
|
|
237
|
-
#### 3b. Size and create the droplet
|
|
238
|
-
|
|
239
|
-
**Assess the appropriate droplet size** by examining what the project runs:
|
|
240
|
-
|
|
241
|
-
| Signal | Minimum slug |
|
|
242
|
-
|--------|-------------|
|
|
243
|
-
| Single static site or tiny API | `s-1vcpu-1gb` |
|
|
244
|
-
| One or two lightweight services (Node/Python) | `s-1vcpu-2gb` |
|
|
245
|
-
| Two or more services with a database | `s-2vcpu-4gb` |
|
|
246
|
-
| ML inference, heavy background workers, or 3+ services | `s-4vcpu-8gb` |
|
|
247
|
-
|
|
248
|
-
Then ask the user to confirm the size before creating anything.
|
|
249
|
-
|
|
250
|
-
Once confirmed, create the droplet with `doctl`:
|
|
251
|
-
|
|
252
|
-
```bash
|
|
253
|
-
doctl compute droplet create <project>-runner \
|
|
254
|
-
--region nyc3 \
|
|
255
|
-
--image ubuntu-24-04-x64 \
|
|
256
|
-
--size <confirmed-slug> \
|
|
257
|
-
--ssh-keys $(doctl compute ssh-key list --format ID --no-header | paste -sd,) \
|
|
258
|
-
--wait \
|
|
259
|
-
--format PublicIPv4 \
|
|
260
|
-
--no-header
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
Record the returned IP as `DROPLET_IP`.
|
|
264
|
-
|
|
265
|
-
**Apply the general-web firewall** (the firewall named `general-web`):
|
|
266
|
-
|
|
267
|
-
```bash
|
|
268
|
-
FIREWALL_ID=$(doctl compute firewall list --format ID,Name --no-header | awk '/general-web/{print $1}')
|
|
269
|
-
DROPLET_ID=$(doctl compute droplet list --format ID,Name --no-header | awk '/<project>-runner/{print $1}')
|
|
270
|
-
doctl compute firewall add-droplets "$FIREWALL_ID" --droplet-ids "$DROPLET_ID"
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
**Write `DROPLET_IP` into the Makefile** immediately after the `GITHUB_USER` line:
|
|
274
|
-
|
|
275
|
-
```makefile
|
|
276
|
-
DROPLET_IP ?= <ip>
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
**Register the SSH alias** so subsequent `make ssh` and `make deploy` targets resolve the host:
|
|
280
|
-
|
|
281
|
-
```bash
|
|
282
|
-
make ssh-alias DROPLET_IP=<ip>
|
|
283
|
-
```
|
|
284
|
-
|
|
285
|
-
#### 3c. Walk the user through runner setup
|
|
286
|
-
|
|
287
|
-
Provide the following steps as a numbered checklist. Substitute real values — never leave placeholders.
|
|
288
|
-
|
|
289
|
-
1. **SSH into the droplet and install Docker + `gh` CLI** (if not already present):
|
|
290
|
-
```bash
|
|
291
|
-
ssh root@<DROPLET_IP>
|
|
292
|
-
curl -fsSL https://get.docker.com | sh && systemctl enable --now docker
|
|
293
|
-
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
|
|
294
|
-
| dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
|
|
295
|
-
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] \
|
|
296
|
-
https://cli.github.com/packages stable main" \
|
|
297
|
-
| tee /etc/apt/sources.list.d/github-cli.list > /dev/null
|
|
298
|
-
apt update && apt install gh -y
|
|
299
|
-
```
|
|
300
|
-
|
|
301
|
-
2. **Get a runner registration token** — GitHub → repo → **Settings → Actions → Runners → New self-hosted runner** (Linux x64) and copy the `--token` value.
|
|
302
|
-
|
|
303
|
-
3. **From the local project root**, run:
|
|
304
|
-
```bash
|
|
305
|
-
make setup-runner RUNNER_TOKEN=<TOKEN>
|
|
306
|
-
```
|
|
307
|
-
This uploads `setup-runner.sh` to the VPS and runs it — creating the `runner` user, registering the runner, and starting it as a systemd service.
|
|
308
|
-
|
|
309
|
-
4. **Verify** the runner appears as **Idle** at:
|
|
310
|
-
`<REPO_URL>/settings/actions/runners`
|
|
311
|
-
|
|
312
|
-
---
|
|
313
|
-
|
|
314
|
-
### Deriving the GHCR org/repo slug
|
|
315
|
-
|
|
316
|
-
Priority order:
|
|
317
|
-
1. `name` field in `package.json` or `pyproject.toml` — strip service-specific suffixes (`-backend`, `-frontend`, `-api`) to recover the project base name
|
|
318
|
-
2. GitHub remote URL (`git remote get-url origin`) — owner becomes the org; combine with the base name above or the directory name
|
|
319
|
-
3. Project directory name as a last resort
|
|
320
|
-
|
|
321
|
-
Image naming convention: `ghcr.io/<org>/<project>-<service>`
|
|
322
|
-
Examples: `ghcr.io/acme/myapp-backend`, `ghcr.io/acme/myapp-frontend`
|