hexa-ts-kit

TypeScript dev kit for Claude Code agents: architecture linting, scaffolding, and knowledge analysis.

Built for colocated feature architectures in Vue.js, NestJS, and Playwright projects.

Installation

npm install -g @hyphaene/hexa-ts-kit

Or use directly with npx:

npx @hyphaene/hexa-ts-kit lint

Usage

CLI

# Lint current directory
hexa-ts lint

# Lint only git-changed files (incremental mode)
hexa-ts lint --changed

# Filter by rule categories
hexa-ts lint --rules COL,NAM,VUE

# Analyze files to find matching knowledges
hexa-ts analyze src/domains/contracts/upload.composable.ts

# Analyze git-changed files
hexa-ts analyze --changed

# Scaffold a Vue feature
hexa-ts scaffold vue-feature src/domains/contracts/upload

# Scaffold a NestJS feature
hexa-ts scaffold nestjs-feature src/domains/orders/create

# Scaffold Playwright tests
hexa-ts scaffold playwright-feature e2e/checkout

# Setup vault config (interactive wizard)
hexa-ts vault:init

# Compare vault schemas between refs
hexa-ts vault:diff --repo <alias> <source-ref> <target-ref>

# Quick diff: current branch vs main
hexa-ts vault:quick-diff

MCP Server

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "hexa-ts": {
      "command": "npx",
      "args": ["-y", "-p", "@hyphaene/hexa-ts-kit@latest", "-c", "hexa-ts-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "hexa-ts": {
      "command": "hexa-ts-mcp"
    }
  }
}

Available MCP tools:

| Tool | Description | | ---------- | ------------------------------------- | | lint | Lint files for architecture rules | | analyze | Map files to associated knowledges | | scaffold | Generate colocated feature structures |

Lint Rules

71 rules across 9 categories:

| Category | Prefix | Count | Focus | | ------------ | ------ | ----- | ---------------------------------- | | Colocation | COL | 12 | File placement and structure | | Naming | NAM | 12 | File and export naming conventions | | Vue | VUE | 13 | Vue component patterns | | Composable | CMP | 11 | Composable patterns | | Rules | RUL | 12 | Business rules file patterns | | Query | QRY | 8 | Query/API file patterns | | Translations | TRN | 5 | i18n file patterns | | TypeScript | TSP | 12 | TypeScript patterns | | Domain | DOM | 4 | Domain boundary rules |

Output Formats

# Console output (default)
hexa-ts lint

# JSON output (for agents)
hexa-ts lint --format json

Scaffold Templates

Vue Feature

src/domains/{domain}/{feature}/
├── Feature.vue
├── feature.composable.ts
├── feature.rules.ts
├── feature.types.ts
├── feature.query.ts
├── feature.translations.ts
└── __tests__/
    └── feature.rules.test.ts

NestJS Feature

src/domains/{domain}/{feature}/
├── feature.module.ts
├── feature.controller.ts
├── feature.service.ts
├── feature.types.ts
└── __tests__/
    └── feature.controller.e2e.spec.ts

Playwright Feature

e2e/{feature}/
├── feature.spec.ts
├── feature.page.ts
└── feature.fixtures.ts

Knowledge Analysis

The analyze command maps files to knowledge documents based on file patterns:

$ hexa-ts analyze upload.composable.ts

{
  "success": true,
  "files": ["upload.composable.ts"],
  "mappings": [
    {
      "file": "upload.composable.ts",
      "knowledges": ["vue-composable.knowledge.md"]
    }
  ]
}

Knowledge files use frontmatter to declare their matching patterns:

---
name: vue-composable
match: "*.composable.ts"
---

Vault Diff

Compare vault.schema.json between git refs to detect configuration changes before deployment.

Modes

Multi-repo (from anywhere, using --repo flag):

hexa-ts vault:diff --repo <alias> <source-ref> <target-ref>
hexa-ts vault:extract --repo <alias> <ref>

In-repo (from inside the git repo):

hexa-ts vault:diff <source-ref> <target-ref>
hexa-ts vault:extract <ref>

Global Configuration

Create ~/.hexa/vault.yaml to define repo aliases for multi-repo mode:

repos:
  <alias>:
    url: "<git-remote-url>"
    schemaPath: "<path/to/vault.schema.json>"
    turbineService: "<service-name>"  # optional
cacheDir: "~/.hexa/vault/.cache"

Each repo entry requires:

• url: Git remote URL (SSH or HTTPS)
• schemaPath: Path to vault.schema.json relative to repo root
• turbineService (optional): Turbine service name for environment resolution

Cache

Multi-repo mode uses bare git clones cached in ~/.hexa/vault/.cache/. On each run, the cache is fetched automatically to stay up to date. If a fetch fails, the cache is re-cloned from scratch.

Commands

# Multi-repo: compare two refs
hexa-ts vault:diff --repo <alias> <source-ref> <target-ref>

# In-repo: compare two refs
hexa-ts vault:diff <source-ref> <target-ref>

# Quick diff: current branch vs main (in-repo only)
hexa-ts vault:quick-diff

# Extract schema from a ref
hexa-ts vault:extract --repo <alias> <ref>
hexa-ts vault:extract <ref>

# JSON output (for agents)
hexa-ts vault:diff --repo <alias> <source-ref> <target-ref> --format json

Output

Vault Schema Diff
Source: <source-ref>
Target: <target-ref>
──────────────────────────────────────────────────

+ Added:
  config.newFeature: { enabled, options }
  config.workflows: enum(TYPE_A | TYPE_B)[]

- Removed:
  config.deprecatedFlag: boolean

~ Changed:
  config.items[]: string → number

──────────────────────────────────────────────────
Summary: +2 -1 ~1

⚠ Breaking changes detected (removals or type changes)

The command exits with code 1 if breaking changes are detected (removals or type changes).

Setup: vault:init

Generate ~/.hexa/vault.yaml automatically by scanning your filesystem for repos with vault.schema.json:

# Interactive wizard (React Ink)
hexa-ts vault:init

# Non-interactive (auto-detect and write)
hexa-ts vault:init --no-interactive --scan <paths>

The wizard:

1. Asks which directories to scan
2. Discovers git repos containing vault.schema.json
3. Deduplicates by remote URL (skips worktrees)
4. Suggests aliases for each repo
5. Previews and writes ~/.hexa/vault.yaml

Development

Playground

Interactive web UI for testing lint rules.

Live version: https://hexa-ts-kit.vercel.app/

Local development:

npm run playground

Opens at http://localhost:3000

Requirements

• Node.js 20+
• Git (for --changed mode)

License

MIT