@xylabs/toolchain 7.10.0

package/templates/readme/README.template.md

@@ -0,0 +1,22 @@
+[![logo][]](https://xylabs.com)
+
+# {{name}}
+
+[![npm][npm-badge]][npm-link]
+[![license][license-badge]][license-link]
+
+> {{description}}
+
+{{body}}
+
+## License
+
+See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).
+
+{{typedoc}}
+
+[logo]: https://example.com/logo.svg
+[npm-badge]: https://img.shields.io/npm/v/{{name}}.svg
+[npm-link]: https://www.npmjs.com/package/{{name}}
+[license-badge]: https://img.shields.io/npm/l/{{name}}.svg
+[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE

package/templates/repo/cli/package/package.json.tmpl

@@ -0,0 +1,63 @@
+{
+  "name": "{{npmScope}}/{{packageName}}",
+  "version": "0.1.0",
+  "description": "{{description}}",
+  "keywords": [
+    "xylabs",
+    "{{projectName}}",
+    "cli",
+    "typescript"
+  ],
+  "homepage": "https://xylabs.com",
+  "bugs": {
+    "url": "git+https://github.com/{{githubOrg}}/{{projectName}}/issues",
+    "email": "support@xylabs.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/{{githubOrg}}/{{projectName}}.git"
+  },
+  "license": "LGPL-3.0-only",
+  "author": {
+    "name": "XY Labs Development Team",
+    "email": "support@xylabs.com",
+    "url": "https://xylabs.com"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "{{packageName}}": "dist/bin/{{packageName}}.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "package-compile": "tsc -p tsconfig.build.json --noEmit && tsup && publint"
+  },
+  "dependencies": {
+    "chalk": "~5.6.2",
+    "yargs": "~18.0.0"
+  },
+  "devDependencies": {
+    "@types/yargs": "~17.0.35",
+    "@xylabs/tsconfig": "~{{configVersion}}",
+    "publint": "~0.3.18",
+    "tsup": "~8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.17.1"
+  },
+  "engineStrict": true,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/repo/cli/package/src/__packageName__.ts.tmpl

@@ -0,0 +1,21 @@
+import yargs from 'yargs'
+import { hideBin } from 'yargs/helpers'
+
+import { versionCommand } from './commands/index.ts'
+
+export const {{identifierName}} = async (): Promise<void> => {
+  await yargs(hideBin(process.argv))
+    .scriptName('{{packageName}}')
+    .usage('$0 <command> [options]')
+    .option('verbose', {
+      alias: 'v',
+      type: 'boolean',
+      default: false,
+      describe: 'Enable verbose output',
+    })
+    .command(versionCommand)
+    .demandCommand(1)
+    .strictCommands()
+    .version()
+    .help().argv
+}

package/templates/repo/cli/package/src/actions/index.ts

@@ -0,0 +1 @@
+export { printVersion } from './printVersion.ts'

package/templates/repo/cli/package/src/actions/printVersion.ts.tmpl

@@ -0,0 +1,8 @@
+import chalk from 'chalk'
+
+export function printVersion(): void {
+  console.log(chalk.cyan('{{projectName}}'))
+  console.log(`  Node:    ${process.version}`)
+  console.log(`  Platform: ${process.platform}`)
+  console.log(`  Arch:     ${process.arch}`)
+}

package/templates/repo/cli/package/src/bin/__packageName__.ts.tmpl

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { {{identifierName}} } from '../{{packageName}}.ts'
+
+{{identifierName}}()
+  .then(() => {
+    process.exit(0)
+  })
+  .catch((error) => {
+    console.error(error)
+    process.exit(1)
+  })

package/templates/repo/cli/package/src/commands/index.ts

@@ -0,0 +1 @@
+export { versionCommand } from './versionCommand.ts'

package/templates/repo/cli/package/src/commands/versionCommand.ts.tmpl

@@ -0,0 +1,11 @@
+import type { CommandModule } from 'yargs'
+
+import { printVersion } from '../actions/index.ts'
+
+export const versionCommand: CommandModule = {
+  command: 'info',
+  describe: 'Display {{projectName}} version and environment info',
+  handler: () => {
+    printVersion()
+  },
+}

package/templates/repo/cli/package/src/index.ts.tmpl

@@ -0,0 +1 @@
+export { {{identifierName}} } from './{{packageName}}.ts'

package/templates/repo/cli/package/tsconfig.build.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "incremental": false,
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noImplicitAny": true,
+    "noImplicitOverride": true,
+    "outDir": "dist",
+    "removeComments": false,
+    "resolveJsonModule": true,
+    "skipDefaultLibCheck": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "ESNext"
+  },
+  "exclude": [".github", ".vscode", ".yarn", "dist", "node_modules", "build"],
+  "include": ["src"]
+}

