@theholocron/skills 1.12.1-alpha.1 → 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/README.md CHANGED
@@ -22,7 +22,7 @@ import {} from "@theholocron/skills";
22
22
 
23
23
  <!-- /holocron:installation -->
24
24
 
25
- Each skill is a directory under `skills/` containing a `SKILL.md` file that Claude Code (and compatible
25
+ Each skill is a directory under `skills/src/` containing a `SKILL.md` file that Claude Code (and compatible
26
26
  agents) can load as a slash command.
27
27
 
28
28
  ## Owned skills
@@ -40,18 +40,18 @@ Skills authored and maintained in this repo. Published inside the npm package.
40
40
 
41
41
  ### Project-specific (theholocron)
42
42
 
43
- | Skill | Description |
44
- | --------------------------------------------------------------- | ----------------------------------------------------------------------- |
45
- | [`holocron-skill-config`](./src/holocron-skill-config/SKILL.md) | Scaffold a new `@theholocron/*-config` package in `theholocron/configs` |
46
- | [`holocron-skill-client`](./src/holocron-skill-client/SKILL.md) | Scaffold a new `@theholocron/*-client` package in `theholocron/clients` |
47
- | [`holocron-skill-plugin`](./src/holocron-skill-plugin/SKILL.md) | Scaffold or migrate a new `holocron-plugin-*` package |
48
- | [`holocron-skill-util`](./src/holocron-skill-util/SKILL.md) | Scaffold a new `@theholocron/*-utils` package in `theholocron/utils` |
49
- | [`holocron-skill-skill`](./src/holocron-skill-skill/SKILL.md) | Add a new owned skill to `theholocron/skills` |
43
+ | Skill | Description |
44
+ | --------------------------------------------------------------- | ------------------------------------------------------------ |
45
+ | [`holocron-skill-config`](./src/holocron-skill-config/SKILL.md) | Scaffold a new `@theholocron/*-config` package in `configs/` |
46
+ | [`holocron-skill-client`](./src/holocron-skill-client/SKILL.md) | Scaffold a new `@theholocron/*-client` package in `clients/` |
47
+ | [`holocron-skill-plugin`](./src/holocron-skill-plugin/SKILL.md) | Scaffold or migrate a new `holocron-plugin-*` package |
48
+ | [`holocron-skill-util`](./src/holocron-skill-util/SKILL.md) | Scaffold a new `@theholocron/*-utils` package in `utils/` |
49
+ | [`holocron-skill-skill`](./src/holocron-skill-skill/SKILL.md) | Add a new owned skill to `skills/` |
50
50
 
51
51
  ## External skills
52
52
 
53
53
  Tracked in [`skills-lock.json`](./skills-lock.json) with source provenance and content hash.
54
- Not committed to this repo — fetched from upstream by `holocron skills update` (planned).
54
+ Not committed to this repo — fetched from upstream by `holocron update skills` (planned).
55
55
 
56
56
  | Skill | Source | Description |
57
57
  | ----------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
@@ -96,7 +96,7 @@ GITHUB_TOKEN=$(gh auth token) pnpm exec holocron setup
96
96
  Copy a skill directory into your project's `.agents/skills/` and symlink it:
97
97
 
98
98
  ```sh
99
- cp -r node_modules/@theholocron/skills/skills/git-safety .agents/skills/
99
+ cp -r node_modules/@theholocron/skills/src/git-safety .agents/skills/
100
100
  ln -s ../../.agents/skills/git-safety .claude/skills/git-safety
101
101
  ```
102
102
 
@@ -112,7 +112,7 @@ Add both to `.gitignore`:
112
112
 
113
113
  ### Adding an owned skill
114
114
 
115
- 1. Create `skills/<name>/SKILL.md` with the frontmatter format:
115
+ 1. Create `skills/src/<name>/SKILL.md` with the frontmatter format:
116
116
 
117
117
  ```markdown
118
118
  ---
@@ -125,9 +125,9 @@ Add both to `.gitignore`:
125
125
  …
126
126
  ```
127
127
 
128
- 2. Run `pnpm test` — the smoke test checks that every skill dir has a `SKILL.md`.
129
- 3. Update this README with a row in the owned skills table.
130
- 4. Open a PR with a `feat:` commit — semantic-release handles versioning.
128
+ 2. Run `pnpm --filter @theholocron/skills test:unit` — the smoke test checks that every skill dir has a `SKILL.md`.
129
+ 3. Update this README with a row in the owned skills table, and add the docs page (`docs/src/content/docs/skills/<name>.mdx`), its row in `skills/index.mdx` and its sidebar entry in `astro.config.ts`.
130
+ 4. Open a PR with a `feat(skills):` commit — semantic-release handles versioning.
131
131
 
132
132
  ### Registering an external skill
133
133
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/skills",
3
- "version": "1.12.1-alpha.1",
3
+ "version": "1.12.1-alpha.4",
4
4
  "description": "Shared agent skill registry.",
5
5
  "keywords": [
6
6
  "agent-skills",
@@ -34,6 +34,6 @@
34
34
  "access": "public"
35
35
  },
36
36
  "scripts": {
37
- "verification.unitTests": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=test-report.junit.xml --test-reporter=lcov --test-reporter-destination=lcov.info test/index.mjs"
37
+ "test:unit": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=test-report.junit.xml --test-reporter=lcov --test-reporter-destination=lcov.info test/index.mjs"
38
38
  }
39
39
  }
