@vielzeug/codex 3.0.4 → 3.1.0

package/dist/cli.js

@@ -9,12 +9,14 @@ import { startHttpHost } from './http.js';
 import { resolvePort } from './port.js';
 import { SnapshotRefineCatalog } from './refine-catalog.js';
 import { createMcpServer } from './server.js';
+import { installSkills, SKILL_TARGET_CANDIDATES } from './skills.js';
 import { loadSnapshot } from './snapshot.js';
 import { registerRefineTools } from './tools/refine.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 function usage() {
     log([
         'Usage: codex [--port=<number>] [--snapshot=<directory>] [--debug]',
+        '       codex skills install [--target=<directory>] [--force]',
         '',
         'Options:',
         '  --port=<number>        Run Streamable HTTP on loopback.',
@@ -22,8 +24,29 @@ function usage() {
         '  --debug                Log tool timings and expected tool errors.',
         '  -h, --help             Show help.',
         '  -v, --version          Print version.',
+        '',
+        'Skills:',
+        '  skills install         Copy the bundled agent skill(s) into the project.',
+        `  --target=<directory>   Skills directory. Default: first existing of ${SKILL_TARGET_CANDIDATES.join(', ')}.`,
+        '  --force                Overwrite an already installed skill.',
     ].join('\n'));
 }
