@theholocron/skills 1.3.3 → 1.12.1-alpha.4
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 +1 -1
- package/README.md +136 -0
- package/package.json +12 -26
- package/skills-lock.json +30 -0
- package/src/adr/SKILL.md +53 -0
- package/src/adr/assets/template.md +64 -0
- package/src/commit-standards/SKILL.md +135 -0
- package/src/design/SKILL.md +38 -0
- package/src/destructive-command-guard/SKILL.md +51 -0
- package/src/discover/SKILL.md +44 -0
- package/src/discuss/SKILL.md +38 -0
- package/{git-safety → src/git-safety}/SKILL.md +4 -0
- package/src/holocron-skill-client/SKILL.md +278 -0
- package/src/holocron-skill-config/SKILL.md +246 -0
- package/{holocron-skill-plugin → src/holocron-skill-plugin}/SKILL.md +15 -2
- package/src/holocron-skill-skill/SKILL.md +155 -0
- package/src/holocron-skill-util/SKILL.md +286 -0
- package/src/implement/SKILL.md +54 -0
- package/src/plan/SKILL.md +40 -0
- package/{pr-workflow → src/pr-workflow}/SKILL.md +20 -1
- package/src/review/SKILL.md +78 -0
- package/{security-review → src/security-review}/SKILL.md +3 -0
- package/src/spec/SKILL.md +52 -0
- package/src/verify/SKILL.md +22 -0
- package/commit-standards/SKILL.md +0 -88
- package/holocron-skill-client/SKILL.md +0 -151
- package/holocron-skill-config/SKILL.md +0 -236
- package/holocron-skill-skill/SKILL.md +0 -134
- package/holocron-skill-util/SKILL.md +0 -274
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: discuss
|
|
3
|
+
description: Discussion / RFC Agent. INVOKE WHEN: an architectural decision needs engineering review before being finalized. Converts design analysis into a structured GitHub Discussion.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Discussion / RFC Agent
|
|
7
|
+
|
|
8
|
+
Convert the design analysis into a GitHub Discussion suitable for engineering
|
|
9
|
+
review.
|
|
10
|
+
|
|
11
|
+
Include:
|
|
12
|
+
|
|
13
|
+
# Problem
|
|
14
|
+
|
|
15
|
+
# Context
|
|
16
|
+
|
|
17
|
+
# Constraints
|
|
18
|
+
|
|
19
|
+
# Options
|
|
20
|
+
|
|
21
|
+
For each option:
|
|
22
|
+
|
|
23
|
+
- description
|
|
24
|
+
- advantages
|
|
25
|
+
- disadvantages
|
|
26
|
+
- operational consequences
|
|
27
|
+
- implementation complexity
|
|
28
|
+
|
|
29
|
+
# Recommended Direction
|
|
30
|
+
|
|
31
|
+
State the recommendation as a proposal, not a decision.
|
|
32
|
+
|
|
33
|
+
# Open Questions
|
|
34
|
+
|
|
35
|
+
# Decision Requested
|
|
36
|
+
|
|
37
|
+
Avoid implementation-level details unless they materially affect the
|
|
38
|
+
architectural choice.
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: git-safety
|
|
3
|
+
title: Git Safety
|
|
3
4
|
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
|
---
|
|
5
6
|
|
|
@@ -30,14 +31,17 @@ If you find yourself about to run one of these, stop and ask the user first.
|
|
|
30
31
|
## safe alternatives
|
|
31
32
|
|
|
32
33
|
**Instead of `git reset --hard`:**
|
|
34
|
+
|
|
33
35
|
- `git stash` to save changes temporarily
|
|
34
36
|
- `git stash pop` to restore them later
|
|
35
37
|
|
|
36
38
|
**Instead of force push:**
|
|
39
|
+
|
|
37
40
|
- `git pull --rebase` then normal push to reconcile diverged history
|
|
38
41
|
- If history is intentionally diverged, stop and ask the user how they want to proceed
|
|
39
42
|
|
|
40
43
|
**Instead of `git clean -fd`:**
|
|
44
|
+
|
|
41
45
|
- `git stash --include-untracked` to preserve files
|
|
42
46
|
- Review untracked files with `git status` before deciding to delete
|
|
43
47
|
|
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: holocron-skill-client
|
|
3
|
+
title: "Holocron: New Client"
|
|
4
|
+
description: Scaffold a new @theholocron/<slug>-client package in the clients folder of theholocron/holocron. INVOKE WHEN: user asks to add a new HTTP client package to the clients group. Invoked as /holocron-skill-client.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<!-- editorconfig-checker-disable-file -->
|
|
8
|
+
|
|
9
|
+
# Scaffold a new client package
|
|
10
|
+
|
|
11
|
+
Scaffold a new `@theholocron/<slug>-client` package in `clients/` of `theholocron/holocron`.
|
|
12
|
+
The standalone `theholocron/clients` repo is archived; do not scaffold there.
|
|
13
|
+
|
|
14
|
+
Replace `<slug>` with the vendor name in kebab-case (e.g. `slack`, `stripe`),
|
|
15
|
+
`<Vendor>` with PascalCase (e.g. `Slack`, `Stripe`), and `<BASE_URL>` with
|
|
16
|
+
the API root (e.g. `https://api.stripe.com`).
|
|
17
|
+
|
|
18
|
+
Reference implementations: `clients/axiom-client` (smallest current example —
|
|
19
|
+
`createRestClient`, `stubFetch`, DI fetch, optional `logger` / `errors` sinks)
|
|
20
|
+
and `clients/http-client` (the shared primitives every client builds on).
|
|
21
|
+
Read `clients/axiom-client/package.json` and copy its shape rather than
|
|
22
|
+
trusting this template if they ever disagree.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 1. Create the package directory
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
clients/<slug>-client/
|
|
30
|
+
├── src/
|
|
31
|
+
│ ├── index.ts
|
|
32
|
+
│ ├── index.test.ts
|
|
33
|
+
│ ├── utils.ts
|
|
34
|
+
│ └── <resource>/<resource>.ts
|
|
35
|
+
├── package.json
|
|
36
|
+
├── tsconfig.json
|
|
37
|
+
├── tsdown.config.ts
|
|
38
|
+
├── vitest.config.ts
|
|
39
|
+
└── README.md
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The workspace glob `clients/*` in `pnpm-workspace.yaml` already covers the new
|
|
43
|
+
folder, and knip's `clients/*` entry covers `src/index.ts` and `src/**/*.test.ts`,
|
|
44
|
+
so neither file needs editing. Tests live beside the module they cover
|
|
45
|
+
(`foo.test.ts`); there is no `__tests__` directory. There is no per-package
|
|
46
|
+
`LICENSE`, `CHANGELOG.md`, `eslint.config.ts` (the root config applies) or
|
|
47
|
+
`.releaserc`.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 2. Config files
|
|
52
|
+
|
|
53
|
+
**`clients/<slug>-client/package.json`**
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"name": "@theholocron/<slug>-client",
|
|
58
|
+
"version": "<current clients version>",
|
|
59
|
+
"description": "A TypeScript client for the <Vendor> API",
|
|
60
|
+
"keywords": ["<slug>", "typescript", "http-client", "api"],
|
|
61
|
+
"homepage": "https://docs.theholocron.dev/holocron/clients/<slug>/",
|
|
62
|
+
"bugs": "https://github.com/theholocron/holocron/issues",
|
|
63
|
+
"repository": {
|
|
64
|
+
"type": "git",
|
|
65
|
+
"url": "git+https://github.com/theholocron/holocron.git",
|
|
66
|
+
"directory": "clients/<slug>-client"
|
|
67
|
+
},
|
|
68
|
+
"license": "MIT",
|
|
69
|
+
"author": "Newton Koumantzelis",
|
|
70
|
+
"sideEffects": false,
|
|
71
|
+
"type": "module",
|
|
72
|
+
"exports": {
|
|
73
|
+
".": {
|
|
74
|
+
"types": "./dist/index.d.mts",
|
|
75
|
+
"import": "./dist/index.mjs",
|
|
76
|
+
"default": "./dist/index.mjs"
|
|
77
|
+
}
|
|
78
|
+
},
|
|
79
|
+
"files": ["dist"],
|
|
80
|
+
"scripts": {
|
|
81
|
+
"build": "tsdown && node ../scripts/check-bundle-size.mjs",
|
|
82
|
+
"lint:code": "eslint .",
|
|
83
|
+
"test:watch": "vitest",
|
|
84
|
+
"typecheck": "tsc --noEmit",
|
|
85
|
+
"test:unit": "vitest run"
|
|
86
|
+
},
|
|
87
|
+
"dependencies": {
|
|
88
|
+
"@theholocron/http-client": "workspace:^",
|
|
89
|
+
"@theholocron/observability": "catalog:"
|
|
90
|
+
},
|
|
91
|
+
"devDependencies": {
|
|
92
|
+
"@theholocron/eslint-config": "catalog:configs",
|
|
93
|
+
"@theholocron/tsconfig": "catalog:configs",
|
|
94
|
+
"@theholocron/tsdown-config": "catalog:configs",
|
|
95
|
+
"@theholocron/vitest-config": "catalog:configs",
|
|
96
|
+
"@types/node": "catalog:",
|
|
97
|
+
"@vitest/coverage-v8": "catalog:",
|
|
98
|
+
"@vitest/eslint-plugin": "catalog:",
|
|
99
|
+
"eslint": "catalog:",
|
|
100
|
+
"eslint-plugin-n": "catalog:",
|
|
101
|
+
"globals": "catalog:",
|
|
102
|
+
"tsdown": "catalog:",
|
|
103
|
+
"typescript": "catalog:",
|
|
104
|
+
"vitest": "catalog:"
|
|
105
|
+
},
|
|
106
|
+
"engines": { "node": ">=22.0.0" },
|
|
107
|
+
"publishConfig": { "access": "public" }
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
- **`version`**: read it from any sibling (`clients/http-client/package.json`);
|
|
112
|
+
the whole `clients/` folder is one version group (tags `clients-vX.Y.Z`, one
|
|
113
|
+
`clients/CHANGELOG.md`). `holocron publish bump-versions --group clients`
|
|
114
|
+
moves every package in the group together at release.
|
|
115
|
+
- **License is MIT** (ADR-0016). No `releases` or `wiki` fields.
|
|
116
|
+
- `homepage` uses the slug **without** `-client` (`.../clients/axiom/`),
|
|
117
|
+
matching the docs page you add in step 5.
|
|
118
|
+
- Inside the group, `@theholocron/http-client` is `workspace:^`. Everything
|
|
119
|
+
from `configs/` is `catalog:configs`; `@theholocron/*-utils` would be
|
|
120
|
+
`catalog:utils`; third-party deps are `catalog:`. Never pin exact versions.
|
|
121
|
+
- Drop `@theholocron/observability` and the `logger` / `errors` options in
|
|
122
|
+
step 3 only if you deliberately do not want diagnostics hooks.
|
|
123
|
+
|
|
124
|
+
**`tsdown.config.ts`** and **`vitest.config.ts`** are one line each:
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
export { default } from "@theholocron/tsdown-config/presets/library";
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
export { default } from "@theholocron/vitest-config/bundles/library";
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
**`tsconfig.json`**
|
|
135
|
+
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"display": "<Vendor> API Client",
|
|
139
|
+
"extends": "@theholocron/tsconfig/node-lts",
|
|
140
|
+
"compilerOptions": { "baseUrl": "./", "outDir": "./dist" },
|
|
141
|
+
"include": ["src/**/*.ts"],
|
|
142
|
+
"exclude": ["node_modules", "dist"]
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## 3. Source files
|
|
147
|
+
|
|
148
|
+
### `src/utils.ts` — REST client factory
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
import { createRestClient, type RestClient } from "@theholocron/http-client";
|
|
152
|
+
import type { ErrorSink, Logger } from "@theholocron/observability/core";
|
|
153
|
+
|
|
154
|
+
export type { RestClient };
|
|
155
|
+
|
|
156
|
+
export interface <Vendor>ClientOptions {
|
|
157
|
+
/** <Vendor> API token. */
|
|
158
|
+
token: string;
|
|
159
|
+
/** Override base URL for testing. Defaults to <BASE_URL>. */
|
|
160
|
+
baseUrl?: string;
|
|
161
|
+
/** Override fetch for testing. Defaults to globalThis.fetch. */
|
|
162
|
+
fetch?: typeof fetch;
|
|
163
|
+
/** Structured logger for request/response diagnostics. Defaults to a no-op. */
|
|
164
|
+
logger?: Logger;
|
|
165
|
+
/** Reports transport failures and unexpected 5xx. Defaults to a no-op. */
|
|
166
|
+
errors?: ErrorSink;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
export function create<Vendor>RestClient(opts: <Vendor>ClientOptions): RestClient {
|
|
170
|
+
return createRestClient({
|
|
171
|
+
baseUrl: opts.baseUrl ?? "<BASE_URL>",
|
|
172
|
+
token: opts.token,
|
|
173
|
+
vendor: "<Vendor>",
|
|
174
|
+
fetch: opts.fetch,
|
|
175
|
+
logger: opts.logger,
|
|
176
|
+
errors: opts.errors,
|
|
177
|
+
});
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### `src/<resource>/<resource>.ts` — one file per API resource
|
|
182
|
+
|
|
183
|
+
Each takes the `RestClient` and returns its methods (see
|
|
184
|
+
`clients/axiom-client/src/datasets/datasets.ts`).
|
|
185
|
+
|
|
186
|
+
### `src/index.ts` — factory and public API
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
import { <resource> } from "./<resource>/<resource>.js";
|
|
190
|
+
import { type <Vendor>ClientOptions, create<Vendor>RestClient } from "./utils.js";
|
|
191
|
+
|
|
192
|
+
export type { <Vendor>ClientOptions } from "./utils.js";
|
|
193
|
+
|
|
194
|
+
export function create<Vendor>Client(opts: <Vendor>ClientOptions) {
|
|
195
|
+
const rest = create<Vendor>RestClient(opts);
|
|
196
|
+
return { <resource>: <resource>(rest) };
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
export type <Vendor>Client = ReturnType<typeof create<Vendor>Client>;
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### `src/index.test.ts` — use `stubFetch`
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
import { stubFetch } from "@theholocron/http-client/testing";
|
|
206
|
+
import { describe, expect, it } from "vitest";
|
|
207
|
+
|
|
208
|
+
import { create<Vendor>Client } from "./index.js";
|
|
209
|
+
|
|
210
|
+
describe("create<Vendor>Client", () => {
|
|
211
|
+
it("sends Bearer authorization header", async () => {
|
|
212
|
+
const { fetch, calls } = stubFetch([{ body: {} }]);
|
|
213
|
+
const client = create<Vendor>Client({ token: "t", fetch });
|
|
214
|
+
await client.<resource>.<method>();
|
|
215
|
+
expect(calls[0]?.headers.authorization).toBe("Bearer t");
|
|
216
|
+
});
|
|
217
|
+
});
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
Tests use `stubFetch` (dependency-injected fetch), never `vi.stubGlobal`.
|
|
221
|
+
Cover every public method and the error path.
|
|
222
|
+
|
|
223
|
+
### `README.md`
|
|
224
|
+
|
|
225
|
+
Same shape as `clients/axiom-client/README.md`: title, one-line description,
|
|
226
|
+
Installation (`pnpm add @theholocron/<slug>-client`), Usage, API tables, License.
|
|
227
|
+
|
|
228
|
+
## 4. Monorepo registration
|
|
229
|
+
|
|
230
|
+
1. **Install**: run `pnpm install` from the repo root. It links the new
|
|
231
|
+
workspace package and updates `pnpm-lock.yaml`; commit the lockfile.
|
|
232
|
+
2. **Codecov**: `codecov.yml` has one component per package under the
|
|
233
|
+
`# clients` heading (`component_id: <slug>-client`, `paths: clients/<slug>-client/**`).
|
|
234
|
+
The file is generated by `holocron setup` (the "write codecov.yml" step,
|
|
235
|
+
`codecovConfig()` in `cli/astromech/src/generators/codecov`), which needs
|
|
236
|
+
tokens for its other steps, so in practice add the block by hand in exactly
|
|
237
|
+
that format, keeping the list alphabetical.
|
|
238
|
+
3. **Release**: nothing to edit. `release.config.ts` and the `release`
|
|
239
|
+
task in `astromech.config.ts` release the whole `clients` group by folder.
|
|
240
|
+
4. **Dependency catalog**: only if something outside `clients/` (a plugin, the
|
|
241
|
+
CLI) will consume the package, add it to `catalogs.clients` in
|
|
242
|
+
`pnpm-workspace.yaml` after it has been published, and reference it as
|
|
243
|
+
`catalog:clients`.
|
|
244
|
+
|
|
245
|
+
## 5. Docs
|
|
246
|
+
|
|
247
|
+
- Add `docs/src/content/docs/clients/<slug>.mdx` (frontmatter `title`,
|
|
248
|
+
`description`; copy `axiom.mdx`).
|
|
249
|
+
- Add a row to the table in `docs/src/content/docs/clients/index.mdx`.
|
|
250
|
+
- Add `{ label: "<slug>-client", slug: "clients/<slug>" }` to the Clients
|
|
251
|
+
group of the sidebar in the root `astro.config.ts` (alphabetical).
|
|
252
|
+
|
|
253
|
+
## 6. Non-negotiables
|
|
254
|
+
|
|
255
|
+
1. `version` matches the current `clients/` group version.
|
|
256
|
+
2. `repository.directory` is `clients/<slug>-client`; license `MIT`.
|
|
257
|
+
3. `@theholocron/http-client` is `workspace:^`, never a pinned version.
|
|
258
|
+
4. Tests use `stubFetch` beside the source; no `__tests__` directory.
|
|
259
|
+
5. Docs page, index row, sidebar entry and codecov component ship in the same PR.
|
|
260
|
+
|
|
261
|
+
## 7. Checklist before opening a PR
|
|
262
|
+
|
|
263
|
+
- [ ] Issue filed first; feature branch created from `origin/alpha` before any code
|
|
264
|
+
- [ ] `pnpm install` — workspace symlink created, lockfile updated
|
|
265
|
+
- [ ] `pnpm --filter @theholocron/<slug>-client typecheck` passes
|
|
266
|
+
- [ ] `pnpm --filter @theholocron/<slug>-client lint:code` passes
|
|
267
|
+
- [ ] `pnpm --filter @theholocron/<slug>-client test:unit` passes
|
|
268
|
+
- [ ] `pnpm --filter @theholocron/<slug>-client build` — `dist/` emitted
|
|
269
|
+
- [ ] `version` in `package.json` matches the clients group
|
|
270
|
+
- [ ] `codecov.yml` component added
|
|
271
|
+
- [ ] Docs page, `clients/index.mdx` row and `astro.config.ts` sidebar entry added
|
|
272
|
+
- [ ] `holocron run ci` passes
|
|
273
|
+
- [ ] PR title is a Conventional Commit (`feat(clients): ...`); commits signed (`-s`)
|
|
274
|
+
- [ ] CI green before requesting review
|
|
275
|
+
|
|
276
|
+
After merge, the first publish of a brand-new package needs
|
|
277
|
+
`holocron publish package --initial --group clients` run by a maintainer
|
|
278
|
+
(npm Trusted Publishing needs the package to exist first); do not run it yourself.
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: holocron-skill-config
|
|
3
|
+
title: "Holocron: New Config"
|
|
4
|
+
description: Scaffold a new shareable config package in the configs folder of theholocron/holocron. INVOKE WHEN: user asks to add a new @theholocron/<tool>-config package to the configs group. Invoked as /holocron-skill-config.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<!-- editorconfig-checker-disable-file -->
|
|
8
|
+
|
|
9
|
+
# Scaffold a new config package
|
|
10
|
+
|
|
11
|
+
Scaffold a new shareable config package in `configs/` of `theholocron/holocron`.
|
|
12
|
+
The standalone `theholocron/configs` repo is archived; do not scaffold there.
|
|
13
|
+
|
|
14
|
+
## When to use
|
|
15
|
+
|
|
16
|
+
When the user asks to add a new `@theholocron/<tool>-config` package.
|
|
17
|
+
|
|
18
|
+
Reference implementations: `configs/prettier-config` (single default export),
|
|
19
|
+
`configs/commitlint-config` (same, with peers), and `configs/vitest-config` /
|
|
20
|
+
`configs/tsdown-config` (multi-preset, with `presets/` and `bundles/`). Read
|
|
21
|
+
the sibling's `package.json` and copy its shape if this template ever disagrees.
|
|
22
|
+
|
|
23
|
+
## What to produce
|
|
24
|
+
|
|
25
|
+
Unlike clients and utils, a config package keeps its sources at the package
|
|
26
|
+
root (no `src/`), and its test sits beside `index.ts`:
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
configs/<tool>-config/
|
|
30
|
+
├── package.json
|
|
31
|
+
├── index.ts (or named-export entry; use presets/ for multi-preset)
|
|
32
|
+
├── index.test.ts
|
|
33
|
+
├── tsdown.config.ts
|
|
34
|
+
├── tsconfig.json
|
|
35
|
+
├── vitest.config.ts
|
|
36
|
+
└── README.md
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Multi-preset packages add `presets/*.ts` (and optionally `bundles/*.ts`, a
|
|
40
|
+
preset plus opinionated settings) and re-export them from `index.ts`.
|
|
41
|
+
|
|
42
|
+
There is no per-package `LICENSE` or `.releaserc`, and you do not create a
|
|
43
|
+
`CHANGELOG.md`: the whole `configs/` folder is one version group with a single
|
|
44
|
+
`configs/CHANGELOG.md`. The workspace glob `configs/*` in `pnpm-workspace.yaml`
|
|
45
|
+
already covers the new folder.
|
|
46
|
+
|
|
47
|
+
## File templates
|
|
48
|
+
|
|
49
|
+
### `package.json`
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"name": "@theholocron/<tool>-config",
|
|
54
|
+
"version": "<current configs version>",
|
|
55
|
+
"description": "A <Tool> configuration for <purpose>.",
|
|
56
|
+
"keywords": ["<tool>", "config", "theholocron"],
|
|
57
|
+
"homepage": "https://docs.theholocron.dev/holocron/configs/<tool>-config/",
|
|
58
|
+
"bugs": "https://github.com/theholocron/holocron/issues",
|
|
59
|
+
"repository": {
|
|
60
|
+
"type": "git",
|
|
61
|
+
"url": "git+https://github.com/theholocron/holocron.git",
|
|
62
|
+
"directory": "configs/<tool>-config"
|
|
63
|
+
},
|
|
64
|
+
"license": "MIT",
|
|
65
|
+
"author": "Newton Koumantzelis",
|
|
66
|
+
"sideEffects": false,
|
|
67
|
+
"type": "module",
|
|
68
|
+
"exports": {
|
|
69
|
+
".": {
|
|
70
|
+
"types": "./dist/index.d.ts",
|
|
71
|
+
"import": "./dist/index.js",
|
|
72
|
+
"default": "./dist/index.js"
|
|
73
|
+
},
|
|
74
|
+
"./package.json": "./package.json"
|
|
75
|
+
},
|
|
76
|
+
"files": ["dist/"],
|
|
77
|
+
"scripts": {
|
|
78
|
+
"build": "tsdown",
|
|
79
|
+
"lint:code": "eslint .",
|
|
80
|
+
"test:watch": "vitest",
|
|
81
|
+
"typecheck": "tsc --noEmit",
|
|
82
|
+
"test:unit": "vitest run"
|
|
83
|
+
},
|
|
84
|
+
"devDependencies": {
|
|
85
|
+
"@theholocron/tsconfig": "workspace:*",
|
|
86
|
+
"@theholocron/vitest-config": "workspace:*",
|
|
87
|
+
"@vitest/coverage-v8": "catalog:",
|
|
88
|
+
"tsdown": "catalog:",
|
|
89
|
+
"typescript": "catalog:",
|
|
90
|
+
"vitest": "catalog:"
|
|
91
|
+
},
|
|
92
|
+
"peerDependencies": {
|
|
93
|
+
"<tool>": "^<major>"
|
|
94
|
+
},
|
|
95
|
+
"engines": { "node": ">=22.0.0" },
|
|
96
|
+
"publishConfig": { "access": "public" }
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
- **`version`**: copy it from any sibling (`configs/prettier-config/package.json`).
|
|
101
|
+
The `configs/` folder is a version group (tags `configs-vX.Y.Z`);
|
|
102
|
+
`holocron publish bump-versions --group configs` moves every package together.
|
|
103
|
+
- **License is MIT** (ADR-0016). No `releases` or `wiki` fields.
|
|
104
|
+
- Packages inside the group reference each other as `workspace:*`; third-party
|
|
105
|
+
dev tooling is `catalog:`. Never pin exact versions for those.
|
|
106
|
+
- The tool being configured goes in `peerDependencies`. Optional-per-preset
|
|
107
|
+
peers also go under `peerDependenciesMeta`:
|
|
108
|
+
`"peerDependenciesMeta": { "<tool>": { "optional": true } }`.
|
|
109
|
+
- Export each preset/bundle as a subpath (`"./presets/node"`,
|
|
110
|
+
`"./bundles/library"`, …) with `types` / `import` / `default` pointing at `dist/`.
|
|
111
|
+
`files: ["dist/"]` covers them.
|
|
112
|
+
|
|
113
|
+
### `tsdown.config.ts`
|
|
114
|
+
|
|
115
|
+
Config packages build with a plain tsdown config, not the shared `library`
|
|
116
|
+
preset: the preset lives in `@theholocron/tsdown-config`, which is itself a
|
|
117
|
+
config package, and these packages must not depend on the one they bootstrap.
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
import { defineConfig } from "tsdown";
|
|
121
|
+
export default defineConfig({
|
|
122
|
+
entry: ["index.ts"],
|
|
123
|
+
format: "esm",
|
|
124
|
+
fixedExtension: false,
|
|
125
|
+
dts: true,
|
|
126
|
+
clean: true,
|
|
127
|
+
});
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
For multi-preset packages list every entry point:
|
|
131
|
+
|
|
132
|
+
```ts
|
|
133
|
+
entry: ["index.ts", "presets/node.ts", "presets/react.ts", "bundles/library.ts"],
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### `tsconfig.json`
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{
|
|
140
|
+
"extends": "@theholocron/tsconfig/node-lts",
|
|
141
|
+
"compilerOptions": { "rootDir": ".", "outDir": "dist" },
|
|
142
|
+
"include": ["**/*.ts"],
|
|
143
|
+
"exclude": ["dist", "node_modules", "tsdown.config.ts"]
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### `vitest.config.ts`
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
import { node } from "@theholocron/vitest-config";
|
|
151
|
+
import { defineConfig } from "vitest/config";
|
|
152
|
+
export default defineConfig(node());
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### `index.ts` (single default export)
|
|
156
|
+
|
|
157
|
+
```ts
|
|
158
|
+
import type { Config } from "<tool>";
|
|
159
|
+
|
|
160
|
+
const config = {
|
|
161
|
+
// ...
|
|
162
|
+
} satisfies Config;
|
|
163
|
+
|
|
164
|
+
export default config;
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### `index.ts` (named presets / multi-export)
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
export { node } from "./presets/node.js";
|
|
171
|
+
export { react } from "./presets/react.js";
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Relative imports in config sources use `.js` extensions (TypeScript's ESM
|
|
175
|
+
convention); the resolver finds the `.ts` file at build time.
|
|
176
|
+
|
|
177
|
+
### `index.test.ts` (beside `index.ts`, no `__tests__` directory)
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
import { describe, it, expect } from "vitest";
|
|
181
|
+
import config from "./index.js";
|
|
182
|
+
|
|
183
|
+
describe("<tool>-config", () => {
|
|
184
|
+
it("exports a non-empty config object", () => {
|
|
185
|
+
expect(typeof config).toBe("object");
|
|
186
|
+
expect(Object.keys(config).length).toBeGreaterThan(0);
|
|
187
|
+
});
|
|
188
|
+
});
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### `README.md`
|
|
192
|
+
|
|
193
|
+
Follow `configs/prettier-config/README.md`: title, one-line description linking
|
|
194
|
+
the tool's own docs, Installation (`pnpm add -D @theholocron/<tool>-config <tool>`),
|
|
195
|
+
Usage with the exact file the user creates, then optional presets/bundles.
|
|
196
|
+
Keep it short; link to official docs rather than duplicating them.
|
|
197
|
+
|
|
198
|
+
## Monorepo registration
|
|
199
|
+
|
|
200
|
+
1. Run `pnpm install` from the repo root (links the workspace package, updates
|
|
201
|
+
`pnpm-lock.yaml`; commit the lockfile).
|
|
202
|
+
2. **Codecov**: add a component under the `# configs` heading of `codecov.yml`
|
|
203
|
+
(`component_id: <tool>-config`, `paths: configs/<tool>-config/**`), alphabetical.
|
|
204
|
+
The file is generated by `holocron setup` ("write codecov.yml" step,
|
|
205
|
+
`cli/astromech/src/generators/codecov`); that command needs tokens for its
|
|
206
|
+
other steps, so add the block by hand in exactly that format.
|
|
207
|
+
3. **knip**: `knip.config.ts` has a `configs/*` workspace entry (`configPackage()`).
|
|
208
|
+
Add a dedicated entry only if the package lists optional peers knip should
|
|
209
|
+
ignore (see `configs/eslint-config` there).
|
|
210
|
+
4. **Release**: nothing to edit; the `configs` group releases by folder.
|
|
211
|
+
5. **Dependency catalog**: if other workspaces (packages in `clients/`, `utils/`,
|
|
212
|
+
plugins, the CLI) will consume it, add it to `catalogs.configs` in
|
|
213
|
+
`pnpm-workspace.yaml` once it has been published and use `catalog:configs`.
|
|
214
|
+
6. **Docs**: add `docs/src/content/docs/configs/<tool>-config.mdx`
|
|
215
|
+
(frontmatter `title`, `description`; copy `prettier-config.mdx`), a row in
|
|
216
|
+
`docs/src/content/docs/configs/index.mdx`, and
|
|
217
|
+
`{ label: "<tool>-config", slug: "configs/<tool>-config" }` to the Configs
|
|
218
|
+
group of the sidebar in the root `astro.config.ts` (alphabetical).
|
|
219
|
+
|
|
220
|
+
## Non-negotiables
|
|
221
|
+
|
|
222
|
+
- **TypeScript source, compiled to `dist/` via tsdown.** Never publish raw `.ts`
|
|
223
|
+
or add plain `.js` source. `"files"` must be `["dist/"]`.
|
|
224
|
+
- **Match `version` to the configs group** — read a sibling's `package.json`.
|
|
225
|
+
- **Peer deps, not regular deps.** The tool being configured is a peer.
|
|
226
|
+
- **Deprecation notice** if replacing an existing package — add a banner at the
|
|
227
|
+
top of the old package's `README.md` pointing to the replacement.
|
|
228
|
+
- Tests live beside the source (`index.test.ts`); no `__tests__` directory.
|
|
229
|
+
|
|
230
|
+
## Checklist
|
|
231
|
+
|
|
232
|
+
1. Create `configs/<tool>-config/` with the files above.
|
|
233
|
+
2. `devDependencies` include `@theholocron/tsconfig` and
|
|
234
|
+
`@theholocron/vitest-config` (`workspace:*`), plus `@vitest/coverage-v8`,
|
|
235
|
+
`tsdown`, `typescript`, `vitest` (`catalog:`).
|
|
236
|
+
3. `scripts` use the task names `build`, `test:unit`,
|
|
237
|
+
`typecheck`, `lint:code`.
|
|
238
|
+
4. `pnpm install`, then `pnpm --filter @theholocron/<tool>-config` run
|
|
239
|
+
`build`, `test:unit`, `typecheck` and
|
|
240
|
+
`lint:code` — all must pass.
|
|
241
|
+
5. `codecov.yml` component, docs page, `configs/index.mdx` row and sidebar entry added.
|
|
242
|
+
6. `holocron run ci` passes.
|
|
243
|
+
7. Open a PR with a `feat(configs):` commit, signed with `-s` — semantic-release
|
|
244
|
+
computes the next `configs-v*` version and publishes the group in lockstep.
|
|
245
|
+
The first publish of a brand-new package needs
|
|
246
|
+
`holocron publish package --initial --group configs` run by a maintainer.
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: holocron-skill-plugin
|
|
3
|
+
title: "Holocron: New Plugin"
|
|
3
4
|
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
|
---
|
|
5
6
|
|
|
@@ -41,10 +42,21 @@ Then follow the "Next" steps printed by the command:
|
|
|
41
42
|
5. Commit + push when the capability is functionally complete.
|
|
42
43
|
6. **Wire a typed client** once `@theholocron/<slug>-client` exists.
|
|
43
44
|
|
|
45
|
+
## Checklist before opening a PR
|
|
46
|
+
|
|
47
|
+
- [ ] Feature branch created before any code was written
|
|
48
|
+
- [ ] `pnpm --filter @theholocron/holocron-plugin-<slug> typecheck` passes
|
|
49
|
+
- [ ] `pnpm --filter @theholocron/holocron-plugin-<slug> lint` passes
|
|
50
|
+
- [ ] `pnpm --filter @theholocron/holocron-plugin-<slug> test` passes
|
|
51
|
+
- [ ] Plugin entry added to the docs-theme registry
|
|
52
|
+
- [ ] Docs page added under `docs/` in the same PR
|
|
53
|
+
- [ ] PR title follows Conventional Commits
|
|
54
|
+
- [ ] CI green before requesting review
|
|
55
|
+
|
|
44
56
|
## Step 6: migrate to a typed client
|
|
45
57
|
|
|
46
58
|
The scaffolded `rest.ts` uses the raw `createRestClient` from `@theholocron/cli`.
|
|
47
|
-
Once a typed client package exists in `
|
|
59
|
+
Once a typed client package exists in `clients/` of this repo (`@theholocron/<slug>-client`), replace it:
|
|
48
60
|
|
|
49
61
|
**`src/rest.ts`** — swap to a re-export:
|
|
50
62
|
|
|
@@ -61,7 +73,7 @@ export {
|
|
|
61
73
|
```yaml
|
|
62
74
|
# pnpm-workspace.yaml
|
|
63
75
|
catalog:
|
|
64
|
-
|
|
76
|
+
"@theholocron/<slug>-client": ^<version>
|
|
65
77
|
```
|
|
66
78
|
|
|
67
79
|
```json
|
|
@@ -73,6 +85,7 @@ catalog:
|
|
|
73
85
|
## Auth pattern (4-step precedence)
|
|
74
86
|
|
|
75
87
|
Every plugin's `auth.ts` follows this order:
|
|
88
|
+
|
|
76
89
|
1. `--token` CLI flag (`RuntimeContext.cliToken`)
|
|
77
90
|
2. `HOLOCRON_<VENDOR>_TOKEN` env var
|
|
78
91
|
3. `<VENDOR_NATIVE_ENV_VAR>` env var
|