@@ -12,6 +12,8 @@ superseded-by: []
12
12
  tags: []
13
13
  ---
14
14
 
15
+ <!-- alex disable pros -->
16
+
15
17
  # [Short title of the decision]
16
18
 
17
19
  - Status: [proposed | accepted | rejected | deprecated | superseded by ADR-XXXX]
@@ -94,7 +94,7 @@ Signed-off-by: Your Name <you@example.com>
94
94
 
95
95
  Never skip `-s`. Branch protection and CI enforce DCO.
96
96
 
97
- ## Validate before committing, don't just guess
97
+ ## Validate before committing, don't only guess
98
98
 
99
99
  Per [commitlint's own AI-agent guidance](https://commitlint.js.org/guides/ai-agents.html):
100
100
  treat the resolved commitlint config as a contract, not a memory exercise — verify a
@@ -118,7 +118,7 @@ directly rather than relying on auto-discovery (same pattern this org's own
118
118
  printf '%s' "<message>" | npx commitlint --config node_modules/@theholocron/commitlint-config/dist/index.js
119
119
  ```
120
120
 
121
- If the `commit-msg` hook rejects a commit, the rejected rule name is in the error —
121
+ If the `commit-msg` hook refuses a commit, the rejected rule name is in the error —
122
122
  fix the message and retry. **Don't reach for `git commit --no-verify` to get past an
123
123
  actual commit-message failure** — fix the message. (This is scoped to the message
124
124
  itself: bypassing a hook for a separately-confirmed, pre-existing, unrelated failure
@@ -28,7 +28,7 @@ For each option:
28
28
 
29
29
  # Recommended Direction
30
30
 
31
- State the recommendation clearly as a proposal, not a decision.
31
+ State the recommendation as a proposal, not a decision.
32
32
 
33
33
  # Open Questions
34
34
 
@@ -1,73 +1,99 @@
1
1
  ---
2
2
  name: holocron-skill-client
3
3
  title: "Holocron: New Client"
4
- 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
+ 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
5
  ---
6
6
 
7
7
  <!-- editorconfig-checker-disable-file -->
8
8
 
9
9
  # Scaffold a new client package
10
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
+
11
14
  Replace `<slug>` with the vendor name in kebab-case (e.g. `slack`, `stripe`),
12
15
  `<Vendor>` with PascalCase (e.g. `Slack`, `Stripe`), and `<BASE_URL>` with
13
16
  the API root (e.g. `https://api.stripe.com`).
14
17
 
15
- Reference implementation: `packages/zendesk-client` (the canonical example
16
- of the current patterns — `createRestClient`, `stubFetch`, DI fetch).
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.
17
23
 
18
24
  ---
19
25
 
20
- ## 1. Register in the workspace
21
-
22
- Add to `pnpm-workspace.yaml`:
26
+ ## 1. Create the package directory
23
27
 
24
- ```yaml
25
- packages:
26
- - packages/<slug>-client
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
27
40
  ```
28
41
 
29
- Then run `pnpm install` from the repo root.
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`.
30
48
 
31
49
  ---
32
50
 
33
- ## 2. Config files (identical across all clients)
51
+ ## 2. Config files
34
52
 
35
- **`packages/<slug>-client/package.json`**
53
+ **`clients/<slug>-client/package.json`**
36
54
 
37
55
  ```json
38
56
  {
39
57
  "name": "@theholocron/<slug>-client",
40
- "version": "0.0.0",
58
+ "version": "<current clients version>",
41
59
  "description": "A TypeScript client for the <Vendor> API",
42
- "homepage": "https://github.com/theholocron/clients/tree/main/packages/<slug>-client#readme",
43
- "bugs": "https://github.com/theholocron/clients/issues",
60
+ "keywords": ["<slug>", "typescript", "http-client", "api"],
61
+ "homepage": "https://docs.theholocron.dev/holocron/clients/<slug>/",
62
+ "bugs": "https://github.com/theholocron/holocron/issues",
44
63
  "repository": {
45
64
  "type": "git",
46
- "url": "git+https://github.com/theholocron/clients.git",
47
- "directory": "packages/<slug>-client"
65
+ "url": "git+https://github.com/theholocron/holocron.git",
66
+ "directory": "clients/<slug>-client"
48
67
  },
49
- "license": "GPL-3.0",
68
+ "license": "MIT",
50
69
  "author": "Newton Koumantzelis",
70
+ "sideEffects": false,
51
71
  "type": "module",
52
- "main": "./src/index.ts",
53
- "exports": { ".": "./src/index.ts" },
72
+ "exports": {
73
+ ".": {
74
+ "types": "./dist/index.d.mts",
75
+ "import": "./dist/index.mjs",
76
+ "default": "./dist/index.mjs"
77
+ }
78
+ },
79
+ "files": ["dist"],
54
80
  "scripts": {
55
- "build": "tsdown",
56
- "lint": "eslint .",
57
- "test": "vitest run",
81
+ "build": "tsdown && node ../scripts/check-bundle-size.mjs",
82
+ "lint:code": "eslint .",
58
83
  "test:watch": "vitest",
59
- "test:coverage": "vitest run --coverage",
60
- "typecheck": "tsc --noEmit"
84
+ "typecheck": "tsc --noEmit",
85
+ "test:unit": "vitest run"
61
86
  },
62
87
  "dependencies": {
63
- "@theholocron/http-client": "<current-lockstep-version>"
88
+ "@theholocron/http-client": "workspace:^",
89
+ "@theholocron/observability": "catalog:"
64
90
  },
65
91
  "devDependencies": {
66
- "@types/node": "^22.0.0",
67
- "@theholocron/eslint-config": "catalog:",
68
- "@theholocron/tsconfig": "catalog:",
69
- "@theholocron/tsdown-config": "catalog:",
70
- "@theholocron/vitest-config": "catalog:",
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:",
71
97
  "@vitest/coverage-v8": "catalog:",
72
98
  "@vitest/eslint-plugin": "catalog:",
73
99
  "eslint": "catalog:",
@@ -77,81 +103,176 @@ Then run `pnpm install` from the repo root.
77
103
  "typescript": "catalog:",
78
104
  "vitest": "catalog:"
79
105
  },
80
- "publishConfig": {
81
- "access": "public",
82
- "main": "./dist/index.mjs",
83
- "types": "./dist/index.d.mts",
84
- "exports": {
85
- ".": {
86
- "types": "./dist/index.d.mts",
87
- "import": "./dist/index.mjs",
88
- "default": "./dist/index.mjs"
89
- }
90
- }
91
- },
92
- "files": ["dist", "README.md"],
93
106
  "engines": { "node": ">=22.0.0" },
94
- "releases": "https://github.com/theholocron/clients/releases"
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"]
95
143
  }
96
144
  ```
97
145
 
98
146
  ## 3. Source files
99
147
 
100
- ### `src/client.ts` — REST client factory
148
+ ### `src/utils.ts` — REST client factory
101
149
 
102
150
  ```ts
103
151
  import { createRestClient, type RestClient } from "@theholocron/http-client";
152
+ import type { ErrorSink, Logger } from "@theholocron/observability/core";
153
+
154
+ export type { RestClient };
104
155
 
105
156
  export interface <Vendor>ClientOptions {
157
+ /** <Vendor> API token. */
106
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. */
107
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;
108
167
  }
109
168
 
110
169
  export function create<Vendor>RestClient(opts: <Vendor>ClientOptions): RestClient {
111
170
  return createRestClient({
112
- baseUrl: "<BASE_URL>",
171
+ baseUrl: opts.baseUrl ?? "<BASE_URL>",
113
172
  token: opts.token,
114
173
  vendor: "<Vendor>",
115
174
  fetch: opts.fetch,
175
+ logger: opts.logger,
176
+ errors: opts.errors,
116
177
  });
117
178
  }
118
179
  ```
119
180
 
120
- ### `src/index.ts` — factory + public API
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
121
187
 
122
188
  ```ts
123
- import { create<Vendor>RestClient } from "./client.js";
124
- import { <resources> } from "./<resources>.js";
189
+ import { <resource> } from "./<resource>/<resource>.js";
190
+ import { type <Vendor>ClientOptions, create<Vendor>RestClient } from "./utils.js";
125
191
 
126
- export type { <Vendor>ClientOptions } from "./client.js";
127
- export type * from "./types.js";
192
+ export type { <Vendor>ClientOptions } from "./utils.js";
128
193
 
129
194
  export function create<Vendor>Client(opts: <Vendor>ClientOptions) {
130
195
  const rest = create<Vendor>RestClient(opts);
131
- return { <resources>: <resources>(rest) };
196
+ return { <resource>: <resource>(rest) };
132
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
+ });
133
218
  ```
134
219
 
135
- ## 4. Non-negotiables
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
136
229
 
137
- 1. **Add to `.releaserc.json` `prepareCmd`** — alphabetical order. Omitting this leaves
138
- the package frozen at its initial version while all others advance.
139
- 2. **Set initial `version`** in `package.json` to match the current lockstep version.
140
- 3. **Add entry to `codecov.yml`** under `component_management.individual_components`.
141
- 4. **Use `stubFetch`** in tests — DI pattern, no `vi.stubGlobal`.
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`.
142
244
 
143
- ## 5. Checklist before opening a PR
245
+ ## 5. Docs
144
246
 
145
- - [ ] Feature branch created before any code was written
146
- - [ ] `pnpm install` — workspace symlink created
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
147
265
  - [ ] `pnpm --filter @theholocron/<slug>-client typecheck` passes
148
- - [ ] `pnpm --filter @theholocron/<slug>-client lint` passes
149
- - [ ] `pnpm --filter @theholocron/<slug>-client test` passes
266
+ - [ ] `pnpm --filter @theholocron/<slug>-client lint:code` passes
267
+ - [ ] `pnpm --filter @theholocron/<slug>-client test:unit` passes
150
268
  - [ ] `pnpm --filter @theholocron/<slug>-client build` — `dist/` emitted
151
- - [ ] `packages/<slug>-client` added to `prepareCmd` in `.releaserc.json`
152
- - [ ] `version` in `package.json` set to current lockstep version
153
- - [ ] `codecov.yml` entry added
154
- - [ ] Client entry added to the docs-theme registry
155
- - [ ] Docs page added under `docs/` in the same PR
156
- - [ ] PR title follows Conventional Commits
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`)
157
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.