@theholocron/skills 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +108 -0
- package/package.json +58 -0
- package/skills/commit-standards/SKILL.md +65 -0
- package/skills/git-safety/SKILL.md +52 -0
- package/skills/holocron-skill-client/SKILL.md +151 -0
- package/skills/holocron-skill-config/SKILL.md +145 -0
- package/skills/holocron-skill-plugin/SKILL.md +85 -0
- package/skills/pr-workflow/SKILL.md +45 -0
- package/skills/security-review/SKILL.md +53 -0
- package/skills-lock.json +29 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) Newton Koumantzelis
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# `@theholocron/skills`
|
|
2
|
+
|
|
3
|
+
<!-- holocron:description -->
|
|
4
|
+
|
|
5
|
+
Shared agent skill registry.
|
|
6
|
+
|
|
7
|
+
<!-- /holocron:description -->
|
|
8
|
+
|
|
9
|
+
Each skill is a directory under `skills/` containing a `SKILL.md` file that Claude Code (and compatible
|
|
10
|
+
agents) can load as a slash command.
|
|
11
|
+
|
|
12
|
+
## Owned skills
|
|
13
|
+
|
|
14
|
+
Skills authored and maintained in this repo. Published inside the npm package.
|
|
15
|
+
|
|
16
|
+
### Workflow & safety
|
|
17
|
+
|
|
18
|
+
| Skill | Description |
|
|
19
|
+
|-------|-------------|
|
|
20
|
+
| [`git-safety`](./skills/git-safety/SKILL.md) | Never force-push or run destructive git ops without permission |
|
|
21
|
+
| [`pr-workflow`](./skills/pr-workflow/SKILL.md) | Always open a PR; one-change-per-PR; delete branch on close |
|
|
22
|
+
| [`commit-standards`](./skills/commit-standards/SKILL.md) | Conventional Commits format + DCO signing |
|
|
23
|
+
| [`security-review`](./skills/security-review/SKILL.md) | OWASP-oriented checklist for code review |
|
|
24
|
+
|
|
25
|
+
### Project-specific (theholocron)
|
|
26
|
+
|
|
27
|
+
| Skill | Description |
|
|
28
|
+
|-------|-------------|
|
|
29
|
+
| [`holocron-skill-config`](./skills/holocron-skill-config/SKILL.md) | Scaffold a new `@theholocron/*-config` package in `theholocron/configs` |
|
|
30
|
+
| [`holocron-skill-client`](./skills/holocron-skill-client/SKILL.md) | Scaffold a new `@theholocron/*-client` package in `theholocron/clients` |
|
|
31
|
+
| [`holocron-skill-plugin`](./skills/holocron-skill-plugin/SKILL.md) | Scaffold or migrate a new `holocron-plugin-*` package |
|
|
32
|
+
|
|
33
|
+
## External skills
|
|
34
|
+
|
|
35
|
+
Tracked in [`skills-lock.json`](./skills-lock.json) with source provenance and content hash.
|
|
36
|
+
Not committed to this repo — fetched from upstream by `holocron skills update` (planned).
|
|
37
|
+
|
|
38
|
+
| Skill | Source | Description |
|
|
39
|
+
|-------|--------|-------------|
|
|
40
|
+
| `find-skills` | [vercel-labs/skills](https://github.com/vercel-labs/skills) | Discover and install agent skills from the skills.sh ecosystem |
|
|
41
|
+
| `frontend-design` | [anthropics/skills](https://github.com/anthropics/skills) | Distinctive, intentional UI design guidance |
|
|
42
|
+
| `vercel-cli` | [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin) | Vercel CLI: deploy, env vars, logs, domains, project linking |
|
|
43
|
+
| `turbopack` | [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin) | Turbopack bundler: HMR, CSS, tree shaking, webpack migration |
|
|
44
|
+
|
|
45
|
+
## Installation via `holocron setup`
|
|
46
|
+
|
|
47
|
+
Skills are installed by `holocron setup` based on the `skills` field in
|
|
48
|
+
`holocron.config.ts`. They are written to `.agents/skills/<name>/` with a
|
|
49
|
+
symlink at the agent-specific path, and **gitignored** — treated as dependencies,
|
|
50
|
+
not source.
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
// holocron.config.ts
|
|
54
|
+
import { defineConfig } from "@theholocron/cli";
|
|
55
|
+
|
|
56
|
+
export default defineConfig({
|
|
57
|
+
agent: "claude",
|
|
58
|
+
skills: ["git-safety", "pr-workflow", "commit-standards", "security-review"],
|
|
59
|
+
// ...
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Then run:
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
pnpm add -D @theholocron/skills
|
|
67
|
+
GITHUB_TOKEN=$(gh auth token) pnpm exec holocron setup
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Manual installation
|
|
71
|
+
|
|
72
|
+
Copy a skill directory into your project's `.agents/skills/` and symlink it:
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
cp -r node_modules/@theholocron/skills/skills/git-safety .agents/skills/
|
|
76
|
+
ln -s ../../.agents/skills/git-safety .claude/skills/git-safety
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Add both to `.gitignore`:
|
|
80
|
+
|
|
81
|
+
```gitignore
|
|
82
|
+
# managed by holocron setup — skills
|
|
83
|
+
/.agents/skills/
|
|
84
|
+
/.claude/skills/git-safety
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Contributing
|
|
88
|
+
|
|
89
|
+
### Adding an owned skill
|
|
90
|
+
|
|
91
|
+
1. Create `skills/<name>/SKILL.md` with the frontmatter format:
|
|
92
|
+
```markdown
|
|
93
|
+
---
|
|
94
|
+
name: <name>
|
|
95
|
+
description: One-line description. INVOKE WHEN: <trigger conditions>.
|
|
96
|
+
---
|
|
97
|
+
# skill title
|
|
98
|
+
…
|
|
99
|
+
```
|
|
100
|
+
2. Run `pnpm test` — the smoke test checks that every skill dir has a `SKILL.md`.
|
|
101
|
+
3. Update this README with a row in the owned skills table.
|
|
102
|
+
4. Open a PR with a `feat:` commit — semantic-release handles versioning.
|
|
103
|
+
|
|
104
|
+
### Registering an external skill
|
|
105
|
+
|
|
106
|
+
Run `npx skills add <repo> --skill <name>` from this repo root. This records the
|
|
107
|
+
skill in `skills-lock.json` with its source and content hash but does **not** copy
|
|
108
|
+
it into `skills/` — external skill content is fetched at install time.
|
package/package.json
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@theholocron/skills",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Shared agent skill registry.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"agent",
|
|
7
|
+
"claude",
|
|
8
|
+
"codex",
|
|
9
|
+
"developer-tools",
|
|
10
|
+
"skills",
|
|
11
|
+
"theholocron"
|
|
12
|
+
],
|
|
13
|
+
"homepage": "https://github.com/theholocron/skills#readme",
|
|
14
|
+
"bugs": "https://github.com/theholocron/skills/issues",
|
|
15
|
+
"repository": {
|
|
16
|
+
"type": "git",
|
|
17
|
+
"url": "git+https://github.com/theholocron/skills.git"
|
|
18
|
+
},
|
|
19
|
+
"license": "MIT",
|
|
20
|
+
"author": "Newton Koumantzelis",
|
|
21
|
+
"type": "module",
|
|
22
|
+
"exports": {
|
|
23
|
+
"./package.json": "./package.json",
|
|
24
|
+
"./skills/*": "./skills/*"
|
|
25
|
+
},
|
|
26
|
+
"files": [
|
|
27
|
+
"skills/",
|
|
28
|
+
"skills-lock.json",
|
|
29
|
+
"README.md"
|
|
30
|
+
],
|
|
31
|
+
"devDependencies": {
|
|
32
|
+
"@commitlint/cli": "^21.2.1",
|
|
33
|
+
"@commitlint/config-conventional": "^21.2.0",
|
|
34
|
+
"@commitlint/types": "^21.2.0",
|
|
35
|
+
"@semantic-release/changelog": "^6.0.3",
|
|
36
|
+
"@semantic-release/exec": "^7.1.0",
|
|
37
|
+
"@semantic-release/git": "^10.0.1",
|
|
38
|
+
"@semantic-release/github": "^12.0.9",
|
|
39
|
+
"@theholocron/cli": ">=2.0.0-alpha.0 <2.0.0",
|
|
40
|
+
"@theholocron/commitlint-config": "^7.3.1",
|
|
41
|
+
"@theholocron/holocron-plugin-github": ">=2.0.0-alpha.0 <2.0.0",
|
|
42
|
+
"@theholocron/semantic-release-config": "^7.3.1",
|
|
43
|
+
"conventional-changelog-conventionalcommits": "^10.2.1",
|
|
44
|
+
"semantic-release": "^25.0.7"
|
|
45
|
+
},
|
|
46
|
+
"engines": {
|
|
47
|
+
"node": ">=22",
|
|
48
|
+
"pnpm": ">=10"
|
|
49
|
+
},
|
|
50
|
+
"publishConfig": {
|
|
51
|
+
"access": "public"
|
|
52
|
+
},
|
|
53
|
+
"releases": "https://github.com/theholocron/skills/releases",
|
|
54
|
+
"wiki": "https://github.com/theholocron/skills/wiki",
|
|
55
|
+
"scripts": {
|
|
56
|
+
"test": "node --test test/index.mjs"
|
|
57
|
+
}
|
|
58
|
+
}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: commit-standards
|
|
3
|
+
description: Commit message standards. INVOKE WHEN: writing a commit message, reviewing a commit, opening a PR. Always use Conventional Commits and sign commits with -s (DCO).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# commit standards
|
|
7
|
+
|
|
8
|
+
## Conventional Commits
|
|
9
|
+
|
|
10
|
+
All commit subjects must follow the Conventional Commits format:
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
<type>[optional scope]: <description>
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
### Types
|
|
17
|
+
|
|
18
|
+
| Type | Use for |
|
|
19
|
+
|------|---------|
|
|
20
|
+
| `feat` | New feature (triggers minor version bump) |
|
|
21
|
+
| `fix` | Bug fix (triggers patch bump) |
|
|
22
|
+
| `chore` | Maintenance that doesn't affect published artifacts |
|
|
23
|
+
| `docs` | Documentation-only changes |
|
|
24
|
+
| `ci` | CI/workflow changes (won't appear in changelog) |
|
|
25
|
+
| `test` | Test additions or changes |
|
|
26
|
+
| `refactor` | Code restructuring with no behavior change |
|
|
27
|
+
| `perf` | Performance improvement |
|
|
28
|
+
|
|
29
|
+
### Breaking changes
|
|
30
|
+
|
|
31
|
+
Append `!` after the type/scope, or add `BREAKING CHANGE:` in the footer:
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
feat!: remove deprecated auth endpoint
|
|
35
|
+
|
|
36
|
+
BREAKING CHANGE: the /v1/auth endpoint has been removed; use /v2/auth
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## DCO — always `git commit -s`
|
|
40
|
+
|
|
41
|
+
The `Signed-off-by:` trailer is required on every commit in theholocron repos.
|
|
42
|
+
The `-s` flag generates it automatically from your git config:
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
git commit -s -m "feat: add new thing"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Result:
|
|
49
|
+
```
|
|
50
|
+
feat: add new thing
|
|
51
|
+
|
|
52
|
+
Signed-off-by: Your Name <you@example.com>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Never skip `-s`. Branch protection and CI enforce DCO.
|
|
56
|
+
|
|
57
|
+
## No agent attribution
|
|
58
|
+
|
|
59
|
+
Do not add `Co-Authored-By: Claude` or any agent attribution in commits, PRs,
|
|
60
|
+
issues, or docs. The author is always the user.
|
|
61
|
+
|
|
62
|
+
## Commit scope
|
|
63
|
+
|
|
64
|
+
Keep commits focused. One logical change per commit makes history bisectable and
|
|
65
|
+
makes semantic-release versioning accurate.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: git-safety
|
|
3
|
+
description: Git safety rules. INVOKE WHEN: git push, force push, git reset, git clean, destructive git operations. NEVER force push or do destructive git operations without explicit permission.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# git safety
|
|
7
|
+
|
|
8
|
+
## rules
|
|
9
|
+
|
|
10
|
+
- NEVER force push (`git push --force` or `git push -f`)
|
|
11
|
+
- NEVER `git reset --hard` without explicit user permission
|
|
12
|
+
- NEVER `git clean -fd` without explicit user permission
|
|
13
|
+
- NEVER `git checkout -- .` (discards all changes) without explicit user permission
|
|
14
|
+
- Prefer `git stash` over `git reset` to save work before switching context
|
|
15
|
+
- Always `git pull` (or `git fetch` + rebase) before `git push`
|
|
16
|
+
|
|
17
|
+
## forbidden commands
|
|
18
|
+
|
|
19
|
+
These require EXPLICIT user permission before running:
|
|
20
|
+
|
|
21
|
+
- `git push --force`
|
|
22
|
+
- `git push -f`
|
|
23
|
+
- `git push --force-with-lease`
|
|
24
|
+
- `git reset --hard`
|
|
25
|
+
- `git clean -fd`
|
|
26
|
+
- `git checkout -- .`
|
|
27
|
+
|
|
28
|
+
If you find yourself about to run one of these, stop and ask the user first.
|
|
29
|
+
|
|
30
|
+
## safe alternatives
|
|
31
|
+
|
|
32
|
+
**Instead of `git reset --hard`:**
|
|
33
|
+
- `git stash` to save changes temporarily
|
|
34
|
+
- `git stash pop` to restore them later
|
|
35
|
+
|
|
36
|
+
**Instead of force push:**
|
|
37
|
+
- `git pull --rebase` then normal push to reconcile diverged history
|
|
38
|
+
- If history is intentionally diverged, stop and ask the user how they want to proceed
|
|
39
|
+
|
|
40
|
+
**Instead of `git clean -fd`:**
|
|
41
|
+
- `git stash --include-untracked` to preserve files
|
|
42
|
+
- Review untracked files with `git status` before deciding to delete
|
|
43
|
+
|
|
44
|
+
## standard workflow
|
|
45
|
+
|
|
46
|
+
1. `git pull` (or `git fetch && git rebase origin/main`) before making changes
|
|
47
|
+
2. Create a branch: `git checkout -b <type>/<description>`
|
|
48
|
+
3. Make changes, then `git add <specific-files>` (never `git add -A` carelessly)
|
|
49
|
+
4. `git commit -s` (DCO required in theholocron repos)
|
|
50
|
+
5. `git pull --rebase` again before push to catch any upstream changes
|
|
51
|
+
6. `git push -u origin <branch>` (no force flags)
|
|
52
|
+
7. Open a PR — never push directly to the default branch
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: holocron-skill-client
|
|
3
|
+
description: Scaffold a new @theholocron/<slug>-client package in theholocron/clients. INVOKE WHEN: user asks to add a new HTTP client package to the clients monorepo. Invoked as /holocron-skill-client.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- editorconfig-checker-disable-file -->
|
|
7
|
+
|
|
8
|
+
# Scaffold a new client package
|
|
9
|
+
|
|
10
|
+
Replace `<slug>` with the vendor name in kebab-case (e.g. `slack`, `stripe`),
|
|
11
|
+
`<Vendor>` with PascalCase (e.g. `Slack`, `Stripe`), and `<BASE_URL>` with
|
|
12
|
+
the API root (e.g. `https://api.stripe.com`).
|
|
13
|
+
|
|
14
|
+
Reference implementation: `packages/zendesk-client` (the canonical example
|
|
15
|
+
of the current patterns — `createRestClient`, `stubFetch`, DI fetch).
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 1. Register in the workspace
|
|
20
|
+
|
|
21
|
+
Add to `pnpm-workspace.yaml`:
|
|
22
|
+
|
|
23
|
+
```yaml
|
|
24
|
+
packages:
|
|
25
|
+
- packages/<slug>-client
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Then run `pnpm install` from the repo root.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## 2. Config files (identical across all clients)
|
|
33
|
+
|
|
34
|
+
**`packages/<slug>-client/package.json`**
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"name": "@theholocron/<slug>-client",
|
|
39
|
+
"version": "0.0.0",
|
|
40
|
+
"description": "A TypeScript client for the <Vendor> API",
|
|
41
|
+
"homepage": "https://github.com/theholocron/clients/tree/main/packages/<slug>-client#readme",
|
|
42
|
+
"bugs": "https://github.com/theholocron/clients/issues",
|
|
43
|
+
"repository": {
|
|
44
|
+
"type": "git",
|
|
45
|
+
"url": "git+https://github.com/theholocron/clients.git",
|
|
46
|
+
"directory": "packages/<slug>-client"
|
|
47
|
+
},
|
|
48
|
+
"license": "GPL-3.0",
|
|
49
|
+
"author": "Newton Koumantzelis",
|
|
50
|
+
"type": "module",
|
|
51
|
+
"main": "./src/index.ts",
|
|
52
|
+
"exports": { ".": "./src/index.ts" },
|
|
53
|
+
"scripts": {
|
|
54
|
+
"build": "tsdown",
|
|
55
|
+
"lint": "eslint .",
|
|
56
|
+
"test": "vitest run",
|
|
57
|
+
"test:watch": "vitest",
|
|
58
|
+
"test:coverage": "vitest run --coverage",
|
|
59
|
+
"typecheck": "tsc --noEmit"
|
|
60
|
+
},
|
|
61
|
+
"dependencies": {
|
|
62
|
+
"@theholocron/http-client": "<current-lockstep-version>"
|
|
63
|
+
},
|
|
64
|
+
"devDependencies": {
|
|
65
|
+
"@types/node": "^22.0.0",
|
|
66
|
+
"@theholocron/eslint-config": "catalog:",
|
|
67
|
+
"@theholocron/tsconfig": "catalog:",
|
|
68
|
+
"@theholocron/tsdown-config": "catalog:",
|
|
69
|
+
"@theholocron/vitest-config": "catalog:",
|
|
70
|
+
"@vitest/coverage-v8": "catalog:",
|
|
71
|
+
"@vitest/eslint-plugin": "catalog:",
|
|
72
|
+
"eslint": "catalog:",
|
|
73
|
+
"eslint-plugin-n": "catalog:",
|
|
74
|
+
"globals": "catalog:",
|
|
75
|
+
"tsdown": "catalog:",
|
|
76
|
+
"typescript": "catalog:",
|
|
77
|
+
"vitest": "catalog:"
|
|
78
|
+
},
|
|
79
|
+
"publishConfig": {
|
|
80
|
+
"access": "public",
|
|
81
|
+
"main": "./dist/index.mjs",
|
|
82
|
+
"types": "./dist/index.d.mts",
|
|
83
|
+
"exports": {
|
|
84
|
+
".": {
|
|
85
|
+
"types": "./dist/index.d.mts",
|
|
86
|
+
"import": "./dist/index.mjs",
|
|
87
|
+
"default": "./dist/index.mjs"
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
},
|
|
91
|
+
"files": ["dist", "README.md"],
|
|
92
|
+
"engines": { "node": ">=22.0.0" },
|
|
93
|
+
"releases": "https://github.com/theholocron/clients/releases"
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## 3. Source files
|
|
98
|
+
|
|
99
|
+
### `src/client.ts` — REST client factory
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
import { createRestClient, type RestClient } from "@theholocron/http-client";
|
|
103
|
+
|
|
104
|
+
export interface <Vendor>ClientOptions {
|
|
105
|
+
token: string;
|
|
106
|
+
fetch?: typeof fetch;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
export function create<Vendor>RestClient(opts: <Vendor>ClientOptions): RestClient {
|
|
110
|
+
return createRestClient({
|
|
111
|
+
baseUrl: "<BASE_URL>",
|
|
112
|
+
token: opts.token,
|
|
113
|
+
vendor: "<Vendor>",
|
|
114
|
+
fetch: opts.fetch,
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### `src/index.ts` — factory + public API
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
import { create<Vendor>RestClient } from "./client.js";
|
|
123
|
+
import { <resources> } from "./<resources>.js";
|
|
124
|
+
|
|
125
|
+
export type { <Vendor>ClientOptions } from "./client.js";
|
|
126
|
+
export type * from "./types.js";
|
|
127
|
+
|
|
128
|
+
export function create<Vendor>Client(opts: <Vendor>ClientOptions) {
|
|
129
|
+
const rest = create<Vendor>RestClient(opts);
|
|
130
|
+
return { <resources>: <resources>(rest) };
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## 4. Non-negotiables
|
|
135
|
+
|
|
136
|
+
1. **Add to `.releaserc.json` `prepareCmd`** — alphabetical order. Omitting this leaves
|
|
137
|
+
the package frozen at its initial version while all others advance.
|
|
138
|
+
2. **Set initial `version`** in `package.json` to match the current lockstep version.
|
|
139
|
+
3. **Add entry to `codecov.yml`** under `component_management.individual_components`.
|
|
140
|
+
4. **Use `stubFetch`** in tests — DI pattern, no `vi.stubGlobal`.
|
|
141
|
+
|
|
142
|
+
## 5. Checklist before opening a PR
|
|
143
|
+
|
|
144
|
+
- [ ] `pnpm install` — workspace symlink created
|
|
145
|
+
- [ ] `pnpm --filter @theholocron/<slug>-client typecheck` passes
|
|
146
|
+
- [ ] `pnpm --filter @theholocron/<slug>-client lint` passes
|
|
147
|
+
- [ ] `pnpm --filter @theholocron/<slug>-client test` passes
|
|
148
|
+
- [ ] `pnpm --filter @theholocron/<slug>-client build` — `dist/` emitted
|
|
149
|
+
- [ ] `packages/<slug>-client` added to `prepareCmd` in `.releaserc.json`
|
|
150
|
+
- [ ] `version` in `package.json` set to current lockstep version
|
|
151
|
+
- [ ] `codecov.yml` entry added
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: holocron-skill-config
|
|
3
|
+
description: Scaffold a new shareable config package in theholocron/configs. INVOKE WHEN: user asks to add a new @theholocron/<tool>-config package to the configs monorepo. Invoked as /holocron-skill-config.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- editorconfig-checker-disable-file -->
|
|
7
|
+
|
|
8
|
+
# Scaffold a new config package
|
|
9
|
+
|
|
10
|
+
Scaffold a new shareable config package in `theholocron/configs`.
|
|
11
|
+
|
|
12
|
+
## When to use
|
|
13
|
+
|
|
14
|
+
When the user asks to add a new `@theholocron/<tool>-config` package to this monorepo.
|
|
15
|
+
|
|
16
|
+
## What to produce
|
|
17
|
+
|
|
18
|
+
Seven files in `packages/<tool>-config/`:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
packages/<tool>-config/
|
|
22
|
+
├── package.json
|
|
23
|
+
├── index.js (or named-export entry; use bundles/ for multi-preset)
|
|
24
|
+
└── README.md
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Optionally, if the config needs multiple presets:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
packages/<tool>-config/
|
|
31
|
+
├── package.json
|
|
32
|
+
├── index.js (re-exports all named presets)
|
|
33
|
+
├── presets/
|
|
34
|
+
│ ├── node.js
|
|
35
|
+
│ └── react.js
|
|
36
|
+
├── bundles/ (preset + opinionated settings combined)
|
|
37
|
+
│ └── library.js
|
|
38
|
+
└── README.md
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## File templates
|
|
42
|
+
|
|
43
|
+
### `package.json`
|
|
44
|
+
|
|
45
|
+
Copy the shape from an existing package (e.g. `packages/vitest-config/package.json`).
|
|
46
|
+
Key fields:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"name": "@theholocron/<tool>-config",
|
|
51
|
+
"version": "4.1.0",
|
|
52
|
+
"description": "A <Tool> configuration for <purpose>.",
|
|
53
|
+
"homepage": "https://github.com/theholocron/configs/tree/main/packages/<tool>-config#readme",
|
|
54
|
+
"bugs": "https://github.com/theholocron/configs/issues",
|
|
55
|
+
"repository": {
|
|
56
|
+
"type": "git",
|
|
57
|
+
"url": "git+https://github.com/theholocron/configs.git"
|
|
58
|
+
},
|
|
59
|
+
"license": "GPL-3.0",
|
|
60
|
+
"author": "Newton Koumantzelis",
|
|
61
|
+
"type": "module",
|
|
62
|
+
"exports": {
|
|
63
|
+
".": { "import": "./index.js", "default": "./index.js" }
|
|
64
|
+
},
|
|
65
|
+
"files": ["index.js"],
|
|
66
|
+
"peerDependencies": {
|
|
67
|
+
"<tool>": "^<major>"
|
|
68
|
+
},
|
|
69
|
+
"publishConfig": { "access": "public" }
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
- Match `version` to the current monorepo version (check the root `package.json`).
|
|
74
|
+
- All peer deps that are optional per-preset go under `peerDependenciesMeta`:
|
|
75
|
+
```json
|
|
76
|
+
"peerDependenciesMeta": { "<tool>": { "optional": true } }
|
|
77
|
+
```
|
|
78
|
+
- Export each preset/bundle as a subpath (`"./presets/node"`, `"./bundles/library"`, …)
|
|
79
|
+
and add those to `"files"`.
|
|
80
|
+
|
|
81
|
+
### `index.js` (single-export example)
|
|
82
|
+
|
|
83
|
+
```js
|
|
84
|
+
/**
|
|
85
|
+
* @see https://example.com/docs/config
|
|
86
|
+
* @type {import("<tool>").Config}
|
|
87
|
+
*/
|
|
88
|
+
const config = {
|
|
89
|
+
// ...
|
|
90
|
+
};
|
|
91
|
+
|
|
92
|
+
export default config;
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### `index.js` (multi-export / named presets)
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
export { node } from "./presets/node.js";
|
|
99
|
+
export { react } from "./presets/react.js";
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### `README.md`
|
|
103
|
+
|
|
104
|
+
Follow this structure (see existing READMEs for tone):
|
|
105
|
+
|
|
106
|
+
```markdown
|
|
107
|
+
# <Tool> Config
|
|
108
|
+
|
|
109
|
+
A [<Tool> configuration](official-docs-url) for <one-line description>.
|
|
110
|
+
|
|
111
|
+
## Installation
|
|
112
|
+
|
|
113
|
+
\`\`\`bash
|
|
114
|
+
npm install --save-dev @theholocron/<tool>-config
|
|
115
|
+
\`\`\`
|
|
116
|
+
|
|
117
|
+
## Usage
|
|
118
|
+
|
|
119
|
+
<minimal working example — show the exact file name the user creates and its contents>
|
|
120
|
+
|
|
121
|
+
## <Optional: named presets or bundles section>
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Keep it short. Link to official docs rather than duplicating them.
|
|
125
|
+
|
|
126
|
+
## Non-negotiables
|
|
127
|
+
|
|
128
|
+
- **No build step.** Source JS is the published artifact. Do not add TypeScript
|
|
129
|
+
compilation.
|
|
130
|
+
- **Match version to current monorepo version** — check root `package.json`.
|
|
131
|
+
- **Peer deps, not regular deps.** The tool being configured belongs in
|
|
132
|
+
`peerDependencies`.
|
|
133
|
+
- **Deprecation notice** if replacing an existing package — add a banner at the
|
|
134
|
+
top of the old package's `README.md` pointing to the replacement.
|
|
135
|
+
- Run `pnpm install` after adding the package to pick up workspace resolution.
|
|
136
|
+
- Run `pnpm lint` to verify the new files pass ESLint.
|
|
137
|
+
|
|
138
|
+
## Checklist
|
|
139
|
+
|
|
140
|
+
1. Create `packages/<tool>-config/` with `package.json`, `index.js`, `README.md`
|
|
141
|
+
2. Add `vitest` and `@theholocron/vitest-config: "workspace:*"` to `devDependencies`
|
|
142
|
+
3. Add `"build": "tsdown"`, `"test": "vitest run"`, `"typecheck": "tsc --noEmit"` to scripts
|
|
143
|
+
4. Add entry to `codecov.yml` under `component_management.individual_components`
|
|
144
|
+
5. Verify `pnpm install` resolves, `pnpm build` succeeds, `pnpm test` passes
|
|
145
|
+
6. Open a PR with a `feat:` commit
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: holocron-skill-plugin
|
|
3
|
+
description: Scaffold a new @theholocron/holocron-plugin-<slug> package. INVOKE WHEN: user asks to add a new provider plugin to theholocron/holocron. Since v2.0.0-alpha, use the CLI command instead. Invoked as /holocron-skill-plugin.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- editorconfig-checker-disable-file -->
|
|
7
|
+
|
|
8
|
+
# Scaffold a new holocron plugin
|
|
9
|
+
|
|
10
|
+
Since v2.0.0-alpha, plugin scaffolding is a first-class CLI command.
|
|
11
|
+
Skip this skill; run:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pnpm holocron plugin create <slug> <vendor> \
|
|
15
|
+
--capability <key> \
|
|
16
|
+
--vendor-env <VENDOR_NATIVE_ENV_NAME> \
|
|
17
|
+
--base-url <https://api.vendor.example>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The command produces 18 files under `packages/holocron-plugin-<slug>/`
|
|
21
|
+
matching the same template this skill used to hand-craft:
|
|
22
|
+
|
|
23
|
+
- 5 config files (`package.json`, `tsconfig.json`, `vitest.config.ts`,
|
|
24
|
+
`eslint.config.js`, `tsdown.config.ts`)
|
|
25
|
+
- 1 `README.md`
|
|
26
|
+
- 5 source files (`auth.ts` with 4-step keyring precedence, `rest.ts`,
|
|
27
|
+
`verify-token.ts`, `index.ts` with `AUTH_HINT` export,
|
|
28
|
+
`capabilities/<key>.ts` stub)
|
|
29
|
+
- 6 test files (`helpers.ts`, `auth.test.ts`, `rest.test.ts`,
|
|
30
|
+
`verify-token.test.ts`, `<key>.test.ts` with `it.todo`,
|
|
31
|
+
`index.test.ts`)
|
|
32
|
+
- 1 validation script (`scripts/validate.mjs`)
|
|
33
|
+
|
|
34
|
+
Then follow the "Next" steps printed by the command:
|
|
35
|
+
|
|
36
|
+
1. `pnpm install`
|
|
37
|
+
2. `pnpm --filter @theholocron/holocron-plugin-<slug> typecheck lint test`
|
|
38
|
+
3. Fill in the `<VendorName><Capability>` class methods against the
|
|
39
|
+
capability interface in `packages/cli/src/capabilities/index.ts`.
|
|
40
|
+
4. Replace `it.todo(...)` with real tests.
|
|
41
|
+
5. Commit + push when the capability is functionally complete.
|
|
42
|
+
6. **Wire a typed client** once `@theholocron/<slug>-client` exists.
|
|
43
|
+
|
|
44
|
+
## Step 6: migrate to a typed client
|
|
45
|
+
|
|
46
|
+
The scaffolded `rest.ts` uses the raw `createRestClient` from `@theholocron/cli`.
|
|
47
|
+
Once a typed client package exists in `theholocron/clients`, replace it:
|
|
48
|
+
|
|
49
|
+
**`src/rest.ts`** — swap to a re-export:
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
export {
|
|
53
|
+
create<Vendor>Client,
|
|
54
|
+
type <Vendor>Client,
|
|
55
|
+
type <Vendor>ClientOptions,
|
|
56
|
+
} from "@theholocron/<slug>-client";
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**`pnpm-workspace.yaml` catalog + plugin `package.json`:**
|
|
60
|
+
|
|
61
|
+
```yaml
|
|
62
|
+
# pnpm-workspace.yaml
|
|
63
|
+
catalog:
|
|
64
|
+
"@theholocron/<slug>-client": ^<version>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
"peerDependencies": { "@theholocron/<slug>-client": "catalog:" },
|
|
69
|
+
"peerDependenciesMeta": { "@theholocron/<slug>-client": { "optional": false } },
|
|
70
|
+
"devDependencies": { "@theholocron/<slug>-client": "catalog:" }
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Auth pattern (4-step precedence)
|
|
74
|
+
|
|
75
|
+
Every plugin's `auth.ts` follows this order:
|
|
76
|
+
1. `--token` CLI flag (`RuntimeContext.cliToken`)
|
|
77
|
+
2. `HOLOCRON_<VENDOR>_TOKEN` env var
|
|
78
|
+
3. `<VENDOR_NATIVE_ENV_VAR>` env var
|
|
79
|
+
4. Keyring lookup → `AuthError` if all fail
|
|
80
|
+
|
|
81
|
+
## Design references
|
|
82
|
+
|
|
83
|
+
- `.notes/tool-plugin-create.spec.md` — CLI scaffolding spec
|
|
84
|
+
- `.notes/tech-auth-bootstrap.spec.md` — 4-step token precedence
|
|
85
|
+
- `.notes/tech-vault-choice.spec.md` — Doppler + Infisical adoption
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pr-workflow
|
|
3
|
+
description: Pull request workflow rules. INVOKE WHEN: opening a PR, merging, closing a PR, creating a branch. Always open a PR — never push directly to the default branch.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# PR workflow
|
|
7
|
+
|
|
8
|
+
## core rules
|
|
9
|
+
|
|
10
|
+
- **Always open a PR — never push directly to the default branch.** Even for
|
|
11
|
+
small fixes: create a branch, push it, open a PR. This lets CI run, keeps
|
|
12
|
+
history reviewable, and respects branch protection. The only exception is
|
|
13
|
+
bootstrapping a brand-new repo before protection is set up.
|
|
14
|
+
- **One PR = one focused change.** Squash-merge; the PR title becomes the
|
|
15
|
+
squashed commit subject that semantic-release reads.
|
|
16
|
+
- **File issues for non-trivial work** and reference them in commits/PRs
|
|
17
|
+
(`Closes #N` / `Refs #N`). Skip for typo fixes.
|
|
18
|
+
|
|
19
|
+
## opening a PR
|
|
20
|
+
|
|
21
|
+
1. Create a branch from the correct base (usually `main`; `alpha` in holocron)
|
|
22
|
+
2. Push the branch: `git push -u origin <branch>`
|
|
23
|
+
3. Open the PR with `gh pr create` — title = squashed commit subject (Conventional Commit format)
|
|
24
|
+
4. Reference any related issues in the body
|
|
25
|
+
|
|
26
|
+
## merging
|
|
27
|
+
|
|
28
|
+
- Squash-merge only — the PR title becomes the single commit on the base branch
|
|
29
|
+
- The merge commit subject must follow Conventional Commits so semantic-release
|
|
30
|
+
can compute the correct version bump
|
|
31
|
+
|
|
32
|
+
## closing / discarding
|
|
33
|
+
|
|
34
|
+
**Delete the branch when closing, never just close the PR.** A closed-but-existing
|
|
35
|
+
branch blocks future PR creation for the same branch name — GitHub returns 422
|
|
36
|
+
"A pull request already exists" and the sync silently skips opening a new one.
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
gh pr close <n> --repo <owner>/<repo> --delete-branch
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## bad sync PRs
|
|
43
|
+
|
|
44
|
+
If a workflow-sync PR is stale or wrong, use the command above. Do NOT close the
|
|
45
|
+
PR without deleting the branch or the next sync run will silently fail.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: security-review
|
|
3
|
+
description: Security review checklist. INVOKE WHEN: reviewing code for security issues, auditing a PR, checking for vulnerabilities. Check for OWASP top 10 and common Node.js/TypeScript security pitfalls.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# security review
|
|
7
|
+
|
|
8
|
+
## checklist
|
|
9
|
+
|
|
10
|
+
Run through these for any code that handles user input, authentication, secrets,
|
|
11
|
+
or network requests.
|
|
12
|
+
|
|
13
|
+
### injection
|
|
14
|
+
|
|
15
|
+
- [ ] No SQL built with string concatenation — use parameterized queries
|
|
16
|
+
- [ ] No shell commands built from user input — avoid `exec`/`spawn` with interpolated strings
|
|
17
|
+
- [ ] No `eval()` or `new Function()` with user-controlled strings
|
|
18
|
+
- [ ] Template literals used in shell commands are sanitized
|
|
19
|
+
|
|
20
|
+
### authentication and secrets
|
|
21
|
+
|
|
22
|
+
- [ ] Secrets loaded from environment variables, never hardcoded
|
|
23
|
+
- [ ] No secrets in log output (even at debug level)
|
|
24
|
+
- [ ] No secrets committed to git (check `.env*`, config files, test fixtures)
|
|
25
|
+
- [ ] Tokens/credentials not stored in `localStorage` or cookies without `httpOnly`/`Secure`
|
|
26
|
+
|
|
27
|
+
### input validation
|
|
28
|
+
|
|
29
|
+
- [ ] All external input validated at the boundary (HTTP body, CLI args, env vars)
|
|
30
|
+
- [ ] File paths from user input sanitized against path traversal (`../`)
|
|
31
|
+
- [ ] File uploads restricted by type and size
|
|
32
|
+
|
|
33
|
+
### dependencies
|
|
34
|
+
|
|
35
|
+
- [ ] `pnpm audit` passes (no critical/high vulnerabilities)
|
|
36
|
+
- [ ] New dependencies are from reputable sources with active maintenance
|
|
37
|
+
- [ ] Avoid dependencies that do too much (bloated attack surface)
|
|
38
|
+
|
|
39
|
+
### output / XSS
|
|
40
|
+
|
|
41
|
+
- [ ] User content rendered in HTML is escaped (no `dangerouslySetInnerHTML` with unsanitized input)
|
|
42
|
+
- [ ] Content-Security-Policy headers set where applicable
|
|
43
|
+
|
|
44
|
+
### Node.js specific
|
|
45
|
+
|
|
46
|
+
- [ ] `child_process` calls use the array form of `exec`/`spawn` to avoid shell injection
|
|
47
|
+
- [ ] `fs` operations validate that resolved paths stay within expected directories
|
|
48
|
+
- [ ] Rate limiting on any endpoint that accepts user input
|
|
49
|
+
|
|
50
|
+
## when to stop and escalate
|
|
51
|
+
|
|
52
|
+
If you find a critical vulnerability (data exposure, auth bypass, RCE), stop
|
|
53
|
+
implementation and report it immediately rather than trying to fix it inline.
|
package/skills-lock.json
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"skills": {
|
|
4
|
+
"find-skills": {
|
|
5
|
+
"source": "vercel-labs/skills",
|
|
6
|
+
"sourceType": "github",
|
|
7
|
+
"skillPath": "skills/find-skills/SKILL.md",
|
|
8
|
+
"computedHash": "b146008599c31057cef1c145774cea5d5afb30e8f43fa802e47a4b461419aaaf"
|
|
9
|
+
},
|
|
10
|
+
"frontend-design": {
|
|
11
|
+
"source": "anthropics/skills",
|
|
12
|
+
"sourceType": "github",
|
|
13
|
+
"skillPath": "skills/frontend-design/SKILL.md",
|
|
14
|
+
"computedHash": "4eabc66183767153e404b39d1b839b1c37f2d82d86f0a0d7e880a579d8d62336"
|
|
15
|
+
},
|
|
16
|
+
"turbopack": {
|
|
17
|
+
"source": "vercel/vercel-plugin",
|
|
18
|
+
"sourceType": "github",
|
|
19
|
+
"skillPath": "skills/turbopack/SKILL.md",
|
|
20
|
+
"computedHash": "cd8c2f189adacb88854c20088ab37dfe077cdc0bc1ded3ec3aa4e40be22bcf3c"
|
|
21
|
+
},
|
|
22
|
+
"vercel-cli": {
|
|
23
|
+
"source": "vercel/vercel-plugin",
|
|
24
|
+
"sourceType": "github",
|
|
25
|
+
"skillPath": "skills/vercel-cli/SKILL.md",
|
|
26
|
+
"computedHash": "730854ddcfabf771468e6ab83d0a3635b006d5e1ecbcc59b5682e1b14dd1f5de"
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
}
|