@codewizard-dt/bootstrap 2.10.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/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- package/raw/software-factory-case-study.pdf +0 -0
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict';
|
|
3
|
+
|
|
4
|
+
// serena-write-guard.js — PreToolUse hook (matcher: Write)
|
|
5
|
+
// Blocks Write on existing code files. New files (no fs path yet) are allowed through.
|
|
6
|
+
// Allowlist: markdown, JSON, YAML, config files, test files, and known exempt paths.
|
|
7
|
+
|
|
8
|
+
const fs = require('fs');
|
|
9
|
+
const {
|
|
10
|
+
isAllowedPath, buildEditSuggestion, buildStructuredBlockResponse,
|
|
11
|
+
getStateFilePath, readStateFile, shouldEnforceSerena, isOutsideProject,
|
|
12
|
+
} = require('./lib/serena');
|
|
13
|
+
|
|
14
|
+
let raw = '';
|
|
15
|
+
process.stdin.setEncoding('utf8');
|
|
16
|
+
process.stdin.on('data', d => { raw += d; });
|
|
17
|
+
process.stdin.on('end', () => {
|
|
18
|
+
let data;
|
|
19
|
+
try { data = JSON.parse(raw); } catch (e) { process.exit(0); }
|
|
20
|
+
|
|
21
|
+
if (data.tool_name !== 'Write') process.exit(0);
|
|
22
|
+
|
|
23
|
+
// Fail-open: skip enforcement when Serena is unhealthy for this project.
|
|
24
|
+
if (!shouldEnforceSerena(readStateFile(getStateFilePath()))) process.exit(0);
|
|
25
|
+
|
|
26
|
+
const filePath = String((data.tool_input || {}).file_path ?? '').trim();
|
|
27
|
+
|
|
28
|
+
// Fail-open: if we can't determine the path, let the call through.
|
|
29
|
+
if (!filePath) process.exit(0);
|
|
30
|
+
|
|
31
|
+
// Enforcement is scoped to the project root — Serena can't reach outside it.
|
|
32
|
+
if (isOutsideProject(filePath)) process.exit(0);
|
|
33
|
+
|
|
34
|
+
if (isAllowedPath(filePath, { allowMarkdown: true })) process.exit(0);
|
|
35
|
+
|
|
36
|
+
// New files have no symbols to preserve — native Write is the right tool.
|
|
37
|
+
if (!fs.existsSync(filePath)) process.exit(0);
|
|
38
|
+
|
|
39
|
+
// --- BLOCKED (file exists — Write would clobber symbolic content) ---
|
|
40
|
+
const suggestion = buildEditSuggestion(filePath);
|
|
41
|
+
const reason =
|
|
42
|
+
`serena-write-guard: Writing to existing code file "${filePath}" directly is blocked.\n` +
|
|
43
|
+
`Use Serena's edit tools instead:\n${suggestion}\n\n` +
|
|
44
|
+
`Allowlist policy: .md, .json, .yaml, .env, .sql, .css, .html, config files,\n` +
|
|
45
|
+
`test files (*.test.*, *.spec.*), and paths under .task/, .claude/, node_modules/.`;
|
|
46
|
+
|
|
47
|
+
process.stderr.write(`\n⛔ SERENA-WRITE BLOCK: Direct Write to existing code file — use Serena instead\n` +
|
|
48
|
+
`File: ${filePath}\nSuggested call:\n${suggestion}\n\n`);
|
|
49
|
+
|
|
50
|
+
console.log(JSON.stringify(buildStructuredBlockResponse({
|
|
51
|
+
hook: 'serena-write-guard',
|
|
52
|
+
symbols: [],
|
|
53
|
+
intent: 'write',
|
|
54
|
+
reason,
|
|
55
|
+
})));
|
|
56
|
+
|
|
57
|
+
process.exit(2);
|
|
58
|
+
});
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# prompts/
|
|
2
|
+
|
|
3
|
+
Markdown prompt templates for setup steps that are too context-sensitive for a static file copy — each one gets read by a script in `lib/scripts/`, interpolated with real project values, and handed to the `claude` CLI (`claude --print`) so Claude does the actual detection/generation work in the target project.
|
|
4
|
+
|
|
5
|
+
| Prompt | Driven by | Purpose |
|
|
6
|
+
|--------|-----------|---------|
|
|
7
|
+
| `setup-deployment.md` | `lib/scripts/setup-deployment.sh` | Detects deployable services (Node/Python/Go/Rust) from manifest files, then creates or updates `.github/workflows/security.yml` (always overwritten — generic CodeQL + Gitleaks), `.github/workflows/build.yml` and `.gitleaks.toml` (create-once, confirm before overwrite), and `Makefile` Docker targets (merged with existing targets, never removed/reformatted). Refuses to guess service names/entrypoints it can't confidently identify — stops and asks instead. |
|
|
8
|
+
| `migrate-wiki.md` | `lib/scripts/migrate-project.sh` | Drives the semantic conversion from a legacy `.docs/`-layout project to the LLM Wiki structure, after `sync-wiki-scaffold.sh` has already created the empty scaffold. Runs headlessly with only Bash/Read/Edit/Write (explicitly told not to look for Serena MCP tools). Hard rules: `git mv` every file before editing it (preserves history), never touch `raw/` or template-owned files (`wiki/conventions.md`, `lifecycle.md`), never move a file once it lands at its new path, and never commit — leaves everything staged for the user to review. Contains the full old-path → new-path mapping table (`.docs/tasks/` → `wiki/work/tasks/TASK-NNN`, `.docs/adr/` → `wiki/work/decisions/DEC-NNNN`, etc.) and the per-family status-inference rules. |
|
|
9
|
+
| `setup-strict-typechecks.md` | `lib/scripts/setup-strict-typechecks.sh` | Scans the repo for every language with a type-checking/linting story, researches current strict-mode conventions per language (TypeScript `strict` + `typescript-eslint` strictTypeChecked, Python `mypy --strict`, Go `staticcheck`/`vet`, Rust `deny(warnings)`/Clippy, …) via Context7/Brave Search, installs the required toolchain packages, and wires the config files plus a `make typecheck` target. Accepts an optional language list from the script's CLI args to scope the run. |
|
|
10
|
+
| `setup-design-system.md` | *(none — not currently invoked by any script)* | A generic prompt for wiring an arbitrary design system into a frontend app: migrate tokens/assets into `<APP_SRC_PATH>/design-system/`, wire the CSS import into the app entry point, then convert each prototype reference component into a typed production component driven entirely by CSS custom properties. Takes `<DESIGN_SYSTEM_PATH>`, `<APP_SRC_PATH>`, `<APP_ROUTES_PATH>`, and `<SKILL_NAME>` placeholders. Kept for manual reuse (`claude < setup-design-system.md` with placeholders filled in) when onboarding a design system other than the one `lib/skills/frontend-taste` already automates (house-style, from `~/code/house-style`). |
|
|
11
|
+
|
|
12
|
+
## Conventions
|
|
13
|
+
|
|
14
|
+
- Each prompt is a plain markdown instruction document, not a template engine — the driving script does simple string interpolation (e.g. substituting `__PROJECT_DIR__`) or appends args as plain text (e.g. the language list in `setup-strict-typechecks.md`) before piping the result to `claude --print`.
|
|
15
|
+
- Prompts that touch `wiki/` content reiterate the CRITICAL wiki rules from the root `CLAUDE.md` (immutable `raw/`, never edit template-owned files, `git mv` before edit) because they run in a fresh `claude` invocation with no access to this repo's own `CLAUDE.md` context.
|
|
16
|
+
- If a setup step's logic is static (file copy, directory creation, sentinel-guarded insert), it belongs in `lib/scripts/` or `lib/scripts/templates/` directly — a prompt here is only warranted when the step requires inspecting arbitrary target-project state and making judgment calls.
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# Migrate legacy .docs/ artifacts to the LLM Wiki structure
|
|
2
|
+
|
|
3
|
+
You are migrating the project at `__PROJECT_DIR__` from the legacy `.docs/`-based documentation layout to the LLM Wiki structure. The empty wiki scaffold (directories, `index.md`, `log.md`, `conventions.md`, per-family `lifecycle.md` and `index.md`) has already been created by `sync-wiki-scaffold.sh` — your job is the semantic conversion of the legacy content.
|
|
4
|
+
|
|
5
|
+
Work from the project root (`__PROJECT_DIR__`). You are on a dedicated `wiki-migration` branch with a previously-clean tree.
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
## Tool constraints — read before doing anything else
|
|
9
|
+
|
|
10
|
+
This prompt runs headlessly. **Only these tools are available:**
|
|
11
|
+
|
|
12
|
+
- **Bash** — use for file moves (`mv` or `git mv`), `find`, `mkdir`, `rm`/`git rm`
|
|
13
|
+
- **Read** — use to read any file before editing it
|
|
14
|
+
- **Edit** / **Write** — use for all content changes
|
|
15
|
+
|
|
16
|
+
**Do NOT attempt to use Serena MCP tools.** They are not available in this headless context. Do **not** call `ToolSearch` to look for them — it will return empty and waste turns. Do not look for deferred tools. Start work immediately using Bash and Read.
|
|
17
|
+
|
|
18
|
+
## Hard rules
|
|
19
|
+
|
|
20
|
+
1. **`git mv` every file BEFORE editing its content** — this preserves git history. Move first, edit second. Never copy-and-delete.
|
|
21
|
+
2. `raw/` is immutable — never create, modify, or delete anything under `raw/`.
|
|
22
|
+
3. Never edit `wiki/conventions.md` or any `wiki/work/*/lifecycle.md` — they are template-owned.
|
|
23
|
+
4. Once a file lands at its new path it never moves again — state lives in `status:` frontmatter.
|
|
24
|
+
5. **Do not commit.** Leave all changes staged/unstaged for the user to review. Stage moves with `git add -A` at the very end is fine; no `git commit`.
|
|
25
|
+
6. Read each family's `wiki/work/<family>/lifecycle.md` before migrating that family — it defines the frontmatter schema and valid statuses.
|
|
26
|
+
|
|
27
|
+
## Migration mapping
|
|
28
|
+
|
|
29
|
+
| Old location | New path | Status |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| `.docs/tasks/NNN-slug.md` | `wiki/work/tasks/TASK-NNN-slug.md` | `todo` — or `in-progress` if the old `.docs/tasks/README.md` index marks it as in progress |
|
|
32
|
+
| `.docs/tasks/completed/NNN-slug.md` | `wiki/work/tasks/TASK-NNN-slug.md` | `done` |
|
|
33
|
+
| `.docs/tasks/trashed/NNN-slug.md` | `wiki/work/tasks/TASK-NNN-slug.md` | `trashed` |
|
|
34
|
+
| `.docs/uat/NNN-slug.uat.md` | `wiki/work/uat/UAT-NNN-slug.md` (drop the `.uat` double extension) | `pending` |
|
|
35
|
+
| `.docs/uat/completed/NNN-slug.uat.md` | `wiki/work/uat/UAT-NNN-slug.md` | `passed` |
|
|
36
|
+
| `.docs/uat/skipped/NNN-slug.uat.md` | `wiki/work/uat/UAT-NNN-slug.md` | `skipped` |
|
|
37
|
+
| `.docs/uat/trashed/NNN-slug.uat.md` | `wiki/work/uat/UAT-NNN-slug.md` | `trashed` |
|
|
38
|
+
| `.docs/uat/screenshots/*` | `wiki/work/uat/screenshots/` | — (binary assets, just `git mv`) |
|
|
39
|
+
| `.docs/adr/NNNN-slug.md` and `.docs/adr/completed/NNNN-slug.md` | `wiki/work/decisions/DEC-NNNN-slug.md` | no file-level status — each `## DM.` block keeps its own `Status` field verbatim |
|
|
40
|
+
| `.docs/prd/NNN-slug.md` | `wiki/work/requirements/REQ-NNN-slug.md` | from old frontmatter/body (`draft` or `approved`) |
|
|
41
|
+
| `.docs/prd/archived/NNN-slug.md` | `wiki/work/requirements/REQ-NNN-slug.md` | `retired` |
|
|
42
|
+
| `.docs/bugs/NNNN-slug.md` | `wiki/work/bugs/BUG-NNNN-slug.md` | `open` |
|
|
43
|
+
| `.docs/bugs/in-progress/NNNN-slug.md` | `wiki/work/bugs/BUG-NNNN-slug.md` | `in-progress` |
|
|
44
|
+
| `.docs/bugs/closed/NNNN-slug.md` | `wiki/work/bugs/BUG-NNNN-slug.md` | `closed` |
|
|
45
|
+
| `.docs/roadmaps/NNN-slug.md` | `wiki/work/roadmaps/ROADMAP-NNN-slug.md` | `active` |
|
|
46
|
+
| `.docs/roadmaps/completed/NNN-slug.md` | `wiki/work/roadmaps/ROADMAP-NNN-slug.md` | `done` |
|
|
47
|
+
| Old per-family `README.md` index files | **not migrated** — read them FIRST for status hints (e.g. which tasks are in-progress), then `git rm` them | — |
|
|
48
|
+
|
|
49
|
+
Files that don't match the family's `NNN-slug.md` pattern: migrate them anyway with the next free ID and note the rename in the final report.
|
|
50
|
+
|
|
51
|
+
## Per-file procedure
|
|
52
|
+
|
|
53
|
+
For every artifact file, in this order:
|
|
54
|
+
|
|
55
|
+
1. **`git mv`** to its new path (per the mapping table).
|
|
56
|
+
2. **Normalize frontmatter.** Add a YAML frontmatter block if missing; if one exists, update it in place, preserving any extra keys:
|
|
57
|
+
- `id:` — from the new filename prefix (e.g. `TASK-014`, `DEC-0007`)
|
|
58
|
+
- `title:` — from the first H1 heading; fall back to a humanized filename slug
|
|
59
|
+
- `status:` — per the mapping table (decisions: no file-level status)
|
|
60
|
+
- `created:` / `updated:` — from `git log --follow --format=%ad --date=short -- <file>`; oldest commit date = created, newest = updated; fall back to today's date if no history
|
|
61
|
+
3. **Rewrite in-body links and references:**
|
|
62
|
+
- Relative artifact links in any form (`../tasks/NNN-slug.md`, `completed/NNN-slug.md`, `.docs/tasks/NNN-slug.md`, etc.) → the flat new path with the new ID-prefixed filename (e.g. `../tasks/TASK-014-slug.md` from a UAT file, `TASK-014-slug.md` from a sibling task)
|
|
63
|
+
- `**Implements**: ADR-NNNN#DM` → `implements::[[DEC-NNNN#DM]]`
|
|
64
|
+
- All other `ADR-NNNN` mentions → `DEC-NNNN`
|
|
65
|
+
- `.uat.md` link suffixes → the new `UAT-NNN-slug.md` form
|
|
66
|
+
|
|
67
|
+
## Cross-links (UAT ↔ task)
|
|
68
|
+
|
|
69
|
+
Every migrated UAT file gets:
|
|
70
|
+
- `task: TASK-NNN` in frontmatter (the task with the matching number)
|
|
71
|
+
- `implements::[[TASK-NNN]]` as the first body line under the H1
|
|
72
|
+
|
|
73
|
+
Every task that has a matching UAT gets `uat: ../uat/UAT-NNN-slug.md` in its frontmatter.
|
|
74
|
+
|
|
75
|
+
If a UAT has no matching task (or vice versa), leave the link out and list it in the final report.
|
|
76
|
+
|
|
77
|
+
## ID collisions
|
|
78
|
+
|
|
79
|
+
If the same number exists in two source dirs of one family (e.g. `.docs/tasks/007-a.md` AND `.docs/tasks/completed/007-b.md`), keep the number on the file with the older git history and renumber the newer file to the family's next free ID. Update every link that referenced the renumbered file. Record each remap in the final report.
|
|
80
|
+
|
|
81
|
+
## Family indexes
|
|
82
|
+
|
|
83
|
+
After all files have landed, build each `wiki/work/<family>/index.md` (replace the `_(none yet)_` placeholder) listing **only active items**, per each family's `lifecycle.md`:
|
|
84
|
+
|
|
85
|
+
- requirements: `draft`, `approved` · decisions: groups with ≥1 `proposed` block · roadmaps: `active` · tasks: `todo`, `in-progress` · uat: `pending`, `in-progress`, `failed` · bugs: `open`, `triaged`, `in-progress`
|
|
86
|
+
|
|
87
|
+
Entry format is documented in each index stub. Non-active items are simply not listed — their files stay put.
|
|
88
|
+
|
|
89
|
+
## Log entry
|
|
90
|
+
|
|
91
|
+
Append to `wiki/log.md`:
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
## [YYYY-MM-DD] migrate | .docs → wiki migration
|
|
95
|
+
Migrated N tasks, N UAT files, N decisions, N requirements, N bugs, N roadmaps from the legacy .docs/ layout. <1 sentence on anything notable: ID remaps, missing cross-links, skipped files.>
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Cleanup
|
|
99
|
+
|
|
100
|
+
1. `git rm` the old per-family `README.md` indexes (after extracting status hints).
|
|
101
|
+
2. After all moves, the old family dirs (`.docs/tasks`, `.docs/uat`, `.docs/adr`, `.docs/prd`, `.docs/bugs`, `.docs/roadmaps`) must contain nothing but empty subdirectories and `.gitkeep` files — `git rm` the `.gitkeep`s and remove the empty directories.
|
|
102
|
+
3. **KEEP `.docs/guides/` and `.docs/company-context/`** — they are still used.
|
|
103
|
+
|
|
104
|
+
## Final report
|
|
105
|
+
|
|
106
|
+
End with a concise report:
|
|
107
|
+
- Per-family counts: migrated files and their status distribution
|
|
108
|
+
- Rows added to each family index
|
|
109
|
+
- ID remaps performed (old → new)
|
|
110
|
+
- Anything ambiguous or skipped — listed explicitly, never silently dropped
|
|
111
|
+
- Confirmation that `.docs/` now contains only `guides/` and `company-context/`
|
|
@@ -0,0 +1,322 @@
|
|
|
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`
|