@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,88 @@
|
|
|
1
|
+
name: Build & Push
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
# push:
|
|
5
|
+
# branches: [main] # uncomment to enable automatic deploys on push
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
env:
|
|
9
|
+
REGISTRY: ghcr.io
|
|
10
|
+
OWNER: ${{ github.repository_owner }}
|
|
11
|
+
IMAGE: ${{ github.event.repository.name }}
|
|
12
|
+
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
|
|
13
|
+
|
|
14
|
+
jobs:
|
|
15
|
+
build:
|
|
16
|
+
# Skips automatically until a root-level Dockerfile exists, so this template
|
|
17
|
+
# stays green on repos that don't build a container yet. When the build job
|
|
18
|
+
# skips, the dependent deploy job skips too (neither fails).
|
|
19
|
+
# NOTE: update the guard path if your Dockerfile lives elsewhere,
|
|
20
|
+
# e.g. hashFiles('backend/Dockerfile.prod') for a multi-image repo.
|
|
21
|
+
if: ${{ hashFiles('Dockerfile') != '' }}
|
|
22
|
+
runs-on: ubuntu-latest
|
|
23
|
+
permissions:
|
|
24
|
+
contents: read
|
|
25
|
+
packages: write
|
|
26
|
+
|
|
27
|
+
steps:
|
|
28
|
+
- uses: actions/checkout@v4
|
|
29
|
+
|
|
30
|
+
- uses: docker/setup-buildx-action@v3
|
|
31
|
+
|
|
32
|
+
- name: Get version
|
|
33
|
+
id: version
|
|
34
|
+
run: |
|
|
35
|
+
if [ -f package.json ]; then
|
|
36
|
+
echo "VERSION=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
|
|
37
|
+
else
|
|
38
|
+
echo "VERSION=${GITHUB_SHA::8}" >> $GITHUB_OUTPUT
|
|
39
|
+
fi
|
|
40
|
+
|
|
41
|
+
- uses: docker/login-action@v3
|
|
42
|
+
with:
|
|
43
|
+
registry: ${{ env.REGISTRY }}
|
|
44
|
+
username: ${{ github.actor }}
|
|
45
|
+
password: ${{ secrets.GITHUB_TOKEN }}
|
|
46
|
+
|
|
47
|
+
# TODO: Adjust context and dockerfile paths for your project.
|
|
48
|
+
# For multi-image repos, convert this to a matrix strategy.
|
|
49
|
+
- uses: docker/build-push-action@v6
|
|
50
|
+
with:
|
|
51
|
+
context: .
|
|
52
|
+
file: ./Dockerfile
|
|
53
|
+
push: true
|
|
54
|
+
tags: |
|
|
55
|
+
${{ env.REGISTRY }}/${{ env.OWNER }}/${{ env.IMAGE }}:latest
|
|
56
|
+
${{ env.REGISTRY }}/${{ env.OWNER }}/${{ env.IMAGE }}:${{ steps.version.outputs.VERSION }}
|
|
57
|
+
cache-from: type=gha
|
|
58
|
+
cache-to: type=gha,mode=max
|
|
59
|
+
|
|
60
|
+
deploy:
|
|
61
|
+
needs: build
|
|
62
|
+
# TODO: Configure your runner. Choose one:
|
|
63
|
+
# Option A — Self-hosted runner on deploy server (see lib/scripts/setup-runner.sh):
|
|
64
|
+
# runs-on: [self-hosted, <your-label>]
|
|
65
|
+
# Option B — GitHub-hosted runner + SSH (add SSH_HOST, SSH_USER, SSH_KEY,
|
|
66
|
+
# DEPLOY_PATH as repository secrets, then replace the deploy step below)
|
|
67
|
+
runs-on: ubuntu-latest
|
|
68
|
+
steps:
|
|
69
|
+
# TODO: Replace with your deploy mechanism.
|
|
70
|
+
# Option A (self-hosted runner already on deploy server):
|
|
71
|
+
# - name: Pull and restart
|
|
72
|
+
# run: |
|
|
73
|
+
# cd /opt/your-app
|
|
74
|
+
# docker compose pull
|
|
75
|
+
# docker compose up -d --wait
|
|
76
|
+
#
|
|
77
|
+
# Option B (GitHub-hosted runner + SSH):
|
|
78
|
+
# - uses: appleboy/ssh-action@v1
|
|
79
|
+
# with:
|
|
80
|
+
# host: ${{ secrets.SSH_HOST }}
|
|
81
|
+
# username: ${{ secrets.SSH_USER }}
|
|
82
|
+
# key: ${{ secrets.SSH_KEY }}
|
|
83
|
+
# script: |
|
|
84
|
+
# cd ${{ secrets.DEPLOY_PATH }}
|
|
85
|
+
# docker compose pull
|
|
86
|
+
# docker compose up -d --wait
|
|
87
|
+
- name: Deploy
|
|
88
|
+
run: echo "TODO: Configure deploy step — see comments above."
|
|
@@ -0,0 +1,24 @@
|
|
|
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
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
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
|
+
# ]
|
package/README.md
ADDED
|
@@ -0,0 +1,472 @@
|
|
|
1
|
+
# @codewizard-dt/bootstrap
|
|
2
|
+
|
|
3
|
+
Bootstrap Claude Code projects with an LLM Wiki, reusable skills, enforcement hooks, MCP setup, and project scaffolding from one npm CLI.
|
|
4
|
+
|
|
5
|
+
**Repository:** https://github.com/codewizard-dt/bootstrap-claude
|
|
6
|
+
|
|
7
|
+
## Description
|
|
8
|
+
|
|
9
|
+
`@codewizard-dt/bootstrap` is an npm-distributed setup toolkit for Claude Code users who repeatedly configure the same agent workflow in new repositories. It installs Model Context Protocol servers, syncs a global skill library, copies hook scripts, scaffolds an LLM Wiki, assembles a project-specific MCP tools guide, and provides explicit commands for CI/CD and strict type-checking setup.
|
|
10
|
+
|
|
11
|
+
The project exists to move AI-agent state out of chat history and into structured, versioned markdown. Requirements, decisions, tasks, UAT specs, bug reports, roadmaps, source summaries, and operating logs all live in a predictable wiki layout, so future Claude Code sessions and subagents can resume work from file-system state instead of relying on prior conversation context.
|
|
12
|
+
|
|
13
|
+
The package is aimed at developers and teams using Claude Code as a daily engineering assistant. It provides a reusable operating system for AI-assisted software work: durable knowledge, lifecycle-managed work artifacts, slash-command skills, LSP-first code navigation rules, and safety hooks that keep agent behavior consistent across projects.
|
|
14
|
+
|
|
15
|
+
## Architecture
|
|
16
|
+
|
|
17
|
+
### Overview
|
|
18
|
+
|
|
19
|
+
`@codewizard-dt/bootstrap` is a CLI-plus-template package, not a long-running service. The Node.js CLI in `bin/cli.js` dispatches commands to Bash orchestration scripts, and those scripts install global assets, scaffold project-local files, register MCP servers, and invoke the Claude Code CLI for context-sensitive setup. Most state is written into the target project as markdown, JSON, YAML, and shell-generated scaffolding; the package itself remains stateless between invocations.
|
|
20
|
+
|
|
21
|
+
At a glance, the package entry point selects a script, scripts copy or generate assets, assets become global Claude Code skills/hooks or project-local wiki files, and Claude Code plus MCP servers provide the runtime behavior in the consumer project.
|
|
22
|
+
|
|
23
|
+
### Components
|
|
24
|
+
|
|
25
|
+
#### CLI Entry Point
|
|
26
|
+
|
|
27
|
+
- **Responsibility:** Routes `bootstrap <command>` and `npx @codewizard-dt/bootstrap <command>` invocations to the appropriate setup script.
|
|
28
|
+
- **Tech:** Node.js CommonJS, `child_process.execFileSync`
|
|
29
|
+
- **Inputs:** Commands such as `setup`, `update`, `install`, `deploy`, `migrate`, `typechecks`, and `dashboard`, plus optional extra arguments for deploy, migration, and dashboard (port override) flows.
|
|
30
|
+
- **Outputs:** Executes the selected script with inherited stdio and propagates the script exit status.
|
|
31
|
+
- **Depends on:** Setup Scripts
|
|
32
|
+
|
|
33
|
+
#### Setup Scripts
|
|
34
|
+
|
|
35
|
+
- **Responsibility:** Coordinate project setup, updates, global installs, explicit deployment scaffolding, Serena bootstrapping, wiki migration, and strict type-checking setup.
|
|
36
|
+
- **Tech:** Bash, `rsync`, `find`, `grep`, `claude` CLI, npm-executed shell scripts
|
|
37
|
+
- **Inputs:** Target project path, interactive prompts, CLI flags such as `--dry-run`, API keys supplied by environment variables or stdin, and optional user context for deploy/typecheck setup.
|
|
38
|
+
- **Outputs:** Global hooks and skills, MCP registrations, project-local `wiki/`, `raw/`, `.docs/guides/`, `.mcp.json`, `.serena/project.yml`, and optional deployment or type-check configuration when those explicit commands are run.
|
|
39
|
+
- **Depends on:** CLI Entry Point, Skills Library, Hooks Library, Wiki Scaffold Templates, Prompt Templates, Guide Stubs, Claude Code CLI, MCP servers
|
|
40
|
+
|
|
41
|
+
#### MCP Installer
|
|
42
|
+
|
|
43
|
+
- **Responsibility:** Registers Serena, Brave Search, Context7, and Playwright MCP servers with the correct user or project scope.
|
|
44
|
+
- **Tech:** Bash, `claude mcp add`, `uvx`, `npx`
|
|
45
|
+
- **Inputs:** `--interactive`, `--project-dir`, `BRAVE_API_KEY`, optional `CONTEXT7_API_KEY`, and scope choices from interactive prompts.
|
|
46
|
+
- **Outputs:** User-scope MCP registrations for shared tools and project-scope `.mcp.json` registration for Serena when selected.
|
|
47
|
+
- **Depends on:** Claude Code CLI, uv/uvx, npm package execution
|
|
48
|
+
|
|
49
|
+
#### Skills Library
|
|
50
|
+
|
|
51
|
+
- **Responsibility:** Provides reusable Claude Code skills for requirements, decisions, tasks, UAT, bugs, roadmaps, research, docs, linting, evals, security audits, flashcards, demos, and other agent workflows.
|
|
52
|
+
- **Tech:** Markdown `SKILL.md` files in `lib/skills/`
|
|
53
|
+
- **Inputs:** User-invoked skill names in Claude Code sessions, file paths, task descriptions, requirements, and project context.
|
|
54
|
+
- **Outputs:** Structured agent behavior, wiki work items, generated reports, UAT specs, documentation updates, and guided workflow transitions.
|
|
55
|
+
- **Depends on:** Target project files, MCP guide rules, installed MCP servers where applicable
|
|
56
|
+
|
|
57
|
+
#### Hooks Library
|
|
58
|
+
|
|
59
|
+
- **Responsibility:** Enforces safety and Serena-first code navigation policies across Claude Code sessions, including sessions running with permissive tool modes.
|
|
60
|
+
- **Tech:** Node.js hook scripts in `lib/hooks/`, shared helper modules in `lib/hooks/lib/`
|
|
61
|
+
- **Inputs:** Claude Code PreToolUse, PostToolUse, and SessionStart hook payloads for tools such as Read, Write, Edit, Bash, Grep, Glob, and Agent.
|
|
62
|
+
- **Outputs:** Pass-through decisions, block messages, Serena-equivalent suggestions, and navigation state files under `~/.claude/state/`.
|
|
63
|
+
- **Depends on:** Claude Code hook registration, `.serena/project.yml`, global `~/.claude/hooks/` installation
|
|
64
|
+
|
|
65
|
+
#### Wiki Scaffold Templates
|
|
66
|
+
|
|
67
|
+
- **Responsibility:** Defines the LLM Wiki directory structure, conventions, lifecycle specs, indexes, archive folders, and Claude guidance installed into target projects.
|
|
68
|
+
- **Tech:** Markdown templates under `lib/scripts/templates/wiki/`, `CLAUDE.md` snippets, `.gitkeep` files
|
|
69
|
+
- **Inputs:** Target project path and `sync-wiki-scaffold.sh` copy policy.
|
|
70
|
+
- **Outputs:** `raw/`, `wiki/knowledge/`, `wiki/work/`, lifecycle files, family indexes, archive directories, `wiki/conventions.md`, `wiki/log.md`, and target-project `CLAUDE.md` additions.
|
|
71
|
+
- **Depends on:** Setup Scripts
|
|
72
|
+
|
|
73
|
+
#### Guide Stubs
|
|
74
|
+
|
|
75
|
+
- **Responsibility:** Builds `.docs/guides/mcp-tools.md` from only the MCP sections that apply to the target project.
|
|
76
|
+
- **Tech:** Markdown fragments in `lib/scripts/templates/guides/stubs/`, Bash assembly in `build-mcp-guide.sh`
|
|
77
|
+
- **Inputs:** Target project path and installed MCP server names.
|
|
78
|
+
- **Outputs:** A tailored MCP tools guide in the target project's `.docs/guides/` directory.
|
|
79
|
+
- **Depends on:** MCP Installer, Setup Scripts
|
|
80
|
+
|
|
81
|
+
#### Prompt Templates
|
|
82
|
+
|
|
83
|
+
- **Responsibility:** Provide Claude Code with structured instructions for CI/CD setup, wiki migration, Serena configuration, and strict type-checking setup when static templates are too brittle.
|
|
84
|
+
- **Tech:** Markdown prompt files in `lib/prompts/`
|
|
85
|
+
- **Inputs:** Target project context, raw guide content, script interpolation, and optional user-provided deployment/typecheck details.
|
|
86
|
+
- **Outputs:** Claude-generated project configuration, workflow files, migrated wiki artifacts, and type-check tooling.
|
|
87
|
+
- **Depends on:** Claude Code CLI, raw guides, Setup Scripts
|
|
88
|
+
|
|
89
|
+
#### GitHub Actions Templates
|
|
90
|
+
|
|
91
|
+
- **Responsibility:** Supplies repository automation for secret scanning and a Docker/GHCR build-push template.
|
|
92
|
+
- **Tech:** GitHub Actions YAML, Gitleaks action, Docker Buildx actions
|
|
93
|
+
- **Inputs:** Pushes and pull requests to `main` for `security.yml`; manual `workflow_dispatch` for `build.yml`; root-level `Dockerfile` for container build execution.
|
|
94
|
+
- **Outputs:** Gitleaks scan results, optional GHCR container images, and a placeholder deploy job that must be customized before production use.
|
|
95
|
+
- **Depends on:** GitHub Actions, `.gitleaks.toml`, GitHub package permissions
|
|
96
|
+
|
|
97
|
+
### Component Interaction
|
|
98
|
+
|
|
99
|
+
```mermaid
|
|
100
|
+
flowchart LR
|
|
101
|
+
subgraph User ["Developer"]
|
|
102
|
+
DEV["Shell<br/>npx @codewizard-dt/bootstrap"]
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
subgraph CLI ["Package CLI"]
|
|
106
|
+
BIN["bin/cli.js<br/>Node.js"]
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
subgraph Scripts ["lib/scripts/"]
|
|
110
|
+
SETUP["setup-project.sh"]
|
|
111
|
+
UPDATE["update-project.sh"]
|
|
112
|
+
INSTALL["install-global.sh"]
|
|
113
|
+
MCPS["install-mcps.sh"]
|
|
114
|
+
WIKI["sync-wiki-scaffold.sh"]
|
|
115
|
+
GUIDE["build-mcp-guide.sh"]
|
|
116
|
+
DEPLOY["setup-deployment.sh"]
|
|
117
|
+
SERENA["bootstrap-serena.sh"]
|
|
118
|
+
end
|
|
119
|
+
|
|
120
|
+
subgraph Assets ["Package Assets"]
|
|
121
|
+
SKILLS["Skills<br/>lib/skills/"]
|
|
122
|
+
HOOKS["Hooks<br/>lib/hooks/"]
|
|
123
|
+
TEMPLATES["Wiki Templates<br/>lib/scripts/templates/wiki/"]
|
|
124
|
+
STUBS["Guide Stubs<br/>lib/scripts/templates/guides/stubs/"]
|
|
125
|
+
PROMPTS["Prompt Templates<br/>lib/prompts/"]
|
|
126
|
+
RAW["Raw Guides<br/>raw/guides/"]
|
|
127
|
+
end
|
|
128
|
+
|
|
129
|
+
subgraph Global ["Global Claude Code State"]
|
|
130
|
+
GSKILLS["~/.claude/skills/"]
|
|
131
|
+
GHOOKS["~/.claude/hooks/"]
|
|
132
|
+
GMCP["User MCPs<br/>Brave, Context7, Playwright"]
|
|
133
|
+
end
|
|
134
|
+
|
|
135
|
+
subgraph Target ["Target Project"]
|
|
136
|
+
WIKI_DIR["wiki/ + raw/"]
|
|
137
|
+
DOCS[".docs/guides/mcp-tools.md"]
|
|
138
|
+
MCP_JSON[".mcp.json<br/>Serena"]
|
|
139
|
+
SERENA_CFG[".serena/project.yml"]
|
|
140
|
+
WORKFLOWS[".github/workflows/"]
|
|
141
|
+
end
|
|
142
|
+
|
|
143
|
+
subgraph External ["External Tools"]
|
|
144
|
+
CLAUDE["Claude Code CLI"]
|
|
145
|
+
UVX["uvx<br/>Serena"]
|
|
146
|
+
NPX["npx<br/>MCP packages"]
|
|
147
|
+
GHA["GitHub Actions"]
|
|
148
|
+
NPM["npm Registry"]
|
|
149
|
+
end
|
|
150
|
+
|
|
151
|
+
DEV -->|CLI args| BIN
|
|
152
|
+
BIN -->|execFileSync| SETUP
|
|
153
|
+
BIN -->|execFileSync| UPDATE
|
|
154
|
+
BIN -->|execFileSync| INSTALL
|
|
155
|
+
BIN -->|execFileSync| DEPLOY
|
|
156
|
+
SETUP -->|runs| MCPS
|
|
157
|
+
SETUP -->|runs| INSTALL
|
|
158
|
+
SETUP -->|runs| WIKI
|
|
159
|
+
SETUP -->|runs| GUIDE
|
|
160
|
+
SETUP -->|runs| SERENA
|
|
161
|
+
INSTALL -->|rsync| SKILLS
|
|
162
|
+
INSTALL -->|rsync| HOOKS
|
|
163
|
+
SKILLS -->|copy| GSKILLS
|
|
164
|
+
HOOKS -->|copy| GHOOKS
|
|
165
|
+
MCPS -->|claude mcp add| GMCP
|
|
166
|
+
MCPS -->|project scope| MCP_JSON
|
|
167
|
+
MCPS -->|launches| UVX
|
|
168
|
+
MCPS -->|launches| NPX
|
|
169
|
+
WIKI -->|copy-once + refresh| TEMPLATES
|
|
170
|
+
WIKI -->|writes| WIKI_DIR
|
|
171
|
+
GUIDE -->|assemble selected sections| STUBS
|
|
172
|
+
GUIDE -->|writes| DOCS
|
|
173
|
+
DEPLOY -->|claude -p| PROMPTS
|
|
174
|
+
DEPLOY -->|reads| RAW
|
|
175
|
+
DEPLOY -->|writes| WORKFLOWS
|
|
176
|
+
SERENA -->|claude -p| CLAUDE
|
|
177
|
+
SERENA -->|writes| SERENA_CFG
|
|
178
|
+
WORKFLOWS -->|runs| GHA
|
|
179
|
+
DEV -->|npm publish| NPM
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Data Flow
|
|
183
|
+
|
|
184
|
+
```mermaid
|
|
185
|
+
sequenceDiagram
|
|
186
|
+
participant Dev as Developer
|
|
187
|
+
participant CLI as bin/cli.js
|
|
188
|
+
participant Setup as setup-project.sh
|
|
189
|
+
participant MCP as install-mcps.sh
|
|
190
|
+
participant Global as install-global.sh
|
|
191
|
+
participant Wiki as sync-wiki-scaffold.sh
|
|
192
|
+
participant Guide as build-mcp-guide.sh
|
|
193
|
+
participant Claude as Claude Code CLI
|
|
194
|
+
participant Project as Target Project
|
|
195
|
+
|
|
196
|
+
Dev->>CLI: npx @codewizard-dt/bootstrap setup
|
|
197
|
+
CLI->>Setup: execFileSync(setup-project.sh ".")
|
|
198
|
+
Setup->>MCP: install-mcps.sh --interactive --project-dir <project>
|
|
199
|
+
MCP->>Claude: claude mcp add selected servers
|
|
200
|
+
MCP-->>Project: .mcp.json for Serena when selected
|
|
201
|
+
Setup->>Global: install-global.sh --skip-mcps
|
|
202
|
+
Global-->>Global: rsync skills to ~/.claude/skills/
|
|
203
|
+
Global-->>Global: rsync hooks to ~/.claude/hooks/
|
|
204
|
+
Setup->>Wiki: sync-wiki-scaffold.sh <project>
|
|
205
|
+
Wiki-->>Project: raw/, wiki/, CLAUDE.md snippets, .docs/guides/
|
|
206
|
+
Setup->>Guide: build-mcp-guide.sh <project> <installed-mcps>
|
|
207
|
+
Guide-->>Project: .docs/guides/mcp-tools.md
|
|
208
|
+
Setup->>Claude: bootstrap-serena prompt
|
|
209
|
+
Claude-->>Project: .serena/project.yml
|
|
210
|
+
Setup-->>Dev: setup complete
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
```mermaid
|
|
214
|
+
sequenceDiagram
|
|
215
|
+
participant Dev as Developer
|
|
216
|
+
participant CLI as bin/cli.js
|
|
217
|
+
participant Migrate as migrate-project.sh
|
|
218
|
+
participant Claude as Claude Code CLI
|
|
219
|
+
participant Git as Git
|
|
220
|
+
participant Project as Existing Project
|
|
221
|
+
|
|
222
|
+
Dev->>CLI: npx @codewizard-dt/bootstrap migrate --dry-run
|
|
223
|
+
CLI->>Migrate: execFileSync(migrate-project.sh "." "--dry-run")
|
|
224
|
+
Migrate-->>Dev: legacy .docs inventory
|
|
225
|
+
Dev->>CLI: npx @codewizard-dt/bootstrap migrate
|
|
226
|
+
CLI->>Migrate: execFileSync(migrate-project.sh ".")
|
|
227
|
+
Migrate->>Git: verify clean tree and create wiki-migration branch
|
|
228
|
+
Migrate->>Claude: migration prompt with mapping rules
|
|
229
|
+
Claude->>Project: git mv legacy files, synthesize frontmatter, rewrite links
|
|
230
|
+
Claude-->>Project: wiki/work indexes and log updates
|
|
231
|
+
Migrate-->>Dev: migration branch ready for review
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
### Design Decisions
|
|
235
|
+
|
|
236
|
+
- **CLI dispatch stays thin:** `bin/cli.js` only maps command names to scripts, leaving workflow logic in Bash where filesystem setup and command orchestration are easier to inspect and run directly.
|
|
237
|
+
- **Global skills and hooks, project-local wiki:** Shared agent behavior is installed once under `~/.claude/`, while project knowledge and work state remain versioned inside each repository.
|
|
238
|
+
- **Project-scoped Serena:** Serena is registered against an absolute project path in `.mcp.json`, avoiding cross-project language-server bleed while keeping other MCPs available globally when appropriate.
|
|
239
|
+
- **Copy-once vs. always-refresh templates:** Project-owned files such as indexes and logs are not overwritten, while lifecycle specs, conventions, and guide content can be refreshed from the package.
|
|
240
|
+
- **Hooks enforce behavior where permissions cannot:** PreToolUse and PostToolUse hooks enforce `.env` safety, protected git operations, and Serena-first navigation even when normal allow/deny permissions are bypassed.
|
|
241
|
+
- **Claude-driven scaffolding handles project variance:** Deployment, type-checking, Serena configuration, and wiki migration use prompt templates plus `claude -p` because the right output depends on the consumer project's stack.
|
|
242
|
+
|
|
243
|
+
## Technologies
|
|
244
|
+
|
|
245
|
+
- **Languages and runtimes**
|
|
246
|
+
- Node.js CommonJS for the CLI and hook scripts
|
|
247
|
+
- Bash for installation, synchronization, migration, and setup orchestration
|
|
248
|
+
- Markdown for skills, prompts, wiki templates, raw guides, and project documentation
|
|
249
|
+
- YAML for GitHub Actions workflows and generated Serena/project configuration
|
|
250
|
+
- JSON for `package.json`, `.mcp.json`, hook payloads, and Claude Code settings snippets
|
|
251
|
+
|
|
252
|
+
- **CLI and package distribution**
|
|
253
|
+
- npm package distribution with the scoped package name `@codewizard-dt/bootstrap`
|
|
254
|
+
- `npx` execution for one-command setup
|
|
255
|
+
- `package.json` `bin` mapping to expose the `bootstrap` command
|
|
256
|
+
|
|
257
|
+
- **Automation and scripting**
|
|
258
|
+
- `rsync` for idempotent global asset installation and scaffold synchronization
|
|
259
|
+
- Git for migration preflights, branches, and history-preserving moves
|
|
260
|
+
- Shell utilities used by scripts for path resolution, file detection, and template assembly
|
|
261
|
+
|
|
262
|
+
- **AI and MCP tooling**
|
|
263
|
+
- Claude Code CLI for MCP registration and prompt-driven scaffolding
|
|
264
|
+
- Model Context Protocol (MCP)
|
|
265
|
+
- Serena MCP for LSP-backed code exploration and editing
|
|
266
|
+
- Brave Search MCP for web research
|
|
267
|
+
- Context7 MCP for library documentation lookup
|
|
268
|
+
- Playwright MCP for browser automation and UI inspection
|
|
269
|
+
- uv/uvx for launching Serena from its GitHub source
|
|
270
|
+
|
|
271
|
+
- **Workflow assets**
|
|
272
|
+
- Claude Code skills system using `SKILL.md`
|
|
273
|
+
- Claude Code hooks using PreToolUse, PostToolUse, and SessionStart events
|
|
274
|
+
- LLM Wiki structure with `raw/`, `wiki/knowledge/`, and `wiki/work/`
|
|
275
|
+
- Mermaid diagrams embedded in documentation
|
|
276
|
+
|
|
277
|
+
- **CI/CD and security**
|
|
278
|
+
- GitHub Actions
|
|
279
|
+
- Gitleaks and `.gitleaks.toml`
|
|
280
|
+
- Docker Buildx GitHub Actions template
|
|
281
|
+
- GitHub Container Registry template workflow
|
|
282
|
+
|
|
283
|
+
## Use Cases
|
|
284
|
+
|
|
285
|
+
- **New Claude Code project bootstrap:** Developers can run one command in a repository to install MCP tooling, global skills, global hooks, wiki scaffolding, MCP guides, and Serena configuration, then run deployment scaffolding separately when needed.
|
|
286
|
+
- **Global agent workflow installation:** Users can sync the latest skill and hook library into `~/.claude/` without modifying any project by running the install command.
|
|
287
|
+
- **Legacy documentation migration:** Existing `.docs/`-style projects can be migrated into the current LLM Wiki structure with branch isolation, path mapping, frontmatter synthesis, and link rewrites.
|
|
288
|
+
- **AI-native engineering operations:** Teams can manage requirements, decisions, tasks, UAT, roadmaps, bugs, evals, research, demos, and security audits as durable markdown artifacts that agents can read and update.
|
|
289
|
+
- **Safer code-agent behavior:** Serena-first hooks, `.env` guards, and protected git operation blocks reduce fragile file access patterns and prevent common agent mistakes across normal and permissive sessions.
|
|
290
|
+
|
|
291
|
+
## Skills Demonstrated
|
|
292
|
+
|
|
293
|
+
- **CLI Tool Development (Node.js):** Built an npm-executable CLI with command routing, argument forwarding, inherited stdio, clear usage output, and process exit-code propagation.
|
|
294
|
+
- **Shell Scripting and Idempotent Automation (Bash, rsync):** Implemented repeatable setup scripts with preflight checks, copy-once vs. refresh semantics, interactive and non-interactive modes, and safe global installation behavior.
|
|
295
|
+
- **AI-Native Workflow System Design:** Designed a structured markdown workflow for requirements, decisions, tasks, roadmaps, bugs, UAT, research, evals, and documentation that can be resumed by independent agent sessions.
|
|
296
|
+
- **Knowledge Management Architecture (LLM Wiki):** Modeled project memory as immutable raw sources, timeless knowledge synthesis, and lifecycle-managed work artifacts with conventions, indexes, logs, stable IDs, and typed links.
|
|
297
|
+
- **Model Context Protocol Integration:** Integrated Serena, Brave Search, Context7, and Playwright MCP servers with appropriate scope decisions, API-key handling, and generated MCP usage guidance.
|
|
298
|
+
- **Claude Code Hook Engineering (Node.js):** Built hook scripts that enforce file-safety and LSP-first navigation policies using Claude Code hook payloads, shared helper modules, and persistent navigation state.
|
|
299
|
+
- **Prompt Engineering for Developer Tooling:** Created prompt templates that let Claude Code generate context-sensitive deployment, migration, type-checking, and Serena configuration changes in consumer projects.
|
|
300
|
+
- **CI/CD Pipeline Configuration (GitHub Actions):** Provided security scanning and container build/push workflow templates using Gitleaks, Docker Buildx, GHCR, manual dispatch, and skip guards for repositories without Dockerfiles.
|
|
301
|
+
- **Developer Experience Design:** Organized commands, skills, templates, guides, and troubleshooting paths so repeated Claude Code setup work can be performed from a small set of predictable commands.
|
|
302
|
+
- **Documentation Systems Engineering:** Generated machine-parseable project documentation, skill instructions, lifecycle specs, MCP guides, and runbooks that serve both humans and downstream AI tools.
|
|
303
|
+
|
|
304
|
+
## Deployment
|
|
305
|
+
|
|
306
|
+
### Overview
|
|
307
|
+
|
|
308
|
+
This project deploys as a public npm CLI package. There is no hosted runtime, database, or production server; publishing a new npm version is the release process, while GitHub Actions provides repository security scanning and an optional manual container-build template.
|
|
309
|
+
|
|
310
|
+
### Prerequisites
|
|
311
|
+
|
|
312
|
+
- `node >= 18` for local CLI execution and npm packaging.
|
|
313
|
+
- `npm` with publish access to the `@codewizard-dt` scope.
|
|
314
|
+
- An authenticated npm session via `npm login` or an npm automation token.
|
|
315
|
+
- Git access to the repository at `git@github.com:codewizard-dt/bootstrap-claude.git`.
|
|
316
|
+
- GitHub Actions enabled for repository CI checks.
|
|
317
|
+
- For local smoke tests of setup commands, install Claude Code with `npm install -g @anthropic-ai/claude-code`.
|
|
318
|
+
- For Serena setup smoke tests, install `uv` so `uvx` is available.
|
|
319
|
+
|
|
320
|
+
### Environment Variables
|
|
321
|
+
|
|
322
|
+
No environment variables are required to build or publish this package from a logged-in npm session. The setup scripts and generated workflows reference the following variables and secrets:
|
|
323
|
+
|
|
324
|
+
| Variable | Required | Example | Description |
|
|
325
|
+
|---|---|---|---|
|
|
326
|
+
| `BRAVE_API_KEY` | yes for non-interactive Brave MCP install | `BSA...` | Secret passed to the Brave Search MCP server; prompted interactively if absent. |
|
|
327
|
+
| `CONTEXT7_API_KEY` | optional for Context7 MCP install | `ctx_...` | Optional secret sent as a Context7 MCP HTTP header; Context7 can be installed without it. |
|
|
328
|
+
| `GITHUB_TOKEN` | yes in GitHub Actions | `${{ secrets.GITHUB_TOKEN }}` | GitHub-provided token used by Gitleaks and GHCR login in workflows. |
|
|
329
|
+
| `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` | yes in workflows | `true` | Plain workflow config forcing JavaScript actions to run on Node 24. |
|
|
330
|
+
| `REGISTRY` | yes in `build.yml` | `ghcr.io` | Plain workflow config for the container registry in the template workflow. |
|
|
331
|
+
| `OWNER` | yes in `build.yml` | `${{ github.repository_owner }}` | Plain workflow config used to build GHCR image tags. |
|
|
332
|
+
| `IMAGE` | yes in `build.yml` | `${{ github.event.repository.name }}` | Plain workflow config used to build GHCR image tags. |
|
|
333
|
+
| `CLAUDE_MIGRATION` | optional | `1` | Plain flag recognized by some Serena enforcement hooks to bypass during migration flows. |
|
|
334
|
+
|
|
335
|
+
### Build
|
|
336
|
+
|
|
337
|
+
There is no transpilation or bundling step. The package ships source files directly through the `files` list in `package.json`.
|
|
338
|
+
|
|
339
|
+
```bash
|
|
340
|
+
# Inspect the package contents before publishing
|
|
341
|
+
npm pack --dry-run
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
The publishable surface is `bin/`, `lib/`, `raw/`, `.github/`, and `.gitleaks.toml`.
|
|
345
|
+
|
|
346
|
+
### Run Locally
|
|
347
|
+
|
|
348
|
+
```bash
|
|
349
|
+
# Show CLI usage without making project changes
|
|
350
|
+
node bin/cli.js
|
|
351
|
+
|
|
352
|
+
# Install global MCPs, hooks, and skills
|
|
353
|
+
node bin/cli.js install
|
|
354
|
+
|
|
355
|
+
# Run setup against the current repository
|
|
356
|
+
node bin/cli.js setup
|
|
357
|
+
|
|
358
|
+
# Launch the live wiki/work dashboard for the current repository (Ctrl-C to stop)
|
|
359
|
+
# Serves on http://localhost:4317 by default; pass a port to override
|
|
360
|
+
node bin/cli.js dashboard
|
|
361
|
+
node bin/cli.js dashboard 4400
|
|
362
|
+
|
|
363
|
+
# Preview deployment-scaffold detection for the current repository
|
|
364
|
+
node lib/scripts/setup-deployment.sh --dry-run .
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
The setup command writes to the current project and to `~/.claude/`, so run it from a disposable test repository when validating a release candidate.
|
|
368
|
+
|
|
369
|
+
### Deploy
|
|
370
|
+
|
|
371
|
+
1. Confirm the working tree contains only the intended release changes.
|
|
372
|
+
|
|
373
|
+
```bash
|
|
374
|
+
git status --short
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
2. Preview the package contents.
|
|
378
|
+
|
|
379
|
+
```bash
|
|
380
|
+
npm pack --dry-run
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
3. Bump the npm version.
|
|
384
|
+
|
|
385
|
+
```bash
|
|
386
|
+
npm version patch
|
|
387
|
+
# or: npm version minor
|
|
388
|
+
# or: npm version major
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
4. Publish the package.
|
|
392
|
+
|
|
393
|
+
```bash
|
|
394
|
+
npm publish --access public
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
5. Verify the published version.
|
|
398
|
+
|
|
399
|
+
```bash
|
|
400
|
+
npm view @codewizard-dt/bootstrap version
|
|
401
|
+
npx @codewizard-dt/bootstrap@latest
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
CI/CD details:
|
|
405
|
+
|
|
406
|
+
- `.github/workflows/security.yml` runs Gitleaks on pushes and pull requests targeting `main`.
|
|
407
|
+
- `.github/workflows/build.yml` is manual-only via `workflow_dispatch`; its build job skips unless a root-level `Dockerfile` exists, and its deploy job is a placeholder.
|
|
408
|
+
- No workflow currently publishes the npm package automatically; npm release is manual.
|
|
409
|
+
|
|
410
|
+
### Data & Migrations
|
|
411
|
+
|
|
412
|
+
This package has no database, schema migrations, object storage, queues, or runtime persistence. Data migration support in this repo refers to consumer-project documentation migration through `npx @codewizard-dt/bootstrap migrate`, which creates a reviewable `wiki-migration` branch and moves legacy `.docs/` artifacts into the LLM Wiki structure.
|
|
413
|
+
|
|
414
|
+
### Health Checks & Smoke Tests
|
|
415
|
+
|
|
416
|
+
There is no HTTP health endpoint because this is a CLI package. Use command-level smoke tests:
|
|
417
|
+
|
|
418
|
+
```bash
|
|
419
|
+
# Local CLI usage should print command help and exit nonzero
|
|
420
|
+
node bin/cli.js
|
|
421
|
+
|
|
422
|
+
# Package metadata should resolve from npm after publish
|
|
423
|
+
npm view @codewizard-dt/bootstrap version
|
|
424
|
+
|
|
425
|
+
# The latest package should execute and print usage without a command
|
|
426
|
+
npx @codewizard-dt/bootstrap@latest
|
|
427
|
+
|
|
428
|
+
# Security workflow should pass in GitHub Actions
|
|
429
|
+
gh run list --workflow security.yml --limit 5
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
For end-to-end validation, run `npx @codewizard-dt/bootstrap@latest setup` inside a disposable repository and confirm `wiki/`, `raw/`, `.docs/guides/`, and the selected MCP configuration files are created.
|
|
433
|
+
|
|
434
|
+
### Rollback
|
|
435
|
+
|
|
436
|
+
If a release is bad, prefer deprecating the broken npm version and publishing a fixed version:
|
|
437
|
+
|
|
438
|
+
```bash
|
|
439
|
+
npm deprecate @codewizard-dt/bootstrap@<bad-version> "Contains a release issue; upgrade to <fixed-version>."
|
|
440
|
+
npm version patch
|
|
441
|
+
npm publish --access public
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
If the package version qualifies for npm unpublish rules and removal is necessary:
|
|
445
|
+
|
|
446
|
+
```bash
|
|
447
|
+
npm unpublish @codewizard-dt/bootstrap@<bad-version>
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
For source rollback, revert the release commit and publish a new patch version rather than rewriting repository history.
|
|
451
|
+
|
|
452
|
+
### Observability
|
|
453
|
+
|
|
454
|
+
There is no runtime telemetry, metrics backend, dashboard, or alerting because the project is a CLI package. Operational signals come from GitHub Actions logs, npm package metadata, npm install/publish output, and user-reported command failures.
|
|
455
|
+
|
|
456
|
+
Useful first places to inspect:
|
|
457
|
+
|
|
458
|
+
- GitHub Actions security workflow runs in `.github/workflows/security.yml`.
|
|
459
|
+
- Manual build template runs in `.github/workflows/build.yml`.
|
|
460
|
+
- npm package metadata from `npm view @codewizard-dt/bootstrap`.
|
|
461
|
+
- Local command traces from the setup scripts' stdout/stderr.
|
|
462
|
+
|
|
463
|
+
### Troubleshooting
|
|
464
|
+
|
|
465
|
+
- **`command not found: bootstrap`:** The package binary is not on PATH; run through `npx @codewizard-dt/bootstrap <command>` or use `node bin/cli.js <command>` locally.
|
|
466
|
+
- **`claude: command not found`:** Claude Code is missing; install it with `npm install -g @anthropic-ai/claude-code` before running setup, deploy scaffolding, migration, or typecheck setup.
|
|
467
|
+
- **`uv: command not found`:** Serena setup cannot launch; install uv so `uvx` is available, then rerun setup.
|
|
468
|
+
- **Brave MCP install prompts for an API key:** Set `BRAVE_API_KEY` before non-interactive installs or enter it when prompted by `install-mcps.sh`.
|
|
469
|
+
- **Context7 installs without authenticated access:** Set `CONTEXT7_API_KEY` if authenticated Context7 access is required; otherwise the script can register Context7 without the header.
|
|
470
|
+
- **Hooks copy but do not run:** `install-global.sh` copies scripts to `~/.claude/hooks/`, but hook registration in `~/.claude/settings.json` is a separate manual step documented in `lib/hooks/README.md`.
|
|
471
|
+
- **Manual build workflow skips:** `.github/workflows/build.yml` intentionally skips the build job unless a root-level `Dockerfile` exists.
|
|
472
|
+
- **npm package points at unexpected repository metadata:** Check `package.json` `repository`, `homepage`, and `bugs` fields before publishing; they are independent of the local git remote.
|
package/bin/cli.js
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
const { execFileSync } = require('child_process');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
|
|
6
|
+
const command = process.argv[2];
|
|
7
|
+
const extraArgs = process.argv.slice(3);
|
|
8
|
+
|
|
9
|
+
const SCRIPTS = {
|
|
10
|
+
setup: { script: 'setup-project.sh', args: ['.'] },
|
|
11
|
+
update: { script: 'update-project.sh', args: ['.'] },
|
|
12
|
+
install: { script: 'install-global.sh', args: [] },
|
|
13
|
+
deploy: { script: 'setup-deployment.sh', args: ['.', ...extraArgs] },
|
|
14
|
+
deployment: { script: 'setup-deployment.sh', args: ['.', ...extraArgs] },
|
|
15
|
+
migrate: { script: 'migrate-project.sh', args: ['.', ...extraArgs] },
|
|
16
|
+
typechecks: { script: 'setup-strict-typechecks.sh', args: extraArgs },
|
|
17
|
+
dashboard: { script: 'wiki-dashboard-server.js', args: ['.', ...extraArgs] },
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
if (!command || !SCRIPTS[command]) {
|
|
21
|
+
console.error('Usage: bootstrap <command>');
|
|
22
|
+
console.error('');
|
|
23
|
+
console.error('Commands:');
|
|
24
|
+
console.error(' setup Set up a new project with Claude Code configurations');
|
|
25
|
+
console.error(' update Sync wiki scaffold and install skills globally');
|
|
26
|
+
console.error(' install Install skills globally into ~/.claude/skills/');
|
|
27
|
+
console.error(' deploy Scaffold CI/CD (.github/ workflows + .gitleaks.toml) into the project');
|
|
28
|
+
console.error(' Optional: pass extra context for the Claude agent as a quoted string');
|
|
29
|
+
console.error(' e.g. bootstrap deploy "backend is on port 8080, use s-2vcpu-4gb droplet"');
|
|
30
|
+
console.error(' migrate Migrate a legacy .docs/ project to the wiki structure (Claude-driven)');
|
|
31
|
+
console.error(' Pass --dry-run to preview; runs on a fresh wiki-migration branch');
|
|
32
|
+
console.error(' typechecks Run strict typecheck setup via Claude (optional: language list)');
|
|
33
|
+
console.error(' e.g. bootstrap typechecks typescript python');
|
|
34
|
+
console.error(' dashboard Launch the live wiki/work dashboard in this project (Ctrl-C to stop)');
|
|
35
|
+
console.error(' Optional: pass a port number, e.g. bootstrap dashboard 4400');
|
|
36
|
+
process.exit(1);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const { script, args } = SCRIPTS[command];
|
|
40
|
+
const scriptPath = path.resolve(__dirname, '..', 'lib', 'scripts', script);
|
|
41
|
+
const scriptArgs = args;
|
|
42
|
+
|
|
43
|
+
try {
|
|
44
|
+
execFileSync(scriptPath, scriptArgs, { stdio: 'inherit' });
|
|
45
|
+
} catch (err) {
|
|
46
|
+
process.exit(err.status || 1);
|
|
47
|
+
}
|