Skip to content

Commit 8587e5a

Browse files
davccavalcantedavccavalcante
committed
chore: initial public 1.0.0
Signed-off-by: davccavalcante <davcavalcante@pm.me>
0 parents  commit 8587e5a

95 files changed

Lines changed: 14637 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.editorconfig‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
insert_final_newline = true
7+
indent_style = space
8+
indent_size = 2
9+
trim_trailing_whitespace = true
10+
11+
[*.md]
12+
trim_trailing_whitespace = false

‎.github/CODEOWNERS‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Code owners for @takk/mcpcustoms.
2+
#
3+
# GitHub uses this file to auto-request reviews on pull requests. The rules
4+
# are evaluated top-to-bottom; later patterns override earlier ones. Today
5+
# the project is single-maintainer (Creator-only); every PR routes to
6+
# @davccavalcante.
7+
8+
# Catch-all (every file)
9+
* @davccavalcante
10+
11+
# Public surface (source, tests, examples)
12+
/src/ @davccavalcante
13+
/tests/ @davccavalcante
14+
/examples/ @davccavalcante
15+
16+
# CI/CD and meta
17+
/.github/ @davccavalcante
18+
/.github/workflows/ @davccavalcante
19+
/.github/RELEASING.md @davccavalcante
20+
/.github/CONTRIBUTING.md @davccavalcante
21+
22+
# Governance documents
23+
/LICENSE @davccavalcante
24+
/NOTICE @davccavalcante
25+
/README.md @davccavalcante
26+
/CHANGELOG.md @davccavalcante
27+
/SPEC.md @davccavalcante
28+
/TASK.md @davccavalcante
29+
/package.json @davccavalcante

