@xylabs/toolchain 7.10.0

package/templates/claude/skills/xylabs-e2e-setup/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: xylabs-e2e-setup
+description: >
+  Sets up a complete Playwright end-to-end testing package for a React/Vite monorepo app.
+  Use this skill whenever the user asks to add e2e tests, set up Playwright, add browser testing,
+  or create a test package for a React app — even if they just say something like "add e2e" or
+  "I want to test this in Safari too". The skill creates the full packages/e2e/ directory with
+  page object models, a Playwright config covering Chromium, Firefox, and WebKit, and a webkit-safe
+  home page title test. It adapts to the existing repo's package naming, dev server port, and
+  workspace conventions rather than using generic defaults.
+---
+# xylabs-e2e-setup
+Scaffolds a `packages/e2e/` Playwright testing package that fits neatly into an existing
+React/Vite Yarn-workspaces monorepo. The generated package uses the Page Object Model pattern,
+targets all three browser engines, and includes a WebKit-safe title assertion.
+---
+## Step 1 — Read the repo before writing anything
+Before generating any files, collect these four pieces of information from the repo root:
+1. **App package name** — read `package.json` → `name` field (e.g. `web-explore.xyo.network-react`)
+2. **Dev-server port** — read `vite.config.ts`; look for the parsed `port` variable or the `server.port` value. Default is `3000` if not set.
+3. **Existing e2e scripts** — check whether `package.json` already has `"e2e"` scripts so you don't duplicate them.
+4. **Workspace glob** — confirm `"workspaces": ["packages/*"]` is present so `packages/e2e` will be picked up automatically.
+The e2e package name should be derived from the app name by stripping any leading scope/path noise
+and appending `-e2e`. For example, `web-explore.xyo.network-react` → `web-explore-e2e`.
+---
+## Step 2 — Create `packages/e2e/`
+Create every file below. Adapt the port and package name to what you found in Step 1.
+### `packages/e2e/package.json`
+```json
+{
+  "name": "<derived-e2e-name>",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "playwright test",
+    "test:debug": "playwright test --debug",
+    "test:headed": "playwright test --headed",
+    "test:ui": "playwright test --ui"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0"
+  }
+}
+```
+### `packages/e2e/tsconfig.json`
+```json
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "strict": true,
+    "target": "ES2022"
+  },
+  "exclude": ["node_modules", "test-results", "playwright-report"],
+  "include": ["playwright.config.ts", "tests/**/*.ts", "pages/**/*.ts", "fixtures/**/*.ts"]
+}
+```
+### `packages/e2e/playwright.config.ts`
+Key points:
+- `baseURL` falls back to `http://localhost:<PORT>` (use the port you found)
+- `webServer` restarts the app's own dev server when needed, with `reuseExistingServer: true`
+- `webServer.cwd` is `'../..'` — two levels up from `packages/e2e/` to the repo root
+- `webServer.command` is `'yarn start'` (the standard React/Vite dev-server script)
+- CI mode: `forbidOnly`, 1 worker, 2 retries, `github` reporter
+```typescript
+import { defineConfig, devices } from '@playwright/test'
+const baseURL = process.env['BASE_URL'] ?? 'http://localhost:<PORT>'
+export default defineConfig({
+  forbidOnly: !!process.env['CI'],
+  fullyParallel: true,
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+  ],
+  reporter: process.env['CI'] ? 'github' : 'html',
+  retries: process.env['CI'] ? 2 : 0,
+  testDir: './tests',
+  use: {
+    baseURL,
+    screenshot: 'only-on-failure',
+    trace: 'on-first-retry',
+    video: 'on-first-retry',
+  },
+  webServer: {
+    command: 'yarn start',
+    cwd: '../..',
+    reuseExistingServer: true,
+    url: baseURL,
+  },
+  workers: process.env['CI'] ? 1 : undefined,
+})
+```
+### `packages/e2e/pages/BasePage.ts`
+The `goto` base method navigates and waits for `domcontentloaded`. Subclasses override `goto()` with
+no arguments and call `super.goto('/<path>')`.
+```typescript
+import type { Page } from '@playwright/test'
+export class BasePage {
+  readonly page: Page
+  constructor(page: Page) {
+    this.page = page
+  }
+  async goto(path: string): Promise<void> {
+    await this.page.goto(path)
+    await this.page.waitForLoadState('domcontentloaded')
+  }
+}
+```
+### `packages/e2e/pages/HomePage.ts`
+```typescript
+import type { Locator, Page } from '@playwright/test'
+import { BasePage } from './BasePage.js'
+export class HomePage extends BasePage {
+  readonly nav: Locator
+  constructor(page: Page) {
+    super(page)
+    this.nav = page.locator('nav')
+  }
+  override async goto(): Promise<void> {
+    await super.goto('/')
+  }
+}
+```
+### `packages/e2e/tests/home.spec.ts`
+> **Why the `waitForFunction` call?**
+> In WebKit (Safari), `networkidle` can fire before React (or react-helmet) has written
+> `document.title`. Adding `waitForFunction(() => document.title.length > 0)` polls inside
+> the browser until the title is actually set, so the `toHaveTitle` assertion is always
+> racing against a non-empty string rather than timing out on an empty one.
+```typescript
+import { expect, test } from '@playwright/test'
+import { HomePage } from '../pages/HomePage.js'
+test.describe('Home page', () => {
+  test('loads successfully', async ({ page }) => {
+    const home = new HomePage(page)
+    await home.goto()
+    await page.waitForFunction(() => document.title.length > 0, { timeout: 5000 })
+    await expect(page).toHaveTitle(/.+/)
+  })
+})
+```
+### `packages/e2e/tests/navigation.spec.ts`
+Minimal smoke test — extend the `routes` array as the app grows.
+```typescript
+import { expect, test } from '@playwright/test'
+const routes = [
+  { name: 'Home', path: '/' },
+]
+test.describe('Navigation', () => {
+  for (const route of routes) {
+    test(`${route.name} route renders without errors`, async ({ page }) => {
+      await page.goto(route.path)
+      await expect(page.locator('body')).toBeVisible()
+    })
+  }
+})
+```
+---
+## Step 3 — Wire up root `package.json`
+Add convenience scripts to the root `package.json` so developers can run tests without `cd`-ing
+into `packages/e2e`. Use the e2e package name you derived in Step 1.
+```json
+"e2e": "yarn workspace <derived-e2e-name> test",
+"e2e:debug": "yarn workspace <derived-e2e-name> test:debug",
+"e2e:headed": "yarn workspace <derived-e2e-name> test:headed",
+"e2e:ui": "yarn workspace <derived-e2e-name> test:ui"
+```
+Only add scripts that don't already exist.
+---
+## Step 4 — Update root `.gitignore`
+Playwright generates several output directories that should never be committed. Read the root
+`.gitignore` and append the following block **only if the entries are not already present**:
+```gitignore
+# Playwright
+/packages/e2e/test-results/
+/packages/e2e/playwright-report/
+/packages/e2e/blob-report/
+/packages/e2e/.playwright/
+```
+Do not create a new `.gitignore` if one doesn't exist — if there is no root `.gitignore`, skip
+this step and note it to the user.
+
+---
+## Step 5 — Install Playwright browsers and CLI tool
+After scaffolding, run the following two commands via the Bash tool:
+
+**5a — Install browser binaries:**
+```bash
+yarn workspace <derived-e2e-name> playwright install
+```
+This downloads the Chromium, Firefox, and WebKit browser binaries. Without this step the tests
+will fail immediately with a "browser not found" error.
+
+**5b — Install the `@playwright/cli` package and its skills:**
+```bash
+yarn workspace <derived-e2e-name> add @playwright/cli@latest && yarn workspace <derived-e2e-name> playwright-cli install --skills
+```
+`@playwright/cli` provides the `playwright-cli` binary. Running `playwright-cli install --skills`
+installs the Playwright VS Code agent skills into the workspace so Copilot and other AI tooling
+can generate accurate Playwright tests against the actual page structure.
+
+Do not skip either step or ask the user to run them manually — execute both directly as part of
+the setup.
+
+---
+## Conventions to preserve
+- All files use ESM (`import`/`export`), never CommonJS.
+- Playwright bracket notation for env vars: `process.env['CI']`, not `process.env.CI` — avoids TypeScript strict-mode complaints.
+- `strict: true` in `tsconfig.json`.
+- No `dist/` output — `noEmit: true` because Playwright compiles on the fly via its own ESM loader.

