npm package: @hyphaene/hexa-ts-kit
Description: TypeScript dev kit for Claude Code agents: architecture linting, scaffolding, knowledge analysis
Author: hyphaene
Latest version: 1.13.0

[![npm version](https://img.shields.io/npm/v/@hyphaene/hexa-ts-kit.svg)](https://www.npmjs.com/package/@hyphaene/hexa-ts-kit)

# 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

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

Or use directly with npx:

```bash
npx @hyphaene/hexa-ts-kit lint
```

## Usage

### CLI

```bash
# 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:

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

Or if installed globally:

```json
{
  "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

```bash
# 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:

```bash
$ 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:

```yaml
---
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):

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

**In-repo** (from inside the git repo):

```bash
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:

```yaml
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

```bash
# 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`:

```bash
# 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:**

```bash
npm run playground
```

Opens at http://localhost:3000

## Requirements

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

## License

MIT