Mantle

Appearance

Developer Tooling ​

Mantle ships a full CI and convention-enforcement suite in the CLI.

Quick Start ​

bash
mantle generate hooks            # Husky hooks + worktree provisioning
mantle generate ci-templates     # GitHub Actions workflows
mantle generate knip-config      # Dead code detection config
mantle generate agents           # AGENTS.md for AI assistants

pnpm add -D husky && npx husky   # Install hook runtime

mantle ci                        # Run full pipeline locally

Local CI ​

mantle ci mirrors what GitHub Actions runs.

bash
mantle ci           # lint, build, typecheck, test, conventions
mantle ci --full    # adds integration tests and extended checks

Phases: setup → build → validate → test → quality → integration. Tools that aren't installed (ShellCheck, knip, tofu) are skipped gracefully.

CI blocks on any CRITICAL or HIGH violation, test failure, build error, or dependency architecture violation.

Convention Checks ​

mantle check runs 20 ts-morph rules against your code.

bash
mantle check                      # all rules
mantle check --fast               # CRITICAL only (~2s)
mantle check --severity HIGH      # CRITICAL + HIGH

Severity levels:

SeverityCountExamples
CRITICAL3Handler pattern, handler export, defineLambda required
HIGH11No raw process.env, no raw AWS SDK, entity decorators, response validation
MEDIUM6Permission gaps, metrics, batch retry, mocking

Dependency Architecture ​

bash
mantle check deps

Enforces: no handler→handler imports, no circular deps, entity queries can't import handler code, no deep @j0nathan-ll0yd/* internal imports.

Git Hooks ​

bash
mantle generate hooks

Creates three Husky hooks:

  • pre-commit: secrets scan + dependency architecture (~2–5s)
  • pre-push: full mantle ci pipeline
  • post-checkout: on a fresh linked worktree only, runs scripts/worktree-setup.sh

The setup script seeds only explicitly listed, missing local files from the primary checkout—such as .claude/settings.local.json, .env, .envrc, and local Terraform var files. It deliberately never copies a directory or overwrites a local file. Add instance-specific files to that script's list.

It also installs dependencies for a fresh pnpm worktree. To skip that step:

bash
WORKTREE_SKIP_INSTALL=1 git worktree add ../my-feature -b feat/my-feature

mantle generate hooks preserves existing hooks and setup scripts, so it is safe to use when adopting the feature in an existing instance. Commit the generated files before adding a worktree; the post-checkout hook must be in the new checkout to run.

bash
MANTLE_SKIP_HOOKS=1 git commit    # bypass temporarily

ESLint Rules ​

The custom Mantle rules ship inside @j0nathan-ll0yd/eslint-config (they are wired up automatically by createMantleEslintConfig()). To register the rule plugin on its own:

bash
pnpm add -D @j0nathan-ll0yd/eslint-config
javascript
// eslint.config.mjs
import mantleRules from "@j0nathan-ll0yd/eslint-config/local-rules";
export default [mantleRules.configs.recommended];

Provides 9 rules covering handler patterns, imports, and naming.

Bundle Analysis ​

bash
mantle check bundles              # default 5 MB threshold
mantle check bundles --json       # JSON output for CI

Reports per-Lambda sizes, top dependencies, and tree-shaking ratio.

Dead Code Detection ​

bash
mantle generate knip-config
pnpm add -D knip
mantle check dead-code

MCP Server ​

bash
mantle mcp-server

Exposes 19 tools for AI assistants: validation, infra queries, package reference, deployment workflows, entity queries, dependency analysis, and performance estimation.

Context Generation ​

bash
mantle generate agents            # AGENTS.md project overview
mantle generate graph             # build/graph.json dependency graph
mantle generate repomix           # AI context packing config

Configuration ​

typescript
// mantle.config.ts
import { defineToolingConfig } from "@j0nathan-ll0yd/cli/config";

export default defineToolingConfig({
  name: "my-api",
  database: { provider: "aurora-dsql" },
  ci: {
    formatter: "dprint",
    conventions: { severity: "HIGH" },
  },
  hooks: {
    preCommit: { secretsScan: true, depArchitecture: true },
    prePush: { ci: true },
  },
});

Further Reading ​