@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.
@@ -1,274 +0,0 @@
1
- ---
2
- name: holocron-skill-util
3
- description: Scaffold a new @theholocron/<slug>-utils package in theholocron/utils. INVOKE WHEN: user asks to add a new utility package to the utils monorepo. Invoked as /holocron-skill-util.
4
- ---
5
-
6
- <!-- editorconfig-checker-disable-file -->
7
-
8
- # Scaffold a new utility package
9
-
10
- Scaffold a new `@theholocron/<name>-utils` package in `theholocron/utils`.
11
-
12
- Replace `<name>` with the utility domain in kebab-case (e.g. `color`, `math`, `format`).
13
-
14
- Reference implementations:
15
- - Node-only package: `packages/string-utils` (canonical, no browser APIs)
16
- - Browser-API package: `packages/location-utils` (adds DOM lib + eslint override)
17
-
18
- ---
19
-
20
- ## 1. Create the package directory
21
-
22
- ```
23
- packages/<name>-utils/
24
- ├── src/
25
- │ └── index.ts
26
- ├── package.json
27
- ├── tsdown.config.ts
28
- ├── tsconfig.json
29
- ├── vitest.config.ts
30
- └── README.md
31
- ```
32
-
33
- Tests live colocated in `src/` as `*.test.ts` files alongside the source they cover.
34
-
35
- ---
36
-
37
- ## 2. File templates
38
-
39
- ### `package.json`
40
-
41
- ```json
42
- {
43
- "name": "@theholocron/<name>-utils",
44
- "version": "<current monorepo version>",
45
- "description": "<One-line description.>",
46
- "homepage": "https://github.com/theholocron/utils/tree/main/packages/<name>-utils#readme",
47
- "bugs": "https://github.com/theholocron/utils/issues",
48
- "releases": "https://github.com/theholocron/utils/releases",
49
- "wiki": "https://github.com/theholocron/utils/wiki",
50
- "repository": {
51
- "type": "git",
52
- "url": "git+https://github.com/theholocron/utils.git"
53
- },
54
- "license": "GPL-3.0",
55
- "author": "Newton Koumantzelis",
56
- "type": "module",
57
- "exports": {
58
- ".": {
59
- "import": "./dist/index.js",
60
- "types": "./dist/index.d.ts"
61
- }
62
- },
63
- "files": ["dist", "README.md"],
64
- "scripts": {
65
- "build": "tsdown",
66
- "lint": "eslint .",
67
- "test": "vitest run",
68
- "typecheck": "npx tsc --noEmit"
69
- },
70
- "devDependencies": {
71
- "@theholocron/tsdown-config": "catalog:configs",
72
- "@theholocron/vitest-config": "catalog:configs",
73
- "@tsconfig/node-lts": "catalog:",
74
- "@vitest/coverage-v8": "catalog:",
75
- "tsdown": "catalog:",
76
- "vitest": "catalog:"
77
- },
78
- "packageManager": "pnpm@10.34.4",
79
- "engines": {
80
- "node": ">=22",
81
- "pnpm": ">=10"
82
- },
83
- "publishConfig": {
84
- "access": "public"
85
- }
86
- }
87
- ```
88
-
89
- - **Match `version` to the current monorepo version** — check any existing package's `package.json`.
90
- - Runtime dependencies (if any) go in `"dependencies"`, not `devDependencies`.
91
- - Browser-API packages should add `"happy-dom": "catalog:"` to `devDependencies` for tests.
92
-
93
- ### `tsdown.config.ts`
94
-
95
- ```ts
96
- import { library } from "@theholocron/tsdown-config/presets/library";
97
- import type { UserConfig } from "tsdown";
98
-
99
- const config: UserConfig = library({
100
- deps: { neverBundle: [/^@theholocron\//] },
101
- });
102
-
103
- export default config;
104
- ```
105
-
106
- If the package has runtime dependencies that should also be externalized, add their patterns to `neverBundle` (e.g. `packages/string-utils` externalizes `change-case` and `title-case`).
107
-
108
- ### `tsconfig.json` (Node-only)
109
-
110
- ```json
111
- {
112
- "display": "<Name> Utilities",
113
- "extends": "@tsconfig/node-lts/tsconfig.json",
114
- "compilerOptions": {
115
- "allowImportingTsExtensions": true
116
- },
117
- "include": ["./src/**/*.ts"],
118
- "exclude": ["./node_modules", "**/*.test.ts"]
119
- }
120
- ```
121
-
122
- ### `tsconfig.json` (Browser-API package)
123
-
124
- Add `"lib"` to `compilerOptions`:
125
-
126
- ```json
127
- {
128
- "display": "<Name> Utilities",
129
- "extends": "@tsconfig/node-lts/tsconfig.json",
130
- "compilerOptions": {
131
- "allowImportingTsExtensions": true,
132
- "lib": ["dom", "dom.iterable", "es2022"]
133
- },
134
- "include": ["./src/**/*.ts"],
135
- "exclude": ["./node_modules", "**/*.test.ts"]
136
- }
137
- ```
138
-
139
- ### `vitest.config.ts`
140
-
141
- ```ts
142
- import { library } from "@theholocron/vitest-config/bundles/library";
143
- import { defineConfig } from "vitest/config";
144
-
145
- export default defineConfig(library({ globals: true }) as never);
146
- ```
147
-
148
- `globals: true` is required — tests use `describe`/`test`/`expect` without explicit imports.
149
-
150
- ### `src/index.ts`
151
-
152
- ```ts
153
- // Named exports — no default export
154
- export function myUtil(value: string): string {
155
- return value;
156
- }
157
- ```
158
-
159
- Use named exports throughout. Group related utilities into sibling files (`src/casing.ts`, `src/casting.ts`, …) and re-export from `src/index.ts`:
160
-
161
- ```ts
162
- export * from "./casing.ts";
163
- export * from "./casting.ts";
164
- ```
165
-
166
- Note: source imports use `.ts` extensions — TypeScript's ESM convention.
167
-
168
- ### Test files (`src/<module>.test.ts`)
169
-
170
- ```ts
171
- import { describe, expect, test } from "vitest";
172
-
173
- import { myUtil } from "./index.ts";
174
-
175
- describe("<Name>", () => {
176
- test("does X", () => {
177
- expect(myUtil("input")).toBe("expected");
178
- });
179
- });
180
- ```
181
-
182
- ### `README.md`
183
-
184
- ```markdown
185
- # `@theholocron/<name>-utils`
186
-
187
- <One-line description of what the utilities do.>
188
-
189
- ## Installation
190
-
191
- \`\`\`bash
192
- pnpm add @theholocron/<name>-utils
193
- \`\`\`
194
-
195
- ## Usage
196
-
197
- \`\`\`typescript
198
- import * as <name> from "@theholocron/<name>-utils";
199
-
200
- <minimal working example>
201
- \`\`\`
202
-
203
- ## Documentation
204
-
205
- Check out [The Holocron Archive](https://docs.theholocron.dev/projects/utils/) for more information.
206
- ```
207
-
208
- ---
209
-
210
- ## 3. Register in `release.config.ts`
211
-
212
- Add the new package path to `prepareCmd` **in alphabetical order**:
213
-
214
- ```ts
215
- // release.config.ts
216
- "node -e \"...['packages/array-utils','packages/<name>-utils',...].forEach(...)\"",
217
- ```
218
-
219
- ---
220
-
221
- ## 4. Add to `codecov.yml`
222
-
223
- Append to `component_management.individual_components` (keep alphabetical):
224
-
225
- ```yaml
226
- - component_id: <name>-utils
227
- name: "<name>-utils"
228
- paths:
229
- - packages/<name>-utils/**
230
- ```
231
-
232
- ---
233
-
234
- ## 5. Browser-API packages only: update root `eslint.config.ts`
235
-
236
- Add the new package's source path to the browser override block:
237
-
238
- ```ts
239
- // eslint.config.ts — existing override
240
- files: [
241
- "packages/location-utils/src/**",
242
- "packages/misc-utils/src/**",
243
- "packages/storage-utils/src/**",
244
- "packages/<name>-utils/src/**", // ← add here
245
- ],
246
- rules: {
247
- "n/no-unsupported-features/node-builtins": "off",
248
- },
249
- ```
250
-
251
- ---
252
-
253
- ## Non-negotiables
254
-
255
- - **`catalog:configs`** for `@theholocron/tsdown-config` and `@theholocron/vitest-config`; `catalog:` for everything else — never pin exact versions.
256
- - **`tsdown` and `vitest` must be direct `devDependencies`** — pnpm does not expose transitive binaries.
257
- - **`globals: true`** in every `vitest.config.ts` — required by existing test style.
258
- - **Match version to current monorepo version** before opening a PR.
259
- - **Run `pnpm install`** after adding `package.json` to pick up workspace resolution.
260
-
261
- ---
262
-
263
- ## Checklist
264
-
265
- 1. Create `packages/<name>-utils/` with all files listed above.
266
- 2. Add package path to `prepareCmd` in `release.config.ts` (alphabetical order).
267
- 3. Add `component_id` entry to `codecov.yml` (alphabetical order).
268
- 4. If browser-API package: add `"lib"` to tsconfig + add path to root `eslint.config.ts` override.
269
- 5. Run `pnpm install` — must resolve without errors.
270
- 6. Run `pnpm build` — tsdown must compile successfully.
271
- 7. Run `pnpm test` — all tests must pass.
272
- 8. Run `pnpm typecheck` — no type errors.
273
- 9. Run `pnpm lint` — no lint errors.
274
- 10. Open a PR with a `feat:` commit — semantic-release computes a minor bump and publishes all packages in lockstep.