Skip to content

Commit 44459a3

Browse files
SebTardifSebTardif
committed
Add community health files, AGENTS.md, and security CI
Community health (Closes #15): - CONTRIBUTING.md with dev setup, test commands, PR guidelines - SECURITY.md with private vulnerability reporting guidance - CODE_OF_CONDUCT.md (Contributor Covenant 2.1) - .github/CODEOWNERS - .github/ISSUE_TEMPLATE/ (bug report, feature request, config) - .github/PULL_REQUEST_TEMPLATE.md Agent instructions (Closes #16): - AGENTS.md with project overview, dev commands, architecture, conventions - CLAUDE.md, GEMINI.md, .github/copilot-instructions.md pointers Security scanning (Closes #17): - .github/workflows/security.yml with Trivy + gitleaks - Weekly cron schedule (Monday 6am UTC) - step-security/harden-runner on all jobs - Fix ci.yml concurrency to protect main from cancellation Signed-off-by: Sebastien Tardif <sebtardif@ncf.ca>
1 parent 9267429 commit 44459a3

14 files changed

Lines changed: 469 additions & 1 deletion

‎.github/CODEOWNERS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* @SebTardif

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
name: Bug report
2+
description: Report a bug in the Patchloom VS Code extension
3+
title: "bug: "
4+
labels:
5+
- bug
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
Thanks for the report.
11+
12+
Include the output of `Patchloom: Show Status` if relevant.
13+
- type: textarea
14+
id: summary
15+
attributes:
16+
label: Summary
17+
description: What is going wrong?
18+
placeholder: A short description of the bug.
19+
validations:
20+
required: true
21+
- type: textarea
22+
id: steps
23+
attributes:
24+
label: Reproduction steps
25+
description: List the smallest sequence of steps that reproduces the issue.
26+
placeholder: |
27+
1. Open a workspace
28+
2. Run command `...`
29+
3. Observe `...`
30+
validations:
31+
required: true
32+
- type: textarea
33+
id: expected
34+
attributes:
35+
label: Expected behavior
36+
placeholder: What should have happened?
37+
validations:
38+
required: true
39+
- type: textarea
40+
id: actual
41+
attributes:
42+
label: Actual behavior
43+
placeholder: What happened instead?
44+
validations:
45+
required: true
46+
- type: textarea
47+
id: logs
48+
attributes:
49+
label: Relevant output
50+
description: Paste error messages or Patchloom Show Status output.
51+
render: shell
52+
- type: input
53+
id: vscode-version
54+
attributes:
55+
label: VS Code version
56+
placeholder: "1.90.0"
57+
validations:
58+
required: false
59+
- type: input
60+
id: patchloom-version
61+
attributes:
62+
label: Patchloom CLI version
63+
placeholder: "0.1.0"
64+
validations:
65+
required: false
66+
- type: input
67+
id: environment
68+
attributes:
69+
label: Environment
70+
placeholder: macOS 15, Windows 11, WSL, Remote SSH, etc.
71+
validations:
72+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Patchloom CLI issues
4+
url: https://github.com/patchloom/patchloom/issues
5+
about: For bugs in the CLI itself (not the extension), file an issue on the main repo.
6+
- name: Security reporting policy
7+
url: https://github.com/patchloom/patchloom-vscode/blob/main/SECURITY.md
8+
about: Do not post security vulnerabilities publicly. Read the private reporting policy first.

‎.github/ISSUE_TEMPLATE/feature-request.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Feature request
2+
description: Propose a new extension capability or improvement
3+
title: "feat: "
4+
labels:
5+
- enhancement
6+
body:
7+
- type: textarea
8+
id: problem
9+
attributes:
10+
label: Problem to solve
11+
description: What workflow or limitation are you trying to address?
12+
placeholder: Describe the user problem first.
13+
validations:
14+
required: true
15+
- type: textarea
16+
id: proposal
17+
attributes:
18+
label: Proposed solution
19+
description: What change would you like to see?
20+
placeholder: Describe the command, behavior, or UI you want.
21+
validations:
22+
required: true
23+
- type: textarea
24+
id: alternatives
25+
attributes:
26+
label: Alternatives considered
27+
placeholder: Other approaches or why current behavior is not enough.
28+
validations:
29+
required: false
30+
- type: checkboxes
31+
id: contribution
32+
attributes:
33+
label: Contribution intent
34+
options:
35+
- label: I am willing to help implement this after scope is aligned
36+
required: false

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## Summary
2+
3+
Describe the change in a few sentences.
4+
5+
## Why
6+
7+
Explain why this change is needed.
8+
9+
## Verification
10+
11+
List the checks you ran.
12+
13+
-
14+
15+
## Checklist
16+
17+
- [ ] All commits in this pull request are signed off with `git commit -s`
18+
- [ ] I ran `npm run check` and it passes
19+
- [ ] I updated docs if user-facing behavior changed
20+
- [ ] I am contributing this work under the repository license (MIT)

‎.github/copilot-instructions.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Copilot
2+
3+
See [AGENTS.md](../../AGENTS.md) for project conventions, dev commands, and coding standards.

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ on:
66

77
concurrency:
88
group: ci-${{ github.workflow }}-${{ github.ref }}
9-
cancel-in-progress: true
9+
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
1010

1111
jobs:
1212
build:

‎.github/workflows/security.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: Security
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
push:
7+
branches: [main]
8+
schedule:
9+
- cron: "0 6 * * 1" # Monday 6am UTC
10+
workflow_dispatch:
11+
12+
concurrency:
13+
group: security-${{ github.ref }}
14+
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
15+
16+
permissions:
17+
contents: read
18+
19+
jobs:
20+
trivy:
21+
name: Trivy
22+
runs-on:
23+
- self-hosted
24+
- macOS
25+
- ARM64
26+
- patchloom-vscode
27+
timeout-minutes: 10
28+
steps:
29+
- name: Harden Runner
30+
uses: step-security/harden-runner@v2
31+
with:
32+
egress-policy: audit
33+
- uses: actions/checkout@v4
34+
- name: Install Trivy
35+
run: |
36+
if ! command -v trivy &>/dev/null; then
37+
brew install trivy
38+
fi
39+
- name: Trivy filesystem scan
40+
run: trivy fs --scanners vuln --severity HIGH,CRITICAL --exit-code 1 --ignore-unfixed .
41+
42+
gitleaks:
43+
name: Gitleaks
44+
runs-on:
45+
- self-hosted
46+
- macOS
47+
- ARM64
48+
- patchloom-vscode
49+
timeout-minutes: 5
50+
steps:
51+
- name: Harden Runner
52+
uses: step-security/harden-runner@v2
53+
with:
54+
egress-policy: audit
55+
- uses: actions/checkout@v4
56+
with:
57+
fetch-depth: 0
58+
- name: Install gitleaks
59+
env:
60+
GITLEAKS_VERSION: "8.30.1"
61+
run: |
62+
if command -v gitleaks &>/dev/null; then
63+
echo "gitleaks already installed"
64+
exit 0
65+
fi
66+
archive="${RUNNER_TEMP}/gitleaks.tar.gz"
67+
bindir="${RUNNER_TEMP}/gitleaks-bin"
68+
mkdir -p "$bindir"
69+
case "$(uname -s)-$(uname -m)" in
70+
Linux-x86_64) platform="linux_x64" ;;
71+
Linux-aarch64) platform="linux_arm64" ;;
72+
Darwin-x86_64) platform="darwin_x64" ;;
73+
Darwin-arm64) platform="darwin_arm64" ;;
74+
*) echo "Unsupported platform: $(uname -s)-$(uname -m)" >&2; exit 1 ;;
75+
esac
76+
curl --retry 5 --retry-all-errors --retry-delay 2 -sSfL \
77+
-o "$archive" \
78+
"https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${platform}.tar.gz"
79+
tar -xzf "$archive" -C "$bindir" gitleaks
80+
printf '%s\n' "$bindir" >> "$GITHUB_PATH"
81+
- run: gitleaks detect --source . --exit-code 1