package/templates/claude/skills/xylabs-xy-cli/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: xylabs-xy-cli
+description: >
+  Comprehensive reference for the `xy` CLI provided by `@xylabs/ts-scripts-yarn3`.
+  Use this skill whenever the user asks how to build, lint, test, deploy, or run any
+  tooling command in an XY Labs monorepo — even if they just say something like
+  "how do I compile" or "check my deps". Covers every command, common workflows,
+  single-package targeting, and troubleshooting.
+---
+# xylabs-xy-cli
+
+The `xy` CLI is the unified build toolchain for all XY Labs and XYO Network TypeScript
+monorepos. It wraps compilation, linting, testing, dependency analysis, deployment, and
+repo maintenance into a single tool.
+
+**Always run `xy` commands from the repo root**, never from inside a package directory.
+
+---
+
+## Package Manager Detection
+
+Before running any command, detect the repo's package manager by checking the repo root:
+- `yarn.lock` present → use **yarn** (e.g. `yarn xy build`)
+- `pnpm-lock.yaml` present → use **pnpm** (e.g. `pnpm xy build`)
+
+All commands below are shown without a prefix. Prepend the detected package manager
+when executing (e.g. `xy build` → `yarn xy build` or `pnpm xy build`).
+
+---
+
+## Installation
+
+The CLI is provided by `@xylabs/ts-scripts-yarn3` (or `@xylabs/ts-scripts-react-yarn3`
+for React repos). It is already a devDependency in every XY Labs repo — no separate
+install is needed.
+
+---
+
+## Global Options
+
+All commands accept these flags:
+
+| Flag | Description |
+|---|---|
+| `-j, --jobs` | Max parallel jobs |
+| `-v, --verbose` | Run with verbose logging (default: false) |
+| `-i, --incremental` | Only act on changed packages (default: false) |
+| `-p, --profile` | Profile the action (default: false) |
+| `--version` | Show version number |
+| `--help` | Show help |
+
+---
+
+## Command Reference
+
+### Build & Compile
+
+| Command | Description |
+|---|---|
+| `xy build [package]` | Full build: compile + publint + deplint + lint |
+| `xy compile [package]` | Compile all packages (TypeScript via tsup) + publint |
+| `xy compile-only [package]` | Compile only (no publint) |
+| `xy recompile [package]` | Clean compiled output, then compile again |
+| `xy rebuild [package]` | Clean everything, then full build |
+| `xy copy-assets [package]` | Copy non-TS assets from `src/` to `dist/` |
+| `xy clean [package]` | Remove `dist/` and `build/` artifacts |
+
+### Lint & Fix
+
+| Command | Description |
+|---|---|
+| `xy check` | Run gitlint, publint, repo lint, and lintlint as a batch |
+| `xy lint [package]` | Run ESLint across all packages |
+| `xy fix [package]` | Run ESLint with `--fix` to auto-fix issues |
+| `xy relint [package]` | Clean ESLint cache, then lint from scratch |
+| `xy deplint [package]` | Verify imports match `package.json` dependency declarations |
+| `xy publint [package]` | Validate `package.json` correctness for npm publishing |
+| `xy cycle [package]` | Detect circular dependency cycles |
+| `xy knip` | Find unused exports and dead code |
+| `xy dead [package]` | Check for dead (unreachable) code |
+| `xy sonar` | Run SonarQube analysis |
+| `xy lintlint` | Check for redundant or overridden ESLint rules vs shared config |
+| `xy dupdeps` | Find duplicate dependency declarations across packages |
+
+### Testing
+
+| Command | Description |
+|---|---|
+| `xy test [target]` | Run Vitest tests |
+| `xy retest [target]` | Clean test cache, then run tests |
+
+### Deploy & Publish
+
+| Command | Description |
+|---|---|
+| `xy deploy` | Patch version bump + build + publish |
+| `xy deploy-minor` | Minor version bump + build + publish |
+| `xy deploy-major` | Major version bump + build + publish |
+| `xy deploy-next` | Deploy as `next` tag (pre-release) |
+| `xy publish` | Publish packages to npmjs (without version bump) |
+
+### Dependency Management
+
+| Command | Description |
+|---|---|
+| `xy reinstall` | Remove `node_modules`, reinstall from scratch |
+| `xy up` | Update all dependencies to latest compatible versions |
+| `xy updo` | Update dependencies (interactive) |
+| `xy upplug` | Update Yarn plugins |
+| `xy upyarn` | Update Yarn version |
+| `xy statics` | Confirm static packages |
+| `xy yarn3only` | Check if using Yarn v3 |
+
+### Git & Repo Maintenance
+
+| Command | Description |
+|---|---|
+| `xy gitlint [package]` | Lint git configuration (ignorecase, autocrlf, etc.) |
+| `xy gitignore` | Generate root `.gitignore` and remove package-level ones |
+| `xy npmignore-gen` | Generate `.npmignore` files |
+| `xy license [package]` | Check dependency licenses for compliance |
+| `xy gen-docs [package]` | Generate TypeDoc API documentation |
+| `xy clean-docs` | Clean TypeDoc output |
+
+### README Utilities
+
+| Command | Description |
+|---|---|
+| `xy readme gen [package]` | Generate README.md files from template |
+| `xy readme init` | Initialize README template and logo files |
+
+`xy readme gen` accepts `--template <path>` to specify a custom template and
+`--typedoc` to include TypeDoc reference sections.
+
+### Repo Utilities
+
+| Command | Description |
+|---|---|
+| `xy repo lint` | Check monorepo package structure (root private, workspace globs, etc.) |
+
+### Package Manager Utilities
+
+| Command | Description |
+|---|---|
+| `xy packman convert <target>` | Convert repo to a different package manager (pnpm or yarn) |
+| `xy packman lint` | Check package manager configuration settings |
+
+### Claude Code Integration
+
+| Command | Description |
+|---|---|
+| `xy claude init` | Initialize all Claude configuration (commands, rules, skills, settings) |
+| `xy claude check` | Check if Claude configuration is up to date with templates |
+| `xy claude clean` | Remove all Claude configuration files |
+| `xy claude commands` | Sync slash commands to `.claude/commands/` |
+| `xy claude rules` | Sync rules to `.claude/rules/` |
+| `xy claude skills` | Sync skills to `.claude/skills/` |
+| `xy claude settings` | Initialize `.claude/settings.local.json` |
+
+---
+
+## Targeting a Single Package
+
+Most commands accept an optional `[package]` argument to scope to one package:
+
+```bash
+xy compile my-package
+xy lint my-package
+xy deplint my-package
+```
+
+Use the **package name** from `package.json` (e.g. `@xylabs/assert`), not the directory
+path. You can also use just the short name without the scope (e.g. `assert`).
+
+---
+
+## Common Workflows
+
+### Before pushing code
+```bash
+xy build
+```
+This runs the full pipeline: compile, publint, deplint, and lint. If it passes, the code
+is ready to push.
+
+### After modifying dependencies
+```bash
+xy deplint
+```
+Catches missing or extraneous entries in `package.json` relative to actual imports.
+
+### When lint results seem stale
+```bash
+xy relint
+```
+Clears the ESLint cache and re-lints everything.
+
+### When tests seem stale
+```bash
+xy retest
+```
+Clears the Vitest cache and re-runs tests.
+
+### When things are broken and you want a clean slate
+```bash
+xy rebuild
+```
+Cleans all artifacts, recompiles, and re-lints.
+
+### Nuclear option — full reset
+```bash
+xy reinstall
+```
+Removes `node_modules` and reinstalls everything from scratch.
+
+---
+
+## Troubleshooting
+
+### "Command not found: xy"
+The `xy` binary comes from `@xylabs/ts-scripts-yarn3`. Run `install` via your package
+manager to ensure it is linked. The binary is at `node_modules/.bin/xy`.
+
+### Compile errors in other packages
+`ts-scripts-yarn3` must compile before other packages that depend on it. The repo's
+`compile` script handles this ordering automatically — always use `xy compile`
+from the root, not `tsc` directly.
+
+### Deplint false positives
+Deplint scans TypeScript source imports and `tsconfig.json` extends chains. If a
+dependency is used only in config files (not source), it may flag as unused. Check the
+output carefully before removing.
+
+### Version conflicts
+All packages in a repo share a single version. Never edit version fields manually —
+use `xy deploy` variants to bump versions.