+function runSkills(argv) {
+    const [action, ...rest] = argv;
+    if (action !== 'install') {
+        log(`error: unknown skills command "${action ?? ''}" (expected: install)`);
+        return 1;
+    }
+    const { values } = parseArgs({
+        args: rest,
+        options: { force: { type: 'boolean' }, target: { type: 'string' } },
+        strict: true,
+    });
+    const installed = installSkills({ force: values.force, target: values.target });
+    for (const skill of installed)
+        log(`installed skill "${skill.name}" → ${skill.path}`);
+    return 0;
+}
 export async function main(argv = process.argv.slice(2)) {
     if (argv.includes('--help') || argv.includes('-h')) {
         usage();
@@ -34,6 +57,15 @@ export async function main(argv = process.argv.slice(2)) {
         process.stdout.write(`${pkg.version}\n`);
         return 0;
     }
+    if (argv[0] === 'skills') {
+        try {
+            return runSkills(argv.slice(1));
+        }
+        catch (error) {
+            log(`error: ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+    }
     let values;
     try {
         ({ values } = parseArgs({

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/skills.d.ts

@@ -0,0 +1,26 @@
+import { CodexError } from './errors.js';
+/** Skill directories shipped in the package, in `skills/<name>/SKILL.md` layout. */
+export declare const SKILLS_ROOT: string;
+/** Directories probed, in order, when no `--target` is given. The first existing one wins; if none
+ * exist the first entry is created. */
+export declare const SKILL_TARGET_CANDIDATES: readonly [".agents/skills", ".github/skills", ".claude/skills"];
+export declare class SkillInstallError extends CodexError {
+}
+export interface InstallSkillsOptions {
+    /** Project root to probe for target candidates. Default: `process.cwd()`. */
+    cwd?: string;
+    /** Overwrite an existing skill directory. Default: `false`. */
+    force?: boolean;
+    /** Skill directory root to copy from. Default: {@link SKILLS_ROOT}. */
+    source?: string;
+    /** Explicit target skills directory (absolute or relative to `cwd`). Skips autodetection. */
+    target?: string;
+}
+export interface InstalledSkill {
+    name: string;
+    path: string;
+}
+export declare function listBundledSkills(source?: string): readonly string[];
+export declare function resolveSkillTarget(cwd: string, target?: string): string;
+/** Copies every bundled skill into the resolved target directory and returns what was written. */
+export declare function installSkills(options?: InstallSkillsOptions): readonly InstalledSkill[];

package/dist/skills.js

@@ -0,0 +1,46 @@
+import { cpSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CodexError } from './errors.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Skill directories shipped in the package, in `skills/<name>/SKILL.md` layout. */
+export const SKILLS_ROOT = resolve(__dirname, '../skills');
+/** Directories probed, in order, when no `--target` is given. The first existing one wins; if none
+ * exist the first entry is created. */
+export const SKILL_TARGET_CANDIDATES = ['.agents/skills', '.github/skills', '.claude/skills'];
+export class SkillInstallError extends CodexError {
+}
+export function listBundledSkills(source = SKILLS_ROOT) {
+    if (!existsSync(source))
+        return [];
+    return readdirSync(source, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(source, entry.name, 'SKILL.md')))
+        .map((entry) => entry.name)
+        .sort();
+}
+export function resolveSkillTarget(cwd, target) {
+    if (target)
+        return resolve(cwd, target);
+    const existing = SKILL_TARGET_CANDIDATES.find((candidate) => existsSync(resolve(cwd, candidate)));
+    return resolve(cwd, existing ?? SKILL_TARGET_CANDIDATES[0]);
+}
+/** Copies every bundled skill into the resolved target directory and returns what was written. */
+export function installSkills(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const source = options.source ?? SKILLS_ROOT;
+    const names = listBundledSkills(source);
+    if (names.length === 0)
+        throw new SkillInstallError(`no bundled skills found in ${source}`);
+    const targetRoot = resolveSkillTarget(cwd, options.target);
+    const conflicts = names.filter((name) => existsSync(join(targetRoot, name)));
+    if (conflicts.length > 0 && !options.force) {
+        throw new SkillInstallError(`skill${conflicts.length > 1 ? 's' : ''} already installed: ${conflicts.map((name) => join(targetRoot, name)).join(', ')} (use --force to overwrite)`);
+    }
+    mkdirSync(targetRoot, { recursive: true });
+    return names.map((name) => {
+        const path = join(targetRoot, name);
+        cpSync(join(source, name), path, { force: true, recursive: true });
+        return { name, path };
+    });
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vielzeug/codex",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "MCP server exposing all Vielzeug docs to AI clients",
   "repository": {
     "type": "git",
@@ -14,7 +14,8 @@
   "files": [
     "data",
     "dist",
-    "mcp-setup.json"
+    "mcp-setup.json",
+    "skills"
   ],
   "types": "./dist/index.d.ts",
   "exports": {
@@ -68,7 +69,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.4.1",
-    "@vielzeug/refine": "3.2.1",
+    "@vielzeug/refine": "3.3.0",
     "typescript": "^6.0.3",
     "vitest": "^5.0.0"
   }

package/skills/vielzeug/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: vielzeug
+description: Use when a project depends on any @vielzeug/* package — pick the owning package instead of hand-rolling, and use Refine components, tokens, and theme whenever @vielzeug/refine is installed. Applies to features, fixes, refactors, and UI work in consuming apps.
+---
+
+# Vielzeug
+
+Vielzeug is a set of independent, zero-dependency TypeScript packages published as `@vielzeug/*`. This skill keeps an agent working *with* the installed packages: discover what exists, use the owning package, and build UI from Refine when it is present.
+
+## Detect
+
+1. Read `package.json` (`dependencies`, `devDependencies`, `peerDependencies`) and list every `@vielzeug/*` entry.
+2. Note whether `@vielzeug/refine` is installed. If it is, the **Refine** and **Theme** sections below are mandatory for any UI work.
+3. Read the project's own agent contract (`AGENTS.md`, `.github/copilot-instructions.md`) first — project rules win over this skill.
+
+## Discover, don't recall
+
+Never guess exports, attributes, events, slots, or token names. Look them up:
+
+| Question | MCP tool (`@vielzeug/codex`) | Offline fallback |
+| --- | --- | --- |
+| Which package solves X? | `search-packages`, `list-packages` | the package list below |
+| How do I use package X? | `get-docs` (`index`, `usage`, `api`, `examples`) | `node_modules/@vielzeug/<pkg>/README.md` |
+| Exact signature of an export | `get-type-signature` | `node_modules/@vielzeug/<pkg>/dist/*.d.ts` |
+| Runnable example | `list-examples`, `get-example` | — |
+| Which Refine components exist? | `refine-list-components` | `node_modules/@vielzeug/refine/dist/custom-elements.json` |
+| Attributes, properties, events, slots, CSS parts of `ore-*` | `refine-get-component` | same manifest |
+| Available design tokens | `refine-get-tokens` | `node_modules/@vielzeug/refine/dist/styles/tokens.css` |
+| Is my markup valid? | `refine-validate-usage` | compare against the manifest |
+| Blank component scaffold | `refine-generate-template` | — |
+
+If the MCP server is not connected, install it with `npx -y @vielzeug/codex` (see `node_modules/@vielzeug/codex/mcp-setup.json`) or use the fallback column.
+
+## Use the owning package
+
+If a need matches a package below, use that package. Do not reimplement signals, fetch wrappers, validation, routing, i18n, DI, date math, storage, or event buses by hand, and do not add a third-party library for a need an installed `@vielzeug/*` package already covers. Prefer installing the matching `@vielzeug/*` package over a third-party one when the project already uses Vielzeug, but ask before adding a dependency.
+
+<!-- GENERATED:skill-packages:BEGIN -->
+
+- `@vielzeug/arsenal` — Non-trivial TypeScript utilities — retry, cancellation, cache, safe-path, serialization, prototype-pollution-guarded collections
+- `@vielzeug/assay` — Framework-agnostic DOM testing primitives — scoped queries, event dispatch, async waiting
+- `@vielzeug/clockwork` — Framework-neutral finite state machines with pure transitions and actors
+- `@vielzeug/coins` — Currency formatting and exchange utilities for monetary arithmetic
+- `@vielzeug/conduit` — Typed dependency injection container
+- `@vielzeug/courier` — Typed HTTP client with bounded structured-key caching, prefetching, immutable middleware, and structured errors
+- `@vielzeug/dnd` — Drag-and-drop — drop zones and sortable lists
+- `@vielzeug/familiar` — Web Worker pool with tasks, timeouts, cancellation
+- `@vielzeug/flux` — Minimal push streams with explicit ownership, bounded buffering, and structural bridges
+- `@vielzeug/focus` — Framework-neutral list navigation and focus restoration primitives
+- `@vielzeug/forge` — Typed form state, validation, submission
+- `@vielzeug/gesture` — Framework-neutral two-dimensional pointer drag and one-axis pan recognition with lifecycle-owned handles
+- `@vielzeug/herald` — Typed synchronous event bus with wildcard subscriptions, one-shot waits, and lifecycle tracing
+- `@vielzeug/illusionist` — Typed, deterministic, locale-aware fake data generator with seeded PRNG
+- `@vielzeug/keymap` — Headless keyboard shortcut manager with chord sequences
+- `@vielzeug/ledger` — Serialized reversible command history with atomic framework-neutral state and cancellation ownership
+- `@vielzeug/lingua` — Typed i18n with pluralization and lazy locale loading
+- `@vielzeug/mesh` — Backendless peer-to-peer session transport over WebRTC data channels with manual pairing and host-authoritative star topology
+- `@vielzeug/necromancer` — Lifecycle-owned Web Animations API primitives with native access, per-handle groups, and additive FLIP
+- `@vielzeug/orbit` — Floating UI positioning with lifecycle-owned geometry and middleware
+- `@vielzeug/ore` — Functional web-component authoring on top of ripple
+- `@vielzeug/postmaster` — Typed durable job outbox with leased processing, retries, and dead-letter recovery
+- `@vielzeug/prism` — Responsive SVG charts with explicit updates — line, bar, area, pie, sparkline
+- `@vielzeug/pulse` — Typed WebSocket client with channels, rooms, presence, reconnect
+- `@vielzeug/refine` — Accessible, themeable web components built on ore
+- `@vielzeug/ripple` — Reactive runtime primitives: signals, derived values, effects, scopes, watchers, and async resources
+- `@vielzeug/rune` — Structured scoped logger with remote transport
+- `@vielzeug/sandbox` — Sandboxed iframe runtime with typed postMessage state bridge
+- `@vielzeug/scout` — Trigram fuzzy-search index with highlighting and reactive layer
+- `@vielzeug/scroll` — Virtual list engine for large datasets
+- `@vielzeug/sentinel` — Subscribable snapshots for external browser environment state
+- `@vielzeug/sigil` — QR code generation and scanning — pure matrix encoder, SVG and canvas renderers, native BarcodeDetector scanning
+- `@vielzeug/sourcerer` — Reactive collection sources with local, page, cursor, and infinite pagination
+- `@vielzeug/spell` — Zero-dependency schema validation with Standard Schema interoperability
+- `@vielzeug/tempo` — Temporal-powered date utilities
+- `@vielzeug/vault` — Adapter-free typed storage core with focused browser and SQLite subpaths
+- `@vielzeug/ward` — Ordered authorization rules with immutable policies and typed decisions
+- `@vielzeug/wayfinder` — Client-side router with middleware and guards
+
+<!-- GENERATED:skill-packages:END -->
+
+Common compositions (verify each API with `get-docs` before writing code):
+
+- **State** — `ripple` signals/derived/effects; `clockwork` when state is a finite machine; `ledger` for undo/redo.
+- **Data** — `courier` for HTTP with caching and structured errors; `sourcerer` for paged/cursor/infinite collections; `vault` for storage; `postmaster` for durable jobs; `scout` for fuzzy search; `mesh` for backendless peer sessions on a LAN; `sigil` for QR generation/scanning — prefer `ore-qr-code` / `ore-qr-scanner` when Refine is installed.
+- **Forms** — `forge` for form state, validation, and submission; `spell` for schemas; render fields with Refine inputs when Refine is installed.
+- **App shell** — `wayfinder` routing; `conduit` DI; `herald` events; `lingua` i18n; `rune` logging; `ward` authorization; `keymap` shortcuts.
+- **Dispose** every handle you create (`effect`, subscriptions, clients) when its owner unmounts. Vielzeug APIs return disposables — use them.
+
+## Refine (when `@vielzeug/refine` is installed)
+
+Refine is the UI layer. Build interfaces from `ore-*` elements before anything else.
+
+1. **Bootstrap once**, before rendering any component:
+
+   ```ts
+   import '@vielzeug/refine/fouc.css';   // hide unupgraded elements until first paint
+   import '@vielzeug/refine/tokens.css'; // tokens, animations, cascade layers
+   ```
+
+   Optional: `@vielzeug/refine/styles/preflight.css` for a browser reset.
+
+2. **Register per component** through explicit side-effect subpaths (`import '@vielzeug/refine/button'`), never the whole library, unless the project already does so.
+
+3. **Component first.** For any of these needs, use the Refine element rather than a native element, a hand-built composite, or a third-party widget: buttons, inputs, selects, comboboxes, checkboxes, radios, switches, sliders, date/time pickers, file inputs, OTP, rating, textareas, forms, cards, tables, data grids, lists, tabs, accordions, dialogs, drawers, menus, popovers, tooltips, toasts, alerts, badges, chips, progress, skeletons, avatars, breadcrumbs, pagination, steppers, navbars, sidebars, grids, command palettes. Confirm the tag with `refine-list-components`; read its contract with `refine-get-component`.
+
+4. **Native elements only for document semantics** that no Refine component duplicates (`<main>`, `<section>`, `<article>`, `<h1>`–`<h6>`, `<p>`, `<a>` for plain links, `<img>`).
+
+5. **Follow the element contract**: attributes for primitives, JavaScript properties for objects/arrays/callbacks, standard DOM events (read state from `event.target`), named slots for composition. Icon-only controls need an accessible label.
+
+6. **Type the tags** once in a type entry point: `import type {} from '@vielzeug/refine/frameworks/elements'` (or `/react`, `/vue`). Framework wiring (React 18/19, Vue, Svelte, Angular, SSR guards) is documented in the Refine `frameworks` doc — fetch it with `get-docs` before integrating.
+
+7. **Validate** every fragment you write with `refine-validate-usage` before finishing.
+
+8. **Missing capability?** Do not build a parallel component in the app. Compose existing `ore-*` elements (optionally with `@vielzeug/ore` for a custom element), and report the gap.
+
+## Theme (when `@vielzeug/refine` is installed)
+
+- All visuals come from tokens: spacing `var(--size-*)` on a 4‑point grid, type `var(--text-*)`, radius `var(--rounded-*)`, semantic colors `var(--color-primary|secondary|neutral|success|warning|error|info)`. No hard-coded hex/px in app CSS when a token exists (`refine-get-tokens`).
+- Rebrand with one variable: `:root { --color-primary-hue: 220deg; }`. Override `--color-primary` only when the hue alone is insufficient.
+- Overrides go in an **unlayered** `:root` (or a scoping class) rule; Refine tokens live in `@layer refine.tokens`, so plain rules win. Never use `!important`.
+- Dark mode is `document.documentElement.classList.toggle('dark')`; tokens use `light-dark()`. Do not write `prefers-color-scheme` media blocks for colors.
+- Style components through their documented CSS custom properties and `::part()` hooks, not by piercing the shadow DOM.
+- Other Vielzeug UI packages ship tokens-aligned themes; import them alongside Refine's (`@vielzeug/prism/theme` for charts).
+
+## Other UI packages
+
+Refine covers the widget layer; these cover what it does not. Use them directly only when no `ore-*` element already provides the behavior:
+
+- `prism` — SVG charts (line, bar, area, pie, sparkline) plus `@vielzeug/prism/theme`.
+- `scroll` — virtualized large lists (prefer `ore-datagrid`/`ore-list` for ordinary sizes).
+- `dnd` / `gesture` — sortable lists, drop zones, pointer drag and pan.
+- `necromancer` — Web Animations API primitives and FLIP.
+- `orbit` — floating positioning; reach for `ore-popover`, `ore-tooltip`, `ore-menu` first.
+- `focus` / `keymap` — list navigation, focus restoration, keyboard shortcuts.
+- `ore` — authoring your own custom elements that compose Refine.
+
+## Anti-patterns
+
+- Hand-rolled signals, fetch wrappers, validators, routers, i18n, or DI when the package is installed.
+- Custom modal, dropdown, tooltip, select, tabs, or toast implementations while Refine is installed.
+- `<button>`, `<input>`, `<select>`, `<table>` for interactive UI while Refine is installed.
+- Inline colors, magic pixel values, `!important`, or `@media (prefers-color-scheme)` color rules.
+- Inventing an attribute, event, or slot that `refine-get-component` does not list.
+- Forgetting `tokens.css`/`fouc.css`, or importing the whole library when subpaths suffice.
+- Leaking effects, subscriptions, or clients past their owner's lifetime.
+
+## Done when
+
+- Every new capability maps to an installed `@vielzeug/*` package or is justified as out of scope.
+- No parallel implementation of something an installed package provides.
+- With Refine installed: all interactive UI is `ore-*`, `tokens.css` + `fouc.css` are loaded once, every fragment passed `refine-validate-usage`, and app CSS uses tokens only.
+- Every disposable is disposed by its owner.
+- Claims about package APIs were verified with `get-docs` / `get-type-signature`, not recalled.