‎AGENTS.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# AGENTS.md
2+
3+
## Project overview
4+
5+
Patchloom for VS Code is the official VS Code extension for [Patchloom](https://github.com/patchloom/patchloom). It detects the Patchloom CLI, generates agent rules, configures MCP servers, and provides quick actions from the command palette. The extension is a thin wrapper around the `patchloom` binary with dependency-injected helpers for testability.
6+
7+
## Dev commands
8+
9+
| Command | What it does |
10+
|---------|-------------|
11+
| `npm run compile` | Compile extension source (`tsc -p ./`) |
12+
| `npm run compile-tests` | Compile test source (`tsc -p ./tsconfig.test.json`) |
13+
| `npm run watch` | Watch mode for extension source |
14+
| `npm run test:unit` | Run unit tests (`node --test ./out-test/test/unit/*.test.js`) |
15+
| `npm run test:extension` | Run VS Code extension integration tests |
16+
| `npm run test` | Compile + compile-tests + unit tests + extension tests |
17+
| `npm run package` | Package the `.vsix` using `@vscode/vsce` |
18+
| `npm run check` | Full CI gate: test + package |
19+
20+
Always run `npm run check` before committing.
21+
22+
## Project structure
23+
24+
```
25+
src/
26+
extension.ts Thin entrypoint: registers commands, status bar, config listeners
27+
binary/patchloom.ts Binary discovery, version parsing, compatibility assessment
28+
commands/
29+
configureMcp.ts Configure MCP command: multi-target MCP config injection
30+
initializeProject.ts Initialize Project command: generate/diff AGENTS.md
31+
quickActions.ts Quick Action command: replace, tidy, doc set with diff preview
32+
setupWorkspace.ts Setup Workspace command: guided readiness walkthrough
33+
showStatus.ts Show Status command: diagnostics display
34+
install/managed.ts Managed install safety: checksum, staging, promotion, rollback, persistence
35+
mcp/config.ts MCP config file operations: inspect, configure, resolve targets
36+
status/statusBar.ts Status bar item: create, refresh, dispose
37+
workspace/readiness.ts Workspace readiness: environment detection, folder selection
38+
test/
39+
unit/ Unit tests (node:test, dependency-injected, no VS Code API)
40+
binary.test.ts Binary discovery, managed install, compatibility (32 tests)
41+
binaryDiscovery.test.ts Real executable discovery on PATH (10 tests)
42+
initializeProject.test.ts Status display, agents file classification (14 tests)
43+
managedLifecycle.test.ts Managed install with real file I/O (10 tests)
44+
mcpConfig.test.ts MCP config with real temp directories (9 tests)
45+
quickActions.test.ts Quick action command building (6 tests)
46+
suite/
47+
index.ts VS Code extension integration tests
48+
runExtensionTests.ts Test runner using @vscode/test-electron
49+
```
50+
51+
## Architecture conventions
52+
53+
### Entrypoint
54+
55+
`extension.ts` is thin. It registers commands, sets up the status bar listener, and delegates all logic to submodules.
56+
57+
### Dependency injection
58+
59+
All I/O-dependent functions accept an `inputs` object with injectable callbacks for file reads, writes, shell execution, etc. This keeps unit tests fast and deterministic. Default implementations use real `node:fs/promises` and `node:child_process`.
60+
61+
### Testing
62+
63+
- Unit tests use `node:test` and run without VS Code.
64+
- Extension tests use `@vscode/test-electron` and launch a real VS Code instance.
65+
- Tests compile to `out-test/` via `tsconfig.test.json`.
66+
- Use `tempfile` directories for real I/O tests.
67+
68+
### Binary resolution order
69+
70+
1. `patchloom.path` setting (explicit user config)
71+
2. `PATH` discovery (find executable named `patchloom`)
72+
3. Managed install (global storage directory)
73+
74+
### MCP config targets
75+
76+
| Target | Config file | Key |
77+
|--------|------------|-----|
78+
| VS Code workspace | `.vscode/mcp.json` | `servers` |
79+
| Cursor workspace | `.cursor/mcp.json` | `servers` |
80+
| Windsurf user | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` |
81+
82+
## Coding conventions
83+
84+
- TypeScript strict mode.
85+
- No `any` types without justification.
86+
- Pure helpers with injected I/O for testability.
87+
- Keep `extension.ts` thin. No business logic in the entrypoint.
88+
- `npm run check` is the full gate. Nothing merges unless it passes.
89+
- All commits require a `Signed-off-by` line (DCO). Use `git commit -s`.

‎CLAUDE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Claude Code
2+
3+
See [AGENTS.md](AGENTS.md) for project conventions, dev commands, and coding standards.

0 commit comments

Comments
 (0)