package/templates/claude/skills/xylabs-xy-deplint-fix/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: xylabs-xy-deplint-fix
+description: >
+  Fix dependency declaration errors in one or more packages using `xy deplint --fix`.
+  Use this skill whenever the user asks to fix deplint errors, clean up package.json
+  dependencies, or resolve "dependency should be devDependency" / "missing dependency"
+  warnings in an XY Labs monorepo. If a package name is supplied as an argument, fix
+  only that package. If no argument is given, fix all packages in the repo.
+---
+
+# xylabs-xy-deplint-fix
+
+Diagnoses and fixes `package.json` dependency declaration errors reported by `xy deplint`
+in an XY Labs monorepo. The `--fix` flag handles all error types automatically.
+
+---
+
+## Package Manager Detection
+
+Check the repo root before running any command:
+
+* `yarn.lock` present → prefix commands with **yarn** (e.g. `yarn xy deplint`)
+* `pnpm-lock.yaml` present → prefix commands with **pnpm**
+
+All commands below are shown without a prefix. Prepend accordingly.
+
+---
+
+## What `--fix` handles
+
+| Error message | Fix applied |
+|---|---|
+| `dependency should be devDependency` | Moves from `dependencies` → `devDependencies` |
+| `Unused dependency` | Removes from `dependencies` |
+| `Unused devDependency` | Removes from `devDependencies` |
+| `Unused peerDependency` | Removes from `peerDependencies` |
+| `Missing dependency` | Adds to `dependencies` (version from node_modules) |
+| `Missing devDependency` | Adds to `devDependencies` (version from node_modules) |
+| `Unsatisfied peer dependency` | Adds to appropriate section based on context |
+
+Empty dependency sections are removed automatically. All edits are sorted with
+`sort-package-json`.
+
+---
+
+## Workflow
+
+### Step 1 — Fix
+
+```bash
+# Whole repo
+xy deplint --fix
+
+# Single package
+xy deplint --fix package-name
+```
+
+This scans for problems and applies fixes to `package.json` files in place.
+Review the output to see what was changed.
+
+### Step 2 — Install
+
+After `--fix` modifies `package.json` files, reinstall from the repo root so the
+lockfile and `node_modules` reflect the changes:
+
+```bash
+yarn install   # or: pnpm install
+```
+
+Do **not** use `yarn workspaces focus` — it strips the root-level `xy` script bindings.
+
+### Step 3 — Verify
+
+Re-run deplint without `--fix` to confirm all issues are resolved:
+
+```bash
+xy deplint [package-name]
+```
+
+**Definition of done:**
+
+```text
+Deplint: Found no dependency problems. ✔
+```
+
+If problems remain, repeat from Step 1. Some issues (e.g. newly-added deps introducing
+their own unsatisfied peers) may require multiple passes.
+
+---
+
+## Edge Cases
+
+### Multiple passes required
+
+Fixing missing dependencies may introduce new unsatisfied peer dependency errors, since
+the newly-added package has its own peers. Run the fix → install → verify loop until
+clean.
+
+### Version resolution for missing deps
+
+`--fix` resolves versions by reading the installed version from `node_modules` and
+prefixing with `~`. If the package is not installed, it falls back to `*`. After
+installing and re-running, the version will be resolved correctly on the next pass.
+
+### Aggregator packages
+
+Aggregator packages (no `src/`, only re-export workspace children) may need all workspace
+children as `devDependencies`. `--fix` handles this — it moves deps to devDependencies
+and adds missing transitive deps automatically.
+
+### `dependency should be devDependency` for a runtime import
+
+deplint may flag a dep as "should be devDependency" even when it is imported for a
+runtime value. This happens when the dep is a foundational library that consumers are
+expected to already have installed (behaves like a peer). `--fix` moves it to
+`devDependencies`. If the dep must be guaranteed for external npm consumers, manually
+add it to `peerDependencies` after fixing.
+
+### `yarn workspaces focus` breaks the `xy` command
+
+`yarn workspaces focus <package>` installs only the deps for that one package and removes
+the root-level `xy` script bindings. Always use `yarn install` (full) after fixing.