package/templates/repo/cli/package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "exclude": ["dist"],
+  "extends": "@xylabs/tsconfig"
+}

package/templates/repo/cli/package/tsup.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  bundle: true,
+  clean: false,
+  dts: { entry: ['src/index.ts'] },
+  outExtension: ({ format }) => ({ js: format === 'cjs' ? '.cjs' : '.mjs' }),
+  entry: ['src'],
+  format: ['esm'],
+  outDir: 'dist',
+  sourcemap: true,
+  splitting: false,
+  target: 'esnext',
+  tsconfig: 'tsconfig.build.json',
+})

package/templates/repo/cli/package/xy.config.ts

@@ -0,0 +1,3 @@
+const config = { compile: { browser: false } } as const
+
+export default config

package/templates/repo/cli/root/CLAUDE.md.tmpl

@@ -0,0 +1,38 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Monorepo for {{projectName}} (`{{npmScope}}/{{packageName}}`). Currently contains a single package (`packages/{{packageName}}`) that provides the `{{packageName}}` CLI command, built with yargs.
+
+## Commands
+
+All `xy` commands must be run from the repo root, never from inside a package directory.
+
+```sh
+{{pmName}} xy build                    # Full build (all packages)
+{{pmName}} xy compile                  # TypeScript compilation only
+{{pmName}} xy lint                     # Lint all packages
+{{pmName}} xy lint {{npmScope}}/{{packageName}}       # Lint a single package
+{{pmName}} xy fix                      # Auto-fix lint issues
+{{pmName}} xy test                     # Run all tests
+{{pmName}} xy knip                     # Check for unused exports/dead code
+{{pmName}} xy deplint                  # Verify dependency declarations
+{{pmName}} xy cycle                    # Check for circular dependencies
+```
+
+## Architecture
+
+- **Package manager**: {{pmName}} (workspaces defined in {{pmName}}-workspace.yaml)
+- **Build**: tsup compiles the package to ESM (`.mjs` + `.d.ts`) in `dist/`
+- **Test**: Vitest (node environment)
+- **Lint**: ESLint flat config via `@xylabs/eslint-config-flat`
+
+### CLI structure
+
+The `{{packageName}}` CLI follows the yargs command pattern:
+- Entry point: `src/bin/{{packageName}}.ts`
+- Yargs bootstrap: `src/{{packageName}}.ts`
+- Commands: `src/commands/` (each exports a `CommandModule`)
+- Actions: `src/actions/` (business logic invoked by commands)

package/templates/repo/cli/root/cspell.json.tmpl

@@ -0,0 +1,13 @@
+{
+    "dictionaries": [],
+    "dictionaryDefinitions": [],
+    "ignorePaths": [],
+    "ignoreWords": [],
+    "import": [],
+    "version": "0.2",
+    "words": [
+        "{{projectName}}",
+        "xylabs",
+        "yargs"
+    ]
+}

package/templates/repo/cli/root/eslint.config.ts

@@ -0,0 +1,28 @@
+import {
+  importConfig,
+  rulesConfig,
+  sonarConfig,
+  typescriptTypeCheckedConfig,
+  unicornConfig,
+  workspacesConfig,
+} from '@xylabs/eslint-config-flat'
+import type { Linter } from 'eslint'
+
+const config: Linter.Config[] = [
+  { ignores: ['.yarn', 'dist', 'build', 'coverage', 'docs', 'knip.config.ts', '**/dist', '**/build', '**/docs'] },
+  unicornConfig,
+  workspacesConfig,
+  rulesConfig,
+  ...typescriptTypeCheckedConfig,
+  sonarConfig,
+  {
+    rules: {
+      'sonarjs/public-static-readonly': ['off'],
+      'sonarjs/prefer-single-boolean-return': ['off'],
+    },
+  },
+  ...importConfig,
+  { rules: { 'import-x/no-cycle': ['warn', { maxDepth: 5 }] } },
+]
+
+export default config