‎.github/CONTRIBUTING.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Contributing to @takk/mcpcustoms
2+
3+
Thanks for considering a contribution. This document is the canonical guide for proposing changes to `@takk/mcpcustoms`.
4+
5+
The project is open source under [Apache License 2.0](../LICENSE). The package surface and stability promise are documented in [SPEC.md](../SPEC.md); the live roadmap and deferred work are in [TASK.md](../TASK.md).
6+
7+
---
8+
9+
## 1. Code of conduct
10+
11+
Be respectful, be precise, and assume good faith. The maintainer reads every issue and PR personally; disrespectful, harmful, or manipulative behavior is grounds for removal from the project.
12+
13+
---
14+
15+
## 2. Contributor license
16+
17+
Every contribution is governed by the Apache License 2.0 (the same license the project is published under). Sign off every commit with `git commit -s` (Developer Certificate of Origin):
18+
19+
```bash
20+
git commit -s -m "fix(detectors): tighten the path-traversal pattern"
21+
```
22+
23+
The `-s` flag appends a `Signed-off-by:` trailer that attests you have the right to submit the change under Apache 2.0. PRs without DCO sign-off are not merged.
24+
25+
---
26+
27+
## 3. Local setup
28+
29+
### 3.1 Prerequisites
30+
31+
- **Node 20, 22, or 24.** CI runs the full matrix; pick one for local dev. `.nvmrc` pins the LTS line.
32+
- **pnpm 9 or 10.** The repo uses `pnpm` for install and scripts. `npm` and `yarn` also work but `pnpm-lock.yaml` is the source of truth.
33+
- **git** with `git commit -s` configured (DCO).
34+
35+
### 3.2 Clone and install
36+
37+
```bash
38+
git clone https://github.com/davccavalcante/mcpcustoms.git
39+
cd mcpcustoms
40+
pnpm install
41+
```
42+
43+
### 3.3 Verify locally
44+
45+
```bash
46+
pnpm verify # lint + typecheck + test + build + smoke + publint
47+
# or run individually:
48+
pnpm lint
49+
pnpm typecheck
50+
pnpm test
51+
pnpm test:coverage
52+
pnpm build
53+
pnpm publint
54+
```
55+
56+
Current baseline (verify before opening a PR): **158 tests passing across 19 suites**. Coverage `lines 95.7% / statements 95.3% / functions 98.6% / branches 89.1%`.
57+
58+
---
59+
60+
## 4. Branch and commit conventions
61+
62+
### 4.1 Branch names
63+
64+
- `fix/<short-slug>`: bug fixes
65+
- `feat/<short-slug>`: new optional surface (minor bump)
66+
- `docs/<short-slug>`: README/SPEC/CHANGELOG-only changes
67+
- `chore/<short-slug>`: tooling, deps, CI
68+
- `refactor/<short-slug>`: internal restructuring with no API change
69+
70+
Avoid PRs larger than ~500 LOC; split into smaller logically-coherent PRs.
71+
72+
### 4.2 Commit style
73+
74+
[Conventional Commits](https://www.conventionalcommits.org/) are encouraged but not enforced. What IS enforced:
75+
76+
- **One commit per logical change.** No `WIP` or `fixup` commits in the merged history.
77+
- **Imperative subject up to 70 chars.** Body wrap at 72 cols.
78+
- **DCO sign-off (`git commit -s`).**
79+
- **No commit credits to AI assistants.** This is the Creator's discipline.
80+
81+
### 4.3 What requires a discussion before coding
82+
83+
Open a GitHub Issue first if your change touches:
84+
85+
- New public export (SemVer minor/major impact, see [SPEC.md §5](../SPEC.md#5-stability-promise)).
86+
- New telemetry event kind.
87+
- The on-disk JSON snapshot schema of the file state backend.
88+
- The CLI flags or subcommands.
89+
- The `Detector`, `Policy`, `StateBackend`, or `Signer` interface, or the `Verdict` shape.
90+
91+
For docs-only fixes, typos, or contained internal refactors, skip the issue and open a PR directly.
92+
93+
---
94+
95+
## 5. Pull request workflow
96+
97+
### 5.1 Before opening
98+
99+
- All checks green: `pnpm verify`.
100+
- Coverage thresholds preserved or improved (see `vitest.config.ts`).
101+
- For any change that touches the public API: `SPEC.md` and `README.md` updated.
102+
- For any deprecated surface: `@deprecated` JSDoc + runtime `console.warn` (debounced) + a `### Deprecated` section in the next `CHANGELOG.md` entry.
103+
104+
### 5.2 PR description
105+
106+
Fill the [PULL_REQUEST_TEMPLATE.md](./PULL_REQUEST_TEMPLATE.md) honestly. Empty sections are not acceptable; write "N/A" with a one-line reason if a section truly does not apply.
107+
108+
### 5.3 Review
109+
110+
The maintainer reviews every PR personally. Expect:
111+
112+
- Surgical line-by-line read.
113+
- Question on intent before merge (Creator's discipline: "if you notice any problem, error, or inconsistency, ask before acting").
114+
- Required for governance-touching changes: explicit Creator approval before merge.
115+
116+
### 5.4 After merge
117+
118+
CI publishes nothing on merge to `main`. Publishing is a Creator-triggered, two-step flow via `release.yml` then `npm-publish.yml` (see [RELEASING.md](./RELEASING.md)).
119+
120+
---
121+
122+
## 6. Tests
123+
124+
Add tests for any non-trivial change. Patterns:
125+
126+
- **Vitest** (`tests/**/*.test.ts`). One file per surface area. Inject the clock for time-dependent behavior; detectors are pure functions and need no mocks.
127+
- **Determinism, not network.** Inspection performs no I/O, so tests run fully offline with no fixtures, no real credentials, and no network calls.
128+
- **CLI tests run in-process.** The CLI is exercised by calling `runCli` over an injected `CliIO` (see `tests/cli.test.ts`), never by spawning a `tsx` wrapper, so exit codes and signals are the CLI's own. The distribution smoke (`scripts/smoke-dist.mjs`) spawns the built `dist/cli/index.js` with `node` directly.
129+
130+
Every fix-able bug ships with a regression test that fails pre-fix and passes post-fix.
131+
132+
---
133+
134+
## 7. Security disclosure
135+
136+
Do NOT open a public GitHub Issue for security vulnerabilities. Email `davcavalcante@proton.me` with the prefix `[SECURITY]` and we will coordinate fix + disclosure timeline privately.
137+
138+
---
139+
140+
## 8. Releasing
141+
142+
Releases are maintainer-only. The full runbook lives in [RELEASING.md](./RELEASING.md). Contributors do not tag, do not publish, do not edit historical CHANGELOG entries (those are immutable per Keep a Changelog).
143+
144+
When proposing a change that warrants a release, indicate in your PR description which SemVer bump you believe it triggers (patch / minor / major per [SPEC.md §5.2](../SPEC.md#52-semver-policy)). The maintainer makes the final call.
145+
146+
---
147+
148+
## 9. Communication
149+
150+
- **GitHub Issues** for bug reports + feature requests (see [ISSUE_TEMPLATE/](./ISSUE_TEMPLATE)).
151+
- **GitHub Discussions** (if enabled) for design conversations.
152+
- **Email** `davcavalcante@proton.me` for anything private, sensitive, or trademark/licence-related.
153+
154+
The project's primary language for code, docs, CI, issues, and PRs is **English**. Use English in PR descriptions and code comments.
155+
156+
---
157+
158+
## Contact
159+
160+
**David C Cavalcante**
161+
- Email: [davcavalcante@proton.me](mailto:davcavalcante@proton.me)
162+
- LinkedIn: [linkedin.com/in/hellodav](https://linkedin.com/in/hellodav)
163+
- GitHub: [github.com/davccavalcante](https://github.com/davccavalcante)
164+
- X: [x.com/davccavalcante](https://x.com/davccavalcante)
165+
- Project site: [takk.ag](https://takk.ag)

‎.github/FUNDING.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Optional sponsorship channels for @takk/mcpcustoms.
2+
#
3+
# GitHub renders the "Sponsor" button on the repository page from the entries
4+
# below. All entries are commented out by default; uncomment and fill in the
5+
# matching usernames when channels are provisioned.
6+
#
7+
# See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository
8+
# for the full schema.
9+
10+
# github: davccavalcante # GitHub Sponsors profile (when active)
11+
# patreon: davccavalcante # Patreon username
12+
# open_collective: takk # Open Collective project slug
13+
# ko_fi: davccavalcante # Ko-fi username
14+
# tidelift: npm/@takk%2Fmcpcustoms # Tidelift platform-name/package
15+
# liberapay: davccavalcante # Liberapay username
16+
# issuehunt: davccavalcante # IssueHunt username
17+
# polar: davccavalcante # Polar.sh username
18+
# buy_me_a_coffee: davccavalcante # Buy Me a Coffee username
19+
# thanks_dev: davccavalcante # thanks.dev username
20+
# custom: ["https://takk.ag"] # Custom URLs

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
name: "Bug report"
2+
description: "Report a defect in @takk/mcpcustoms."
3+
title: "[bug] <one-line summary>"
4+
labels: ["bug", "triage"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for filing a bug. Please fill every section honestly, the maintainer reads every issue personally and complete context speeds up triage.
10+
11+
**Security vulnerabilities are NOT bugs filed here.** Email <davcavalcante@proton.me> with prefix `[SECURITY]`.
12+
13+
- type: dropdown
14+
id: surface
15+
attributes:
16+
label: "Affected surface"
17+
description: "Which part of MCPCustoms does the bug occur in?"
18+
options:
19+
- "core / createCustoms (engine)"
20+
- "detectors (parameter / metadata / capability)"
21+
- "policy / verdict / risk score"
22+
- "publisher verification (@takk/mcpcustoms/publisher)"
23+
- "vercel adapter (@takk/mcpcustoms/vercel)"
24+
- "mcp adapter (@takk/mcpcustoms/mcp)"
25+
- "integrations / guard (@takk/mcpcustoms/integrations)"
26+
- "audit trail / state backends (@takk/mcpcustoms/store)"
27+
- "web / edge entry (@takk/mcpcustoms/web | /edge)"
28+
- "CLI (mcpcustoms inspect / verify / keygen / sign)"
29+
- "telemetry / events"
30+
- "types / .d.ts"
31+
- "docs / README / SPEC"
32+
- "CI / workflows"
33+
- "not sure"
34+
validations:
35+
required: true
36+
37+
- type: input
38+
id: version
39+
attributes:
40+
label: "Package version"
41+
description: "Output of `npm view @takk/mcpcustoms version`, or the git SHA if testing local source."
42+
placeholder: "1.0.0"
43+
validations:
44+
required: true
45+
46+
- type: textarea
47+
id: repro
48+
attributes:
49+
label: "Reproduction steps"
50+
description: "Minimal, deterministic steps. Include shell commands, code snippets, env variables. Recreate the bug from a clean clone."
51+
placeholder: |
52+
1. `pnpm add @takk/mcpcustoms`
53+
2. Code snippet:
54+
```ts
55+
import { createCustoms } from '@takk/mcpcustoms';
56+
// ...
57+
```
58+
3. Observe...
59+
render: bash
60+
validations:
61+
required: true
62+
63+
- type: textarea
64+
id: expected
65+
attributes:
66+
label: "Expected behavior"
67+
description: "What did you expect to happen? Cite SPEC.md or README if relevant."
68+
validations:
69+
required: true
70+
71+
- type: textarea
72+
id: actual
73+
attributes:
74+
label: "Actual behavior"
75+
description: "What happened instead? Paste the full verdict, stack traces, error messages, or telemetry events if relevant."
76+
validations:
77+
required: true
78+
79+
- type: textarea
80+
id: console
81+
attributes:
82+
label: "Terminal output"
83+
description: "Paste relevant stderr/stdout here (it will be rendered as a code block)."
84+
render: console
85+
validations:
86+
required: false
87+
88+
- type: input
89+
id: node
90+
attributes:
91+
label: "Node version"
92+
description: "Output of `node -v`. MCPCustoms requires Node >= 20.0.0; CI runs 20, 22, and 24."
93+
placeholder: "v22.0.0"
94+
validations:
95+
required: true
96+
97+
- type: input
98+
id: os
99+
attributes:
100+
label: "Operating system"
101+
description: "e.g. macOS 26 (Apple Silicon), Ubuntu 24.04, Debian 12, Windows 11. Some bugs are platform-specific."
102+
placeholder: "macOS 26 (Apple Silicon)"
103+
validations:
104+
required: true
105+
106+
- type: textarea
107+
id: extra
108+
attributes:
109+
label: "Additional context"
110+
description: "Anything else the maintainer should know: related issues, conjectured root cause, links to upstream issues, etc."
111+
validations:
112+
required: false
113+
114+
- type: checkboxes
115+
id: checklist
116+
attributes:
117+
label: "Pre-submission checklist"
118+
options:
119+
- label: "I read [SPEC.md](https://github.com/davccavalcante/mcpcustoms/blob/main/SPEC.md) and confirmed this is not documented behavior."
120+
required: true
121+
- label: "I searched existing issues and PRs for duplicates."
122+
required: true
123+
- label: "This is NOT a security vulnerability (those go to email per CONTRIBUTING §7)."
124+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: "Security vulnerability"
4+
url: "mailto:davcavalcante@proton.me?subject=%5BSECURITY%5D%20"
5+
about: "Do NOT open a public issue for security vulnerabilities. Email davcavalcante@proton.me with prefix [SECURITY]. We coordinate fix and disclosure privately."
6+
- name: "General discussion / questions"
7+
url: "https://github.com/davccavalcante/mcpcustoms/discussions"
8+
about: "For design conversations, usage questions, or anything that is not a bug report or feature request, use GitHub Discussions."
9+
- name: "Read the spec first"
10+
url: "https://github.com/davccavalcante/mcpcustoms/blob/main/SPEC.md"
11+
about: "Before opening an issue about behavior, read SPEC.md, the binding contract for the public surface, the inspection and verdict semantics, and the SemVer policy."

0 commit comments

Comments
 (0)