package/templates/gitignore/gitignore/template.gitignore

@@ -0,0 +1,51 @@
+# Build outputs (root)
+/build
+/dist
+/docs
+/storybook-static
+
+# Build outputs (packages)
+packages/*/build
+packages/*/dist
+packages/*/docs
+packages/*/storybook-static
+
+# Coverage
+/coverage
+packages/*/coverage
+
+# TypeScript
+*.tsbuildinfo
+
+# Logs
+*.log
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+
+# Node
+node_modules
+
+# Yarn
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Lint
+.eslintcache
+
+# Claude Code
+.claude
+CLAUDE.local.md
+
+# Claude Code worktrees
+.claude-worktrees

package/templates/gitignore/template.gitignore

@@ -0,0 +1,51 @@
+# Build outputs (root)
+/build
+/dist
+/docs
+/storybook-static
+
+# Build outputs (packages)
+packages/*/build
+packages/*/dist
+packages/*/docs
+packages/*/storybook-static
+
+# Coverage
+/coverage
+packages/*/coverage
+
+# TypeScript
+*.tsbuildinfo
+
+# Logs
+*.log
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+
+# Node
+node_modules
+
+# Yarn
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Lint
+.eslintcache
+
+# Claude Code
+.claude
+CLAUDE.local.md
+
+# Claude Code worktrees
+.claude-worktrees

package/templates/readme/README.body.md

@@ -0,0 +1,25 @@
+## Install
+
+Using npm:
+
+```sh
+npm install {{name}}
+```
+
+Using yarn:
+
+```sh
+yarn add {{name}}
+```
+
+Using pnpm:
+
+```sh
+pnpm add {{name}}
+```
+
+Using bun:
+
+```sh
+bun add {{name}}
+```