package/templates/repo/cli/root/github/workflows/build-pnpm.yml.tmpl

@@ -0,0 +1,34 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - develop
+      - main
+      - next
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        node: [22]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: ${{ github.head_ref }}
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+          cache: pnpm
+
+      - name: install
+        run: pnpm install
+
+      - name: build
+        run: pnpm xy build

package/templates/repo/cli/root/github/workflows/build-yarn.yml.tmpl

@@ -0,0 +1,32 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - develop
+      - main
+      - next
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        node: [22]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: ${{ github.head_ref }}
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+          cache: yarn
+
+      - name: install
+        run: yarn install --immutable
+
+      - name: build
+        run: yarn xy build

package/templates/repo/cli/root/gitignore.tmpl

@@ -0,0 +1,47 @@
+# 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
+
+# Lint
+.eslintcache
+
+# Claude Code
+.claude
+CLAUDE.local.md
+
+# Claude Code worktrees
+.claude-worktrees
+
+tmp
+AGENTS.md
+.agents
+output

package/templates/repo/cli/root/knip.config.ts

@@ -0,0 +1,16 @@
+import type { KnipConfig } from 'knip'
+
+const config: KnipConfig = {
+  workspaces: {
+    '.': {},
+    'packages/*': {},
+  },
+  typescript: {
+    config: [
+      'tsconfig.json',
+      'packages/**/*/tsconfig.json',
+    ],
+  },
+}
+
+export default config

package/templates/repo/cli/root/package.json.tmpl

@@ -0,0 +1,54 @@
+{
+  "name": "{{npmScope}}/{{projectName}}-build",
+  "private": true,
+  "description": "{{description}}",
+  "keywords": [
+    "xylabs",
+    "{{projectName}}",
+    "typescript",
+    "esm"
+  ],
+  "homepage": "https://xylabs.com",
+  "bugs": {
+    "url": "git+https://github.com/{{githubOrg}}/{{projectName}}/issues",
+    "email": "support@xylabs.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/{{githubOrg}}/{{projectName}}.git"
+  },
+  "license": "LGPL-3.0-only",
+  "author": {
+    "name": "XY Labs Development Team",
+    "email": "support@xylabs.com",
+    "url": "https://xylabs.com"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@types/node": "~25.5.2",
+    "@vitest/coverage-v8": "~4.1.3",
+    "chalk": "~5.6.2",
+    "@xylabs/eslint-config-flat": "~{{configVersion}}",
+    "@xylabs/ts-scripts-common": "~{{configVersion}}",
+    "{{pmPackage}}": "~{{configVersion}}",
+    "@xylabs/tsconfig": "~{{configVersion}}",
+    "eslint": "~10.2.0",
+    "eslint-import-resolver-typescript": "~4.4.4",
+    "knip": "~6.3.0",
+    "tsup": "~8.5.1",
+    "typescript": "^5",
+    "vite": "^8.0.7",
+    "vitest": "^4.1.3",
+    "yargs": "~18.0.0"
+  },
+  "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319",
+  "engineStrict": true,
+  "volta": {
+    "node": "22.3.0"
+  }
+}

package/templates/repo/cli/root/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - 'packages/**/*'

package/templates/repo/cli/root/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "exclude": [".yarn", "dist", "docs", "**/dist", "**/docs"],
+  "extends": "@xylabs/tsconfig"
+}

package/templates/repo/cli/root/vitest.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: 'v8' as const,
+      reporter: ['text', 'lcov', 'json-summary'],
+      reportsDirectory: './coverage',
+      include: ['packages/*/src/**/*.ts'],
+      exclude: [
+        '**/*.spec.ts',
+        '**/*.test.ts',
+        '**/*.bench.ts',
+        '**/spec/**',
+        '**/index.ts',
+        '**/*.d.ts',
+      ],
+    },
+    globals: true,
+    watch: false,
+    projects: [
+      {
+        test: {
+          name: 'node',
+          environment: 'node',
+          include: ['packages/*/src/spec/**/*.spec.ts'],
+        },
+      },
+    ],
+  },
+})

package/templates/repo/cli/root/xy.config.ts.tmpl

@@ -0,0 +1,5 @@
+import type { XyConfig } from '{{pmPackage}}'
+
+const config: XyConfig = {}
+
+export default config